diff options
Diffstat (limited to 'documentation/dev-manual/custom-distribution.rst')
-rw-r--r-- | documentation/dev-manual/custom-distribution.rst | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst new file mode 100644 index 0000000000..0bc386d606 --- /dev/null +++ b/documentation/dev-manual/custom-distribution.rst | |||
@@ -0,0 +1,135 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Creating Your Own Distribution | ||
4 | ****************************** | ||
5 | |||
6 | When you build an image using the Yocto Project and do not alter any | ||
7 | distribution :term:`Metadata`, you are using the Poky distribution. | ||
8 | Poky is explicitly a *reference* distribution for testing and | ||
9 | development purposes. It enables most hardware and software features | ||
10 | so that they can be tested, but this also means that from a security | ||
11 | point of view the attack surface is very large. Additionally, at some | ||
12 | point it is likely that you will want to gain more control over package | ||
13 | alternative selections, compile-time options, and other low-level | ||
14 | configurations. For both of these reasons, if you are using the Yocto | ||
15 | Project for production use then you are strongly encouraged to create | ||
16 | your own distribution. | ||
17 | |||
18 | To create your own distribution, the basic steps consist of creating | ||
19 | your own distribution layer, creating your own distribution | ||
20 | configuration file, and then adding any needed code and Metadata to the | ||
21 | layer. 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 | |||
117 | Copying and modifying the Poky distribution | ||
118 | =========================================== | ||
119 | |||
120 | Instead of creating a custom distribution from scratch as per above, you may | ||
121 | wish to start your custom distribution configuration by copying the Poky | ||
122 | distribution provided within the ``meta-poky`` layer and then modifying it. | ||
123 | This 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. | ||