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 8creating a Poky distribution. If you wish to gain more control over 9package alternative selections, compile-time options, and other 10low-level configurations, you can create your own distribution. 11 12To create your own distribution, the basic steps consist of creating 13your own distribution layer, creating your own distribution 14configuration file, and then adding any needed code and Metadata to the 15layer. The following steps provide some more detail: 16 17- *Create a layer for your new distro:* Create your distribution layer 18 so that you can keep your Metadata and code for the distribution 19 separate. It is strongly recommended that you create and use your own 20 layer for configuration and code. Using your own layer as compared to 21 just placing configurations in a ``local.conf`` configuration file 22 makes it easier to reproduce the same build configuration when using 23 multiple build machines. See the 24 ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" 25 section for information on how to quickly set up a layer. 26 27- *Create the distribution configuration file:* The distribution 28 configuration file needs to be created in the ``conf/distro`` 29 directory of your layer. You need to name it using your distribution 30 name (e.g. ``mydistro.conf``). 31 32 .. note:: 33 34 The :term:`DISTRO` variable in your ``local.conf`` file determines the 35 name of your distribution. 36 37 You can split out parts of your configuration file into include files 38 and then "require" them from within your distribution configuration 39 file. Be sure to place the include files in the 40 ``conf/distro/include`` directory of your layer. A common example 41 usage of include files would be to separate out the selection of 42 desired version and revisions for individual recipes. 43 44 Your configuration file needs to set the following required 45 variables: 46 47 - :term:`DISTRO_NAME` 48 49 - :term:`DISTRO_VERSION` 50 51 These following variables are optional and you typically set them 52 from the distribution configuration file: 53 54 - :term:`DISTRO_FEATURES` 55 56 - :term:`DISTRO_EXTRA_RDEPENDS` 57 58 - :term:`DISTRO_EXTRA_RRECOMMENDS` 59 60 - :term:`TCLIBC` 61 62 .. tip:: 63 64 If you want to base your distribution configuration file on the 65 very basic configuration from OE-Core, you can use 66 ``conf/distro/defaultsetup.conf`` as a reference and just include 67 variables that differ as compared to ``defaultsetup.conf``. 68 Alternatively, you can create a distribution configuration file 69 from scratch using the ``defaultsetup.conf`` file or configuration files 70 from another distribution such as Poky as a reference. 71 72- *Provide miscellaneous variables:* Be sure to define any other 73 variables for which you want to create a default or enforce as part 74 of the distribution configuration. You can include nearly any 75 variable from the ``local.conf`` file. The variables you use are not 76 limited to the list in the previous bulleted item. 77 78- *Point to Your distribution configuration file:* In your ``local.conf`` 79 file in the :term:`Build Directory`, set your :term:`DISTRO` variable to 80 point to your distribution's configuration file. For example, if your 81 distribution's configuration file is named ``mydistro.conf``, then 82 you point to it as follows:: 83 84 DISTRO = "mydistro" 85 86- *Add more to the layer if necessary:* Use your layer to hold other 87 information needed for the distribution: 88 89 - Add recipes for installing distro-specific configuration files 90 that are not already installed by another recipe. If you have 91 distro-specific configuration files that are included by an 92 existing recipe, you should add an append file (``.bbappend``) for 93 those. For general information and recommendations on how to add 94 recipes to your layer, see the 95 ":ref:`dev-manual/layers:creating your own layer`" and 96 ":ref:`dev-manual/layers:following best practices when creating layers`" 97 sections. 98 99 - Add any image recipes that are specific to your distribution. 100 101 - Add a ``psplash`` append file for a branded splash screen, using 102 the :term:`SPLASH_IMAGES` variable. 103 104 - Add any other append files to make custom changes that are 105 specific to individual recipes. 106 107 For information on append files, see the 108 ":ref:`dev-manual/layers:appending other layers metadata with your layer`" 109 section. 110