1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Creating Your Own Distribution 4****************************** 5 6When you build an image using the Yocto Project and do not alter any 7distribution :term:`Metadata`, you are using the Poky distribution. 8Poky is explicitly a *reference* distribution for testing and 9development purposes. It enables most hardware and software features 10so that they can be tested, but this also means that from a security 11point of view the attack surface is very large. Additionally, at some 12point it is likely that you will want to gain more control over package 13alternative selections, compile-time options, and other low-level 14configurations. For both of these reasons, if you are using the Yocto 15Project for production use then you are strongly encouraged to create 16your own distribution. 17 18To create your own distribution, the basic steps consist of creating 19your own distribution layer, creating your own distribution 20configuration file, and then adding any needed code and Metadata to the 21layer. The following steps provide some more detail: 22 23- *Create a layer for your new distro:* Create your distribution layer 24 so that you can keep your Metadata and code for the distribution 25 separate. It is strongly recommended that you create and use your own 26 layer for configuration and code. Using your own layer as compared to 27 just placing configurations in a ``local.conf`` configuration file 28 makes it easier to reproduce the same build configuration when using 29 multiple build machines. See the 30 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 31 section for information on how to quickly set up a layer. 32 33- *Create the distribution configuration file:* The distribution 34 configuration file needs to be created in the ``conf/distro`` 35 directory of your layer. You need to name it using your distribution 36 name (e.g. ``mydistro.conf``). 37 38 .. note:: 39 40 The :term:`DISTRO` variable in your ``local.conf`` file determines the 41 name of your distribution. 42 43 You can split out parts of your configuration file into include files 44 and then "require" them from within your distribution configuration 45 file. Be sure to place the include files in the 46 ``conf/distro/include`` directory of your layer. A common example 47 usage of include files would be to separate out the selection of 48 desired version and revisions for individual recipes. 49 50 Your configuration file needs to set the following required 51 variables: 52 53 - :term:`DISTRO_NAME` 54 55 - :term:`DISTRO_VERSION` 56 57 These following variables are optional and you typically set them 58 from the distribution configuration file: 59 60 - :term:`DISTRO_FEATURES` 61 62 - :term:`DISTRO_EXTRA_RDEPENDS` 63 64 - :term:`DISTRO_EXTRA_RRECOMMENDS` 65 66 - :term:`TCLIBC` 67 68 .. tip:: 69 70 If you want to base your distribution configuration file on the 71 very basic configuration from OE-Core, you can use 72 ``conf/distro/defaultsetup.conf`` as a reference and just include 73 variables that differ as compared to ``defaultsetup.conf``. 74 Alternatively, you can create a distribution configuration file 75 from scratch using the ``defaultsetup.conf`` file or configuration files 76 from another distribution such as Poky as a reference. 77 78- *Provide miscellaneous variables:* Be sure to define any other 79 variables for which you want to create a default or enforce as part 80 of the distribution configuration. You can include nearly any 81 variable from the ``local.conf`` file. The variables you use are not 82 limited to the list in the previous bulleted item. 83 84- *Point to Your distribution configuration file:* In your ``local.conf`` 85 file in the :term:`Build Directory`, set your :term:`DISTRO` variable to 86 point to your distribution's configuration file. For example, if your 87 distribution's configuration file is named ``mydistro.conf``, then 88 you point to it as follows:: 89 90 DISTRO = "mydistro" 91 92- *Add more to the layer if necessary:* Use your layer to hold other 93 information needed for the distribution: 94 95 - Add recipes for installing distro-specific configuration files 96 that are not already installed by another recipe. If you have 97 distro-specific configuration files that are included by an 98 existing recipe, you should add an append file (``.bbappend``) for 99 those. For general information and recommendations on how to add 100 recipes to your layer, see the 101 ":ref:`dev-manual/layers:creating your own layer`" and 102 ":ref:`dev-manual/layers:following best practices when creating layers`" 103 sections. 104 105 - Add any image recipes that are specific to your distribution. 106 107 - Add a ``psplash`` append file for a branded splash screen, using 108 the :term:`SPLASH_IMAGES` variable. 109 110 - Add any other append files to make custom changes that are 111 specific to individual recipes. 112 113 For information on append files, see the 114 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 115 section. 116 117Copying and modifying the Poky distribution 118=========================================== 119 120Instead of creating a custom distribution from scratch as per above, you may 121wish to start your custom distribution configuration by copying the Poky 122distribution provided within the ``meta-poky`` layer and then modifying it. 123This is fine, however if you do this you should keep the following in mind: 124 125- Every reference to Poky needs to be updated in your copy so that it 126 will still apply. This includes override usage within files (e.g. ``:poky``) 127 and in directory names. This is a good opportunity to evaluate each one of 128 these customizations to see if they are needed for your use case. 129 130- Unless you also intend to use them, the ``poky-tiny``, ``poky-altcfg`` and 131 ``poky-bleeding`` variants and any references to them can be removed. 132 133- More generally, the Poky distribution configuration enables a lot more 134 than you likely need for your production use case. You should evaluate *every* 135 configuration choice made in your copy to determine if it is needed. 136