diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2022-11-24 17:50:52 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2022-12-01 19:20:29 +0000 |
commit | 945c669138a76be18c6b4da4f8f907d2a5cfd83f (patch) | |
tree | cebff3cae5021d4fcceb5aa51fce1c2aead97ed2 /documentation/dev-manual/custom-distribution.rst | |
parent | 6fe3143800925463279d0664fc7f3372b53c6c52 (diff) | |
download | poky-945c669138a76be18c6b4da4f8f907d2a5cfd83f.tar.gz |
manuals: split dev-manual/common-tasks.rst
A 500 KB source file is always harder to manage,
and can have section title conflicts.
So, the "Common Tasks" document is gone and all
its constituents are moved up one level.
You now have 40 chapters in the Development Tasks Manual.
(From yocto-docs rev: 8a45bc469411410020b8e688c137395fcaf3761b)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/custom-distribution.rst')
-rw-r--r-- | documentation/dev-manual/custom-distribution.rst | 108 |
1 files changed, 108 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..e5b1ad777a --- /dev/null +++ b/documentation/dev-manual/custom-distribution.rst | |||
@@ -0,0 +1,108 @@ | |||
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 | ||
8 | creating a Poky distribution. If you wish to gain more control over | ||
9 | package alternative selections, compile-time options, and other | ||
10 | low-level configurations, you can create your own distribution. | ||
11 | |||
12 | To create your own distribution, the basic steps consist of creating | ||
13 | your own distribution layer, creating your own distribution | ||
14 | configuration file, and then adding any needed code and Metadata to the | ||
15 | layer. 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. For | ||
102 | information on append files, see the | ||
103 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" | ||
104 | section. | ||
105 | |||
106 | - Add any other append files to make custom changes that are | ||
107 | specific to individual recipes. | ||
108 | |||