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