summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/TODO11
-rw-r--r--documentation/ref-manual/classes.rst2473
-rw-r--r--documentation/ref-manual/devtool-reference.rst159
-rw-r--r--documentation/ref-manual/examples/hello-autotools/hello_2.10.bb9
-rw-r--r--documentation/ref-manual/examples/hello-single/files/helloworld.c8
-rw-r--r--documentation/ref-manual/examples/hello-single/hello.bb17
-rw-r--r--documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb14
-rw-r--r--documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb15
-rw-r--r--documentation/ref-manual/faq.rst626
-rw-r--r--documentation/ref-manual/features.rst270
-rw-r--r--documentation/ref-manual/history.rst74
-rw-r--r--documentation/ref-manual/images.rst37
-rw-r--r--documentation/ref-manual/index.rst2
-rw-r--r--documentation/ref-manual/kickstart.rst80
-rw-r--r--documentation/ref-manual/migration-1.3.rst195
-rw-r--r--documentation/ref-manual/migration-1.4.rst237
-rw-r--r--documentation/ref-manual/migration-1.5.rst353
-rw-r--r--documentation/ref-manual/migration-1.6.rst416
-rw-r--r--documentation/ref-manual/migration-1.7.rst223
-rw-r--r--documentation/ref-manual/migration-1.8.rst183
-rw-r--r--documentation/ref-manual/migration-2.0.rst281
-rw-r--r--documentation/ref-manual/migration-2.1.rst436
-rw-r--r--documentation/ref-manual/migration-2.2.rst450
-rw-r--r--documentation/ref-manual/migration-2.3.rst523
-rw-r--r--documentation/ref-manual/migration-2.4.rst327
-rw-r--r--documentation/ref-manual/migration-2.5.rst310
-rw-r--r--documentation/ref-manual/migration-2.6.rst457
-rw-r--r--documentation/ref-manual/migration-2.7.rst180
-rw-r--r--documentation/ref-manual/migration-3.0.rst320
-rw-r--r--documentation/ref-manual/migration-3.1.rst276
-rw-r--r--documentation/ref-manual/migration-3.2.rst313
-rw-r--r--documentation/ref-manual/migration-general.rst54
-rw-r--r--documentation/ref-manual/migration.rst31
-rw-r--r--documentation/ref-manual/qa-checks.rst188
-rw-r--r--documentation/ref-manual/release-process.rst122
-rw-r--r--documentation/ref-manual/resources.rst101
-rw-r--r--documentation/ref-manual/structure.rst231
-rw-r--r--documentation/ref-manual/svg/releases.svg1744
-rw-r--r--documentation/ref-manual/system-requirements.rst383
-rw-r--r--documentation/ref-manual/tasks.rst255
-rw-r--r--documentation/ref-manual/terms.rst232
-rw-r--r--documentation/ref-manual/variables.rst6276
-rw-r--r--documentation/ref-manual/varlocality.rst2
43 files changed, 8484 insertions, 10410 deletions
diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO
deleted file mode 100644
index ee0db977cc..0000000000
--- a/documentation/ref-manual/TODO
+++ /dev/null
@@ -1,11 +0,0 @@
1Handbook Todo List:
2
3 * Document adding a new IMAGE_FEATURE to the customising images section
4 * Add instructions about using zaurus/openmoko emulation
5 * Add component overview/block diagrams
6 * Software Deevelopment intro should mention its software development for
7 intended target and could be a different arch etc and thus special case.
8 * Expand insane.bbclass documentation to cover tests
9 * Document remaining classes (see list in ref-classes)
10 * Document formfactor
11
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index be112e0faf..ab71cbe40c 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -13,8 +13,14 @@ some default behavior.
13 13
14Any :term:`Metadata` usually found in a recipe can also be 14Any :term:`Metadata` usually found in a recipe can also be
15placed in a class file. Class files are identified by the extension 15placed in a class file. Class files are identified by the extension
16``.bbclass`` and are usually placed in a ``classes/`` directory beneath 16``.bbclass`` and are usually placed in one of a set of subdirectories
17the ``meta*/`` directory found in the :term:`Source Directory`. 17beneath the ``meta*/`` directory found in the :term:`Source Directory`:
18
19 - ``classes-recipe/`` - classes intended to be inherited by recipes
20 individually
21 - ``classes-global/`` - classes intended to be inherited globally
22 - ``classes/`` - classes whose usage context is not clearly defined
23
18Class files can also be pointed to by 24Class files can also be pointed to by
19:term:`BUILDDIR` (e.g. ``build/``) in the same way as 25:term:`BUILDDIR` (e.g. ``build/``) in the same way as
20``.conf`` files in the ``conf`` directory. Class files are searched for 26``.conf`` files in the ``conf`` directory. Class files are searched for
@@ -22,16 +28,16 @@ in :term:`BBPATH` using the same method by which ``.conf``
22files are searched. 28files are searched.
23 29
24This chapter discusses only the most useful and important classes. Other 30This chapter discusses only the most useful and important classes. Other
25classes do exist within the ``meta/classes`` directory in the Source 31classes do exist within the ``meta/classes*`` directories in the Source
26Directory. You can reference the ``.bbclass`` files directly for more 32Directory. You can reference the ``.bbclass`` files directly for more
27information. 33information.
28 34
29.. _ref-classes-allarch: 35.. _ref-classes-allarch:
30 36
31``allarch.bbclass`` 37``allarch``
32=================== 38===========
33 39
34The ``allarch`` class is inherited by recipes that do not produce 40The :ref:`ref-classes-allarch` class is inherited by recipes that do not produce
35architecture-specific output. The class disables functionality that is 41architecture-specific output. The class disables functionality that is
36normally needed for recipes that produce executable binaries (such as 42normally needed for recipes that produce executable binaries (such as
37building the cross-compiler and a C library as pre-requisites, and 43building the cross-compiler and a C library as pre-requisites, and
@@ -43,42 +49,43 @@ splitting out of debug symbols during packaging).
43 produce packages that depend on tunings through use of the 49 produce packages that depend on tunings through use of the
44 :term:`RDEPENDS` and 50 :term:`RDEPENDS` and
45 :term:`TUNE_PKGARCH` variables, should never be 51 :term:`TUNE_PKGARCH` variables, should never be
46 configured for all architectures using ``allarch``. This is the case 52 configured for all architectures using :ref:`ref-classes-allarch`. This is the case
47 even if the recipes do not produce architecture-specific output. 53 even if the recipes do not produce architecture-specific output.
48 54
49 Configuring such recipes for all architectures causes the 55 Configuring such recipes for all architectures causes the
50 ``do_package_write_*`` tasks to 56 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks to
51 have different signatures for the machines with different tunings. 57 have different signatures for the machines with different tunings.
52 Additionally, unnecessary rebuilds occur every time an image for a 58 Additionally, unnecessary rebuilds occur every time an image for a
53 different ``MACHINE`` is built even when the recipe never changes. 59 different :term:`MACHINE` is built even when the recipe never changes.
54 60
55By default, all recipes inherit the :ref:`base <ref-classes-base>` and 61By default, all recipes inherit the :ref:`ref-classes-base` and
56:ref:`package <ref-classes-package>` classes, which enable 62:ref:`ref-classes-package` classes, which enable
57functionality needed for recipes that produce executable output. If your 63functionality needed for recipes that produce executable output. If your
58recipe, for example, only produces packages that contain configuration 64recipe, for example, only produces packages that contain configuration
59files, media files, or scripts (e.g. Python and Perl), then it should 65files, media files, or scripts (e.g. Python and Perl), then it should
60inherit the ``allarch`` class. 66inherit the :ref:`ref-classes-allarch` class.
61 67
62.. _ref-classes-archiver: 68.. _ref-classes-archiver:
63 69
64``archiver.bbclass`` 70``archiver``
65==================== 71============
66 72
67The ``archiver`` class supports releasing source code and other 73The :ref:`ref-classes-archiver` class supports releasing source code and other
68materials with the binaries. 74materials with the binaries.
69 75
70For more details on the source archiver, see the 76For more details on the source :ref:`ref-classes-archiver`, see the
71":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" 77":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`"
72section in the Yocto Project Development Tasks Manual. You can also see 78section in the Yocto Project Development Tasks Manual. You can also see
73the :term:`ARCHIVER_MODE` variable for information 79the :term:`ARCHIVER_MODE` variable for information
74about the variable flags (varflags) that help control archive creation. 80about the variable flags (varflags) that help control archive creation.
75 81
76.. _ref-classes-autotools: 82.. _ref-classes-autotools:
77 83
78``autotools*.bbclass`` 84``autotools*``
79====================== 85==============
80 86
81The ``autotools*`` classes support Autotooled packages. 87The :ref:`autotools* <ref-classes-autotools>` classes support packages built with the
88:wikipedia:`GNU Autotools <GNU_Autotools>`.
82 89
83The ``autoconf``, ``automake``, and ``libtool`` packages bring 90The ``autoconf``, ``automake``, and ``libtool`` packages bring
84standardization. This class defines a set of tasks (e.g. ``configure``, 91standardization. This class defines a set of tasks (e.g. ``configure``,
@@ -86,16 +93,16 @@ standardization. This class defines a set of tasks (e.g. ``configure``,
86should usually be enough to define a few standard variables and then 93should usually be enough to define a few standard variables and then
87simply ``inherit autotools``. These classes can also work with software 94simply ``inherit autotools``. These classes can also work with software
88that emulates Autotools. For more information, see the 95that emulates Autotools. For more information, see the
89":ref:`dev-manual/common-tasks:autotooled package`" section 96":ref:`dev-manual/new-recipe:building an autotooled package`" section
90in the Yocto Project Development Tasks Manual. 97in the Yocto Project Development Tasks Manual.
91 98
92By default, the ``autotools*`` classes use out-of-tree builds (i.e. 99By default, the :ref:`autotools* <ref-classes-autotools>` classes use out-of-tree builds (i.e.
93``autotools.bbclass`` building with ``B != S``). 100``autotools.bbclass`` building with ``B != S``).
94 101
95If the software being built by a recipe does not support using 102If the software being built by a recipe does not support using
96out-of-tree builds, you should have the recipe inherit the 103out-of-tree builds, you should have the recipe inherit the
97``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves 104:ref:`autotools-brokensep <ref-classes-autotools>` class. The :ref:`autotools-brokensep <ref-classes-autotools>` class behaves
98the same as the ``autotools`` class but builds with :term:`B` 105the same as the :ref:`ref-classes-autotools` class but builds with :term:`B`
99== :term:`S`. This method is useful when out-of-tree build 106== :term:`S`. This method is useful when out-of-tree build
100support is either not present or is broken. 107support is either not present or is broken.
101 108
@@ -105,35 +112,34 @@ support is either not present or is broken.
105 all possible. 112 all possible.
106 113
107It's useful to have some idea of how the tasks defined by the 114It's useful to have some idea of how the tasks defined by the
108``autotools*`` classes work and what they do behind the scenes. 115:ref:`autotools* <ref-classes-autotools>` classes work and what they do behind the scenes.
109 116
110- :ref:`ref-tasks-configure` - Regenerates the 117- :ref:`ref-tasks-configure` --- regenerates the
111 configure script (using ``autoreconf``) and then launches it with a 118 configure script (using ``autoreconf``) and then launches it with a
112 standard set of arguments used during cross-compilation. You can pass 119 standard set of arguments used during cross-compilation. You can pass
113 additional parameters to ``configure`` through the ``EXTRA_OECONF`` 120 additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
114 or :term:`PACKAGECONFIG_CONFARGS` 121 or :term:`PACKAGECONFIG_CONFARGS`
115 variables. 122 variables.
116 123
117- :ref:`ref-tasks-compile` - Runs ``make`` with 124- :ref:`ref-tasks-compile` --- runs ``make`` with
118 arguments that specify the compiler and linker. You can pass 125 arguments that specify the compiler and linker. You can pass
119 additional arguments through the ``EXTRA_OEMAKE`` variable. 126 additional arguments through the :term:`EXTRA_OEMAKE` variable.
120 127
121- :ref:`ref-tasks-install` - Runs ``make install`` and 128- :ref:`ref-tasks-install` --- runs ``make install`` and
122 passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. 129 passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
123 130
124.. _ref-classes-base: 131.. _ref-classes-base:
125 132
126``base.bbclass`` 133``base``
127================ 134========
128 135
129The ``base`` class is special in that every ``.bb`` file implicitly 136The :ref:`ref-classes-base` class is special in that every ``.bb`` file implicitly
130inherits the class. This class contains definitions for standard basic 137inherits the class. This class contains definitions for standard basic
131tasks such as fetching, unpacking, configuring (empty by default), 138tasks such as fetching, unpacking, configuring (empty by default),
132compiling (runs any ``Makefile`` present), installing (empty by default) 139compiling (runs any ``Makefile`` present), installing (empty by default)
133and packaging (empty by default). These classes are often overridden or 140and packaging (empty by default). These tasks are often overridden or
134extended by other classes such as the 141extended by other classes such as the :ref:`ref-classes-autotools` class or the
135:ref:`autotools <ref-classes-autotools>` class or the 142:ref:`ref-classes-package` class.
136:ref:`package <ref-classes-package>` class.
137 143
138The class also contains some commonly used functions such as 144The class also contains some commonly used functions such as
139``oe_runmake``, which runs ``make`` with the arguments specified in 145``oe_runmake``, which runs ``make`` with the arguments specified in
@@ -142,18 +148,18 @@ arguments passed directly to ``oe_runmake``.
142 148
143.. _ref-classes-bash-completion: 149.. _ref-classes-bash-completion:
144 150
145``bash-completion.bbclass`` 151``bash-completion``
146=========================== 152===================
147 153
148Sets up packaging and dependencies appropriate for recipes that build 154Sets up packaging and dependencies appropriate for recipes that build
149software that includes bash-completion data. 155software that includes bash-completion data.
150 156
151.. _ref-classes-bin-package: 157.. _ref-classes-bin-package:
152 158
153``bin_package.bbclass`` 159``bin_package``
154======================= 160===============
155 161
156The ``bin_package`` class is a helper class for recipes that extract the 162The :ref:`ref-classes-bin-package` class is a helper class for recipes that extract the
157contents of a binary package (e.g. an RPM) and install those contents 163contents of a binary package (e.g. an RPM) and install those contents
158rather than building the binary from source. The binary package is 164rather than building the binary from source. The binary package is
159extracted and new packages in the configured output package format are 165extracted and new packages in the configured output package format are
@@ -168,21 +174,19 @@ example use for this class.
168 the "subpath" parameter limits the checkout to a specific subpath 174 the "subpath" parameter limits the checkout to a specific subpath
169 of the tree. Here is an example where ``${BP}`` is used so that the files 175 of the tree. Here is an example where ``${BP}`` is used so that the files
170 are extracted into the subdirectory expected by the default value of 176 are extracted into the subdirectory expected by the default value of
171 ``S``: 177 :term:`S`::
172 ::
173
174 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
175 178
179 SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
176 180
177 See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for 181 See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
178 more information on supported BitBake Fetchers. 182 more information on supported BitBake Fetchers.
179 183
180.. _ref-classes-binconfig: 184.. _ref-classes-binconfig:
181 185
182``binconfig.bbclass`` 186``binconfig``
183===================== 187=============
184 188
185The ``binconfig`` class helps to correct paths in shell scripts. 189The :ref:`ref-classes-binconfig` class helps to correct paths in shell scripts.
186 190
187Before ``pkg-config`` had become widespread, libraries shipped shell 191Before ``pkg-config`` had become widespread, libraries shipped shell
188scripts to give information about the libraries and include paths needed 192scripts to give information about the libraries and include paths needed
@@ -199,52 +203,33 @@ information.
199 203
200.. _ref-classes-binconfig-disabled: 204.. _ref-classes-binconfig-disabled:
201 205
202``binconfig-disabled.bbclass`` 206``binconfig-disabled``
203============================== 207======================
204 208
205An alternative version of the :ref:`binconfig <ref-classes-binconfig>` 209An alternative version of the :ref:`ref-classes-binconfig`
206class, which disables binary configuration scripts by making them return 210class, which disables binary configuration scripts by making them return
207an error in favor of using ``pkg-config`` to query the information. The 211an error in favor of using ``pkg-config`` to query the information. The
208scripts to be disabled should be specified using the 212scripts to be disabled should be specified using the :term:`BINCONFIG`
209:term:`BINCONFIG` variable within the recipe inheriting 213variable within the recipe inheriting the class.
210the class.
211
212.. _ref-classes-blacklist:
213
214``blacklist.bbclass``
215=====================
216
217The ``blacklist`` class prevents the OpenEmbedded build system from
218building specific recipes (blacklists them). To use this class, inherit
219the class globally and set :term:`PNBLACKLIST` for
220each recipe you wish to blacklist. Specify the :term:`PN`
221value as a variable flag (varflag) and provide a reason, which is
222reported, if the package is requested to be built as the value. For
223example, if you want to blacklist a recipe called "exoticware", you add
224the following to your ``local.conf`` or distribution configuration:
225::
226
227 INHERIT += "blacklist"
228 PNBLACKLIST[exoticware] = "Not supported by our organization."
229 214
230.. _ref-classes-buildhistory: 215.. _ref-classes-buildhistory:
231 216
232``buildhistory.bbclass`` 217``buildhistory``
233======================== 218================
234 219
235The ``buildhistory`` class records a history of build output metadata, 220The :ref:`ref-classes-buildhistory` class records a history of build output metadata,
236which can be used to detect possible regressions as well as used for 221which can be used to detect possible regressions as well as used for
237analysis of the build output. For more information on using Build 222analysis of the build output. For more information on using Build
238History, see the 223History, see the
239":ref:`dev-manual/common-tasks:maintaining build output quality`" 224":ref:`dev-manual/build-quality:maintaining build output quality`"
240section in the Yocto Project Development Tasks Manual. 225section in the Yocto Project Development Tasks Manual.
241 226
242.. _ref-classes-buildstats: 227.. _ref-classes-buildstats:
243 228
244``buildstats.bbclass`` 229``buildstats``
245====================== 230==============
246 231
247The ``buildstats`` class records performance statistics about each task 232The :ref:`ref-classes-buildstats` class records performance statistics about each task
248executed during the build (e.g. elapsed time, CPU usage, and I/O usage). 233executed during the build (e.g. elapsed time, CPU usage, and I/O usage).
249 234
250When you use this class, the output goes into the 235When you use this class, the output goes into the
@@ -258,124 +243,224 @@ Collecting build statistics is enabled by default through the
258:term:`USER_CLASSES` variable from your 243:term:`USER_CLASSES` variable from your
259``local.conf`` file. Consequently, you do not have to do anything to 244``local.conf`` file. Consequently, you do not have to do anything to
260enable the class. However, if you want to disable the class, simply 245enable the class. However, if you want to disable the class, simply
261remove "buildstats" from the ``USER_CLASSES`` list. 246remove ":ref:`ref-classes-buildstats`" from the :term:`USER_CLASSES` list.
262 247
263.. _ref-classes-buildstats-summary: 248.. _ref-classes-buildstats-summary:
264 249
265``buildstats-summary.bbclass`` 250``buildstats-summary``
266============================== 251======================
267 252
268When inherited globally, prints statistics at the end of the build on 253When inherited globally, prints statistics at the end of the build on
269sstate re-use. In order to function, this class requires the 254sstate re-use. In order to function, this class requires the
270:ref:`buildstats <ref-classes-buildstats>` class be enabled. 255:ref:`ref-classes-buildstats` class be enabled.
256
257.. _ref-classes-cargo:
258
259``cargo``
260=========
261
262The :ref:`ref-classes-cargo` class allows to compile Rust language programs
263using `Cargo <https://doc.rust-lang.org/cargo/>`__. Cargo is Rust's package
264manager, allowing to fetch package dependencies and build your program.
265
266Using this class makes it very easy to build Rust programs. All you need
267is to use the :term:`SRC_URI` variable to point to a source repository
268which can be built by Cargo, typically one that was created by the
269``cargo new`` command, containing a ``Cargo.toml`` file, a ``Cargo.lock`` file and a ``src``
270subdirectory.
271
272If you want to build and package tests of the program, inherit the
273:ref:`ref-classes-ptest-cargo` class instead of :ref:`ref-classes-cargo`.
274
275You will find an example (that show also how to handle possible git source dependencies) in the
276:oe_git:`zvariant_3.12.0.bb </openembedded-core/tree/meta-selftest/recipes-extended/zvariant/zvariant_3.12.0.bb>`
277recipe. Another example, with only crate dependencies, is the
278:oe_git:`uutils-coreutils </meta-openembedded/tree/meta-oe/recipes-core/uutils-coreutils>`
279recipe, which was generated by the `cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__
280tool.
281
282This class inherits the :ref:`ref-classes-cargo_common` class.
283
284.. _ref-classes-cargo_c:
285
286``cargo_c``
287===========
288
289The :ref:`ref-classes-cargo_c` class can be inherited by a recipe to generate
290a Rust library that can be called by C/C++ code. The recipe which inherits this
291class has to only replace ``inherit cargo`` by ``inherit cargo_c``.
292
293See the :yocto_git:`rust-c-lib-example_git.bb
294</poky/tree/meta-selftest/recipes-devtools/rust/rust-c-lib-example_git.bb>`
295example recipe.
296
297.. _ref-classes-cargo_common:
298
299``cargo_common``
300================
301
302The :ref:`ref-classes-cargo_common` class is an internal class
303that is not intended to be used directly.
304
305An exception is the "rust" recipe, to build the Rust compiler and runtime
306library, which is built by Cargo but cannot use the :ref:`ref-classes-cargo`
307class. This is why this class was introduced.
308
309.. _ref-classes-cargo-update-recipe-crates:
310
311``cargo-update-recipe-crates``
312===============================
313
314The :ref:`ref-classes-cargo-update-recipe-crates` class allows
315recipe developers to update the list of Cargo crates in :term:`SRC_URI`
316by reading the ``Cargo.lock`` file in the source tree.
317
318To do so, create a recipe for your program, for example using
319:doc:`devtool </ref-manual/devtool-reference>`,
320make it inherit the :ref:`ref-classes-cargo` and
321:ref:`ref-classes-cargo-update-recipe-crates` and run::
322
323 bitbake -c update_crates recipe
324
325This creates a ``recipe-crates.inc`` file that you can include in your
326recipe::
327
328 require ${BPN}-crates.inc
329
330That's also something you can achieve by using the
331`cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ tool.
271 332
272.. _ref-classes-ccache: 333.. _ref-classes-ccache:
273 334
274``ccache.bbclass`` 335``ccache``
275================== 336==========
276 337
277The ``ccache`` class enables the C/C++ Compiler Cache for the build. 338The :ref:`ref-classes-ccache` class enables the C/C++ Compiler Cache for the build.
278This class is used to give a minor performance boost during the build. 339This class is used to give a minor performance boost during the build.
279However, using the class can lead to unexpected side-effects. Thus, it 340
280is recommended that you do not use this class. See 341See https://ccache.samba.org/ for information on the C/C++ Compiler
281https://ccache.samba.org/ for information on the C/C++ Compiler 342Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>`
282Cache. 343file for details about how to enable this mechanism in your configuration
344file, how to disable it for specific recipes, and how to share ``ccache``
345files between builds.
346
347However, using the class can lead to unexpected side-effects. Thus, using
348this class is not recommended.
283 349
284.. _ref-classes-chrpath: 350.. _ref-classes-chrpath:
285 351
286``chrpath.bbclass`` 352``chrpath``
287=================== 353===========
288 354
289The ``chrpath`` class is a wrapper around the "chrpath" utility, which 355The :ref:`ref-classes-chrpath` class is a wrapper around the "chrpath" utility, which
290is used during the build process for ``nativesdk``, ``cross``, and 356is used during the build process for :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, and
291``cross-canadian`` recipes to change ``RPATH`` records within binaries 357:ref:`ref-classes-cross-canadian` recipes to change ``RPATH`` records within binaries
292in order to make them relocatable. 358in order to make them relocatable.
293 359
294.. _ref-classes-clutter: 360.. _ref-classes-cmake:
295 361
296``clutter.bbclass`` 362``cmake``
297=================== 363=========
298 364
299The ``clutter`` class consolidates the major and minor version naming 365The :ref:`ref-classes-cmake` class allows recipes to build software using the
300and other common items used by Clutter and related recipes. 366`CMake <https://cmake.org/overview/>`__ build system. You can use the
367:term:`EXTRA_OECMAKE` variable to specify additional configuration options to
368pass to the ``cmake`` command line.
301 369
302.. note:: 370By default, the :ref:`ref-classes-cmake` class uses
371`Ninja <https://ninja-build.org/>`__ instead of GNU make for building, which
372offers better build performance. If a recipe is broken with Ninja, then the
373recipe can set the :term:`OECMAKE_GENERATOR` variable to ``Unix Makefiles`` to
374use GNU make instead.
303 375
304 Unlike some other classes related to specific libraries, recipes 376If you need to install custom CMake toolchain files supplied by the application
305 building other software that uses Clutter do not need to inherit this 377being built, you should install them (during :ref:`ref-tasks-install`) to the
306 class unless they use the same recipe versioning scheme that the 378preferred CMake Module directory: ``${D}${datadir}/cmake/modules/``.
307 Clutter and related recipes do.
308 379
309.. _ref-classes-cmake: 380.. _ref-classes-cmake-qemu:
310 381
311``cmake.bbclass`` 382``cmake-qemu``
312================= 383==============
313 384
314The ``cmake`` class allows for recipes that need to build software using 385The :ref:`ref-classes-cmake-qemu` class might be used instead of the
315the `CMake <https://cmake.org/overview/>`__ build system. You can use 386:ref:`ref-classes-cmake` class. In addition to the features provided by the
316the :term:`EXTRA_OECMAKE` variable to specify 387:ref:`ref-classes-cmake` class, the :ref:`ref-classes-cmake-qemu` class passes
317additional configuration options to be passed using the ``cmake`` 388the ``CMAKE_CROSSCOMPILING_EMULATOR`` setting to ``cmake``. This allows to use
318command line. 389QEMU user-mode emulation for the execution of cross-compiled binaries on the
390host machine. For more information about ``CMAKE_CROSSCOMPILING_EMULATOR``
391please refer to the `related section of the CMake documentation
392<https://cmake.org/cmake/help/latest/variable/CMAKE_CROSSCOMPILING_EMULATOR.html>`__.
319 393
320On the occasion that you would be installing custom CMake toolchain 394Not all platforms are supported by QEMU. This class only works for machines with
321files supplied by the application being built, you should install them 395``qemu-usermode`` in the :ref:`ref-features-machine`. Using QEMU user-mode therefore
322to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` 396involves a certain risk, which is also the reason why this feature is not part of
323Modules during 397the main :ref:`ref-classes-cmake` class by default.
324:ref:`ref-tasks-install`. 398
399One use case is the execution of cross-compiled unit tests with CTest on the build
400machine. If ``CMAKE_CROSSCOMPILING_EMULATOR`` is configured::
401
402 cmake --build --target test
403
404works transparently with QEMU user-mode.
405
406If the CMake project is developed with this use case in mind this works very nicely.
407This also applies to an IDE configured to use ``cmake-native`` for cross-compiling.
325 408
326.. _ref-classes-cml1: 409.. _ref-classes-cml1:
327 410
328``cml1.bbclass`` 411``cml1``
329================ 412========
330 413
331The ``cml1`` class provides basic support for the Linux kernel style 414The :ref:`ref-classes-cml1` class provides basic support for the Linux kernel style
332build configuration system. 415build configuration system. "cml" stands for "Configuration Menu Language", which
416originates from the Linux kernel but is also used in other projects such as U-Boot
417and BusyBox. It could have been called "kconfig" too.
333 418
334.. _ref-classes-compress_doc: 419.. _ref-classes-compress_doc:
335 420
336``compress_doc.bbclass`` 421``compress_doc``
337======================== 422================
338 423
339Enables compression for man pages and info pages. This class is intended 424Enables compression for manual and info pages. This class is intended
340to be inherited globally. The default compression mechanism is gz (gzip) 425to be inherited globally. The default compression mechanism is gz (gzip)
341but you can select an alternative mechanism by setting the 426but you can select an alternative mechanism by setting the
342:term:`DOC_COMPRESS` variable. 427:term:`DOC_COMPRESS` variable.
343 428
344.. _ref-classes-copyleft_compliance: 429.. _ref-classes-copyleft_compliance:
345 430
346``copyleft_compliance.bbclass`` 431``copyleft_compliance``
347=============================== 432=======================
348 433
349The ``copyleft_compliance`` class preserves source code for the purposes 434The :ref:`ref-classes-copyleft_compliance` class preserves source code for the purposes
350of license compliance. This class is an alternative to the ``archiver`` 435of license compliance. This class is an alternative to the :ref:`ref-classes-archiver`
351class and is still used by some users even though it has been deprecated 436class and is still used by some users even though it has been deprecated
352in favor of the :ref:`archiver <ref-classes-archiver>` class. 437in favor of the :ref:`ref-classes-archiver` class.
353 438
354.. _ref-classes-copyleft_filter: 439.. _ref-classes-copyleft_filter:
355 440
356``copyleft_filter.bbclass`` 441``copyleft_filter``
357=========================== 442===================
358 443
359A class used by the :ref:`archiver <ref-classes-archiver>` and 444A class used by the :ref:`ref-classes-archiver` and
360:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes 445:ref:`ref-classes-copyleft_compliance` classes
361for filtering licenses. The ``copyleft_filter`` class is an internal 446for filtering licenses. The ``copyleft_filter`` class is an internal
362class and is not intended to be used directly. 447class and is not intended to be used directly.
363 448
364.. _ref-classes-core-image: 449.. _ref-classes-core-image:
365 450
366``core-image.bbclass`` 451``core-image``
367====================== 452==============
368 453
369The ``core-image`` class provides common definitions for the 454The :ref:`ref-classes-core-image` class provides common definitions for the
370``core-image-*`` image recipes, such as support for additional 455``core-image-*`` image recipes, such as support for additional
371:term:`IMAGE_FEATURES`. 456:term:`IMAGE_FEATURES`.
372 457
373.. _ref-classes-cpan: 458.. _ref-classes-cpan:
374 459
375``cpan*.bbclass`` 460``cpan*``
376================= 461=========
377 462
378The ``cpan*`` classes support Perl modules. 463The :ref:`cpan* <ref-classes-cpan>` classes support Perl modules.
379 464
380Recipes for Perl modules are simple. These recipes usually only need to 465Recipes for Perl modules are simple. These recipes usually only need to
381point to the source's archive and then inherit the proper class file. 466point to the source's archive and then inherit the proper class file.
@@ -388,23 +473,49 @@ authors used.
388- Modules that use ``Build.PL``-based build system require using 473- Modules that use ``Build.PL``-based build system require using
389 ``cpan_build.bbclass`` in their recipes. 474 ``cpan_build.bbclass`` in their recipes.
390 475
391Both build methods inherit the ``cpan-base`` class for basic Perl 476Both build methods inherit the :ref:`cpan-base <ref-classes-cpan>` class for basic Perl
392support. 477support.
393 478
479.. _ref-classes-create-spdx:
480
481``create-spdx``
482===============
483
484The :ref:`ref-classes-create-spdx` class provides support for
485automatically creating :term:`SPDX` :term:`SBOM` documents based upon image
486and SDK contents.
487
488This class is meant to be inherited globally from a configuration file::
489
490 INHERIT += "create-spdx"
491
492The toplevel :term:`SPDX` output file is generated in JSON format as a
493``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the
494:term:`Build Directory`. There are other related files in the same directory,
495as well as in ``tmp/deploy/spdx``.
496
497The exact behaviour of this class, and the amount of output can be controlled
498by the :term:`SPDX_PRETTY`, :term:`SPDX_ARCHIVE_PACKAGED`,
499:term:`SPDX_ARCHIVE_SOURCES` and :term:`SPDX_INCLUDE_SOURCES` variables.
500
501See the description of these variables and the
502":ref:`dev-manual/sbom:creating a software bill of materials`"
503section in the Yocto Project Development Manual for more details.
504
394.. _ref-classes-cross: 505.. _ref-classes-cross:
395 506
396``cross.bbclass`` 507``cross``
397================= 508=========
398 509
399The ``cross`` class provides support for the recipes that build the 510The :ref:`ref-classes-cross` class provides support for the recipes that build the
400cross-compilation tools. 511cross-compilation tools.
401 512
402.. _ref-classes-cross-canadian: 513.. _ref-classes-cross-canadian:
403 514
404``cross-canadian.bbclass`` 515``cross-canadian``
405========================== 516==================
406 517
407The ``cross-canadian`` class provides support for the recipes that build 518The :ref:`ref-classes-cross-canadian` class provides support for the recipes that build
408the Canadian Cross-compilation tools for SDKs. See the 519the Canadian Cross-compilation tools for SDKs. See the
409":ref:`overview-manual/concepts:cross-development toolchain generation`" 520":ref:`overview-manual/concepts:cross-development toolchain generation`"
410section in the Yocto Project Overview and Concepts Manual for more 521section in the Yocto Project Overview and Concepts Manual for more
@@ -412,21 +523,85 @@ discussion on these cross-compilation tools.
412 523
413.. _ref-classes-crosssdk: 524.. _ref-classes-crosssdk:
414 525
415``crosssdk.bbclass`` 526``crosssdk``
416==================== 527============
417 528
418The ``crosssdk`` class provides support for the recipes that build the 529The :ref:`ref-classes-crosssdk` class provides support for the recipes that build the
419cross-compilation tools used for building SDKs. See the 530cross-compilation tools used for building SDKs. See the
420":ref:`overview-manual/concepts:cross-development toolchain generation`" 531":ref:`overview-manual/concepts:cross-development toolchain generation`"
421section in the Yocto Project Overview and Concepts Manual for more 532section in the Yocto Project Overview and Concepts Manual for more
422discussion on these cross-compilation tools. 533discussion on these cross-compilation tools.
423 534
535.. _ref-classes-cve-check:
536
537``cve-check``
538=============
539
540The :ref:`ref-classes-cve-check` class looks for known CVEs (Common Vulnerabilities
541and Exposures) while building with BitBake. This class is meant to be
542inherited globally from a configuration file::
543
544 INHERIT += "cve-check"
545
546To filter out obsolete CVE database entries which are known not to impact software from Poky and OE-Core,
547add following line to the build configuration file::
548
549 include cve-extra-exclusions.inc
550
551You can also look for vulnerabilities in specific packages by passing
552``-c cve_check`` to BitBake.
553
554After building the software with Bitbake, CVE check output reports are available in ``tmp/deploy/cve``
555and image specific summaries in ``tmp/deploy/images/*.cve`` or ``tmp/deploy/images/*.json`` files.
556
557When building, the CVE checker will emit build time warnings for any detected
558issues which are in the state ``Unpatched``, meaning that CVE issue seems to affect the software component
559and version being compiled and no patches to address the issue are applied. Other states
560for detected CVE issues are: ``Patched`` meaning that a patch to address the issue is already
561applied, and ``Ignored`` meaning that the issue can be ignored.
562
563The ``Patched`` state of a CVE issue is detected from patch files with the format
564``CVE-ID.patch``, e.g. ``CVE-2019-20633.patch``, in the :term:`SRC_URI` and using
565CVE metadata of format ``CVE: CVE-ID`` in the commit message of the patch file.
566
567If the recipe adds ``CVE-ID`` as flag of the :term:`CVE_STATUS` variable with status
568mapped to ``Ignored``, then the CVE state is reported as ``Ignored``::
569
570 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
571
572If CVE check reports that a recipe contains false positives or false negatives, these may be
573fixed in recipes by adjusting the CVE product name using :term:`CVE_PRODUCT` and :term:`CVE_VERSION` variables.
574:term:`CVE_PRODUCT` defaults to the plain recipe name :term:`BPN` which can be adjusted to one or more CVE
575database vendor and product pairs using the syntax::
576
577 CVE_PRODUCT = "flex_project:flex"
578
579where ``flex_project`` is the CVE database vendor name and ``flex`` is the product name. Similarly
580if the default recipe version :term:`PV` does not match the version numbers of the software component
581in upstream releases or the CVE database, then the :term:`CVE_VERSION` variable can be used to set the
582CVE database compatible version number, for example::
583
584 CVE_VERSION = "2.39"
585
586Any bugs or missing or incomplete information in the CVE database entries should be fixed in the CVE database
587via the `NVD feedback form <https://nvd.nist.gov/info/contact-form>`__.
588
589Users should note that security is a process, not a product, and thus also CVE checking, analyzing results,
590patching and updating the software should be done as a regular process. The data and assumptions
591required for CVE checker to reliably detect issues are frequently broken in various ways.
592These can only be detected by reviewing the details of the issues and iterating over the generated reports,
593and following what happens in other Linux distributions and in the greater open source community.
594
595You will find some more details in the
596":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`"
597section in the Development Tasks Manual.
598
424.. _ref-classes-debian: 599.. _ref-classes-debian:
425 600
426``debian.bbclass`` 601``debian``
427================== 602==========
428 603
429The ``debian`` class renames output packages so that they follow the 604The :ref:`ref-classes-debian` class renames output packages so that they follow the
430Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and 605Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
431``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library 606``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
432name and version as part of the package name. 607name and version as part of the package name.
@@ -438,10 +613,10 @@ naming scheme.
438 613
439.. _ref-classes-deploy: 614.. _ref-classes-deploy:
440 615
441``deploy.bbclass`` 616``deploy``
442================== 617==========
443 618
444The ``deploy`` class handles deploying files to the 619The :ref:`ref-classes-deploy` class handles deploying files to the
445:term:`DEPLOY_DIR_IMAGE` directory. The main 620:term:`DEPLOY_DIR_IMAGE` directory. The main
446function of this class is to allow the deploy step to be accelerated by 621function of this class is to allow the deploy step to be accelerated by
447shared state. Recipes that inherit this class should define their own 622shared state. Recipes that inherit this class should define their own
@@ -450,113 +625,109 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
450add the task at the appropriate place, which is usually after 625add the task at the appropriate place, which is usually after
451:ref:`ref-tasks-compile` or 626:ref:`ref-tasks-compile` or
452:ref:`ref-tasks-install`. The class then takes care of 627:ref:`ref-tasks-install`. The class then takes care of
453staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. 628staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
629
630.. _ref-classes-devicetree:
631
632``devicetree``
633==============
634
635The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles
636device tree source files that are not in the kernel tree.
637
638The compilation of out-of-tree device tree sources is the same as the kernel
639in-tree device tree compilation process. This includes the ability to include
640sources from the kernel such as SoC ``dtsi`` files as well as C header files,
641such as ``gpio.h``.
642
643The :ref:`ref-tasks-compile` task will compile two kinds of files:
644
645- Regular device tree sources with a ``.dts`` extension.
646
647- Device tree overlays, detected from the presence of the ``/plugin/;``
648 string in the file contents.
649
650This class deploys the generated device tree binaries into
651``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}/devicetree/``. This is similar to
652what the :ref:`ref-classes-kernel-devicetree` class does, with the added
653``devicetree`` subdirectory to avoid name clashes. Additionally, the device
654trees are populated into the sysroot for access via the sysroot from within
655other recipes.
656
657By default, all device tree sources located in :term:`DT_FILES_PATH` directory
658are compiled. To select only particular sources, set :term:`DT_FILES` to
659a space-separated list of files (relative to :term:`DT_FILES_PATH`). For
660convenience, both ``.dts`` and ``.dtb`` extensions can be used.
661
662An extra padding is appended to non-overlay device trees binaries. This
663can typically be used as extra space for adding extra properties at boot time.
664The padding size can be modified by setting :term:`DT_PADDING_SIZE`
665to the desired size, in bytes.
666
667See :oe_git:`devicetree.bbclass sources
668</openembedded-core/tree/meta/classes-recipe/devicetree.bbclass>`
669for further variables controlling this class.
670
671Here is an excerpt of an example ``recipes-kernel/linux/devicetree-acme.bb``
672recipe inheriting this class::
673
674 inherit devicetree
675 COMPATIBLE_MACHINE = "^mymachine$"
676 SRC_URI:mymachine = "file://mymachine.dts"
454 677
455.. _ref-classes-devshell: 678.. _ref-classes-devshell:
456 679
457``devshell.bbclass`` 680``devshell``
458==================== 681============
459 682
460The ``devshell`` class adds the ``do_devshell`` task. Distribution 683The :ref:`ref-classes-devshell` class adds the :ref:`ref-tasks-devshell` task. Distribution
461policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`" 684policy dictates whether to include this class. See the ":ref:`dev-manual/development-shell:using a development shell`"
462section in the Yocto Project Development Tasks Manual for more 685section in the Yocto Project Development Tasks Manual for more
463information about using ``devshell``. 686information about using :ref:`ref-classes-devshell`.
464 687
465.. _ref-classes-devupstream: 688.. _ref-classes-devupstream:
466 689
467``devupstream.bbclass`` 690``devupstream``
468======================= 691===============
469 692
470The ``devupstream`` class uses 693The :ref:`ref-classes-devupstream` class uses
471:term:`BBCLASSEXTEND` to add a variant of the 694:term:`BBCLASSEXTEND` to add a variant of the
472recipe that fetches from an alternative URI (e.g. Git) instead of a 695recipe that fetches from an alternative URI (e.g. Git) instead of a
473tarball. Following is an example: 696tarball. Here is an example::
474::
475 697
476 BBCLASSEXTEND = "devupstream:target" 698 BBCLASSEXTEND = "devupstream:target"
477 SRC_URI_class-devupstream = "git://git.example.com/example" 699 SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
478 SRCREV_class-devupstream = "abcd1234" 700 SRCREV:class-devupstream = "abcd1234"
479 701
480Adding the above statements to your recipe creates a variant that has 702Adding the above statements to your recipe creates a variant that has
481:term:`DEFAULT_PREFERENCE` set to "-1". 703:term:`DEFAULT_PREFERENCE` set to "-1".
482Consequently, you need to select the variant of the recipe to use it. 704Consequently, you need to select the variant of the recipe to use it.
483Any development-specific adjustments can be done by using the 705Any development-specific adjustments can be done by using the
484``class-devupstream`` override. Here is an example: 706``class-devupstream`` override. Here is an example::
485::
486 707
487 DEPENDS_append_class-devupstream = " gperf-native" 708 DEPENDS:append:class-devupstream = " gperf-native"
488 do_configure_prepend_class-devupstream() { 709 do_configure:prepend:class-devupstream() {
489 touch ${S}/README 710 touch ${S}/README
490 } 711 }
491 712
492The class 713The class
493currently only supports creating a development variant of the target 714currently only supports creating a development variant of the target
494recipe, not ``native`` or ``nativesdk`` variants. 715recipe, not :ref:`ref-classes-native` or :ref:`ref-classes-nativesdk` variants.
495 716
496The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides 717The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
497support for ``native`` and ``nativesdk`` variants. Consequently, this 718support for :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk` variants. Consequently, this
498functionality can be added in a future release. 719functionality can be added in a future release.
499 720
500Support for other version control systems such as Subversion is limited 721Support for other version control systems such as Subversion is limited
501due to BitBake's automatic fetch dependencies (e.g. 722due to BitBake's automatic fetch dependencies (e.g.
502``subversion-native``). 723``subversion-native``).
503 724
504.. _ref-classes-distutils:
505
506``distutils*.bbclass``
507======================
508
509The ``distutils*`` classes support recipes for Python version 2.x
510extensions, which are simple. These recipes usually only need to point
511to the source's archive and then inherit the proper class. Building is
512split into two methods depending on which method the module authors
513used.
514
515- Extensions that use an Autotools-based build system require Autotools
516 and the classes based on ``distutils`` in their recipes.
517
518- Extensions that use build systems based on ``distutils`` require the
519 ``distutils`` class in their recipes.
520
521- Extensions that use build systems based on ``setuptools`` require the
522 :ref:`setuptools <ref-classes-setuptools>` class in their recipes.
523
524The ``distutils-common-base`` class is required by some of the
525``distutils*`` classes to provide common Python2 support.
526
527.. _ref-classes-distutils3:
528
529``distutils3*.bbclass``
530=======================
531
532The ``distutils3*`` classes support recipes for Python version 3.x
533extensions, which are simple. These recipes usually only need to point
534to the source's archive and then inherit the proper class. Building is
535split into three methods depending on which method the module authors
536used.
537
538- Extensions that use an Autotools-based build system require Autotools
539 and ``distutils``-based classes in their recipes.
540
541- Extensions that use ``distutils``-based build systems require the
542 ``distutils`` class in their recipes.
543
544- Extensions that use build systems based on ``setuptools3`` require
545 the :ref:`setuptools3 <ref-classes-setuptools>` class in their
546 recipes.
547
548The ``distutils3*`` classes either inherit their corresponding
549``distutils*`` class or replicate them using a Python3 version instead
550(e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is
551the same as ``distutils-base`` but inherits ``python3native`` instead of
552``pythonnative``).
553
554.. _ref-classes-externalsrc: 725.. _ref-classes-externalsrc:
555 726
556``externalsrc.bbclass`` 727``externalsrc``
557======================= 728===============
558 729
559The ``externalsrc`` class supports building software from source code 730The :ref:`ref-classes-externalsrc` class supports building software from source code
560that is external to the OpenEmbedded build system. Building software 731that is external to the OpenEmbedded build system. Building software
561from an external source tree means that the build system's normal fetch, 732from an external source tree means that the build system's normal fetch,
562unpack, and patch process is not used. 733unpack, and patch process is not used.
@@ -564,37 +735,34 @@ unpack, and patch process is not used.
564By default, the OpenEmbedded build system uses the :term:`S` 735By default, the OpenEmbedded build system uses the :term:`S`
565and :term:`B` variables to locate unpacked recipe source code 736and :term:`B` variables to locate unpacked recipe source code
566and to build it, respectively. When your recipe inherits the 737and to build it, respectively. When your recipe inherits the
567``externalsrc`` class, you use the 738:ref:`ref-classes-externalsrc` class, you use the
568:term:`EXTERNALSRC` and 739:term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` variables to
569:term:`EXTERNALSRC_BUILD` variables to 740ultimately define :term:`S` and :term:`B`.
570ultimately define ``S`` and ``B``.
571 741
572By default, this class expects the source code to support recipe builds 742By default, this class expects the source code to support recipe builds
573that use the :term:`B` variable to point to the directory in 743that use the :term:`B` variable to point to the directory in
574which the OpenEmbedded build system places the generated objects built 744which the OpenEmbedded build system places the generated objects built
575from the recipes. By default, the ``B`` directory is set to the 745from the recipes. By default, the :term:`B` directory is set to the
576following, which is separate from the source directory (``S``): 746following, which is separate from the source directory (:term:`S`)::
577::
578 747
579 ${WORKDIR}/${BPN}/{PV}/ 748 ${WORKDIR}/${BPN}-{PV}/
580 749
581See these variables for more information: 750See these variables for more information:
582:term:`WORKDIR`, :term:`BPN`, and 751:term:`WORKDIR`, :term:`BPN`, and
583:term:`PV`, 752:term:`PV`,
584 753
585For more information on the ``externalsrc`` class, see the comments in 754For more information on the :ref:`ref-classes-externalsrc` class, see the comments in
586``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. 755``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
587For information on how to use the 756For information on how to use the :ref:`ref-classes-externalsrc` class, see the
588``externalsrc`` class, see the 757":ref:`dev-manual/building:building software from an external source`"
589":ref:`dev-manual/common-tasks:building software from an external source`"
590section in the Yocto Project Development Tasks Manual. 758section in the Yocto Project Development Tasks Manual.
591 759
592.. _ref-classes-extrausers: 760.. _ref-classes-extrausers:
593 761
594``extrausers.bbclass`` 762``extrausers``
595====================== 763==============
596 764
597The ``extrausers`` class allows additional user and group configuration 765The :ref:`ref-classes-extrausers` class allows additional user and group configuration
598to be applied at the image level. Inheriting this class either globally 766to be applied at the image level. Inheriting this class either globally
599or from an image recipe allows additional user and group operations to 767or from an image recipe allows additional user and group operations to
600be performed using the 768be performed using the
@@ -602,16 +770,13 @@ be performed using the
602 770
603.. note:: 771.. note::
604 772
605 The user and group operations added using the 773 The user and group operations added using the :ref:`ref-classes-extrausers`
606 extrausers
607 class are not tied to a specific recipe outside of the recipe for the 774 class are not tied to a specific recipe outside of the recipe for the
608 image. Thus, the operations can be performed across the image as a 775 image. Thus, the operations can be performed across the image as a
609 whole. Use the 776 whole. Use the :ref:`ref-classes-useradd` class to add user and group
610 useradd 777 configuration to a specific recipe.
611 class to add user and group configuration to a specific recipe.
612 778
613Here is an example that uses this class in an image recipe: 779Here is an example that uses this class in an image recipe::
614::
615 780
616 inherit extrausers 781 inherit extrausers
617 EXTRA_USERS_PARAMS = "\ 782 EXTRA_USERS_PARAMS = "\
@@ -624,31 +789,42 @@ Here is an example that uses this class in an image recipe:
624 " 789 "
625 790
626Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns 791Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
627passwords: 792passwords. First on host, create the (escaped) password hash::
628:: 793
794 printf "%q" $(mkpasswd -m sha256crypt tester01)
795
796The resulting hash is set to a variable and used in ``useradd`` command parameters::
629 797
630 inherit extrausers 798 inherit extrausers
799 PASSWD = "\$X\$ABC123\$A-Long-Hash"
631 EXTRA_USERS_PARAMS = "\ 800 EXTRA_USERS_PARAMS = "\
632 useradd -P tester01 tester-jim; \ 801 useradd -p '${PASSWD}' tester-jim; \
633 useradd -P tester01 tester-sue; \ 802 useradd -p '${PASSWD}' tester-sue; \
634 " 803 "
635 804
636Finally, here is an example that sets the root password to "1876*18": 805Finally, here is an example that sets the root password::
637::
638 806
639 inherit extrausers 807 inherit extrausers
640 EXTRA_USERS_PARAMS = "\ 808 EXTRA_USERS_PARAMS = "\
641 usermod -P 1876*18 root; \ 809 usermod -p '${PASSWD}' root; \
642 " 810 "
643 811
812.. note::
813
814 From a security perspective, hardcoding a default password is not
815 generally a good idea or even legal in some jurisdictions. It is
816 recommended that you do not do this if you are building a production
817 image.
818
819
644.. _ref-classes-features_check: 820.. _ref-classes-features_check:
645 821
646``features_check.bbclass`` 822``features_check``
647================================= 823==================
648 824
649The ``features_check`` class allows individual recipes to check 825The :ref:`ref-classes-features_check` class allows individual recipes to check
650for required and conflicting 826for required and conflicting :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES`
651:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`. 827or :term:`COMBINED_FEATURES`.
652 828
653This class provides support for the following variables: 829This class provides support for the following variables:
654 830
@@ -669,10 +845,10 @@ triggered.
669 845
670.. _ref-classes-fontcache: 846.. _ref-classes-fontcache:
671 847
672``fontcache.bbclass`` 848``fontcache``
673===================== 849=============
674 850
675The ``fontcache`` class generates the proper post-install and 851The :ref:`ref-classes-fontcache` class generates the proper post-install and
676post-remove (postinst and postrm) scriptlets for font packages. These 852post-remove (postinst and postrm) scriptlets for font packages. These
677scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts 853scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
678to the font information cache. Since the cache files are 854to the font information cache. Since the cache files are
@@ -685,20 +861,20 @@ packages containing the fonts.
685 861
686.. _ref-classes-fs-uuid: 862.. _ref-classes-fs-uuid:
687 863
688``fs-uuid.bbclass`` 864``fs-uuid``
689=================== 865===========
690 866
691The ``fs-uuid`` class extracts UUID from 867The :ref:`ref-classes-fs-uuid` class extracts UUID from
692``${``\ :term:`ROOTFS`\ ``}``, which must have been built 868``${``\ :term:`ROOTFS`\ ``}``, which must have been built
693by the time that this function gets called. The ``fs-uuid`` class only 869by the time that this function gets called. The :ref:`ref-classes-fs-uuid` class only
694works on ``ext`` file systems and depends on ``tune2fs``. 870works on ``ext`` file systems and depends on ``tune2fs``.
695 871
696.. _ref-classes-gconf: 872.. _ref-classes-gconf:
697 873
698``gconf.bbclass`` 874``gconf``
699================= 875=========
700 876
701The ``gconf`` class provides common functionality for recipes that need 877The :ref:`ref-classes-gconf` class provides common functionality for recipes that need
702to install GConf schemas. The schemas will be put into a separate 878to install GConf schemas. The schemas will be put into a separate
703package (``${``\ :term:`PN`\ ``}-gconf``) that is created 879package (``${``\ :term:`PN`\ ``}-gconf``) that is created
704automatically when this class is inherited. This package uses the 880automatically when this class is inherited. This package uses the
@@ -707,29 +883,66 @@ register and unregister the schemas in the target image.
707 883
708.. _ref-classes-gettext: 884.. _ref-classes-gettext:
709 885
710``gettext.bbclass`` 886``gettext``
711=================== 887===========
712 888
713The ``gettext`` class provides support for building software that uses 889The :ref:`ref-classes-gettext` class provides support for building
714the GNU ``gettext`` internationalization and localization system. All 890software that uses the GNU ``gettext`` internationalization and localization
715recipes building software that use ``gettext`` should inherit this 891system. All recipes building software that use ``gettext`` should inherit this
716class. 892class.
717 893
894.. _ref-classes-github-releases:
895
896``github-releases``
897===================
898
899For recipes that fetch release tarballs from github, the :ref:`ref-classes-github-releases`
900class sets up a standard way for checking available upstream versions
901(to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)).
902
903To use it, add ":ref:`ref-classes-github-releases`" to the inherit line in the recipe,
904and if the default value of :term:`GITHUB_BASE_URI` is not suitable,
905then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}``
906in the value you set for :term:`SRC_URI` within the recipe.
907
718.. _ref-classes-gnomebase: 908.. _ref-classes-gnomebase:
719 909
720``gnomebase.bbclass`` 910``gnomebase``
721===================== 911=============
722 912
723The ``gnomebase`` class is the base class for recipes that build 913The :ref:`ref-classes-gnomebase` class is the base class for recipes that build
724software from the GNOME stack. This class sets 914software from the GNOME stack. This class sets
725:term:`SRC_URI` to download the source from the GNOME 915:term:`SRC_URI` to download the source from the GNOME
726mirrors as well as extending :term:`FILES` with the typical 916mirrors as well as extending :term:`FILES` with the typical
727GNOME installation paths. 917GNOME installation paths.
728 918
919.. _ref-classes-go:
920
921``go``
922======
923
924The :ref:`ref-classes-go` class supports building Go programs. The behavior of
925this class is controlled by the mandatory :term:`GO_IMPORT` variable, and
926by the optional :term:`GO_INSTALL` and :term:`GO_INSTALL_FILTEROUT` ones.
927
928To build a Go program with the Yocto Project, you can use the
929:yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
930recipe as an example.
931
932.. _ref-classes-go-mod:
933
934``go-mod``
935==========
936
937The :ref:`ref-classes-go-mod` class allows to use Go modules, and inherits the
938:ref:`ref-classes-go` class.
939
940See the associated :term:`GO_WORKDIR` variable.
941
729.. _ref-classes-gobject-introspection: 942.. _ref-classes-gobject-introspection:
730 943
731``gobject-introspection.bbclass`` 944``gobject-introspection``
732================================= 945=========================
733 946
734Provides support for recipes building software that supports GObject 947Provides support for recipes building software that supports GObject
735introspection. This functionality is only enabled if the 948introspection. This functionality is only enabled if the
@@ -740,16 +953,17 @@ introspection. This functionality is only enabled if the
740 953
741.. note:: 954.. note::
742 955
743 This functionality is backfilled by default and, if not applicable, 956 This functionality is :ref:`backfilled <ref-features-backfill>` by default
744 should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or 957 and, if not applicable, should be disabled through
745 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively. 958 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
959 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
746 960
747.. _ref-classes-grub-efi: 961.. _ref-classes-grub-efi:
748 962
749``grub-efi.bbclass`` 963``grub-efi``
750==================== 964============
751 965
752The ``grub-efi`` class provides ``grub-efi``-specific functions for 966The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for
753building bootable images. 967building bootable images.
754 968
755This class supports several variables: 969This class supports several variables:
@@ -778,10 +992,10 @@ This class supports several variables:
778 992
779.. _ref-classes-gsettings: 993.. _ref-classes-gsettings:
780 994
781``gsettings.bbclass`` 995``gsettings``
782===================== 996=============
783 997
784The ``gsettings`` class provides common functionality for recipes that 998The :ref:`ref-classes-gsettings` class provides common functionality for recipes that
785need to install GSettings (glib) schemas. The schemas are assumed to be 999need to install GSettings (glib) schemas. The schemas are assumed to be
786part of the main package. Appropriate post-install and post-remove 1000part of the main package. Appropriate post-install and post-remove
787(postinst/postrm) scriptlets are added to register and unregister the 1001(postinst/postrm) scriptlets are added to register and unregister the
@@ -789,18 +1003,18 @@ schemas in the target image.
789 1003
790.. _ref-classes-gtk-doc: 1004.. _ref-classes-gtk-doc:
791 1005
792``gtk-doc.bbclass`` 1006``gtk-doc``
793=================== 1007===========
794 1008
795The ``gtk-doc`` class is a helper class to pull in the appropriate 1009The :ref:`ref-classes-gtk-doc` class is a helper class to pull in the appropriate
796``gtk-doc`` dependencies and disable ``gtk-doc``. 1010``gtk-doc`` dependencies and disable ``gtk-doc``.
797 1011
798.. _ref-classes-gtk-icon-cache: 1012.. _ref-classes-gtk-icon-cache:
799 1013
800``gtk-icon-cache.bbclass`` 1014``gtk-icon-cache``
801========================== 1015==================
802 1016
803The ``gtk-icon-cache`` class generates the proper post-install and 1017The :ref:`ref-classes-gtk-icon-cache` class generates the proper post-install and
804post-remove (postinst/postrm) scriptlets for packages that use GTK+ and 1018post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
805install icons. These scriptlets call ``gtk-update-icon-cache`` to add 1019install icons. These scriptlets call ``gtk-update-icon-cache`` to add
806the fonts to GTK+'s icon cache. Since the cache files are 1020the fonts to GTK+'s icon cache. Since the cache files are
@@ -810,10 +1024,10 @@ creation.
810 1024
811.. _ref-classes-gtk-immodules-cache: 1025.. _ref-classes-gtk-immodules-cache:
812 1026
813``gtk-immodules-cache.bbclass`` 1027``gtk-immodules-cache``
814=============================== 1028=======================
815 1029
816The ``gtk-immodules-cache`` class generates the proper post-install and 1030The :ref:`ref-classes-gtk-immodules-cache` class generates the proper post-install and
817post-remove (postinst/postrm) scriptlets for packages that install GTK+ 1031post-remove (postinst/postrm) scriptlets for packages that install GTK+
818input method modules for virtual keyboards. These scriptlets call 1032input method modules for virtual keyboards. These scriptlets call
819``gtk-update-icon-cache`` to add the input method modules to the cache. 1033``gtk-update-icon-cache`` to add the input method modules to the cache.
@@ -828,19 +1042,19 @@ the packages containing the modules.
828 1042
829.. _ref-classes-gzipnative: 1043.. _ref-classes-gzipnative:
830 1044
831``gzipnative.bbclass`` 1045``gzipnative``
832====================== 1046==============
833 1047
834The ``gzipnative`` class enables the use of different native versions of 1048The :ref:`ref-classes-gzipnative` class enables the use of different native versions of
835``gzip`` and ``pigz`` rather than the versions of these tools from the 1049``gzip`` and ``pigz`` rather than the versions of these tools from the
836build host. 1050build host.
837 1051
838.. _ref-classes-icecc: 1052.. _ref-classes-icecc:
839 1053
840``icecc.bbclass`` 1054``icecc``
841================= 1055=========
842 1056
843The ``icecc`` class supports 1057The :ref:`ref-classes-icecc` class supports
844`Icecream <https://github.com/icecc/icecream>`__, which facilitates 1058`Icecream <https://github.com/icecc/icecream>`__, which facilitates
845taking compile jobs and distributing them among remote machines. 1059taking compile jobs and distributing them among remote machines.
846 1060
@@ -848,7 +1062,7 @@ The class stages directories with symlinks from ``gcc`` and ``g++`` to
848``icecc``, for both native and cross compilers. Depending on each 1062``icecc``, for both native and cross compilers. Depending on each
849configure or compile, the OpenEmbedded build system adds the directories 1063configure or compile, the OpenEmbedded build system adds the directories
850at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and 1064at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
851``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` 1065``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
852compilers, respectively. 1066compilers, respectively.
853 1067
854For the cross compiler, the class creates a ``tar.gz`` file that 1068For the cross compiler, the class creates a ``tar.gz`` file that
@@ -856,8 +1070,8 @@ contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
856is the version of the cross-compiler used in the cross-development 1070is the version of the cross-compiler used in the cross-development
857toolchain, accordingly. 1071toolchain, accordingly.
858 1072
859The class handles all three different compile stages (i.e native 1073The class handles all three different compile stages (i.e native,
860,cross-kernel and target) and creates the necessary environment 1074cross-kernel and target) and creates the necessary environment
861``tar.gz`` file to be used by the remote machines. The class also 1075``tar.gz`` file to be used by the remote machines. The class also
862supports SDK generation. 1076supports SDK generation.
863 1077
@@ -867,67 +1081,66 @@ using ``which``. If :term:`ICECC_ENV_EXEC` is set
867in your ``local.conf`` file, the variable should point to the 1081in your ``local.conf`` file, the variable should point to the
868``icecc-create-env`` script provided by the user. If you do not point to 1082``icecc-create-env`` script provided by the user. If you do not point to
869a user-provided script, the build system uses the default script 1083a user-provided script, the build system uses the default script
870provided by the recipe ``icecc-create-env-native.bb``. 1084provided by the recipe :oe_git:`icecc-create-env_0.1.bb
1085</openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`.
871 1086
872.. note:: 1087.. note::
873 1088
874 This script is a modified version and not the one that comes with 1089 This script is a modified version and not the one that comes with
875 icecc. 1090 ``icecream``.
876 1091
877If you do not want the Icecream distributed compile support to apply to 1092If you do not want the Icecream distributed compile support to apply to
878specific recipes or classes, you can effectively "blacklist" them by 1093specific recipes or classes, you can ask them to be ignored by Icecream
879listing the recipes and classes using the 1094by listing the recipes and classes using the
880:term:`ICECC_USER_PACKAGE_BL` and 1095:term:`ICECC_RECIPE_DISABLE` and
881:term:`ICECC_USER_CLASS_BL`, variables, 1096:term:`ICECC_CLASS_DISABLE` variables,
882respectively, in your ``local.conf`` file. Doing so causes the 1097respectively, in your ``local.conf`` file. Doing so causes the
883OpenEmbedded build system to handle these compilations locally. 1098OpenEmbedded build system to handle these compilations locally.
884 1099
885Additionally, you can list recipes using the 1100Additionally, you can list recipes using the
886:term:`ICECC_USER_PACKAGE_WL` variable in 1101:term:`ICECC_RECIPE_ENABLE` variable in
887your ``local.conf`` file to force ``icecc`` to be enabled for recipes 1102your ``local.conf`` file to force ``icecc`` to be enabled for recipes
888using an empty :term:`PARALLEL_MAKE` variable. 1103using an empty :term:`PARALLEL_MAKE` variable.
889 1104
890Inheriting the ``icecc`` class changes all sstate signatures. 1105Inheriting the :ref:`ref-classes-icecc` class changes all sstate signatures.
891Consequently, if a development team has a dedicated build system that 1106Consequently, if a development team has a dedicated build system that
892populates :term:`SSTATE_MIRRORS` and they want to 1107populates :term:`SSTATE_MIRRORS` and they want to
893reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build 1108reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
894system need to either inherit the ``icecc`` class or nobody should. 1109system need to either inherit the :ref:`ref-classes-icecc` class or nobody should.
895 1110
896At the distribution level, you can inherit the ``icecc`` class to be 1111At the distribution level, you can inherit the :ref:`ref-classes-icecc` class to be
897sure that all builders start with the same sstate signatures. After 1112sure that all builders start with the same sstate signatures. After
898inheriting the class, you can then disable the feature by setting the 1113inheriting the class, you can then disable the feature by setting the
899:term:`ICECC_DISABLED` variable to "1" as follows: 1114:term:`ICECC_DISABLED` variable to "1" as follows::
900::
901 1115
902 INHERIT_DISTRO_append = " icecc" 1116 INHERIT_DISTRO:append = " icecc"
903 ICECC_DISABLED ??= "1" 1117 ICECC_DISABLED ??= "1"
904 1118
905This practice 1119This practice
906makes sure everyone is using the same signatures but also requires 1120makes sure everyone is using the same signatures but also requires
907individuals that do want to use Icecream to enable the feature 1121individuals that do want to use Icecream to enable the feature
908individually as follows in your ``local.conf`` file: 1122individually as follows in your ``local.conf`` file::
909::
910 1123
911 ICECC_DISABLED = "" 1124 ICECC_DISABLED = ""
912 1125
913.. _ref-classes-image: 1126.. _ref-classes-image:
914 1127
915``image.bbclass`` 1128``image``
916================= 1129=========
917 1130
918The ``image`` class helps support creating images in different formats. 1131The :ref:`ref-classes-image` class helps support creating images in different formats.
919First, the root filesystem is created from packages using one of the 1132First, the root filesystem is created from packages using one of the
920``rootfs*.bbclass`` files (depending on the package format used) and 1133``rootfs*.bbclass`` files (depending on the package format used) and
921then one or more image files are created. 1134then one or more image files are created.
922 1135
923- The ``IMAGE_FSTYPES`` variable controls the types of images to 1136- The :term:`IMAGE_FSTYPES` variable controls the types of images to
924 generate. 1137 generate.
925 1138
926- The ``IMAGE_INSTALL`` variable controls the list of packages to 1139- The :term:`IMAGE_INSTALL` variable controls the list of packages to
927 install into the image. 1140 install into the image.
928 1141
929For information on customizing images, see the 1142For information on customizing images, see the
930":ref:`dev-manual/common-tasks:customizing images`" section 1143":ref:`dev-manual/customizing-images:customizing images`" section
931in the Yocto Project Development Tasks Manual. For information on how 1144in the Yocto Project Development Tasks Manual. For information on how
932images are created, see the 1145images are created, see the
933":ref:`overview-manual/concepts:images`" section in the 1146":ref:`overview-manual/concepts:images`" section in the
@@ -935,49 +1148,66 @@ Yocto Project Overview and Concepts Manual.
935 1148
936.. _ref-classes-image-buildinfo: 1149.. _ref-classes-image-buildinfo:
937 1150
938``image-buildinfo.bbclass`` 1151``image-buildinfo``
939=========================== 1152===================
1153
1154The :ref:`ref-classes-image-buildinfo` class writes a plain text file containing
1155build information to the target filesystem at ``${sysconfdir}/buildinfo``
1156by default (as specified by :term:`IMAGE_BUILDINFO_FILE`).
1157This can be useful for manually determining the origin of any given
1158image. It writes out two sections:
1159
1160#. `Build Configuration`: a list of variables and their values (specified
1161 by :term:`IMAGE_BUILDINFO_VARS`, which defaults to :term:`DISTRO` and
1162 :term:`DISTRO_VERSION`)
940 1163
941The ``image-buildinfo`` class writes information to the target 1164#. `Layer Revisions`: the revisions of all of the layers used in the
942filesystem on ``/etc/build``. 1165 build.
1166
1167Additionally, when building an SDK it will write the same contents
1168to ``/buildinfo`` by default (as specified by
1169:term:`SDK_BUILDINFO_FILE`).
943 1170
944.. _ref-classes-image_types: 1171.. _ref-classes-image_types:
945 1172
946``image_types.bbclass`` 1173``image_types``
947======================= 1174===============
948 1175
949The ``image_types`` class defines all of the standard image output types 1176The :ref:`ref-classes-image_types` class defines all of the standard image output types
950that you can enable through the 1177that you can enable through the
951:term:`IMAGE_FSTYPES` variable. You can use this 1178:term:`IMAGE_FSTYPES` variable. You can use this
952class as a reference on how to add support for custom image output 1179class as a reference on how to add support for custom image output
953types. 1180types.
954 1181
955By default, the :ref:`image <ref-classes-image>` class automatically 1182By default, the :ref:`ref-classes-image` class automatically
956enables the ``image_types`` class. The ``image`` class uses the 1183enables the :ref:`ref-classes-image_types` class. The :ref:`ref-classes-image` class uses the
957``IMGCLASSES`` variable as follows: 1184``IMGCLASSES`` variable as follows::
958::
959 1185
960 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" 1186 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
961 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" 1187 # Only Linux SDKs support populate_sdk_ext, fall back to populate_sdk_base
1188 # in the non-Linux SDK_OS case, such as mingw32
1189 inherit populate_sdk_base
1190 IMGCLASSES += "${@['', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
962 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" 1191 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
963 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" 1192 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
964 IMGCLASSES += "image_types_wic" 1193 IMGCLASSES += "image_types_wic"
965 IMGCLASSES += "rootfs-postcommands" 1194 IMGCLASSES += "rootfs-postcommands"
966 IMGCLASSES += "image-postinst-intercepts" 1195 IMGCLASSES += "image-postinst-intercepts"
967 inherit ${IMGCLASSES} 1196 IMGCLASSES += "overlayfs-etc"
1197 inherit_defer ${IMGCLASSES}
968 1198
969The ``image_types`` class also handles conversion and compression of images. 1199The :ref:`ref-classes-image_types` class also handles conversion and compression of images.
970 1200
971.. note:: 1201.. note::
972 1202
973 To build a VMware VMDK image, you need to add "wic.vmdk" to 1203 To build a VMware VMDK image, you need to add "wic.vmdk" to
974 ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk 1204 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
975 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. 1205 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
976 1206
977.. _ref-classes-image-live: 1207.. _ref-classes-image-live:
978 1208
979``image-live.bbclass`` 1209``image-live``
980====================== 1210==============
981 1211
982This class controls building "live" (i.e. HDDIMG and ISO) images. Live 1212This class controls building "live" (i.e. HDDIMG and ISO) images. Live
983images contain syslinux for legacy booting, as well as the bootloader 1213images contain syslinux for legacy booting, as well as the bootloader
@@ -987,43 +1217,12 @@ specified by :term:`EFI_PROVIDER` if
987Normally, you do not use this class directly. Instead, you add "live" to 1217Normally, you do not use this class directly. Instead, you add "live" to
988:term:`IMAGE_FSTYPES`. 1218:term:`IMAGE_FSTYPES`.
989 1219
990.. _ref-classes-image-mklibs:
991
992``image-mklibs.bbclass``
993========================
994
995The ``image-mklibs`` class enables the use of the ``mklibs`` utility
996during the :ref:`ref-tasks-rootfs` task, which optimizes
997the size of libraries contained in the image.
998
999By default, the class is enabled in the ``local.conf.template`` using
1000the :term:`USER_CLASSES` variable as follows:
1001::
1002
1003 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1004
1005.. _ref-classes-image-prelink:
1006
1007``image-prelink.bbclass``
1008=========================
1009
1010The ``image-prelink`` class enables the use of the ``prelink`` utility
1011during the :ref:`ref-tasks-rootfs` task, which optimizes
1012the dynamic linking of shared libraries to reduce executable startup
1013time.
1014
1015By default, the class is enabled in the ``local.conf.template`` using
1016the :term:`USER_CLASSES` variable as follows:
1017::
1018
1019 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1020
1021.. _ref-classes-insane: 1220.. _ref-classes-insane:
1022 1221
1023``insane.bbclass`` 1222``insane``
1024================== 1223==========
1025 1224
1026The ``insane`` class adds a step to the package generation process so 1225The :ref:`ref-classes-insane` class adds a step to the package generation process so
1027that output quality assurance checks are generated by the OpenEmbedded 1226that output quality assurance checks are generated by the OpenEmbedded
1028build system. A range of checks are performed that check the build's 1227build system. A range of checks are performed that check the build's
1029output for common problems that show up during runtime. Distribution 1228output for common problems that show up during runtime. Distribution
@@ -1043,17 +1242,16 @@ configuration). However, to skip one or more checks in recipes, you
1043should use :term:`INSANE_SKIP`. For example, to skip 1242should use :term:`INSANE_SKIP`. For example, to skip
1044the check for symbolic link ``.so`` files in the main package of a 1243the check for symbolic link ``.so`` files in the main package of a
1045recipe, add the following to the recipe. You need to realize that the 1244recipe, add the following to the recipe. You need to realize that the
1046package name override, in this example ``${PN}``, must be used: 1245package name override, in this example ``${PN}``, must be used::
1047::
1048 1246
1049 INSANE_SKIP_${PN} += "dev-so" 1247 INSANE_SKIP:${PN} += "dev-so"
1050 1248
1051Please keep in mind that the QA checks 1249Please keep in mind that the QA checks
1052exist in order to detect real or potential problems in the packaged 1250are meant to detect real or potential problems in the packaged
1053output. So exercise caution when disabling these checks. 1251output. So exercise caution when disabling these checks.
1054 1252
1055The following list shows the tests you can list with the ``WARN_QA`` and 1253The tests you can list with the :term:`WARN_QA` and
1056``ERROR_QA`` variables: 1254:term:`ERROR_QA` variables are:
1057 1255
1058- ``already-stripped:`` Checks that produced binaries have not 1256- ``already-stripped:`` Checks that produced binaries have not
1059 already been stripped prior to the build system extracting debug 1257 already been stripped prior to the build system extracting debug
@@ -1070,8 +1268,8 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1070 software, like bootloaders, might need to bypass this check. 1268 software, like bootloaders, might need to bypass this check.
1071 1269
1072- ``buildpaths:`` Checks for paths to locations on the build host 1270- ``buildpaths:`` Checks for paths to locations on the build host
1073 inside the output files. Currently, this test triggers too many false 1271 inside the output files. Not only can these leak information about
1074 positives and thus is not normally enabled. 1272 the build environment, they also hinder binary reproducibility.
1075 1273
1076- ``build-deps:`` Determines if a build-time dependency that is 1274- ``build-deps:`` Determines if a build-time dependency that is
1077 specified through :term:`DEPENDS`, explicit 1275 specified through :term:`DEPENDS`, explicit
@@ -1084,20 +1282,30 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1084 the package is installed into the image during the 1282 the package is installed into the image during the
1085 :ref:`ref-tasks-rootfs` task because the auto-detected 1283 :ref:`ref-tasks-rootfs` task because the auto-detected
1086 dependency was not satisfied. An example of this would be where the 1284 dependency was not satisfied. An example of this would be where the
1087 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically 1285 :ref:`ref-classes-update-rc.d` class automatically
1088 adds a dependency on the ``initscripts-functions`` package to 1286 adds a dependency on the ``initscripts-functions`` package to
1089 packages that install an initscript that refers to 1287 packages that install an initscript that refers to
1090 ``/etc/init.d/functions``. The recipe should really have an explicit 1288 ``/etc/init.d/functions``. The recipe should really have an explicit
1091 ``RDEPENDS`` for the package in question on ``initscripts-functions`` 1289 :term:`RDEPENDS` for the package in question on ``initscripts-functions``
1092 so that the OpenEmbedded build system is able to ensure that the 1290 so that the OpenEmbedded build system is able to ensure that the
1093 ``initscripts`` recipe is actually built and thus the 1291 ``initscripts`` recipe is actually built and thus the
1094 ``initscripts-functions`` package is made available. 1292 ``initscripts-functions`` package is made available.
1095 1293
1294- ``configure-gettext:`` Checks that if a recipe is building something
1295 that uses automake and the automake files contain an ``AM_GNU_GETTEXT``
1296 directive, that the recipe also inherits the :ref:`ref-classes-gettext`
1297 class to ensure that gettext is available during the build.
1298
1096- ``compile-host-path:`` Checks the 1299- ``compile-host-path:`` Checks the
1097 :ref:`ref-tasks-compile` log for indications that 1300 :ref:`ref-tasks-compile` log for indications that
1098 paths to locations on the build host were used. Using such paths 1301 paths to locations on the build host were used. Using such paths
1099 might result in host contamination of the build output. 1302 might result in host contamination of the build output.
1100 1303
1304- ``cve_status_not_in_db:`` Checks for each component if CVEs that are ignored
1305 via :term:`CVE_STATUS`, that those are (still) reported for this component
1306 in the NIST database. If not, a warning is printed. This check is disabled
1307 by default.
1308
1101- ``debug-deps:`` Checks that all packages except ``-dbg`` packages 1309- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1102 do not depend on ``-dbg`` packages, which would cause a packaging 1310 do not depend on ``-dbg`` packages, which would cause a packaging
1103 bug. 1311 bug.
@@ -1128,10 +1336,15 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1128- ``dev-so:`` Checks that the ``.so`` symbolic links are in the 1336- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1129 ``-dev`` package and not in any of the other packages. In general, 1337 ``-dev`` package and not in any of the other packages. In general,
1130 these symlinks are only useful for development purposes. Thus, the 1338 these symlinks are only useful for development purposes. Thus, the
1131 ``-dev`` package is the correct location for them. Some very rare 1339 ``-dev`` package is the correct location for them. In very rare
1132 cases do exist for dynamically loaded modules where these symlinks 1340 cases, such as dynamically loaded modules, these symlinks
1133 are needed instead in the main package. 1341 are needed instead in the main package.
1134 1342
1343- ``empty-dirs:`` Checks that packages are not installing files to
1344 directories that are normally expected to be empty (such as ``/tmp``)
1345 The list of directories that are checked is specified by the
1346 :term:`QA_EMPTY_DIRS` variable.
1347
1135- ``file-rdeps:`` Checks that file-level dependencies identified by 1348- ``file-rdeps:`` Checks that file-level dependencies identified by
1136 the OpenEmbedded build system at packaging time are satisfied. For 1349 the OpenEmbedded build system at packaging time are satisfied. For
1137 example, a shell script might start with the line ``#!/bin/bash``. 1350 example, a shell script might start with the line ``#!/bin/bash``.
@@ -1166,12 +1379,12 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1166 might result in host contamination of the build output. 1379 might result in host contamination of the build output.
1167 1380
1168- ``installed-vs-shipped:`` Reports when files have been installed 1381- ``installed-vs-shipped:`` Reports when files have been installed
1169 within ``do_install`` but have not been included in any package by 1382 within :ref:`ref-tasks-install` but have not been included in any package by
1170 way of the :term:`FILES` variable. Files that do not 1383 way of the :term:`FILES` variable. Files that do not
1171 appear in any package cannot be present in an image later on in the 1384 appear in any package cannot be present in an image later on in the
1172 build process. Ideally, all installed files should be packaged or not 1385 build process. Ideally, all installed files should be packaged or not
1173 installed at all. These files can be deleted at the end of 1386 installed at all. These files can be deleted at the end of
1174 ``do_install`` if the files are not needed in any package. 1387 :ref:`ref-tasks-install` if the files are not needed in any package.
1175 1388
1176- ``invalid-chars:`` Checks that the recipe metadata variables 1389- ``invalid-chars:`` Checks that the recipe metadata variables
1177 :term:`DESCRIPTION`, 1390 :term:`DESCRIPTION`,
@@ -1181,18 +1394,17 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1181 1394
1182- ``invalid-packageconfig:`` Checks that no undefined features are 1395- ``invalid-packageconfig:`` Checks that no undefined features are
1183 being added to :term:`PACKAGECONFIG`. For 1396 being added to :term:`PACKAGECONFIG`. For
1184 example, any name "foo" for which the following form does not exist: 1397 example, any name "foo" for which the following form does not exist::
1185 ::
1186 1398
1187 PACKAGECONFIG[foo] = "..." 1399 PACKAGECONFIG[foo] = "..."
1188 1400
1189- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` 1401- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
1190 file containing these paths is incorrect since ``libtool`` adds the 1402 file containing these paths is incorrect since ``libtool`` adds the
1191 correct sysroot prefix when using the files automatically itself. 1403 correct sysroot prefix when using the files automatically itself.
1192 1404
1193- ``ldflags:`` Ensures that the binaries were linked with the 1405- ``ldflags:`` Ensures that the binaries were linked with the
1194 :term:`LDFLAGS` options provided by the build system. 1406 :term:`LDFLAGS` options provided by the build system.
1195 If this test fails, check that the ``LDFLAGS`` variable is being 1407 If this test fails, check that the :term:`LDFLAGS` variable is being
1196 passed to the linker command. 1408 passed to the linker command.
1197 1409
1198- ``libdir:`` Checks for libraries being installed into incorrect 1410- ``libdir:`` Checks for libraries being installed into incorrect
@@ -1205,11 +1417,39 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1205 ``/usr/libexec``. This check is not performed if the ``libexecdir`` 1417 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1206 variable has been set explicitly to ``/usr/libexec``. 1418 variable has been set explicitly to ``/usr/libexec``.
1207 1419
1420- ``mime:`` Check that if a package contains mime type files (``.xml``
1421 files in ``${datadir}/mime/packages``) that the recipe also inherits
1422 the :ref:`ref-classes-mime` class in order to ensure that these get
1423 properly installed.
1424
1425- ``mime-xdg:`` Checks that if a package contains a .desktop file with a
1426 'MimeType' key present, that the recipe inherits the
1427 :ref:`ref-classes-mime-xdg` class that is required in order for that
1428 to be activated.
1429
1430- ``missing-update-alternatives:`` Check that if a recipe sets the
1431 :term:`ALTERNATIVE` variable that the recipe also inherits
1432 :ref:`ref-classes-update-alternatives` such that the alternative will
1433 be correctly set up.
1434
1208- ``packages-list:`` Checks for the same package being listed 1435- ``packages-list:`` Checks for the same package being listed
1209 multiple times through the :term:`PACKAGES` variable 1436 multiple times through the :term:`PACKAGES` variable
1210 value. Installing the package in this manner can cause errors during 1437 value. Installing the package in this manner can cause errors during
1211 packaging. 1438 packaging.
1212 1439
1440- ``patch-fuzz:`` Checks for fuzz in patch files that may allow
1441 them to apply incorrectly if the underlying code changes.
1442
1443- ``patch-status-core:`` Checks that the Upstream-Status is specified
1444 and valid in the headers of patches for recipes in the OE-Core layer.
1445
1446- ``patch-status-noncore:`` Checks that the Upstream-Status is specified
1447 and valid in the headers of patches for recipes in layers other than
1448 OE-Core.
1449
1450- ``perllocalpod:`` Checks for ``perllocal.pod`` being erroneously
1451 installed and packaged by a recipe.
1452
1213- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an 1453- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1214 invalid format. 1454 invalid format.
1215 1455
@@ -1232,7 +1472,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1232 invalid characters (i.e. characters other than 0-9, a-z, ., +, and 1472 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1233 -). 1473 -).
1234 1474
1235- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is 1475- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
1236 undefined during :ref:`ref-tasks-package`. 1476 undefined during :ref:`ref-tasks-package`.
1237 1477
1238- ``pkgvarcheck:`` Checks through the variables 1478- ``pkgvarcheck:`` Checks through the variables
@@ -1252,23 +1492,31 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1252- ``pn-overrides:`` Checks that a recipe does not have a name 1492- ``pn-overrides:`` Checks that a recipe does not have a name
1253 (:term:`PN`) value that appears in 1493 (:term:`PN`) value that appears in
1254 :term:`OVERRIDES`. If a recipe is named such that 1494 :term:`OVERRIDES`. If a recipe is named such that
1255 its ``PN`` value matches something already in ``OVERRIDES`` (e.g. 1495 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1256 ``PN`` happens to be the same as :term:`MACHINE` or 1496 :term:`PN` happens to be the same as :term:`MACHINE` or
1257 :term:`DISTRO`), it can have unexpected consequences. 1497 :term:`DISTRO`), it can have unexpected consequences.
1258 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively 1498 For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
1259 turn into ``FILES = "xyz"``. 1499 turn into ``FILES = "xyz"``.
1260 1500
1261- ``rpaths:`` Checks for rpaths in the binaries that contain build 1501- ``rpaths:`` Checks for rpaths in the binaries that contain build
1262 system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` 1502 system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
1263 options are being passed to the linker commands and your binaries 1503 options are being passed to the linker commands and your binaries
1264 have potential security issues. 1504 have potential security issues.
1265 1505
1506- ``shebang-size:`` Check that the shebang line (``#!`` in the first line)
1507 in a packaged script is not longer than 128 characters, which can cause
1508 an error at runtime depending on the operating system.
1509
1266- ``split-strip:`` Reports that splitting or stripping debug symbols 1510- ``split-strip:`` Reports that splitting or stripping debug symbols
1267 from binaries has failed. 1511 from binaries has failed.
1268 1512
1269- ``staticdev:`` Checks for static library files (``*.a``) in 1513- ``staticdev:`` Checks for static library files (``*.a``) in
1270 non-``staticdev`` packages. 1514 non-``staticdev`` packages.
1271 1515
1516- ``src-uri-bad:`` Checks that the :term:`SRC_URI` value set by a recipe
1517 does not contain a reference to ``${PN}`` (instead of the correct
1518 ``${BPN}``) nor refers to unstable Github archive tarballs.
1519
1272- ``symlink-to-sysroot:`` Checks for symlinks in packages that point 1520- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1273 into :term:`TMPDIR` on the host. Such symlinks will 1521 into :term:`TMPDIR` on the host. Such symlinks will
1274 work on the host, but are clearly invalid when running on the target. 1522 work on the host, but are clearly invalid when running on the target.
@@ -1279,33 +1527,46 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1279 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance 1527 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
1280 issues. 1528 issues.
1281 1529
1530- ``unhandled-features-check:`` check that if one of the variables that
1531 the :ref:`ref-classes-features_check` class supports (e.g.
1532 :term:`REQUIRED_DISTRO_FEATURES`) is set by a recipe, then the recipe
1533 also inherits :ref:`ref-classes-features_check` in order for the
1534 requirement to actually work.
1535
1536- ``unimplemented-ptest:`` Checks that ptests are implemented for upstream
1537 tests.
1538
1282- ``unlisted-pkg-lics:`` Checks that all declared licenses applying 1539- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1283 for a package are also declared on the recipe level (i.e. any license 1540 for a package are also declared on the recipe level (i.e. any license
1284 in ``LICENSE_*`` should appear in :term:`LICENSE`). 1541 in ``LICENSE:*`` should appear in :term:`LICENSE`).
1285 1542
1286- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) 1543- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1287 in the binaries that by default on a standard system are searched by 1544 in the binaries that by default on a standard system are searched by
1288 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will 1545 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1289 not cause any breakage, they do waste space and are unnecessary. 1546 not cause any breakage, they do waste space and are unnecessary.
1290 1547
1548- ``usrmerge:`` If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this
1549 check will ensure that no package installs files to root (``/bin``,
1550 ``/sbin``, ``/lib``, ``/lib64``) directories.
1551
1291- ``var-undefined:`` Reports when variables fundamental to packaging 1552- ``var-undefined:`` Reports when variables fundamental to packaging
1292 (i.e. :term:`WORKDIR`, 1553 (i.e. :term:`WORKDIR`,
1293 :term:`DEPLOY_DIR`, :term:`D`, 1554 :term:`DEPLOY_DIR`, :term:`D`,
1294 :term:`PN`, and :term:`PKGD`) are undefined 1555 :term:`PN`, and :term:`PKGD`) are undefined
1295 during :ref:`ref-tasks-package`. 1556 during :ref:`ref-tasks-package`.
1296 1557
1297- ``version-going-backwards:`` If Build History is enabled, reports 1558- ``version-going-backwards:`` If the :ref:`ref-classes-buildhistory`
1298 when a package being written out has a lower version than the 1559 class is enabled, reports when a package being written out has a lower
1299 previously written package under the same name. If you are placing 1560 version than the previously written package under the same name. If
1300 output packages into a feed and upgrading packages on a target system 1561 you are placing output packages into a feed and upgrading packages on
1301 using that feed, the version of a package going backwards can result 1562 a target system using that feed, the version of a package going
1302 in the target system not correctly upgrading to the "new" version of 1563 backwards can result in the target system not correctly upgrading to
1303 the package. 1564 the "new" version of the package.
1304 1565
1305 .. note:: 1566 .. note::
1306 1567
1307 If you are not using runtime package management on your target 1568 This is only relevant when you are using runtime package management
1308 system, then you do not need to worry about this situation. 1569 on your target system.
1309 1570
1310- ``xorg-driver-abi:`` Checks that all packages containing Xorg 1571- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1311 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides 1572 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
@@ -1315,184 +1576,188 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1315 automatically get these versions. Consequently, you should only need 1576 automatically get these versions. Consequently, you should only need
1316 to explicitly add dependencies to binary driver recipes. 1577 to explicitly add dependencies to binary driver recipes.
1317 1578
1318.. _ref-classes-insserv:
1319
1320``insserv.bbclass``
1321===================
1322
1323The ``insserv`` class uses the ``insserv`` utility to update the order
1324of symbolic links in ``/etc/rc?.d/`` within an image based on
1325dependencies specified by LSB headers in the ``init.d`` scripts
1326themselves.
1327
1328.. _ref-classes-kernel: 1579.. _ref-classes-kernel:
1329 1580
1330``kernel.bbclass`` 1581``kernel``
1331================== 1582==========
1332 1583
1333The ``kernel`` class handles building Linux kernels. The class contains 1584The :ref:`ref-classes-kernel` class handles building Linux kernels. The class contains
1334code to build all kernel trees. All needed headers are staged into the 1585code to build all kernel trees. All needed headers are staged into the
1335``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds 1586:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
1336using the :ref:`module <ref-classes-module>` class. 1587using the :ref:`ref-classes-module` class.
1337 1588
1338This means that each built kernel module is packaged separately and 1589If a file named ``defconfig`` is listed in :term:`SRC_URI`, then by default
1339inter-module dependencies are created by parsing the ``modinfo`` output. 1590:ref:`ref-tasks-configure` copies it as ``.config`` in the build directory,
1340If all modules are required, then installing the ``kernel-modules`` 1591so it is automatically used as the kernel configuration for the build. This
1341package installs all packages with modules and various other kernel 1592copy is not performed in case ``.config`` already exists there: this allows
1342packages such as ``kernel-vmlinux``. 1593recipes to produce a configuration by other means in
1343 1594``do_configure:prepend``.
1344The ``kernel`` class contains logic that allows you to embed an initial 1595
1345RAM filesystem (initramfs) image when you build the kernel image. For 1596Each built kernel module is packaged separately and inter-module
1346information on how to build an initramfs, see the 1597dependencies are created by parsing the ``modinfo`` output. If all modules
1347":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in 1598are required, then installing the ``kernel-modules`` package installs all
1599packages with modules and various other kernel packages such as
1600``kernel-vmlinux``.
1601
1602The :ref:`ref-classes-kernel` class contains logic that allows you to embed an initial
1603RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For
1604information on how to build an :term:`Initramfs`, see the
1605":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section in
1348the Yocto Project Development Tasks Manual. 1606the Yocto Project Development Tasks Manual.
1349 1607
1350Various other classes are used by the ``kernel`` and ``module`` classes 1608Various other classes are used by the :ref:`ref-classes-kernel` and :ref:`ref-classes-module` classes
1351internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`, 1609internally including the :ref:`ref-classes-kernel-arch`, :ref:`ref-classes-module-base`, and
1352:ref:`module-base <ref-classes-module-base>`, and 1610:ref:`ref-classes-linux-kernel-base` classes.
1353:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1354 1611
1355.. _ref-classes-kernel-arch: 1612.. _ref-classes-kernel-arch:
1356 1613
1357``kernel-arch.bbclass`` 1614``kernel-arch``
1358======================= 1615===============
1359 1616
1360The ``kernel-arch`` class sets the ``ARCH`` environment variable for 1617The :ref:`ref-classes-kernel-arch` class sets the ``ARCH`` environment variable for
1361Linux kernel compilation (including modules). 1618Linux kernel compilation (including modules).
1362 1619
1363.. _ref-classes-kernel-devicetree: 1620.. _ref-classes-kernel-devicetree:
1364 1621
1365``kernel-devicetree.bbclass`` 1622``kernel-devicetree``
1366============================= 1623=====================
1367 1624
1368The ``kernel-devicetree`` class, which is inherited by the 1625The :ref:`ref-classes-kernel-devicetree` class, which is inherited by the
1369:ref:`kernel <ref-classes-kernel>` class, supports device tree 1626:ref:`ref-classes-kernel` class, supports device tree generation.
1370generation. 1627
1628Its behavior is mainly controlled by the following variables:
1629
1630- :term:`KERNEL_DEVICETREE_BUNDLE`: whether to bundle the kernel and device tree
1631- :term:`KERNEL_DTBDEST`: directory where to install DTB files
1632- :term:`KERNEL_DTBVENDORED`: whether to keep vendor subdirectories
1633- :term:`KERNEL_DTC_FLAGS`: flags for ``dtc``, the Device Tree Compiler
1634- :term:`KERNEL_PACKAGE_NAME`: base name of the kernel packages
1371 1635
1372.. _ref-classes-kernel-fitimage: 1636.. _ref-classes-kernel-fitimage:
1373 1637
1374``kernel-fitimage.bbclass`` 1638``kernel-fitimage``
1375=========================== 1639===================
1376 1640
1377The ``kernel-fitimage`` class provides support to pack a kernel image, 1641The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image,
1378device trees, a U-boot script, a Initramfs bundle and a RAM disk 1642device trees, a U-boot script, an :term:`Initramfs` bundle and a RAM disk
1379into a single FIT image. In theory, a FIT image can support any number 1643into a single FIT image. In theory, a FIT image can support any number
1380of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees. 1644of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees.
1381However, ``kernel-fitimage`` currently only supports 1645However, :ref:`ref-classes-kernel-fitimage` currently only supports
1382limited usescases: just one kernel image, an optional U-boot script, 1646limited usecases: just one kernel image, an optional U-boot script,
1383an optional Initramfs bundle, an optional RAM disk, and any number of 1647an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of
1384device tree. 1648device trees.
1385 1649
1386To create a FIT image, it is required that :term:`KERNEL_CLASSES` 1650To create a FIT image, it is required that :term:`KERNEL_CLASSES`
1387is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` 1651is set to include ":ref:`ref-classes-kernel-fitimage`" and one of :term:`KERNEL_IMAGETYPE`,
1388is set to "fitImage". 1652:term:`KERNEL_ALT_IMAGETYPE` or :term:`KERNEL_IMAGETYPES` to include "fitImage".
1389 1653
1390The options for the device tree compiler passed to ``mkimage -D`` 1654The options for the device tree compiler passed to ``mkimage -D``
1391when creating the FIT image are specified using the 1655when creating the FIT image are specified using the
1392:term:`UBOOT_MKIMAGE_DTCOPTS` variable. 1656:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1393 1657
1394Only a single kernel can be added to the FIT image created by 1658Only a single kernel can be added to the FIT image created by
1395``kernel-fitimage`` and the kernel image in FIT is mandatory. The 1659:ref:`ref-classes-kernel-fitimage` and the kernel image in FIT is mandatory. The
1396address where the kernel image is to be loaded by U-Boot is 1660address where the kernel image is to be loaded by U-Boot is
1397specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by 1661specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1398:term:`UBOOT_ENTRYPOINT`. 1662:term:`UBOOT_ENTRYPOINT`. Setting :term:`FIT_ADDRESS_CELLS` to "2"
1663is necessary if such addresses are 64 bit ones.
1399 1664
1400Multiple device trees can be added to the FIT image created by 1665Multiple device trees can be added to the FIT image created by
1401``kernel-fitimage`` and the device tree is optional. 1666:ref:`ref-classes-kernel-fitimage` and the device tree is optional.
1402The address where the device tree is to be loaded by U-Boot is 1667The address where the device tree is to be loaded by U-Boot is
1403specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays 1668specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
1404and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. 1669and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
1405 1670
1406Only a single RAM disk can be added to the FIT image created by 1671Only a single RAM disk can be added to the FIT image created by
1407``kernel-fitimage`` and the RAM disk in FIT is optional. 1672:ref:`ref-classes-kernel-fitimage` and the RAM disk in FIT is optional.
1408The address where the RAM disk image is to be loaded by U-Boot 1673The address where the RAM disk image is to be loaded by U-Boot
1409is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by 1674is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1410:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when 1675:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to the FIT image when
1411:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` 1676:term:`INITRAMFS_IMAGE` is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE`
1412is set to 0. 1677is not set to 1.
1413 1678
1414Only a single Initramfs bundle can be added to the FIT image created by 1679Only a single :term:`Initramfs` bundle can be added to the FIT image created by
1415``kernel-fitimage`` and the Initramfs bundle in FIT is optional. 1680:ref:`ref-classes-kernel-fitimage` and the :term:`Initramfs` bundle in FIT is optional.
1416In case of Initramfs, the kernel is configured to be bundled with the rootfs 1681In case of :term:`Initramfs`, the kernel is configured to be bundled with the root filesystem
1417in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin). 1682in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
1418When the kernel is copied to RAM and executed, it unpacks the Initramfs rootfs. 1683When the kernel is copied to RAM and executed, it unpacks the :term:`Initramfs` root filesystem.
1419The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE` 1684The :term:`Initramfs` bundle can be enabled when :term:`INITRAMFS_IMAGE`
1420is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1. 1685is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1421The address where the Initramfs bundle is to be loaded by U-boot is specified 1686The address where the :term:`Initramfs` bundle is to be loaded by U-boot is specified
1422by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`. 1687by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1423 1688
1424Only a single U-boot boot script can be added to the FIT image created by 1689Only a single U-boot boot script can be added to the FIT image created by
1425``kernel-fitimage`` and the boot script is optional. 1690:ref:`ref-classes-kernel-fitimage` and the boot script is optional.
1426The boot script is specified in the ITS file as a text file containing 1691The boot script is specified in the ITS file as a text file containing
1427U-boot commands. When using a boot script the user should configure the 1692U-boot commands. When using a boot script the user should configure the
1428U-boot ``do_install`` task to copy the script to sysroot. 1693U-boot :ref:`ref-tasks-install` task to copy the script to sysroot.
1429So the script can be included in the the FIT image by the ``kernel-fitimage`` 1694So the script can be included in the FIT image by the :ref:`ref-classes-kernel-fitimage`
1430class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to 1695class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1431load the boot script from the FIT image and executes it. 1696load the boot script from the FIT image and execute it.
1432 1697
1433The FIT image generated by ``kernel-fitimage`` class is signed when the 1698The FIT image generated by the :ref:`ref-classes-kernel-fitimage` class is signed when the
1434variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, 1699variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1435:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set 1700:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1436appropriately. The default values used for :term:`FIT_HASH_ALG` and 1701appropriately. The default values used for :term:`FIT_HASH_ALG` and
1437:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and 1702:term:`FIT_SIGN_ALG` in :ref:`ref-classes-kernel-fitimage` are "sha256" and
1438"rsa2048" respectively. The keys for signing fitImage can be generated using 1703"rsa2048" respectively. The keys for signing the FIT image can be generated using
1439the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and 1704the :ref:`ref-classes-kernel-fitimage` class when both :term:`FIT_GENERATE_KEYS` and
1440:term:`UBOOT_SIGN_ENABLE` are set to "1". 1705:term:`UBOOT_SIGN_ENABLE` are set to "1".
1441 1706
1442 1707
1443.. _ref-classes-kernel-grub: 1708.. _ref-classes-kernel-grub:
1444 1709
1445``kernel-grub.bbclass`` 1710``kernel-grub``
1446======================= 1711===============
1447 1712
1448The ``kernel-grub`` class updates the boot area and the boot menu with 1713The :ref:`ref-classes-kernel-grub` class updates the boot area and the boot menu with
1449the kernel as the priority boot mechanism while installing a RPM to 1714the kernel as the priority boot mechanism while installing a RPM to
1450update the kernel on a deployed target. 1715update the kernel on a deployed target.
1451 1716
1452.. _ref-classes-kernel-module-split: 1717.. _ref-classes-kernel-module-split:
1453 1718
1454``kernel-module-split.bbclass`` 1719``kernel-module-split``
1455=============================== 1720=======================
1456 1721
1457The ``kernel-module-split`` class provides common functionality for 1722The :ref:`ref-classes-kernel-module-split` class provides common functionality for
1458splitting Linux kernel modules into separate packages. 1723splitting Linux kernel modules into separate packages.
1459 1724
1460.. _ref-classes-kernel-uboot: 1725.. _ref-classes-kernel-uboot:
1461 1726
1462``kernel-uboot.bbclass`` 1727``kernel-uboot``
1463======================== 1728================
1464 1729
1465The ``kernel-uboot`` class provides support for building from 1730The :ref:`ref-classes-kernel-uboot` class provides support for building from
1466vmlinux-style kernel sources. 1731vmlinux-style kernel sources.
1467 1732
1468.. _ref-classes-kernel-uimage: 1733.. _ref-classes-kernel-uimage:
1469 1734
1470``kernel-uimage.bbclass`` 1735``kernel-uimage``
1471========================= 1736=================
1472 1737
1473The ``kernel-uimage`` class provides support to pack uImage. 1738The :ref:`ref-classes-kernel-uimage` class provides support to pack uImage.
1474 1739
1475.. _ref-classes-kernel-yocto: 1740.. _ref-classes-kernel-yocto:
1476 1741
1477``kernel-yocto.bbclass`` 1742``kernel-yocto``
1478======================== 1743================
1479 1744
1480The ``kernel-yocto`` class provides common functionality for building 1745The :ref:`ref-classes-kernel-yocto` class provides common functionality for building
1481from linux-yocto style kernel source repositories. 1746from linux-yocto style kernel source repositories.
1482 1747
1483.. _ref-classes-kernelsrc: 1748.. _ref-classes-kernelsrc:
1484 1749
1485``kernelsrc.bbclass`` 1750``kernelsrc``
1486===================== 1751=============
1487 1752
1488The ``kernelsrc`` class sets the Linux kernel source and version. 1753The :ref:`ref-classes-kernelsrc` class sets the Linux kernel source and version.
1489 1754
1490.. _ref-classes-lib_package: 1755.. _ref-classes-lib_package:
1491 1756
1492``lib_package.bbclass`` 1757``lib_package``
1493======================= 1758===============
1494 1759
1495The ``lib_package`` class supports recipes that build libraries and 1760The :ref:`ref-classes-lib_package` class supports recipes that build libraries and
1496produce executable binaries, where those binaries should not be 1761produce executable binaries, where those binaries should not be
1497installed by default along with the library. Instead, the binaries are 1762installed by default along with the library. Instead, the binaries are
1498added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to 1763added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
@@ -1500,40 +1765,40 @@ make their installation optional.
1500 1765
1501.. _ref-classes-libc*: 1766.. _ref-classes-libc*:
1502 1767
1503``libc*.bbclass`` 1768``libc*``
1504================= 1769=========
1505 1770
1506The ``libc*`` classes support recipes that build packages with ``libc``: 1771The :ref:`ref-classes-libc*` classes support recipes that build packages with ``libc``:
1507 1772
1508- The ``libc-common`` class provides common support for building with 1773- The :ref:`libc-common <ref-classes-libc*>` class provides common support for building with
1509 ``libc``. 1774 ``libc``.
1510 1775
1511- The ``libc-package`` class supports packaging up ``glibc`` and 1776- The :ref:`libc-package <ref-classes-libc*>` class supports packaging up ``glibc`` and
1512 ``eglibc``. 1777 ``eglibc``.
1513 1778
1514.. _ref-classes-license: 1779.. _ref-classes-license:
1515 1780
1516``license.bbclass`` 1781``license``
1517=================== 1782===========
1518 1783
1519The ``license`` class provides license manifest creation and license 1784The :ref:`ref-classes-license` class provides license manifest creation and license
1520exclusion. This class is enabled by default using the default value for 1785exclusion. This class is enabled by default using the default value for
1521the :term:`INHERIT_DISTRO` variable. 1786the :term:`INHERIT_DISTRO` variable.
1522 1787
1523.. _ref-classes-linux-kernel-base: 1788.. _ref-classes-linux-kernel-base:
1524 1789
1525``linux-kernel-base.bbclass`` 1790``linux-kernel-base``
1526============================= 1791=====================
1527 1792
1528The ``linux-kernel-base`` class provides common functionality for 1793The :ref:`ref-classes-linux-kernel-base` class provides common functionality for
1529recipes that build out of the Linux kernel source tree. These builds 1794recipes that build out of the Linux kernel source tree. These builds
1530goes beyond the kernel itself. For example, the Perf recipe also 1795goes beyond the kernel itself. For example, the Perf recipe also
1531inherits this class. 1796inherits this class.
1532 1797
1533.. _ref-classes-linuxloader: 1798.. _ref-classes-linuxloader:
1534 1799
1535``linuxloader.bbclass`` 1800``linuxloader``
1536======================= 1801===============
1537 1802
1538Provides the function ``linuxloader()``, which gives the value of the 1803Provides the function ``linuxloader()``, which gives the value of the
1539dynamic loader/linker provided on the platform. This value is used by a 1804dynamic loader/linker provided on the platform. This value is used by a
@@ -1541,80 +1806,101 @@ number of other classes.
1541 1806
1542.. _ref-classes-logging: 1807.. _ref-classes-logging:
1543 1808
1544``logging.bbclass`` 1809``logging``
1545=================== 1810===========
1546 1811
1547The ``logging`` class provides the standard shell functions used to log 1812The :ref:`ref-classes-logging` class provides the standard shell functions used to log
1548messages for various BitBake severity levels (i.e. ``bbplain``, 1813messages for various BitBake severity levels (i.e. ``bbplain``,
1549``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). 1814``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1550 1815
1551This class is enabled by default since it is inherited by the ``base`` 1816This class is enabled by default since it is inherited by the :ref:`ref-classes-base`
1552class. 1817class.
1553 1818
1554.. _ref-classes-meta: 1819.. _ref-classes-meson:
1555 1820
1556``meta.bbclass`` 1821``meson``
1557================ 1822=========
1558 1823
1559The ``meta`` class is inherited by recipes that do not build any output 1824The :ref:`ref-classes-meson` class allows to create recipes that build software
1560packages themselves, but act as a "meta" target for building other 1825using the `Meson <https://mesonbuild.com/>`__ build system. You can use the
1561recipes. 1826:term:`MESON_BUILDTYPE`, :term:`MESON_TARGET` and :term:`EXTRA_OEMESON`
1827variables to specify additional configuration options to be passed using the
1828``meson`` command line.
1562 1829
1563.. _ref-classes-metadata_scm: 1830.. _ref-classes-metadata_scm:
1564 1831
1565``metadata_scm.bbclass`` 1832``metadata_scm``
1566======================== 1833================
1567 1834
1568The ``metadata_scm`` class provides functionality for querying the 1835The :ref:`ref-classes-metadata_scm` class provides functionality for querying the
1569branch and revision of a Source Code Manager (SCM) repository. 1836branch and revision of a Source Code Manager (SCM) repository.
1570 1837
1571The :ref:`base <ref-classes-base>` class uses this class to print the 1838The :ref:`ref-classes-base` class uses this class to print the revisions of
1572revisions of each layer before starting every build. The 1839each layer before starting every build. The :ref:`ref-classes-metadata_scm`
1573``metadata_scm`` class is enabled by default because it is inherited by 1840class is enabled by default because it is inherited by the
1574the ``base`` class. 1841:ref:`ref-classes-base` class.
1575 1842
1576.. _ref-classes-migrate_localcount: 1843.. _ref-classes-migrate_localcount:
1577 1844
1578``migrate_localcount.bbclass`` 1845``migrate_localcount``
1579============================== 1846======================
1580 1847
1581The ``migrate_localcount`` class verifies a recipe's localcount data and 1848The :ref:`ref-classes-migrate_localcount` class verifies a recipe's localcount data and
1582increments it appropriately. 1849increments it appropriately.
1583 1850
1584.. _ref-classes-mime: 1851.. _ref-classes-mime:
1585 1852
1586``mime.bbclass`` 1853``mime``
1587================ 1854========
1588 1855
1589The ``mime`` class generates the proper post-install and post-remove 1856The :ref:`ref-classes-mime` class generates the proper post-install and post-remove
1590(postinst/postrm) scriptlets for packages that install MIME type files. 1857(postinst/postrm) scriptlets for packages that install MIME type files.
1591These scriptlets call ``update-mime-database`` to add the MIME types to 1858These scriptlets call ``update-mime-database`` to add the MIME types to
1592the shared database. 1859the shared database.
1593 1860
1861.. _ref-classes-mime-xdg:
1862
1863``mime-xdg``
1864============
1865
1866The :ref:`ref-classes-mime-xdg` class generates the proper
1867post-install and post-remove (postinst/postrm) scriptlets for packages
1868that install ``.desktop`` files containing ``MimeType`` entries.
1869These scriptlets call ``update-desktop-database`` to add the MIME types
1870to the database of MIME types handled by desktop files.
1871
1872Thanks to this class, when users open a file through a file browser
1873on recently created images, they don't have to choose the application
1874to open the file from the pool of all known applications, even the ones
1875that cannot open the selected file.
1876
1877If you have recipes installing their ``.desktop`` files as absolute
1878symbolic links, the detection of such files cannot be done by the current
1879implementation of this class. In this case, you have to add the corresponding
1880package names to the :term:`MIME_XDG_PACKAGES` variable.
1881
1594.. _ref-classes-mirrors: 1882.. _ref-classes-mirrors:
1595 1883
1596``mirrors.bbclass`` 1884``mirrors``
1597=================== 1885===========
1598 1886
1599The ``mirrors`` class sets up some standard 1887The :ref:`ref-classes-mirrors` class sets up some standard
1600:term:`MIRRORS` entries for source code mirrors. These 1888:term:`MIRRORS` entries for source code mirrors. These
1601mirrors provide a fall-back path in case the upstream source specified 1889mirrors provide a fall-back path in case the upstream source specified
1602in :term:`SRC_URI` within recipes is unavailable. 1890in :term:`SRC_URI` within recipes is unavailable.
1603 1891
1604This class is enabled by default since it is inherited by the 1892This class is enabled by default since it is inherited by the
1605:ref:`base <ref-classes-base>` class. 1893:ref:`ref-classes-base` class.
1606 1894
1607.. _ref-classes-module: 1895.. _ref-classes-module:
1608 1896
1609``module.bbclass`` 1897``module``
1610================== 1898==========
1611 1899
1612The ``module`` class provides support for building out-of-tree Linux 1900The :ref:`ref-classes-module` class provides support for building out-of-tree Linux
1613kernel modules. The class inherits the 1901kernel modules. The class inherits the :ref:`ref-classes-module-base` and
1614:ref:`module-base <ref-classes-module-base>` and 1902:ref:`ref-classes-kernel-module-split` classes, and implements the
1615:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, 1903:ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The class provides
1616and implements the :ref:`ref-tasks-compile` and
1617:ref:`ref-tasks-install` tasks. The class provides
1618everything needed to build and package a kernel module. 1904everything needed to build and package a kernel module.
1619 1905
1620For general information on out-of-tree Linux kernel modules, see the 1906For general information on out-of-tree Linux kernel modules, see the
@@ -1623,50 +1909,49 @@ section in the Yocto Project Linux Kernel Development Manual.
1623 1909
1624.. _ref-classes-module-base: 1910.. _ref-classes-module-base:
1625 1911
1626``module-base.bbclass`` 1912``module-base``
1627======================= 1913===============
1628 1914
1629The ``module-base`` class provides the base functionality for building 1915The :ref:`ref-classes-module-base` class provides the base functionality for
1630Linux kernel modules. Typically, a recipe that builds software that 1916building Linux kernel modules. Typically, a recipe that builds software that
1631includes one or more kernel modules and has its own means of building 1917includes one or more kernel modules and has its own means of building the module
1632the module inherits this class as opposed to inheriting the 1918inherits this class as opposed to inheriting the :ref:`ref-classes-module`
1633:ref:`module <ref-classes-module>` class. 1919class.
1634 1920
1635.. _ref-classes-multilib*: 1921.. _ref-classes-multilib*:
1636 1922
1637``multilib*.bbclass`` 1923``multilib*``
1638===================== 1924=============
1639 1925
1640The ``multilib*`` classes provide support for building libraries with 1926The :ref:`ref-classes-multilib*` classes provide support for building libraries with
1641different target optimizations or target architectures and installing 1927different target optimizations or target architectures and installing
1642them side-by-side in the same image. 1928them side-by-side in the same image.
1643 1929
1644For more information on using the Multilib feature, see the 1930For more information on using the Multilib feature, see the
1645":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`" 1931":ref:`dev-manual/libraries:combining multiple versions of library files into one image`"
1646section in the Yocto Project Development Tasks Manual. 1932section in the Yocto Project Development Tasks Manual.
1647 1933
1648.. _ref-classes-native: 1934.. _ref-classes-native:
1649 1935
1650``native.bbclass`` 1936``native``
1651================== 1937==========
1652 1938
1653The ``native`` class provides common functionality for recipes that 1939The :ref:`ref-classes-native` class provides common functionality for recipes that
1654build tools to run on the :term:`Build Host` (i.e. tools that use the compiler 1940build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1655or other tools from the build host). 1941or other tools from the build host).
1656 1942
1657You can create a recipe that builds tools that run natively on the host 1943You can create a recipe that builds tools that run natively on the host
1658a couple different ways: 1944a couple different ways:
1659 1945
1660- Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` 1946- Create a ``myrecipe-native.bb`` recipe that inherits the :ref:`ref-classes-native`
1661 class. If you use this method, you must order the inherit statement 1947 class. If you use this method, you must order the inherit statement
1662 in the recipe after all other inherit statements so that the 1948 in the recipe after all other inherit statements so that the
1663 ``native`` class is inherited last. 1949 :ref:`ref-classes-native` class is inherited last.
1664 1950
1665 .. note:: 1951 .. note::
1666 1952
1667 When creating a recipe this way, the recipe name must follow this 1953 When creating a recipe this way, the recipe name must follow this
1668 naming convention: 1954 naming convention::
1669 ::
1670 1955
1671 myrecipe-native.bb 1956 myrecipe-native.bb
1672 1957
@@ -1674,79 +1959,76 @@ a couple different ways:
1674 Not using this naming convention can lead to subtle problems 1959 Not using this naming convention can lead to subtle problems
1675 caused by existing code that depends on that naming convention. 1960 caused by existing code that depends on that naming convention.
1676 1961
1677- Create or modify a target recipe that contains the following: 1962- Create or modify a target recipe that contains the following::
1678 ::
1679 1963
1680 BBCLASSEXTEND = "native" 1964 BBCLASSEXTEND = "native"
1681 1965
1682 Inside the 1966 Inside the
1683 recipe, use ``_class-native`` and ``_class-target`` overrides to 1967 recipe, use ``:class-native`` and ``:class-target`` overrides to
1684 specify any functionality specific to the respective native or target 1968 specify any functionality specific to the respective native or target
1685 case. 1969 case.
1686 1970
1687Although applied differently, the ``native`` class is used with both 1971Although applied differently, the :ref:`ref-classes-native` class is used with both
1688methods. The advantage of the second method is that you do not need to 1972methods. The advantage of the second method is that you do not need to
1689have two separate recipes (assuming you need both) for native and 1973have two separate recipes (assuming you need both) for native and
1690target. All common parts of the recipe are automatically shared. 1974target. All common parts of the recipe are automatically shared.
1691 1975
1692.. _ref-classes-nativesdk: 1976.. _ref-classes-nativesdk:
1693 1977
1694``nativesdk.bbclass`` 1978``nativesdk``
1695===================== 1979=============
1696 1980
1697The ``nativesdk`` class provides common functionality for recipes that 1981The :ref:`ref-classes-nativesdk` class provides common functionality for recipes that
1698wish to build tools to run as part of an SDK (i.e. tools that run on 1982wish to build tools to run as part of an SDK (i.e. tools that run on
1699:term:`SDKMACHINE`). 1983:term:`SDKMACHINE`).
1700 1984
1701You can create a recipe that builds tools that run on the SDK machine a 1985You can create a recipe that builds tools that run on the SDK machine a
1702couple different ways: 1986couple different ways:
1703 1987
1704- Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the 1988- Create a ``nativesdk-myrecipe.bb`` recipe that inherits the
1705 ``nativesdk`` class. If you use this method, you must order the 1989 :ref:`ref-classes-nativesdk` class. If you use this method, you must order the
1706 inherit statement in the recipe after all other inherit statements so 1990 inherit statement in the recipe after all other inherit statements so
1707 that the ``nativesdk`` class is inherited last. 1991 that the :ref:`ref-classes-nativesdk` class is inherited last.
1708 1992
1709- Create a ``nativesdk`` variant of any recipe by adding the following: 1993- Create a :ref:`ref-classes-nativesdk` variant of any recipe by adding the following::
1710 ::
1711 1994
1712 BBCLASSEXTEND = "nativesdk" 1995 BBCLASSEXTEND = "nativesdk"
1713 1996
1714 Inside the 1997 Inside the
1715 recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to 1998 recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to
1716 specify any functionality specific to the respective SDK machine or 1999 specify any functionality specific to the respective SDK machine or
1717 target case. 2000 target case.
1718 2001
1719.. note:: 2002.. note::
1720 2003
1721 When creating a recipe, you must follow this naming convention: 2004 When creating a recipe, you must follow this naming convention::
1722 ::
1723 2005
1724 nativesdk-myrecipe.bb 2006 nativesdk-myrecipe.bb
1725 2007
1726 2008
1727 Not doing so can lead to subtle problems because code exists that 2009 Not doing so can lead to subtle problems because there is code that
1728 depends on the naming convention. 2010 depends on the naming convention.
1729 2011
1730Although applied differently, the ``nativesdk`` class is used with both 2012Although applied differently, the :ref:`ref-classes-nativesdk` class is used with both
1731methods. The advantage of the second method is that you do not need to 2013methods. The advantage of the second method is that you do not need to
1732have two separate recipes (assuming you need both) for the SDK machine 2014have two separate recipes (assuming you need both) for the SDK machine
1733and the target. All common parts of the recipe are automatically shared. 2015and the target. All common parts of the recipe are automatically shared.
1734 2016
1735.. _ref-classes-nopackages: 2017.. _ref-classes-nopackages:
1736 2018
1737``nopackages.bbclass`` 2019``nopackages``
1738====================== 2020==============
1739 2021
1740Disables packaging tasks for those recipes and classes where packaging 2022Disables packaging tasks for those recipes and classes where packaging
1741is not needed. 2023is not needed.
1742 2024
1743.. _ref-classes-npm: 2025.. _ref-classes-npm:
1744 2026
1745``npm.bbclass`` 2027``npm``
1746=============== 2028=======
1747 2029
1748Provides support for building Node.js software fetched using the `node 2030Provides support for building Node.js software fetched using the
1749package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. 2031:wikipedia:`node package manager (NPM) <Npm_(software)>`.
1750 2032
1751.. note:: 2033.. note::
1752 2034
@@ -1754,77 +2036,175 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1754 fetcher to have dependencies fetched and packaged automatically. 2036 fetcher to have dependencies fetched and packaged automatically.
1755 2037
1756For information on how to create NPM packages, see the 2038For information on how to create NPM packages, see the
1757":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`" 2039":ref:`dev-manual/packages:creating node package manager (npm) packages`"
1758section in the Yocto Project Development Tasks Manual. 2040section in the Yocto Project Development Tasks Manual.
1759 2041
1760.. _ref-classes-oelint: 2042.. _ref-classes-oelint:
1761 2043
1762``oelint.bbclass`` 2044``oelint``
1763================== 2045==========
1764 2046
1765The ``oelint`` class is an obsolete lint checking tool that exists in 2047The :ref:`ref-classes-oelint` class is an obsolete lint checking tool available in
1766``meta/classes`` in the :term:`Source Directory`. 2048``meta/classes`` in the :term:`Source Directory`.
1767 2049
1768A number of classes exist that could be generally useful in OE-Core but 2050There are some classes that could be generally useful in OE-Core but
1769are never actually used within OE-Core itself. The ``oelint`` class is 2051are never actually used within OE-Core itself. The :ref:`ref-classes-oelint` class is
1770one such example. However, being aware of this class can reduce the 2052one such example. However, being aware of this class can reduce the
1771proliferation of different versions of similar classes across multiple 2053proliferation of different versions of similar classes across multiple
1772layers. 2054layers.
1773 2055
2056.. _ref-classes-overlayfs:
2057
2058``overlayfs``
2059=============
2060
2061It's often desired in Embedded System design to have a read-only root filesystem.
2062But a lot of different applications might want to have read-write access to
2063some parts of a filesystem. It can be especially useful when your update mechanism
2064overwrites the whole root filesystem, but you may want your application data to be preserved
2065between updates. The :ref:`ref-classes-overlayfs` class provides a way
2066to achieve that by means of ``overlayfs`` and at the same time keeping the base
2067root filesystem read-only.
2068
2069To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
2070layer in your machine configuration. The underlying file system can be anything that
2071is supported by ``overlayfs``. This has to be done in your machine configuration::
2072
2073 OVERLAYFS_MOUNT_POINT[data] = "/data"
2074
2075.. note::
2076
2077 * QA checks fail to catch file existence if you redefine this variable in your recipe!
2078 * Only the existence of the systemd mount unit file is checked, not its contents.
2079 * To get more details on ``overlayfs``, its internals and supported operations, please refer
2080 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`__.
2081
2082The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
2083(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
2084
2085Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
2086
2087 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
2088
2089To support several mount points you can use a different variable flag. Assuming we
2090want to have a writable location on the file system, but do not need that the data
2091survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
2092file system.
2093
2094In your machine configuration::
2095
2096 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
2097
2098and then in your recipe::
2099
2100 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
2101
2102On a practical note, your application recipe might require multiple
2103overlays to be mounted before running to avoid writing to the underlying
2104file system (which can be forbidden in case of read-only file system)
2105To achieve that :ref:`ref-classes-overlayfs` provides a ``systemd``
2106helper service for mounting overlays. This helper service is named
2107``${PN}-overlays.service`` and can be depended on in your application recipe
2108(named ``application`` in the following example) ``systemd`` unit by adding
2109to the unit the following::
2110
2111 [Unit]
2112 After=application-overlays.service
2113 Requires=application-overlays.service
2114
2115.. note::
2116
2117 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
2118 In order to get ``/etc`` in overlayfs, see :ref:`ref-classes-overlayfs-etc`.
2119
2120.. _ref-classes-overlayfs-etc:
2121
2122``overlayfs-etc``
2123=================
2124
2125In order to have the ``/etc`` directory in overlayfs a special handling at early
2126boot stage is required. The idea is to supply a custom init script that mounts
2127``/etc`` before launching the actual init program, because the latter already
2128requires ``/etc`` to be mounted.
2129
2130Example usage in image recipe::
2131
2132 IMAGE_FEATURES += "overlayfs-etc"
2133
2134.. note::
2135
2136 This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
2137
2138Your machine configuration should define at least the device, mount point, and file system type
2139you are going to use for ``overlayfs``::
2140
2141 OVERLAYFS_ETC_MOUNT_POINT = "/data"
2142 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
2143 OVERLAYFS_ETC_FSTYPE ?= "ext4"
2144
2145To control more mount options you should consider setting mount options
2146(``defaults`` is used by default)::
2147
2148 OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
2149
2150The class provides two options for ``/sbin/init`` generation:
2151
2152- The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig``
2153 and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage
2154 that you won't need to change any kernel parameters in order to make it work,
2155 but it poses a restriction that package-management can't be used, because updating
2156 the init manager would remove the generated script.
2157
2158- If you wish to keep original init as is, you can set::
2159
2160 OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
2161
2162 Then the generated init will be named ``/sbin/preinit`` and you would need to extend your
2163 kernel parameters manually in your bootloader configuration.
2164
1774.. _ref-classes-own-mirrors: 2165.. _ref-classes-own-mirrors:
1775 2166
1776``own-mirrors.bbclass`` 2167``own-mirrors``
1777======================= 2168===============
1778 2169
1779The ``own-mirrors`` class makes it easier to set up your own 2170The :ref:`ref-classes-own-mirrors` class makes it easier to set up your own
1780:term:`PREMIRRORS` from which to first fetch source 2171:term:`PREMIRRORS` from which to first fetch source
1781before attempting to fetch it from the upstream specified in 2172before attempting to fetch it from the upstream specified in
1782:term:`SRC_URI` within each recipe. 2173:term:`SRC_URI` within each recipe.
1783 2174
1784To use this class, inherit it globally and specify 2175To use this class, inherit it globally and specify
1785:term:`SOURCE_MIRROR_URL`. Here is an example: 2176:term:`SOURCE_MIRROR_URL`. Here is an example::
1786::
1787 2177
1788 INHERIT += "own-mirrors" 2178 INHERIT += "own-mirrors"
1789 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" 2179 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1790 2180
1791You can specify only a single URL 2181You can specify only a single URL
1792in ``SOURCE_MIRROR_URL``. 2182in :term:`SOURCE_MIRROR_URL`.
1793 2183
1794.. _ref-classes-package: 2184.. _ref-classes-package:
1795 2185
1796``package.bbclass`` 2186``package``
1797=================== 2187===========
1798 2188
1799The ``package`` class supports generating packages from a build's 2189The :ref:`ref-classes-package` class supports generating packages from a build's
1800output. The core generic functionality is in ``package.bbclass``. The 2190output. The core generic functionality is in ``package.bbclass``. The
1801code specific to particular package types resides in these 2191code specific to particular package types resides in these
1802package-specific classes: 2192package-specific classes: :ref:`ref-classes-package_deb`,
1803:ref:`package_deb <ref-classes-package_deb>`, 2193:ref:`ref-classes-package_rpm`, :ref:`ref-classes-package_ipk`.
1804:ref:`package_rpm <ref-classes-package_rpm>`,
1805:ref:`package_ipk <ref-classes-package_ipk>`, and
1806:ref:`package_tar <ref-classes-package_tar>`.
1807
1808.. note::
1809
1810 The
1811 package_tar
1812 class is broken and not supported. It is recommended that you do not
1813 use this class.
1814 2194
1815You can control the list of resulting package formats by using the 2195You can control the list of resulting package formats by using the
1816``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` 2196:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
1817configuration file, which is located in the :term:`Build Directory`. 2197configuration file, which is located in the :term:`Build Directory`.
1818When defining the variable, you can 2198When defining the variable, you can specify one or more package types.
1819specify one or more package types. Since images are generated from 2199Since images are generated from packages, a packaging class is needed
1820packages, a packaging class is needed to enable image generation. The 2200to enable image generation. The first class listed in this variable is
1821first class listed in this variable is used for image generation. 2201used for image generation.
1822 2202
1823If you take the optional step to set up a repository (package feed) on 2203If you take the optional step to set up a repository (package feed) on
1824the development host that can be used by DNF, you can install packages 2204the development host that can be used by DNF, you can install packages
1825from the feed while you are running the image on the target (i.e. 2205from the feed while you are running the image on the target (i.e.
1826runtime installation of packages). For more information, see the 2206runtime installation of packages). For more information, see the
1827":ref:`dev-manual/common-tasks:using runtime package management`" 2207":ref:`dev-manual/packages:using runtime package management`"
1828section in the Yocto Project Development Tasks Manual. 2208section in the Yocto Project Development Tasks Manual.
1829 2209
1830The package-specific class you choose can affect build-time performance 2210The package-specific class you choose can affect build-time performance
@@ -1834,8 +2214,8 @@ the same or similar package. This comparison takes into account a
1834complete build of the package with all dependencies previously built. 2214complete build of the package with all dependencies previously built.
1835The reason for this discrepancy is because the RPM package manager 2215The reason for this discrepancy is because the RPM package manager
1836creates and processes more :term:`Metadata` than the IPK package 2216creates and processes more :term:`Metadata` than the IPK package
1837manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to 2217manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
1838"package_ipk" if you are building smaller systems. 2218":ref:`ref-classes-package_ipk`" if you are building smaller systems.
1839 2219
1840Before making your package manager decision, however, you should 2220Before making your package manager decision, however, you should
1841consider some further things about using RPM: 2221consider some further things about using RPM:
@@ -1860,120 +2240,182 @@ at these two Yocto Project mailing list links:
1860 2240
1861.. _ref-classes-package_deb: 2241.. _ref-classes-package_deb:
1862 2242
1863``package_deb.bbclass`` 2243``package_deb``
1864======================= 2244===============
1865 2245
1866The ``package_deb`` class provides support for creating packages that 2246The :ref:`ref-classes-package_deb` class provides support for creating packages that
1867use the Debian (i.e. ``.deb``) file format. The class ensures the 2247use the Debian (i.e. ``.deb``) file format. The class ensures the
1868packages are written out in a ``.deb`` file format to the 2248packages are written out in a ``.deb`` file format to the
1869``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. 2249``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1870 2250
1871This class inherits the :ref:`package <ref-classes-package>` class and 2251This class inherits the :ref:`ref-classes-package` class and
1872is enabled through the :term:`PACKAGE_CLASSES` 2252is enabled through the :term:`PACKAGE_CLASSES`
1873variable in the ``local.conf`` file. 2253variable in the ``local.conf`` file.
1874 2254
1875.. _ref-classes-package_ipk: 2255.. _ref-classes-package_ipk:
1876 2256
1877``package_ipk.bbclass`` 2257``package_ipk``
1878======================= 2258===============
1879 2259
1880The ``package_ipk`` class provides support for creating packages that 2260The :ref:`ref-classes-package_ipk` class provides support for creating packages that
1881use the IPK (i.e. ``.ipk``) file format. The class ensures the packages 2261use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1882are written out in a ``.ipk`` file format to the 2262are written out in a ``.ipk`` file format to the
1883``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. 2263``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1884 2264
1885This class inherits the :ref:`package <ref-classes-package>` class and 2265This class inherits the :ref:`ref-classes-package` class and
1886is enabled through the :term:`PACKAGE_CLASSES` 2266is enabled through the :term:`PACKAGE_CLASSES`
1887variable in the ``local.conf`` file. 2267variable in the ``local.conf`` file.
1888 2268
1889.. _ref-classes-package_rpm: 2269.. _ref-classes-package_rpm:
1890 2270
1891``package_rpm.bbclass`` 2271``package_rpm``
1892======================= 2272===============
1893 2273
1894The ``package_rpm`` class provides support for creating packages that 2274The :ref:`ref-classes-package_rpm` class provides support for creating packages that
1895use the RPM (i.e. ``.rpm``) file format. The class ensures the packages 2275use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1896are written out in a ``.rpm`` file format to the 2276are written out in a ``.rpm`` file format to the
1897``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. 2277``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1898 2278
1899This class inherits the :ref:`package <ref-classes-package>` class and 2279This class inherits the :ref:`ref-classes-package` class and
1900is enabled through the :term:`PACKAGE_CLASSES`
1901variable in the ``local.conf`` file.
1902
1903.. _ref-classes-package_tar:
1904
1905``package_tar.bbclass``
1906=======================
1907
1908The ``package_tar`` class provides support for creating tarballs. The
1909class ensures the packages are written out in a tarball format to the
1910``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
1911
1912This class inherits the :ref:`package <ref-classes-package>` class and
1913is enabled through the :term:`PACKAGE_CLASSES` 2280is enabled through the :term:`PACKAGE_CLASSES`
1914variable in the ``local.conf`` file. 2281variable in the ``local.conf`` file.
1915 2282
1916.. note::
1917
1918 You cannot specify the ``package_tar`` class first using the
1919 ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
1920 file formats for your image or SDK.
1921
1922.. _ref-classes-packagedata: 2283.. _ref-classes-packagedata:
1923 2284
1924``packagedata.bbclass`` 2285``packagedata``
1925======================= 2286===============
1926 2287
1927The ``packagedata`` class provides common functionality for reading 2288The :ref:`ref-classes-packagedata` class provides common functionality for reading
1928``pkgdata`` files found in :term:`PKGDATA_DIR`. These 2289``pkgdata`` files found in :term:`PKGDATA_DIR`. These
1929files contain information about each output package produced by the 2290files contain information about each output package produced by the
1930OpenEmbedded build system. 2291OpenEmbedded build system.
1931 2292
1932This class is enabled by default because it is inherited by the 2293This class is enabled by default because it is inherited by the
1933:ref:`package <ref-classes-package>` class. 2294:ref:`ref-classes-package` class.
1934 2295
1935.. _ref-classes-packagegroup: 2296.. _ref-classes-packagegroup:
1936 2297
1937``packagegroup.bbclass`` 2298``packagegroup``
1938======================== 2299================
1939 2300
1940The ``packagegroup`` class sets default values appropriate for package 2301The :ref:`ref-classes-packagegroup` class sets default values appropriate for package
1941group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and 2302group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
1942so forth). It is highly recommended that all package group recipes 2303so forth). It is highly recommended that all package group recipes
1943inherit this class. 2304inherit this class.
1944 2305
1945For information on how to use this class, see the 2306For information on how to use this class, see the
1946":ref:`dev-manual/common-tasks:customizing images using custom package groups`" 2307":ref:`dev-manual/customizing-images:customizing images using custom package groups`"
1947section in the Yocto Project Development Tasks Manual. 2308section in the Yocto Project Development Tasks Manual.
1948 2309
1949Previously, this class was called the ``task`` class. 2310Previously, this class was called the ``task`` class.
1950 2311
1951.. _ref-classes-patch: 2312.. _ref-classes-patch:
1952 2313
1953``patch.bbclass`` 2314``patch``
1954================= 2315=========
1955 2316
1956The ``patch`` class provides all functionality for applying patches 2317The :ref:`ref-classes-patch` class provides all functionality for applying patches
1957during the :ref:`ref-tasks-patch` task. 2318during the :ref:`ref-tasks-patch` task.
1958 2319
1959This class is enabled by default because it is inherited by the 2320This class is enabled by default because it is inherited by the
1960:ref:`base <ref-classes-base>` class. 2321:ref:`ref-classes-base` class.
1961 2322
1962.. _ref-classes-perlnative: 2323.. _ref-classes-perlnative:
1963 2324
1964``perlnative.bbclass`` 2325``perlnative``
1965====================== 2326==============
1966 2327
1967When inherited by a recipe, the ``perlnative`` class supports using the 2328When inherited by a recipe, the :ref:`ref-classes-perlnative` class supports using the
1968native version of Perl built by the build system rather than using the 2329native version of Perl built by the build system rather than using the
1969version provided by the build host. 2330version provided by the build host.
1970 2331
2332.. _ref-classes-pypi:
2333
2334``pypi``
2335========
2336
2337The :ref:`ref-classes-pypi` class sets variables appropriately for recipes that build
2338Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index.
2339By default it determines the PyPI package name based upon :term:`BPN`
2340(stripping the "python-" or "python3-" prefix off if present), however in
2341some cases you may need to set it manually in the recipe by setting
2342:term:`PYPI_PACKAGE`.
2343
2344Variables set by the :ref:`ref-classes-pypi` class include :term:`SRC_URI`, :term:`SECTION`,
2345:term:`HOMEPAGE`, :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`
2346and :term:`CVE_PRODUCT`.
2347
2348.. _ref-classes-python_flit_core:
2349
2350``python_flit_core``
2351====================
2352
2353The :ref:`ref-classes-python_flit_core` class enables building Python modules which declare
2354the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2355``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
2356section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2357
2358Python modules built with ``flit_core.buildapi`` are pure Python (no
2359``C`` or ``Rust`` extensions).
2360
2361Internally this uses the :ref:`ref-classes-python_pep517` class.
2362
2363.. _ref-classes-python_pep517:
2364
2365``python_pep517``
2366=================
2367
2368The :ref:`ref-classes-python_pep517` class builds and installs a Python ``wheel`` binary
2369archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__).
2370
2371Recipes wouldn't inherit this directly, instead typically another class will
2372inherit this and add the relevant native dependencies.
2373
2374Examples of classes which do this are :ref:`ref-classes-python_flit_core`,
2375:ref:`ref-classes-python_setuptools_build_meta`, and
2376:ref:`ref-classes-python_poetry_core`.
2377
2378.. _ref-classes-python_poetry_core:
2379
2380``python_poetry_core``
2381======================
2382
2383The :ref:`ref-classes-python_poetry_core` class enables building Python modules which use the
2384`Poetry Core <https://python-poetry.org>`__ build system.
2385
2386Internally this uses the :ref:`ref-classes-python_pep517` class.
2387
2388.. _ref-classes-python_pyo3:
2389
2390``python_pyo3``
2391===============
2392
2393The :ref:`ref-classes-python_pyo3` class helps make sure that Python extensions
2394written in Rust and built with `PyO3 <https://pyo3.rs/>`__, properly set up the
2395environment for cross compilation.
2396
2397This class is internal to the :ref:`ref-classes-python-setuptools3_rust` class
2398and is not meant to be used directly in recipes.
2399
2400.. _ref-classes-python-setuptools3_rust:
2401
2402``python-setuptools3_rust``
2403===========================
2404
2405The :ref:`ref-classes-python-setuptools3_rust` class enables building Python
2406extensions implemented in Rust with `PyO3 <https://pyo3.rs/>`__, which allows
2407to compile and distribute Python extensions written in Rust as easily
2408as if they were written in C.
2409
2410This class inherits the :ref:`ref-classes-setuptools3` and
2411:ref:`ref-classes-python_pyo3` classes.
2412
1971.. _ref-classes-pixbufcache: 2413.. _ref-classes-pixbufcache:
1972 2414
1973``pixbufcache.bbclass`` 2415``pixbufcache``
1974======================= 2416===============
1975 2417
1976The ``pixbufcache`` class generates the proper post-install and 2418The :ref:`ref-classes-pixbufcache` class generates the proper post-install and
1977post-remove (postinst/postrm) scriptlets for packages that install 2419post-remove (postinst/postrm) scriptlets for packages that install
1978pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets 2420pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
1979call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. 2421call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
@@ -1988,24 +2430,24 @@ containing the loaders.
1988 2430
1989.. _ref-classes-pkgconfig: 2431.. _ref-classes-pkgconfig:
1990 2432
1991``pkgconfig.bbclass`` 2433``pkgconfig``
1992===================== 2434=============
1993 2435
1994The ``pkgconfig`` class provides a standard way to get header and 2436The :ref:`ref-classes-pkgconfig` class provides a standard way to get header and
1995library information by using ``pkg-config``. This class aims to smooth 2437library information by using ``pkg-config``. This class aims to smooth
1996integration of ``pkg-config`` into libraries that use it. 2438integration of ``pkg-config`` into libraries that use it.
1997 2439
1998During staging, BitBake installs ``pkg-config`` data into the 2440During staging, BitBake installs ``pkg-config`` data into the
1999``sysroots/`` directory. By making use of sysroot functionality within 2441``sysroots/`` directory. By making use of sysroot functionality within
2000``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the 2442``pkg-config``, the :ref:`ref-classes-pkgconfig` class no longer has to manipulate the
2001files. 2443files.
2002 2444
2003.. _ref-classes-populate-sdk: 2445.. _ref-classes-populate-sdk:
2004 2446
2005``populate_sdk.bbclass`` 2447``populate_sdk``
2006======================== 2448================
2007 2449
2008The ``populate_sdk`` class provides support for SDK-only recipes. For 2450The :ref:`ref-classes-populate-sdk` class provides support for SDK-only recipes. For
2009information on advantages gained when building a cross-development 2451information on advantages gained when building a cross-development
2010toolchain using the :ref:`ref-tasks-populate_sdk` 2452toolchain using the :ref:`ref-tasks-populate_sdk`
2011task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" 2453task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
@@ -2014,40 +2456,39 @@ Software Development Kit (eSDK) manual.
2014 2456
2015.. _ref-classes-populate-sdk-*: 2457.. _ref-classes-populate-sdk-*:
2016 2458
2017``populate_sdk_*.bbclass`` 2459``populate_sdk_*``
2018========================== 2460==================
2019 2461
2020The ``populate_sdk_*`` classes support SDK creation and consist of the 2462The :ref:`ref-classes-populate-sdk-*` classes support SDK creation and consist of the
2021following classes: 2463following classes:
2022 2464
2023- ``populate_sdk_base``: The base class supporting SDK creation under 2465- :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`: The base class supporting SDK creation under
2024 all package managers (i.e. DEB, RPM, and opkg). 2466 all package managers (i.e. DEB, RPM, and opkg).
2025 2467
2026- ``populate_sdk_deb``: Supports creation of the SDK given the Debian 2468- :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the Debian
2027 package manager. 2469 package manager.
2028 2470
2029- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM 2471- :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the RPM
2030 package manager. 2472 package manager.
2031 2473
2032- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg 2474- :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the opkg
2033 (IPK format) package manager. 2475 (IPK format) package manager.
2034 2476
2035- ``populate_sdk_ext``: Supports extensible SDK creation under all 2477- :ref:`populate_sdk_ext <ref-classes-populate-sdk-*>`: Supports extensible SDK creation under all
2036 package managers. 2478 package managers.
2037 2479
2038The ``populate_sdk_base`` class inherits the appropriate 2480The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class inherits the appropriate
2039``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on 2481``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
2040:term:`IMAGE_PKGTYPE`. 2482:term:`IMAGE_PKGTYPE`.
2041 2483
2042The base class ensures all source and destination directories are 2484The base class ensures all source and destination directories are
2043established and then populates the SDK. After populating the SDK, the 2485established and then populates the SDK. After populating the SDK, the
2044``populate_sdk_base`` class constructs two sysroots: 2486:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class constructs two sysroots:
2045``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which 2487``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
2046contains the cross-compiler and associated tooling, and the target, 2488contains the cross-compiler and associated tooling, and the target,
2047which contains a target root filesystem that is configured for the SDK 2489which contains a target root filesystem that is configured for the SDK
2048usage. These two images reside in :term:`SDK_OUTPUT`, 2490usage. These two images reside in :term:`SDK_OUTPUT`,
2049which consists of the following: 2491which consists of the following::
2050::
2051 2492
2052 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs 2493 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2053 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs 2494 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
@@ -2055,9 +2496,9 @@ which consists of the following:
2055Finally, the base populate SDK class creates the toolchain environment 2496Finally, the base populate SDK class creates the toolchain environment
2056setup script, the tarball of the SDK, and the installer. 2497setup script, the tarball of the SDK, and the installer.
2057 2498
2058The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and 2499The respective :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`, :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`, and
2059``populate_sdk_ipk`` classes each support the specific type of SDK. 2500:ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>` classes each support the specific type of SDK.
2060These classes are inherited by and used with the ``populate_sdk_base`` 2501These classes are inherited by and used with the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
2061class. 2502class.
2062 2503
2063For more information on the cross-development toolchain generation, see 2504For more information on the cross-development toolchain generation, see
@@ -2072,10 +2513,10 @@ Software Development Kit (eSDK) manual.
2072 2513
2073.. _ref-classes-prexport: 2514.. _ref-classes-prexport:
2074 2515
2075``prexport.bbclass`` 2516``prexport``
2076==================== 2517============
2077 2518
2078The ``prexport`` class provides functionality for exporting 2519The :ref:`ref-classes-prexport` class provides functionality for exporting
2079:term:`PR` values. 2520:term:`PR` values.
2080 2521
2081.. note:: 2522.. note::
@@ -2085,10 +2526,10 @@ The ``prexport`` class provides functionality for exporting
2085 2526
2086.. _ref-classes-primport: 2527.. _ref-classes-primport:
2087 2528
2088``primport.bbclass`` 2529``primport``
2089==================== 2530============
2090 2531
2091The ``primport`` class provides functionality for importing 2532The :ref:`ref-classes-primport` class provides functionality for importing
2092:term:`PR` values. 2533:term:`PR` values.
2093 2534
2094.. note:: 2535.. note::
@@ -2098,130 +2539,142 @@ The ``primport`` class provides functionality for importing
2098 2539
2099.. _ref-classes-prserv: 2540.. _ref-classes-prserv:
2100 2541
2101``prserv.bbclass`` 2542``prserv``
2102================== 2543==========
2103 2544
2104The ``prserv`` class provides functionality for using a :ref:`PR 2545The :ref:`ref-classes-prserv` class provides functionality for using a :ref:`PR
2105service <dev-manual/common-tasks:working with a pr service>` in order to 2546service <dev-manual/packages:working with a pr service>` in order to
2106automatically manage the incrementing of the :term:`PR` 2547automatically manage the incrementing of the :term:`PR`
2107variable for each recipe. 2548variable for each recipe.
2108 2549
2109This class is enabled by default because it is inherited by the 2550This class is enabled by default because it is inherited by the
2110:ref:`package <ref-classes-package>` class. However, the OpenEmbedded 2551:ref:`ref-classes-package` class. However, the OpenEmbedded
2111build system will not enable the functionality of this class unless 2552build system will not enable the functionality of this class unless
2112:term:`PRSERV_HOST` has been set. 2553:term:`PRSERV_HOST` has been set.
2113 2554
2114.. _ref-classes-ptest: 2555.. _ref-classes-ptest:
2115 2556
2116``ptest.bbclass`` 2557``ptest``
2117================= 2558=========
2118 2559
2119The ``ptest`` class provides functionality for packaging and installing 2560The :ref:`ref-classes-ptest` class provides functionality for packaging and installing
2120runtime tests for recipes that build software that provides these tests. 2561runtime tests for recipes that build software that provides these tests.
2121 2562
2122This class is intended to be inherited by individual recipes. However, 2563This class is intended to be inherited by individual recipes. However,
2123the class' functionality is largely disabled unless "ptest" appears in 2564the class' functionality is largely disabled unless "ptest" appears in
2124:term:`DISTRO_FEATURES`. See the 2565:term:`DISTRO_FEATURES`. See the
2125":ref:`dev-manual/common-tasks:testing packages with ptest`" 2566":ref:`dev-manual/packages:testing packages with ptest`"
2126section in the Yocto Project Development Tasks Manual for more information 2567section in the Yocto Project Development Tasks Manual for more information
2127on ptest. 2568on ptest.
2128 2569
2570.. _ref-classes-ptest-cargo:
2571
2572``ptest-cargo``
2573===============
2574
2575The :ref:`ref-classes-ptest-cargo` class is a class which extends the
2576:ref:`ref-classes-cargo` class and adds ``compile_ptest_cargo`` and
2577``install_ptest_cargo`` steps to respectively build and install
2578test suites defined in the ``Cargo.toml`` file, into a dedicated
2579``-ptest`` package.
2580
2129.. _ref-classes-ptest-gnome: 2581.. _ref-classes-ptest-gnome:
2130 2582
2131``ptest-gnome.bbclass`` 2583``ptest-gnome``
2132======================= 2584===============
2133 2585
2134Enables package tests (ptests) specifically for GNOME packages, which 2586Enables package tests (ptests) specifically for GNOME packages, which
2135have tests intended to be executed with ``gnome-desktop-testing``. 2587have tests intended to be executed with ``gnome-desktop-testing``.
2136 2588
2137For information on setting up and running ptests, see the 2589For information on setting up and running ptests, see the
2138":ref:`dev-manual/common-tasks:testing packages with ptest`" 2590":ref:`dev-manual/packages:testing packages with ptest`"
2139section in the Yocto Project Development Tasks Manual. 2591section in the Yocto Project Development Tasks Manual.
2140 2592
2141.. _ref-classes-python-dir: 2593.. _ref-classes-python3-dir:
2142 2594
2143``python-dir.bbclass`` 2595``python3-dir``
2144====================== 2596===============
2145 2597
2146The ``python-dir`` class provides the base version, location, and site 2598The :ref:`ref-classes-python3-dir` class provides the base version, location, and site
2147package location for Python. 2599package location for Python 3.
2148 2600
2149.. _ref-classes-python3native: 2601.. _ref-classes-python3native:
2150 2602
2151``python3native.bbclass`` 2603``python3native``
2152========================= 2604=================
2153 2605
2154The ``python3native`` class supports using the native version of Python 2606The :ref:`ref-classes-python3native` class supports using the native version of Python
21553 built by the build system rather than support of the version provided 26073 built by the build system rather than support of the version provided
2156by the build host. 2608by the build host.
2157 2609
2158.. _ref-classes-pythonnative: 2610.. _ref-classes-python3targetconfig:
2159 2611
2160``pythonnative.bbclass`` 2612``python3targetconfig``
2161======================== 2613=======================
2162 2614
2163When inherited by a recipe, the ``pythonnative`` class supports using 2615The :ref:`ref-classes-python3targetconfig` class supports using the native version of Python
2164the native version of Python built by the build system rather than using 26163 built by the build system rather than support of the version provided
2165the version provided by the build host. 2617by the build host, except that the configuration for the target machine
2618is accessible (such as correct installation directories). This also adds a
2619dependency on target ``python3``, so should only be used where appropriate
2620in order to avoid unnecessarily lengthening builds.
2166 2621
2167.. _ref-classes-qemu: 2622.. _ref-classes-qemu:
2168 2623
2169``qemu.bbclass`` 2624``qemu``
2170================ 2625========
2171 2626
2172The ``qemu`` class provides functionality for recipes that either need 2627The :ref:`ref-classes-qemu` class provides functionality for recipes that either need
2173QEMU or test for the existence of QEMU. Typically, this class is used to 2628QEMU or test for the existence of QEMU. Typically, this class is used to
2174run programs for a target system on the build host using QEMU's 2629run programs for a target system on the build host using QEMU's
2175application emulation mode. 2630application emulation mode.
2176 2631
2177.. _ref-classes-recipe_sanity: 2632.. _ref-classes-recipe_sanity:
2178 2633
2179``recipe_sanity.bbclass`` 2634``recipe_sanity``
2180========================= 2635=================
2181 2636
2182The ``recipe_sanity`` class checks for the presence of any host system 2637The :ref:`ref-classes-recipe_sanity` class checks for the presence of any host system
2183recipe prerequisites that might affect the build (e.g. variables that 2638recipe prerequisites that might affect the build (e.g. variables that
2184are set or software that is present). 2639are set or software that is present).
2185 2640
2186.. _ref-classes-relocatable: 2641.. _ref-classes-relocatable:
2187 2642
2188``relocatable.bbclass`` 2643``relocatable``
2189======================= 2644===============
2190 2645
2191The ``relocatable`` class enables relocation of binaries when they are 2646The :ref:`ref-classes-relocatable` class enables relocation of binaries when they are
2192installed into the sysroot. 2647installed into the sysroot.
2193 2648
2194This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class 2649This class makes use of the :ref:`ref-classes-chrpath` class and is used by
2195and is used by both the :ref:`cross <ref-classes-cross>` and 2650both the :ref:`ref-classes-cross` and :ref:`ref-classes-native` classes.
2196:ref:`native <ref-classes-native>` classes.
2197 2651
2198.. _ref-classes-remove-libtool: 2652.. _ref-classes-remove-libtool:
2199 2653
2200``remove-libtool.bbclass`` 2654``remove-libtool``
2201========================== 2655==================
2202 2656
2203The ``remove-libtool`` class adds a post function to the 2657The :ref:`ref-classes-remove-libtool` class adds a post function to the
2204:ref:`ref-tasks-install` task to remove all ``.la`` files 2658:ref:`ref-tasks-install` task to remove all ``.la`` files
2205installed by ``libtool``. Removing these files results in them being 2659installed by ``libtool``. Removing these files results in them being
2206absent from both the sysroot and target packages. 2660absent from both the sysroot and target packages.
2207 2661
2208If a recipe needs the ``.la`` files to be installed, then the recipe can 2662If a recipe needs the ``.la`` files to be installed, then the recipe can
2209override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: 2663override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
2210::
2211 2664
2212 REMOVE_LIBTOOL_LA = "0" 2665 REMOVE_LIBTOOL_LA = "0"
2213 2666
2214.. note:: 2667.. note::
2215 2668
2216 The ``remove-libtool`` class is not enabled by default. 2669 The :ref:`ref-classes-remove-libtool` class is not enabled by default.
2217 2670
2218.. _ref-classes-report-error: 2671.. _ref-classes-report-error:
2219 2672
2220``report-error.bbclass`` 2673``report-error``
2221======================== 2674================
2222 2675
2223The ``report-error`` class supports enabling the :ref:`error reporting 2676The :ref:`ref-classes-report-error` class supports enabling the :ref:`error reporting
2224tool <dev-manual/common-tasks:using the error reporting tool>`", 2677tool <dev-manual/error-reporting-tool:using the error reporting tool>`",
2225which allows you to submit build error information to a central database. 2678which allows you to submit build error information to a central database.
2226 2679
2227The class collects debug information for recipe, recipe version, task, 2680The class collects debug information for recipe, recipe version, task,
@@ -2232,10 +2685,10 @@ are created and stored in
2232 2685
2233.. _ref-classes-rm-work: 2686.. _ref-classes-rm-work:
2234 2687
2235``rm_work.bbclass`` 2688``rm_work``
2236=================== 2689===========
2237 2690
2238The ``rm_work`` class supports deletion of temporary workspace, which 2691The :ref:`ref-classes-rm-work` class supports deletion of temporary workspace, which
2239can ease your hard drive demands during builds. 2692can ease your hard drive demands during builds.
2240 2693
2241The OpenEmbedded build system can use a substantial amount of disk space 2694The OpenEmbedded build system can use a substantial amount of disk space
@@ -2244,61 +2697,76 @@ under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2244system generates the packages for a recipe, the work files for that 2697system generates the packages for a recipe, the work files for that
2245recipe are no longer needed. However, by default, the build system 2698recipe are no longer needed. However, by default, the build system
2246preserves these files for inspection and possible debugging purposes. If 2699preserves these files for inspection and possible debugging purposes. If
2247you would rather have these files deleted to save disk space as the 2700you would rather have these files deleted to save disk space as the build
2248build progresses, you can enable ``rm_work`` by adding the following to 2701progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to
2249your ``local.conf`` file, which is found in the :term:`Build Directory`. 2702your ``local.conf`` file, which is found in the :term:`Build Directory`::
2250::
2251 2703
2252 INHERIT += "rm_work" 2704 INHERIT += "rm_work"
2253 2705
2254If you are 2706If you are modifying and building source code out of the work directory for a
2255modifying and building source code out of the work directory for a 2707recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your
2256recipe, enabling ``rm_work`` will potentially result in your changes to 2708changes to the source being lost. To exclude some recipes from having their work
2257the source being lost. To exclude some recipes from having their work 2709directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the
2258directories deleted by ``rm_work``, you can add the names of the recipe 2710recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable,
2259or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which 2711which can also be set in your ``local.conf`` file. Here is an example::
2260can also be set in your ``local.conf`` file. Here is an example:
2261::
2262 2712
2263 RM_WORK_EXCLUDE += "busybox glibc" 2713 RM_WORK_EXCLUDE += "busybox glibc"
2264 2714
2265.. _ref-classes-rootfs*: 2715.. _ref-classes-rootfs*:
2266 2716
2267``rootfs*.bbclass`` 2717``rootfs*``
2268=================== 2718===========
2269 2719
2270The ``rootfs*`` classes support creating the root filesystem for an 2720The :ref:`ref-classes-rootfs*` classes support creating the root filesystem for an
2271image and consist of the following classes: 2721image and consist of the following classes:
2272 2722
2273- The ``rootfs-postcommands`` class, which defines filesystem 2723- The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class, which defines filesystem
2274 post-processing functions for image recipes. 2724 post-processing functions for image recipes.
2275 2725
2276- The ``rootfs_deb`` class, which supports creation of root filesystems 2726- The :ref:`rootfs_deb <ref-classes-rootfs*>` class, which supports creation of root filesystems
2277 for images built using ``.deb`` packages. 2727 for images built using ``.deb`` packages.
2278 2728
2279- The ``rootfs_rpm`` class, which supports creation of root filesystems 2729- The :ref:`rootfs_rpm <ref-classes-rootfs*>` class, which supports creation of root filesystems
2280 for images built using ``.rpm`` packages. 2730 for images built using ``.rpm`` packages.
2281 2731
2282- The ``rootfs_ipk`` class, which supports creation of root filesystems 2732- The :ref:`rootfs_ipk <ref-classes-rootfs*>` class, which supports creation of root filesystems
2283 for images built using ``.ipk`` packages. 2733 for images built using ``.ipk`` packages.
2284 2734
2285- The ``rootfsdebugfiles`` class, which installs additional files found 2735- The :ref:`rootfsdebugfiles <ref-classes-rootfs*>` class, which installs additional files found
2286 on the build host directly into the root filesystem. 2736 on the build host directly into the root filesystem.
2287 2737
2288The root filesystem is created from packages using one of the 2738The root filesystem is created from packages using one of the
2289``rootfs*.bbclass`` files as determined by the 2739:ref:`ref-classes-rootfs*` files as determined by the :term:`PACKAGE_CLASSES`
2290:term:`PACKAGE_CLASSES` variable. 2740variable.
2291 2741
2292For information on how root filesystem images are created, see the 2742For information on how root filesystem images are created, see the
2293":ref:`overview-manual/concepts:image generation`" 2743":ref:`overview-manual/concepts:image generation`"
2294section in the Yocto Project Overview and Concepts Manual. 2744section in the Yocto Project Overview and Concepts Manual.
2295 2745
2746.. _ref-classes-rust:
2747
2748``rust``
2749========
2750
2751The :ref:`ref-classes-rust` class is an internal class which is just used
2752in the "rust" recipe, to build the Rust compiler and runtime
2753library. Except for this recipe, it is not intended to be used directly.
2754
2755.. _ref-classes-rust-common:
2756
2757``rust-common``
2758===============
2759
2760The :ref:`ref-classes-rust-common` class is an internal class to the
2761:ref:`ref-classes-cargo_common` and :ref:`ref-classes-rust` classes and is not
2762intended to be used directly.
2763
2296.. _ref-classes-sanity: 2764.. _ref-classes-sanity:
2297 2765
2298``sanity.bbclass`` 2766``sanity``
2299================== 2767==========
2300 2768
2301The ``sanity`` class checks to see if prerequisite software is present 2769The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present
2302on the host system so that users can be notified of potential problems 2770on the host system so that users can be notified of potential problems
2303that might affect their build. The class also performs basic user 2771that might affect their build. The class also performs basic user
2304configuration checks from the ``local.conf`` configuration file to 2772configuration checks from the ``local.conf`` configuration file to
@@ -2307,72 +2775,117 @@ usually determines whether to include this class.
2307 2775
2308.. _ref-classes-scons: 2776.. _ref-classes-scons:
2309 2777
2310``scons.bbclass`` 2778``scons``
2311================= 2779=========
2312 2780
2313The ``scons`` class supports recipes that need to build software that 2781The :ref:`ref-classes-scons` class supports recipes that need to build software
2314uses the SCons build system. You can use the 2782that uses the SCons build system. You can use the :term:`EXTRA_OESCONS`
2315:term:`EXTRA_OESCONS` variable to specify 2783variable to specify additional configuration options you want to pass SCons
2316additional configuration options you want to pass SCons command line. 2784command line.
2317 2785
2318.. _ref-classes-sdl: 2786.. _ref-classes-sdl:
2319 2787
2320``sdl.bbclass`` 2788``sdl``
2321=============== 2789=======
2322 2790
2323The ``sdl`` class supports recipes that need to build software that uses 2791The :ref:`ref-classes-sdl` class supports recipes that need to build software that uses
2324the Simple DirectMedia Layer (SDL) library. 2792the Simple DirectMedia Layer (SDL) library.
2325 2793
2326.. _ref-classes-setuptools: 2794.. _ref-classes-python_setuptools_build_meta:
2327 2795
2328``setuptools.bbclass`` 2796``python_setuptools_build_meta``
2329====================== 2797================================
2798
2799The :ref:`ref-classes-python_setuptools_build_meta` class enables building
2800Python modules which declare the
2801`PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2802``setuptools.build_meta`` ``build-backend`` in the ``[build-system]``
2803section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2330 2804
2331The ``setuptools`` class supports Python version 2.x extensions that use 2805Python modules built with ``setuptools.build_meta`` can be pure Python or
2332build systems based on ``setuptools``. If your recipe uses these build 2806include ``C`` or ``Rust`` extensions).
2333systems, the recipe needs to inherit the ``setuptools`` class. 2807
2808Internally this uses the :ref:`ref-classes-python_pep517` class.
2334 2809
2335.. _ref-classes-setuptools3: 2810.. _ref-classes-setuptools3:
2336 2811
2337``setuptools3.bbclass`` 2812``setuptools3``
2338======================= 2813===============
2339 2814
2340The ``setuptools3`` class supports Python version 3.x extensions that 2815The :ref:`ref-classes-setuptools3` class supports Python version 3.x extensions
2341use build systems based on ``setuptools3``. If your recipe uses these 2816that use build systems based on ``setuptools`` (e.g. only have a ``setup.py``
2342build systems, the recipe needs to inherit the ``setuptools3`` class. 2817and have not migrated to the official ``pyproject.toml`` format). If your recipe
2818uses these build systems, the recipe needs to inherit the
2819:ref:`ref-classes-setuptools3` class.
2343 2820
2344.. _ref-classes-sign_rpm: 2821 .. note::
2822
2823 The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-compile` task now calls
2824 ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format
2825 (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__).
2826
2827 A consequence of this is that legacy software still using deprecated
2828 ``distutils`` from the Python standard library cannot be packaged as
2829 ``wheels``. A common solution is the replace
2830 ``from distutils.core import setup`` with ``from setuptools import setup``.
2831
2832 .. note::
2833
2834 The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-install` task now
2835 installs the ``wheel`` binary archive. In current versions of
2836 ``setuptools`` the legacy ``setup.py install`` method is deprecated. If
2837 the ``setup.py`` cannot be used with wheels, for example it creates files
2838 outside of the Python module or standard entry points, then
2839 :ref:`ref-classes-setuptools3_legacy` should be used.
2345 2840
2346``sign_rpm.bbclass`` 2841.. _ref-classes-setuptools3_legacy:
2842
2843``setuptools3_legacy``
2844======================
2845
2846The :ref:`ref-classes-setuptools3_legacy` class supports
2847Python version 3.x extensions that use build systems based on ``setuptools``
2848(e.g. only have a ``setup.py`` and have not migrated to the official
2849``pyproject.toml`` format). Unlike :ref:`ref-classes-setuptools3`,
2850this uses the traditional ``setup.py`` ``build`` and ``install`` commands and
2851not wheels. This use of ``setuptools`` like this is
2852`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__
2853but still relatively common.
2854
2855.. _ref-classes-setuptools3-base:
2856
2857``setuptools3-base``
2347==================== 2858====================
2348 2859
2349The ``sign_rpm`` class supports generating signed RPM packages. 2860The :ref:`ref-classes-setuptools3-base` class provides a reusable base for
2861other classes that support building Python version 3.x extensions. If you need
2862functionality that is not provided by the :ref:`ref-classes-setuptools3` class,
2863you may want to ``inherit setuptools3-base``. Some recipes do not need the tasks
2864in the :ref:`ref-classes-setuptools3` class and inherit this class instead.
2350 2865
2351.. _ref-classes-sip: 2866.. _ref-classes-sign_rpm:
2352 2867
2353``sip.bbclass`` 2868``sign_rpm``
2354=============== 2869============
2355 2870
2356The ``sip`` class supports recipes that build or package SIP-based 2871The :ref:`ref-classes-sign_rpm` class supports generating signed RPM packages.
2357Python bindings.
2358 2872
2359.. _ref-classes-siteconfig: 2873.. _ref-classes-siteconfig:
2360 2874
2361``siteconfig.bbclass`` 2875``siteconfig``
2362====================== 2876==============
2363 2877
2364The ``siteconfig`` class provides functionality for handling site 2878The :ref:`ref-classes-siteconfig` class provides functionality for handling site
2365configuration. The class is used by the 2879configuration. The class is used by the :ref:`ref-classes-autotools` class to
2366:ref:`autotools <ref-classes-autotools>` class to accelerate the 2880accelerate the :ref:`ref-tasks-configure` task.
2367:ref:`ref-tasks-configure` task.
2368 2881
2369.. _ref-classes-siteinfo: 2882.. _ref-classes-siteinfo:
2370 2883
2371``siteinfo.bbclass`` 2884``siteinfo``
2372==================== 2885============
2373 2886
2374The ``siteinfo`` class provides information about the targets that might 2887The :ref:`ref-classes-siteinfo` class provides information about the targets
2375be needed by other classes or recipes. 2888that might be needed by other classes or recipes.
2376 2889
2377As an example, consider Autotools, which can require tests that must 2890As an example, consider Autotools, which can require tests that must
2378execute on the target hardware. Since this is not possible in general 2891execute on the target hardware. Since this is not possible in general
@@ -2381,20 +2894,20 @@ results so these tests can be skipped over but still make the correct
2381values available. The ``meta/site directory`` contains test results 2894values available. The ``meta/site directory`` contains test results
2382sorted into different categories such as architecture, endianness, and 2895sorted into different categories such as architecture, endianness, and
2383the ``libc`` used. Site information provides a list of files containing 2896the ``libc`` used. Site information provides a list of files containing
2384data relevant to the current build in the ``CONFIG_SITE`` variable that 2897data relevant to the current build in the :term:`CONFIG_SITE` variable that
2385Autotools automatically picks up. 2898Autotools automatically picks up.
2386 2899
2387The class also provides variables like ``SITEINFO_ENDIANNESS`` and 2900The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2388``SITEINFO_BITS`` that can be used elsewhere in the metadata. 2901:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
2389 2902
2390.. _ref-classes-sstate: 2903.. _ref-classes-sstate:
2391 2904
2392``sstate.bbclass`` 2905``sstate``
2393================== 2906==========
2394 2907
2395The ``sstate`` class provides support for Shared State (sstate). By 2908The :ref:`ref-classes-sstate` class provides support for Shared State (sstate).
2396default, the class is enabled through the 2909By default, the class is enabled through the :term:`INHERIT_DISTRO` variable's
2397:term:`INHERIT_DISTRO` variable's default value. 2910default value.
2398 2911
2399For more information on sstate, see the 2912For more information on sstate, see the
2400":ref:`overview-manual/concepts:shared state cache`" 2913":ref:`overview-manual/concepts:shared state cache`"
@@ -2402,10 +2915,10 @@ section in the Yocto Project Overview and Concepts Manual.
2402 2915
2403.. _ref-classes-staging: 2916.. _ref-classes-staging:
2404 2917
2405``staging.bbclass`` 2918``staging``
2406=================== 2919===========
2407 2920
2408The ``staging`` class installs files into individual recipe work 2921The :ref:`ref-classes-staging` class installs files into individual recipe work
2409directories for sysroots. The class contains the following key tasks: 2922directories for sysroots. The class contains the following key tasks:
2410 2923
2411- The :ref:`ref-tasks-populate_sysroot` task, 2924- The :ref:`ref-tasks-populate_sysroot` task,
@@ -2418,25 +2931,25 @@ directories for sysroots. The class contains the following key tasks:
2418 installs the files into the individual recipe work directories (i.e. 2931 installs the files into the individual recipe work directories (i.e.
2419 :term:`WORKDIR`). 2932 :term:`WORKDIR`).
2420 2933
2421The code in the ``staging`` class is complex and basically works in two 2934The code in the :ref:`ref-classes-staging` class is complex and basically works
2422stages: 2935in two stages:
2423 2936
2424- *Stage One:* The first stage addresses recipes that have files they 2937- *Stage One:* The first stage addresses recipes that have files they
2425 want to share with other recipes that have dependencies on the 2938 want to share with other recipes that have dependencies on the
2426 originating recipe. Normally these dependencies are installed through 2939 originating recipe. Normally these dependencies are installed through
2427 the :ref:`ref-tasks-install` task into 2940 the :ref:`ref-tasks-install` task into
2428 ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task 2941 ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task
2429 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This 2942 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2430 subset of files is controlled by the 2943 subset of files is controlled by the
2431 :term:`SYSROOT_DIRS`, 2944 :term:`SYSROOT_DIRS`,
2432 :term:`SYSROOT_DIRS_NATIVE`, and 2945 :term:`SYSROOT_DIRS_NATIVE`, and
2433 :term:`SYSROOT_DIRS_BLACKLIST` 2946 :term:`SYSROOT_DIRS_IGNORE`
2434 variables. 2947 variables.
2435 2948
2436 .. note:: 2949 .. note::
2437 2950
2438 Additionally, a recipe can customize the files further by 2951 Additionally, a recipe can customize the files further by
2439 declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` 2952 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
2440 variable. 2953 variable.
2441 2954
2442 A shared state (sstate) object is built from these files and the 2955 A shared state (sstate) object is built from these files and the
@@ -2478,11 +2991,11 @@ stages:
2478 recommended for general use, the files do allow some issues such 2991 recommended for general use, the files do allow some issues such
2479 as user creation and module indexes to be addressed. 2992 as user creation and module indexes to be addressed.
2480 2993
2481 Because recipes can have other dependencies outside of ``DEPENDS`` 2994 Because recipes can have other dependencies outside of :term:`DEPENDS`
2482 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), 2995 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2483 the sysroot creation function ``extend_recipe_sysroot`` is also added 2996 the sysroot creation function ``extend_recipe_sysroot`` is also added
2484 as a pre-function for those tasks whose dependencies are not through 2997 as a pre-function for those tasks whose dependencies are not through
2485 ``DEPENDS`` but operate similarly. 2998 :term:`DEPENDS` but operate similarly.
2486 2999
2487 When installing dependencies into the sysroot, the code traverses the 3000 When installing dependencies into the sysroot, the code traverses the
2488 dependency graph and processes dependencies in exactly the same way 3001 dependency graph and processes dependencies in exactly the same way
@@ -2492,8 +3005,7 @@ stages:
2492 dependencies traversed or installed. The same sstate dependency code 3005 dependencies traversed or installed. The same sstate dependency code
2493 is used so that builds should be identical regardless of whether 3006 is used so that builds should be identical regardless of whether
2494 sstate was used or not. For a closer look, see the 3007 sstate was used or not. For a closer look, see the
2495 ``setscene_depvalid()`` function in the 3008 ``setscene_depvalid()`` function in the :ref:`ref-classes-sstate` class.
2496 :ref:`sstate <ref-classes-sstate>` class.
2497 3009
2498 The build system is careful to maintain manifests of the files it 3010 The build system is careful to maintain manifests of the files it
2499 installs so that any given dependency can be installed as needed. The 3011 installs so that any given dependency can be installed as needed. The
@@ -2502,11 +3014,11 @@ stages:
2502 3014
2503.. _ref-classes-syslinux: 3015.. _ref-classes-syslinux:
2504 3016
2505``syslinux.bbclass`` 3017``syslinux``
2506==================== 3018============
2507 3019
2508The ``syslinux`` class provides syslinux-specific functions for building 3020The :ref:`ref-classes-syslinux` class provides syslinux-specific functions for
2509bootable images. 3021building bootable images.
2510 3022
2511The class supports the following variables: 3023The class supports the following variables:
2512 3024
@@ -2545,11 +3057,11 @@ The class supports the following variables:
2545 3057
2546.. _ref-classes-systemd: 3058.. _ref-classes-systemd:
2547 3059
2548``systemd.bbclass`` 3060``systemd``
2549=================== 3061===========
2550 3062
2551The ``systemd`` class provides support for recipes that install systemd 3063The :ref:`ref-classes-systemd` class provides support for recipes that install
2552unit files. 3064systemd unit files.
2553 3065
2554The functionality for this class is disabled unless you have "systemd" 3066The functionality for this class is disabled unless you have "systemd"
2555in :term:`DISTRO_FEATURES`. 3067in :term:`DISTRO_FEATURES`.
@@ -2566,36 +3078,35 @@ You should set :term:`SYSTEMD_SERVICE` to the
2566name of the service file. You should also use a package name override to 3078name of the service file. You should also use a package name override to
2567indicate the package to which the value applies. If the value applies to 3079indicate the package to which the value applies. If the value applies to
2568the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here 3080the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
2569is an example from the connman recipe: 3081is an example from the connman recipe::
2570::
2571 3082
2572 SYSTEMD_SERVICE_${PN} = "connman.service" 3083 SYSTEMD_SERVICE:${PN} = "connman.service"
2573 3084
2574Services are set up to start on boot automatically 3085Services are set up to start on boot automatically
2575unless you have set 3086unless you have set
2576:term:`SYSTEMD_AUTO_ENABLE` to "disable". 3087:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2577 3088
2578For more information on ``systemd``, see the 3089For more information on :ref:`ref-classes-systemd`, see the
2579":ref:`dev-manual/common-tasks:selecting an initialization manager`" 3090":ref:`dev-manual/init-manager:selecting an initialization manager`"
2580section in the Yocto Project Development Tasks Manual. 3091section in the Yocto Project Development Tasks Manual.
2581 3092
2582.. _ref-classes-systemd-boot: 3093.. _ref-classes-systemd-boot:
2583 3094
2584``systemd-boot.bbclass`` 3095``systemd-boot``
2585======================== 3096================
2586 3097
2587The ``systemd-boot`` class provides functions specific to the 3098The :ref:`ref-classes-systemd-boot` class provides functions specific to the
2588systemd-boot bootloader for building bootable images. This is an 3099systemd-boot bootloader for building bootable images. This is an
2589internal class and is not intended to be used directly. 3100internal class and is not intended to be used directly.
2590 3101
2591.. note:: 3102.. note::
2592 3103
2593 The ``systemd-boot`` class is a result from merging the ``gummiboot`` class 3104 The :ref:`ref-classes-systemd-boot` class is a result from merging the ``gummiboot`` class
2594 used in previous Yocto Project releases with the ``systemd`` project. 3105 used in previous Yocto Project releases with the ``systemd`` project.
2595 3106
2596Set the :term:`EFI_PROVIDER` variable to 3107Set the :term:`EFI_PROVIDER` variable to ":ref:`ref-classes-systemd-boot`" to
2597"systemd-boot" to use this class. Doing so creates a standalone EFI 3108use this class. Doing so creates a standalone EFI bootloader that is not
2598bootloader that is not dependent on systemd. 3109dependent on systemd.
2599 3110
2600For information on more variables used and supported in this class, see 3111For information on more variables used and supported in this class, see
2601the :term:`SYSTEMD_BOOT_CFG`, 3112the :term:`SYSTEMD_BOOT_CFG`,
@@ -2608,76 +3119,71 @@ for more information.
2608 3119
2609.. _ref-classes-terminal: 3120.. _ref-classes-terminal:
2610 3121
2611``terminal.bbclass`` 3122``terminal``
2612==================== 3123============
2613 3124
2614The ``terminal`` class provides support for starting a terminal session. 3125The :ref:`ref-classes-terminal` class provides support for starting a terminal
2615The :term:`OE_TERMINAL` variable controls which 3126session. The :term:`OE_TERMINAL` variable controls which terminal emulator is
2616terminal emulator is used for the session. 3127used for the session.
2617 3128
2618Other classes use the ``terminal`` class anywhere a separate terminal 3129Other classes use the :ref:`ref-classes-terminal` class anywhere a separate
2619session needs to be started. For example, the 3130terminal session needs to be started. For example, the :ref:`ref-classes-patch`
2620:ref:`patch <ref-classes-patch>` class assuming 3131class assuming :term:`PATCHRESOLVE` is set to "user", the
2621:term:`PATCHRESOLVE` is set to "user", the 3132:ref:`ref-classes-cml1` class, and the :ref:`ref-classes-devshell` class all
2622:ref:`cml1 <ref-classes-cml1>` class, and the 3133use the :ref:`ref-classes-terminal` class.
2623:ref:`devshell <ref-classes-devshell>` class all use the ``terminal``
2624class.
2625 3134
2626.. _ref-classes-testimage*: 3135.. _ref-classes-testimage:
2627 3136
2628``testimage*.bbclass`` 3137``testimage``
2629====================== 3138=============
2630 3139
2631The ``testimage*`` classes support running automated tests against 3140The :ref:`ref-classes-testimage` class supports running automated tests against
2632images using QEMU and on actual hardware. The classes handle loading the 3141images using QEMU and on actual hardware. The classes handle loading the
2633tests and starting the image. To use the classes, you need to perform 3142tests and starting the image. To use the classes, you need to perform
2634steps to set up the environment. 3143steps to set up the environment.
2635 3144
2636.. note:: 3145To enable this class, add the following to your configuration::
2637 3146
2638 Best practices include using :term:`IMAGE_CLASSES` rather than 3147 IMAGE_CLASSES += "testimage"
2639 :term:`INHERIT` to inherit the ``testimage`` class for automated image
2640 testing.
2641 3148
2642The tests are commands that run on the target system over ``ssh``. Each 3149The tests are commands that run on the target system over ``ssh``. Each
2643test is written in Python and makes use of the ``unittest`` module. 3150test is written in Python and makes use of the ``unittest`` module.
2644 3151
2645The ``testimage.bbclass`` runs tests on an image when called using the 3152The :ref:`ref-classes-testimage` class runs tests on an image when called using the
2646following: 3153following::
2647::
2648 3154
2649 $ bitbake -c testimage image 3155 $ bitbake -c testimage image
2650 3156
2651The ``testimage-auto`` class 3157Alternatively, if you wish to have tests automatically run for each image
2652runs tests on an image after the image is constructed (i.e. 3158after it is built, you can set :term:`TESTIMAGE_AUTO`::
2653:term:`TESTIMAGE_AUTO` must be set to "1"). 3159
3160 TESTIMAGE_AUTO = "1"
2654 3161
2655For information on how to enable, run, and create new tests, see the 3162For information on how to enable, run, and create new tests, see the
2656":ref:`dev-manual/common-tasks:performing automated runtime testing`" 3163":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
2657section in the Yocto Project Development Tasks Manual. 3164section in the Yocto Project Development Tasks Manual.
2658 3165
2659.. _ref-classes-testsdk: 3166.. _ref-classes-testsdk:
2660 3167
2661``testsdk.bbclass`` 3168``testsdk``
2662=================== 3169===========
2663 3170
2664This class supports running automated tests against software development 3171This class supports running automated tests against software development
2665kits (SDKs). The ``testsdk`` class runs tests on an SDK when called 3172kits (SDKs). The :ref:`ref-classes-testsdk` class runs tests on an SDK when called
2666using the following: 3173using the following::
2667::
2668 3174
2669 $ bitbake -c testsdk image 3175 $ bitbake -c testsdk image
2670 3176
2671.. note:: 3177.. note::
2672 3178
2673 Best practices include using :term:`IMAGE_CLASSES` rather than 3179 Best practices include using :term:`IMAGE_CLASSES` rather than
2674 :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK 3180 :term:`INHERIT` to inherit the :ref:`ref-classes-testsdk` class for automated SDK
2675 testing. 3181 testing.
2676 3182
2677.. _ref-classes-texinfo: 3183.. _ref-classes-texinfo:
2678 3184
2679``texinfo.bbclass`` 3185``texinfo``
2680=================== 3186===========
2681 3187
2682This class should be inherited by recipes whose upstream packages invoke 3188This class should be inherited by recipes whose upstream packages invoke
2683the ``texinfo`` utilities at build-time. Native and cross recipes are 3189the ``texinfo`` utilities at build-time. Native and cross recipes are
@@ -2694,10 +3200,10 @@ host system.
2694 3200
2695.. _ref-classes-toaster: 3201.. _ref-classes-toaster:
2696 3202
2697``toaster.bbclass`` 3203``toaster``
2698=================== 3204===========
2699 3205
2700The ``toaster`` class collects information about packages and images and 3206The :ref:`ref-classes-toaster` class collects information about packages and images and
2701sends them as events that the BitBake user interface can receive. The 3207sends them as events that the BitBake user interface can receive. The
2702class is enabled when the Toaster user interface is running. 3208class is enabled when the Toaster user interface is running.
2703 3209
@@ -2705,49 +3211,84 @@ This class is not intended to be used directly.
2705 3211
2706.. _ref-classes-toolchain-scripts: 3212.. _ref-classes-toolchain-scripts:
2707 3213
2708``toolchain-scripts.bbclass`` 3214``toolchain-scripts``
2709============================= 3215=====================
2710 3216
2711The ``toolchain-scripts`` class provides the scripts used for setting up 3217The :ref:`ref-classes-toolchain-scripts` class provides the scripts used for setting up
2712the environment for installed SDKs. 3218the environment for installed SDKs.
2713 3219
2714.. _ref-classes-typecheck: 3220.. _ref-classes-typecheck:
2715 3221
2716``typecheck.bbclass`` 3222``typecheck``
2717===================== 3223=============
2718 3224
2719The ``typecheck`` class provides support for validating the values of 3225The :ref:`ref-classes-typecheck` class provides support for validating the values of
2720variables set at the configuration level against their defined types. 3226variables set at the configuration level against their defined types.
2721The OpenEmbedded build system allows you to define the type of a 3227The OpenEmbedded build system allows you to define the type of a
2722variable using the "type" varflag. Here is an example: 3228variable using the "type" varflag. Here is an example::
2723::
2724 3229
2725 IMAGE_FEATURES[type] = "list" 3230 IMAGE_FEATURES[type] = "list"
2726 3231
2727.. _ref-classes-uboot-config: 3232.. _ref-classes-uboot-config:
2728 3233
2729``uboot-config.bbclass`` 3234``uboot-config``
2730======================== 3235================
2731 3236
2732The ``uboot-config`` class provides support for U-Boot configuration for 3237The :ref:`ref-classes-uboot-config` class provides support for U-Boot configuration for
2733a machine. Specify the machine in your recipe as follows: 3238a machine. Specify the machine in your recipe as follows::
2734::
2735 3239
2736 UBOOT_CONFIG ??= <default> 3240 UBOOT_CONFIG ??= <default>
2737 UBOOT_CONFIG[foo] = "config,images" 3241 UBOOT_CONFIG[foo] = "config,images,binary"
2738 3242
2739You can also specify the machine using this method: 3243You can also specify the machine using this method::
2740::
2741 3244
2742 UBOOT_MACHINE = "config" 3245 UBOOT_MACHINE = "config"
2743 3246
2744See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional 3247See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2745information. 3248information.
2746 3249
3250.. _ref-classes-uboot-sign:
3251
3252``uboot-sign``
3253==============
3254
3255The :ref:`ref-classes-uboot-sign` class provides support for U-Boot verified boot.
3256It is intended to be inherited from U-Boot recipes.
3257
3258The variables used by this class are:
3259
3260- :term:`SPL_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when
3261 building the FIT image.
3262- :term:`SPL_SIGN_ENABLE`: enable signing the FIT image.
3263- :term:`SPL_SIGN_KEYDIR`: directory containing the signing keys.
3264- :term:`SPL_SIGN_KEYNAME`: base filename of the signing keys.
3265- :term:`UBOOT_FIT_ADDRESS_CELLS`: ``#address-cells`` value for the FIT image.
3266- :term:`UBOOT_FIT_DESC`: description string encoded into the FIT image.
3267- :term:`UBOOT_FIT_GENERATE_KEYS`: generate the keys if they don't exist yet.
3268- :term:`UBOOT_FIT_HASH_ALG`: hash algorithm for the FIT image.
3269- :term:`UBOOT_FIT_KEY_GENRSA_ARGS`: ``openssl genrsa`` arguments.
3270- :term:`UBOOT_FIT_KEY_REQ_ARGS`: ``openssl req`` arguments.
3271- :term:`UBOOT_FIT_SIGN_ALG`: signature algorithm for the FIT image.
3272- :term:`UBOOT_FIT_SIGN_NUMBITS`: size of the private key for FIT image
3273 signing.
3274- :term:`UBOOT_FIT_KEY_SIGN_PKCS`: algorithm for the public key certificate
3275 for FIT image signing.
3276- :term:`UBOOT_FITIMAGE_ENABLE`: enable the generation of a U-Boot FIT image.
3277- :term:`UBOOT_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when
3278 rebuilding the FIT image containing the kernel.
3279
3280See U-Boot's documentation for details about `verified boot
3281<https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/verified-boot.txt>`__
3282and the `signature process
3283<https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/signature.txt>`__.
3284
3285See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class
3286imitates.
3287
2747.. _ref-classes-uninative: 3288.. _ref-classes-uninative:
2748 3289
2749``uninative.bbclass`` 3290``uninative``
2750===================== 3291=============
2751 3292
2752Attempts to isolate the build system from the host distribution's C 3293Attempts to isolate the build system from the host distribution's C
2753library in order to make re-use of native shared state artifacts across 3294library in order to make re-use of native shared state artifacts across
@@ -2762,21 +3303,21 @@ yourself, publish the resulting tarball (e.g. via HTTP) and set
2762``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an 3303``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2763example, see the ``meta/conf/distro/include/yocto-uninative.inc``. 3304example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2764 3305
2765The ``uninative`` class is also used unconditionally by the extensible 3306The :ref:`ref-classes-uninative` class is also used unconditionally by the extensible
2766SDK. When building the extensible SDK, ``uninative-tarball`` is built 3307SDK. When building the extensible SDK, ``uninative-tarball`` is built
2767and the resulting tarball is included within the SDK. 3308and the resulting tarball is included within the SDK.
2768 3309
2769.. _ref-classes-update-alternatives: 3310.. _ref-classes-update-alternatives:
2770 3311
2771``update-alternatives.bbclass`` 3312``update-alternatives``
2772=============================== 3313=======================
2773 3314
2774The ``update-alternatives`` class helps the alternatives system when 3315The :ref:`ref-classes-update-alternatives` class helps the alternatives system when
2775multiple sources provide the same command. This situation occurs when 3316multiple sources provide the same command. This situation occurs when
2776several programs that have the same or similar function are installed 3317several programs that have the same or similar function are installed
2777with the same name. For example, the ``ar`` command is available from 3318with the same name. For example, the ``ar`` command is available from
2778the ``busybox``, ``binutils`` and ``elfutils`` packages. The 3319the ``busybox``, ``binutils`` and ``elfutils`` packages. The
2779``update-alternatives`` class handles renaming the binaries so that 3320:ref:`ref-classes-update-alternatives` class handles renaming the binaries so that
2780multiple packages can be installed without conflicts. The ``ar`` command 3321multiple packages can be installed without conflicts. The ``ar`` command
2781still works regardless of which packages are installed or subsequently 3322still works regardless of which packages are installed or subsequently
2782removed. The class renames the conflicting binary in each package and 3323removed. The class renames the conflicting binary in each package and
@@ -2796,7 +3337,7 @@ To use this class, you need to define a number of variables:
2796These variables list alternative commands needed by a package, provide 3337These variables list alternative commands needed by a package, provide
2797pathnames for links, default links for targets, and so forth. For 3338pathnames for links, default links for targets, and so forth. For
2798details on how to use this class, see the comments in the 3339details on how to use this class, see the comments in the
2799:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes/update-alternatives.bbclass>` 3340:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes-recipe/update-alternatives.bbclass>`
2800file. 3341file.
2801 3342
2802.. note:: 3343.. note::
@@ -2806,43 +3347,42 @@ file.
2806 3347
2807.. _ref-classes-update-rc.d: 3348.. _ref-classes-update-rc.d:
2808 3349
2809``update-rc.d.bbclass`` 3350``update-rc.d``
2810======================= 3351===============
2811 3352
2812The ``update-rc.d`` class uses ``update-rc.d`` to safely install an 3353The :ref:`ref-classes-update-rc.d` class uses ``update-rc.d`` to safely install an
2813initialization script on behalf of the package. The OpenEmbedded build 3354initialization script on behalf of the package. The OpenEmbedded build
2814system takes care of details such as making sure the script is stopped 3355system takes care of details such as making sure the script is stopped
2815before a package is removed and started when the package is installed. 3356before a package is removed and started when the package is installed.
2816 3357
2817Three variables control this class: ``INITSCRIPT_PACKAGES``, 3358Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
2818``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links 3359:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
2819for details. 3360for details.
2820 3361
2821.. _ref-classes-useradd: 3362.. _ref-classes-useradd:
2822 3363
2823``useradd*.bbclass`` 3364``useradd*``
2824==================== 3365============
2825 3366
2826The ``useradd*`` classes support the addition of users or groups for 3367The :ref:`useradd* <ref-classes-useradd>` classes support the addition of users or groups for
2827usage by the package on the target. For example, if you have packages 3368usage by the package on the target. For example, if you have packages
2828that contain system services that should be run under their own user or 3369that contain system services that should be run under their own user or
2829group, you can use these classes to enable creation of the user or 3370group, you can use these classes to enable creation of the user or
2830group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` 3371group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb
3372</openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>`
2831recipe in the :term:`Source Directory` provides a simple 3373recipe in the :term:`Source Directory` provides a simple
2832example that shows how to add three users and groups to two packages. 3374example that shows how to add three users and groups to two packages.
2833See the ``useradd-example.bb`` recipe for more information on how to use
2834these classes.
2835 3375
2836The ``useradd_base`` class provides basic functionality for user or 3376The :ref:`useradd_base <ref-classes-useradd>` class provides basic functionality for user or
2837groups settings. 3377groups settings.
2838 3378
2839The ``useradd*`` classes support the 3379The :ref:`useradd* <ref-classes-useradd>` classes support the
2840:term:`USERADD_PACKAGES`, 3380:term:`USERADD_PACKAGES`,
2841:term:`USERADD_PARAM`, 3381:term:`USERADD_PARAM`,
2842:term:`GROUPADD_PARAM`, and 3382:term:`GROUPADD_PARAM`, and
2843:term:`GROUPMEMS_PARAM` variables. 3383:term:`GROUPMEMS_PARAM` variables.
2844 3384
2845The ``useradd-staticids`` class supports the addition of users or groups 3385The :ref:`useradd-staticids <ref-classes-useradd>` class supports the addition of users or groups
2846that have static user identification (``uid``) and group identification 3386that have static user identification (``uid``) and group identification
2847(``gid``) values. 3387(``gid``) values.
2848 3388
@@ -2858,61 +3398,58 @@ set static values, the OpenEmbedded build system looks in
2858:term:`BBPATH` for ``files/passwd`` and ``files/group`` 3398:term:`BBPATH` for ``files/passwd`` and ``files/group``
2859files for the values. 3399files for the values.
2860 3400
2861To use static ``uid`` and ``gid`` values, you need to set some 3401To use static ``uid`` and ``gid`` values, you need to set some variables. See
2862variables. See the :term:`USERADDEXTENSION`, 3402the :term:`USERADDEXTENSION`, :term:`USERADD_UID_TABLES`,
2863:term:`USERADD_UID_TABLES`, 3403:term:`USERADD_GID_TABLES`, and :term:`USERADD_ERROR_DYNAMIC` variables.
2864:term:`USERADD_GID_TABLES`, and 3404You can also see the :ref:`ref-classes-useradd` class for additional
2865:term:`USERADD_ERROR_DYNAMIC` variables. 3405information.
2866You can also see the :ref:`useradd <ref-classes-useradd>` class for
2867additional information.
2868 3406
2869.. note:: 3407.. note::
2870 3408
2871 You do not use the ``useradd-staticids`` class directly. You either enable 3409 You do not use the :ref:`useradd-staticids <ref-classes-useradd>` class directly. You either enable
2872 or disable the class by setting the ``USERADDEXTENSION`` variable. If you 3410 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
2873 enable or disable the class in a configured system, :term:`TMPDIR` might 3411 enable or disable the class in a configured system, :term:`TMPDIR` might
2874 contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` 3412 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
2875 directory will correct this condition. 3413 directory will correct this condition.
2876 3414
2877.. _ref-classes-utility-tasks: 3415.. _ref-classes-utility-tasks:
2878 3416
2879``utility-tasks.bbclass`` 3417``utility-tasks``
2880========================= 3418=================
2881 3419
2882The ``utility-tasks`` class provides support for various "utility" type 3420The :ref:`ref-classes-utility-tasks` class provides support for various
2883tasks that are applicable to all recipes, such as 3421"utility" type tasks that are applicable to all recipes, such as
2884:ref:`ref-tasks-clean` and 3422:ref:`ref-tasks-clean` and :ref:`ref-tasks-listtasks`.
2885:ref:`ref-tasks-listtasks`.
2886 3423
2887This class is enabled by default because it is inherited by the 3424This class is enabled by default because it is inherited by the
2888:ref:`base <ref-classes-base>` class. 3425:ref:`ref-classes-base` class.
2889 3426
2890.. _ref-classes-utils: 3427.. _ref-classes-utils:
2891 3428
2892``utils.bbclass`` 3429``utils``
2893================= 3430=========
2894 3431
2895The ``utils`` class provides some useful Python functions that are 3432The :ref:`ref-classes-utils` class provides some useful Python functions that are
2896typically used in inline Python expressions (e.g. ``${@...}``). One 3433typically used in inline Python expressions (e.g. ``${@...}``). One
2897example use is for ``bb.utils.contains()``. 3434example use is for ``bb.utils.contains()``.
2898 3435
2899This class is enabled by default because it is inherited by the 3436This class is enabled by default because it is inherited by the
2900:ref:`base <ref-classes-base>` class. 3437:ref:`ref-classes-base` class.
2901 3438
2902.. _ref-classes-vala: 3439.. _ref-classes-vala:
2903 3440
2904``vala.bbclass`` 3441``vala``
2905================ 3442========
2906 3443
2907The ``vala`` class supports recipes that need to build software written 3444The :ref:`ref-classes-vala` class supports recipes that need to build software written
2908using the Vala programming language. 3445using the Vala programming language.
2909 3446
2910.. _ref-classes-waf: 3447.. _ref-classes-waf:
2911 3448
2912``waf.bbclass`` 3449``waf``
2913=============== 3450=======
2914 3451
2915The ``waf`` class supports recipes that need to build software that uses 3452The :ref:`ref-classes-waf` class supports recipes that need to build software that uses
2916the Waf build system. You can use the 3453the Waf build system. You can use the
2917:term:`EXTRA_OECONF` or 3454:term:`EXTRA_OECONF` or
2918:term:`PACKAGECONFIG_CONFARGS` variables 3455:term:`PACKAGECONFIG_CONFARGS` variables
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 5075f0c224..9319addc3c 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -22,8 +22,7 @@ Getting Help
22 22
23The ``devtool`` command line is organized similarly to Git in that it 23The ``devtool`` command line is organized similarly to Git in that it
24has a number of sub-commands for each function. You can run 24has a number of sub-commands for each function. You can run
25``devtool --help`` to see all the commands: 25``devtool --help`` to see all the commands::
26::
27 26
28 $ devtool -h 27 $ devtool -h
29 NOTE: Starting bitbake server... 28 NOTE: Starting bitbake server...
@@ -79,8 +78,7 @@ has a number of sub-commands for each function. You can run
79 78
80As directed in the general help output, you can 79As directed in the general help output, you can
81get more syntax on a specific command by providing the command name and 80get more syntax on a specific command by providing the command name and
82using "--help": 81using ``--help``::
83::
84 82
85 $ devtool add --help 83 $ devtool add --help
86 NOTE: Starting bitbake server... 84 NOTE: Starting bitbake server...
@@ -128,8 +126,7 @@ common working area used across the tool.
128The following figure shows the workspace structure: 126The following figure shows the workspace structure:
129 127
130.. image:: figures/build-workspace-directory.png 128.. image:: figures/build-workspace-directory.png
131 :align: center 129 :scale: 100%
132 :scale: 70%
133 130
134.. code-block:: none 131.. code-block:: none
135 132
@@ -167,19 +164,18 @@ Adding a New Recipe to the Workspace Layer
167========================================== 164==========================================
168 165
169Use the ``devtool add`` command to add a new recipe to the workspace 166Use the ``devtool add`` command to add a new recipe to the workspace
170layer. The recipe you add should not exist - ``devtool`` creates it for 167layer. The recipe you add should not exist --- ``devtool`` creates it for
171you. The source files the recipe uses should exist in an external area. 168you. The source files the recipe uses should exist in an external area.
172 169
173The following example creates and adds a new recipe named ``jackson`` to 170The following example creates and adds a new recipe named ``jackson`` to
174a workspace layer the tool creates. The source code built by the recipes 171a workspace layer the tool creates. The source code built by the recipes
175resides in ``/home/user/sources/jackson``: 172resides in ``/home/user/sources/jackson``::
176::
177 173
178 $ devtool add jackson /home/user/sources/jackson 174 $ devtool add jackson /home/user/sources/jackson
179 175
180If you add a recipe and the workspace layer does not exist, the command 176If you add a recipe and the workspace layer does not exist, the command
181creates the layer and populates it as described in "`The Workspace Layer 177creates the layer and populates it as described in
182Structure <#devtool-the-workspace-layer-structure>`__" section. 178":ref:`devtool-the-workspace-layer-structure`" section.
183 179
184Running ``devtool add`` when the workspace layer exists causes the tool 180Running ``devtool add`` when the workspace layer exists causes the tool
185to add the recipe, append files, and source files into the existing 181to add the recipe, append files, and source files into the existing
@@ -201,8 +197,7 @@ unpacking files from a remote URI. In some cases, you might want to
201specify a source revision by branch, tag, or commit hash. You can 197specify a source revision by branch, tag, or commit hash. You can
202specify these options when using the ``devtool add`` command: 198specify these options when using the ``devtool add`` command:
203 199
204- To specify a source branch, use the ``--srcbranch`` option: 200- To specify a source branch, use the ``--srcbranch`` option::
205 ::
206 201
207 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson 202 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson
208 203
@@ -210,8 +205,7 @@ specify these options when using the ``devtool add`` command:
210 branch. 205 branch.
211 206
212- To specify a specific tag or commit hash, use the ``--srcrev`` 207- To specify a specific tag or commit hash, use the ``--srcrev``
213 option: 208 option::
214 ::
215 209
216 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson 210 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson
217 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson 211 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
@@ -269,8 +263,7 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
269up as a Git repository if the source had not already been fetched from 263up as a Git repository if the source had not already been fetched from
270Git, checks out a branch for development, and applies any patches from 264Git, checks out a branch for development, and applies any patches from
271the recipe as commits on top. You can use the following command to 265the recipe as commits on top. You can use the following command to
272checkout the source files: 266checkout the source files::
273::
274 267
275 $ devtool modify recipe 268 $ devtool modify recipe
276 269
@@ -290,10 +283,7 @@ is identified using the ``EDITOR`` variable, on the specified recipe.
290When you use the ``devtool edit-recipe`` command, you must supply the 283When you use the ``devtool edit-recipe`` command, you must supply the
291root name of the recipe (i.e. no version, paths, or extensions). Also, 284root name of the recipe (i.e. no version, paths, or extensions). Also,
292the recipe file itself must reside in the workspace as a result of the 285the recipe file itself must reside in the workspace as a result of the
293``devtool add`` or ``devtool upgrade`` commands. However, you can 286``devtool add`` or ``devtool upgrade`` commands.
294override that requirement by using the "-a" or "--any-recipe" option.
295Using either of these options allows you to edit any recipe regardless
296of its location.
297 287
298.. _devtool-updating-a-recipe: 288.. _devtool-updating-a-recipe:
299 289
@@ -309,8 +299,7 @@ compile, and test the code.
309 299
310When you are satisfied with the results and you have committed your 300When you are satisfied with the results and you have committed your
311changes to the Git repository, you can then run the 301changes to the Git repository, you can then run the
312``devtool update-recipe`` to create the patches and update the recipe: 302``devtool update-recipe`` to create the patches and update the recipe::
313::
314 303
315 $ devtool update-recipe recipe 304 $ devtool update-recipe recipe
316 305
@@ -321,8 +310,7 @@ Often, you might want to apply customizations made to your software in
321your own layer rather than apply them to the original recipe. If so, you 310your own layer rather than apply them to the original recipe. If so, you
322can use the ``-a`` or ``--append`` option with the 311can use the ``-a`` or ``--append`` option with the
323``devtool update-recipe`` command. These options allow you to specify 312``devtool update-recipe`` command. These options allow you to specify
324the layer into which to write an append file: 313the layer into which to write an append file::
325::
326 314
327 $ devtool update-recipe recipe -a base-layer-directory 315 $ devtool update-recipe recipe -a base-layer-directory
328 316
@@ -339,27 +327,40 @@ Checking on the Upgrade Status of a Recipe
339Upstream recipes change over time. Consequently, you might find that you 327Upstream recipes change over time. Consequently, you might find that you
340need to determine if you can upgrade a recipe to a newer version. 328need to determine if you can upgrade a recipe to a newer version.
341 329
342To check on the upgrade status of a recipe, use the 330To check on the upgrade status of a recipe, you can use the
343``devtool check-upgrade-status`` command. The command displays a table 331``devtool latest-version recipe`` command, which quickly shows the current
344of your current recipe versions, the latest upstream versions, the email 332version and the latest version available upstream. To get a more global
345address of the recipe's maintainer, and any additional information such 333picture, use the ``devtool check-upgrade-status`` command, which takes a
346as commit hash strings and reasons you might not be able to upgrade a 334list of recipes as input, or no arguments, in which case it checks all
347particular recipe. 335available recipes. This command will only print the recipes for which
336a new upstream version is available. Each such recipe will have its current
337version and latest upstream version, as well as the email of the maintainer
338and any additional information such as the commit hash or reason for not
339being able to upgrade it, displayed in a table.
340
341This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`,
342:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`,
343:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN`
344variables in package recipes.
348 345
349.. note:: 346.. note::
350 347
348 - Most of the time, the above variables are unnecessary. They are only
349 required when upstream does something unusual, and default
350 mechanisms cannot find the new upstream versions.
351
351 - For the ``oe-core`` layer, recipe maintainers come from the 352 - For the ``oe-core`` layer, recipe maintainers come from the
352 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` 353 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>`
353 file. 354 file.
354 355
355 - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` 356 - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)`
356 rather than a 357 rather than a tarball, the commit hash points to the commit that matches
357 tarball, the commit hash points to the commit that matches the 358 the recipe's latest version tag, or in the absence of suitable tags,
358 recipe's latest version tag. 359 to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1``
360 in the recipe).
359 361
360As with all ``devtool`` commands, you can get help on the individual 362As with all ``devtool`` commands, you can get help on the individual
361command: 363command::
362::
363 364
364 $ devtool check-upgrade-status -h 365 $ devtool check-upgrade-status -h
365 NOTE: Starting bitbake server... 366 NOTE: Starting bitbake server...
@@ -377,33 +378,30 @@ command:
377Unless you provide a specific recipe name on the command line, the 378Unless you provide a specific recipe name on the command line, the
378command checks all recipes in all configured layers. 379command checks all recipes in all configured layers.
379 380
380Following is a partial example table that reports on all the recipes. 381Here is a partial example table that reports on all the recipes::
382
383 $ devtool check-upgrade-status
384 ...
385 INFO: bind 9.16.20 9.16.21 Armin Kuster <akuster808@gmail.com>
386 INFO: inetutils 2.1 2.2 Tom Rini <trini@konsulko.com>
387 INFO: iproute2 5.13.0 5.14.0 Changhyeok Bae <changhyeok.bae@gmail.com>
388 INFO: openssl 1.1.1l 3.0.0 Alexander Kanavin <alex.kanavin@gmail.com>
389 INFO: base-passwd 3.5.29 3.5.51 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
390 ...
391
381Notice the reported reason for not upgrading the ``base-passwd`` recipe. 392Notice the reported reason for not upgrading the ``base-passwd`` recipe.
382In this example, while a new version is available upstream, you do not 393In this example, while a new version is available upstream, you do not
383want to use it because the dependency on ``cdebconf`` is not easily 394want to use it because the dependency on ``cdebconf`` is not easily
384satisfied. 395satisfied. Maintainers can explicit the reason that is shown by adding
396the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe.
397See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>`
398for an example::
385 399
386.. note:: 400 RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility"
387
388 When a reason for not upgrading displays, the reason is usually
389 written into the recipe using the ``RECIPE_NO_UPDATE_REASON``
390 variable. See the
391 :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
392 recipe for an example.
393
394::
395 401
396 $ devtool check-upgrade-status 402Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1``
397 ... 403in a recipe when there's currently no way to determine its latest upstream
398 NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> 404version.
399 NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
400 NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
401 .
402 .
403 .
404 NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
405 NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
406 NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
407 405
408.. _devtool-upgrading-a-recipe: 406.. _devtool-upgrading-a-recipe:
409 407
@@ -412,8 +410,8 @@ Upgrading a Recipe
412 410
413As software matures, upstream recipes are upgraded to newer versions. As 411As software matures, upstream recipes are upgraded to newer versions. As
414a developer, you need to keep your local recipes up-to-date with the 412a developer, you need to keep your local recipes up-to-date with the
415upstream version releases. Several methods exist by which you can 413upstream version releases. There are several ways of upgrading recipes.
416upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" 414You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`"
417section of the Yocto Project Development Tasks Manual. This section 415section of the Yocto Project Development Tasks Manual. This section
418overviews the ``devtool upgrade`` command. 416overviews the ``devtool upgrade`` command.
419 417
@@ -441,7 +439,7 @@ You can read more on the ``devtool upgrade`` workflow in the
441":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`" 439":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`"
442section in the Yocto Project Application Development and the Extensible 440section in the Yocto Project Application Development and the Extensible
443Software Development Kit (eSDK) manual. You can also see an example of 441Software Development Kit (eSDK) manual. You can also see an example of
444how to use ``devtool upgrade`` in the ":ref:`dev-manual/common-tasks:using \`\`devtool upgrade\`\``" 442how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``"
445section in the Yocto Project Development Tasks Manual. 443section in the Yocto Project Development Tasks Manual.
446 444
447.. _devtool-resetting-a-recipe: 445.. _devtool-resetting-a-recipe:
@@ -462,8 +460,7 @@ files have been modified, the command preserves the modified files in a
462separate "attic" subdirectory under the workspace layer. 460separate "attic" subdirectory under the workspace layer.
463 461
464Here is an example that resets the workspace directory that contains the 462Here is an example that resets the workspace directory that contains the
465``mtr`` recipe: 463``mtr`` recipe::
466::
467 464
468 $ devtool reset mtr 465 $ devtool reset mtr
469 NOTE: Cleaning sysroot for recipe mtr... 466 NOTE: Cleaning sysroot for recipe mtr...
@@ -481,9 +478,8 @@ Use the ``devtool build`` command to build your recipe. The
481 478
482When you use the ``devtool build`` command, you must supply the root 479When you use the ``devtool build`` command, you must supply the root
483name of the recipe (i.e. do not provide versions, paths, or extensions). 480name of the recipe (i.e. do not provide versions, paths, or extensions).
484You can use either the "-s" or the "--disable-parallel-make" options to 481You can use either the ``-s`` or the ``--disable-parallel-make`` options to
485disable parallel makes during the build. Here is an example: 482disable parallel makes during the build. Here is an example::
486::
487 483
488 $ devtool build recipe 484 $ devtool build recipe
489 485
@@ -499,8 +495,7 @@ device for testing. For proper integration into a final image, you need
499to edit your custom image recipe appropriately. 495to edit your custom image recipe appropriately.
500 496
501When you use the ``devtool build-image`` command, you must supply the 497When you use the ``devtool build-image`` command, you must supply the
502name of the image. This command has no command line options: 498name of the image. This command has no command line options::
503::
504 499
505 $ devtool build-image image 500 $ devtool build-image image
506 501
@@ -510,8 +505,7 @@ Deploying Your Software on the Target Machine
510============================================= 505=============================================
511 506
512Use the ``devtool deploy-target`` command to deploy the recipe's build 507Use the ``devtool deploy-target`` command to deploy the recipe's build
513output to the live target machine: 508output to the live target machine::
514::
515 509
516 $ devtool deploy-target recipe target 510 $ devtool deploy-target recipe target
517 511
@@ -529,8 +523,8 @@ you do, the package manager is bypassed.
529 should never use it to update an image that will be used in 523 should never use it to update an image that will be used in
530 production. 524 production.
531 525
532Some conditions exist that could prevent a deployed application from 526Some conditions could prevent a deployed application from
533behaving as expected. When both of the following conditions exist, your 527behaving as expected. When both of the following conditions are met, your
534application has the potential to not behave correctly when run on the 528application has the potential to not behave correctly when run on the
535target: 529target:
536 530
@@ -541,7 +535,7 @@ target:
541- The target does not physically have the packages on which the 535- The target does not physically have the packages on which the
542 application depends installed. 536 application depends installed.
543 537
544If both of these conditions exist, your application will not behave as 538If both of these conditions are met, your application will not behave as
545expected. The reason for this misbehavior is because the 539expected. The reason for this misbehavior is because the
546``devtool deploy-target`` command does not deploy the packages (e.g. 540``devtool deploy-target`` command does not deploy the packages (e.g.
547libraries) on which your new application depends. The assumption is that 541libraries) on which your new application depends. The assumption is that
@@ -562,8 +556,7 @@ Use the ``devtool undeploy-target`` command to remove deployed build
562output from the target machine. For the ``devtool undeploy-target`` 556output from the target machine. For the ``devtool undeploy-target``
563command to work, you must have previously used the 557command to work, you must have previously used the
564":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`" 558":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`"
565command. 559command::
566::
567 560
568 $ devtool undeploy-target recipe target 561 $ devtool undeploy-target recipe target
569 562
@@ -582,15 +575,13 @@ new workspace layer, it is populated with the ``README`` file and the
582``conf`` directory only. 575``conf`` directory only.
583 576
584The following example creates a new workspace layer in your current 577The following example creates a new workspace layer in your current
585working and by default names the workspace layer "workspace": 578working and by default names the workspace layer "workspace"::
586::
587 579
588 $ devtool create-workspace 580 $ devtool create-workspace
589 581
590You can create a workspace layer anywhere by supplying a pathname with 582You can create a workspace layer anywhere by supplying a pathname with
591the command. The following command creates a new workspace layer named 583the command. The following command creates a new workspace layer named
592"new-workspace": 584"new-workspace"::
593::
594 585
595 $ devtool create-workspace /home/scottrif/new-workspace 586 $ devtool create-workspace /home/scottrif/new-workspace
596 587
@@ -603,15 +594,13 @@ Use the ``devtool status`` command to list the recipes currently in your
603workspace. Information includes the paths to their respective external 594workspace. Information includes the paths to their respective external
604source trees. 595source trees.
605 596
606The ``devtool status`` command has no command-line options: 597The ``devtool status`` command has no command-line options::
607::
608 598
609 $ devtool status 599 $ devtool status
610 600
611Following is sample output after using 601Here is sample output after using
612:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` 602:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>`
613to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory: 603to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
614::
615 604
616 $ devtool status 605 $ devtool status
617 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) 606 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb
deleted file mode 100644
index aa2beb9a9b..0000000000
--- a/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb
+++ /dev/null
@@ -1,9 +0,0 @@
1DESCRIPTION = "GNU Helloworld application"
2SECTION = "examples"
3LICENSE = "GPLv3"
4LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504"
5
6SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
7SRC_URI[sha256sum] = "31e066137a962676e89f69d1b65382de95a7ef7d914b8cb956f41ea72e0f516b"
8
9inherit autotools-brokensep gettext
diff --git a/documentation/ref-manual/examples/hello-single/files/helloworld.c b/documentation/ref-manual/examples/hello-single/files/helloworld.c
deleted file mode 100644
index fc7169b7b8..0000000000
--- a/documentation/ref-manual/examples/hello-single/files/helloworld.c
+++ /dev/null
@@ -1,8 +0,0 @@
1#include <stdio.h>
2
3int main(void)
4{
5 printf("Hello world!\n");
6
7 return 0;
8}
diff --git a/documentation/ref-manual/examples/hello-single/hello.bb b/documentation/ref-manual/examples/hello-single/hello.bb
deleted file mode 100644
index 90d3aefd86..0000000000
--- a/documentation/ref-manual/examples/hello-single/hello.bb
+++ /dev/null
@@ -1,17 +0,0 @@
1DESCRIPTION = "Simple helloworld application"
2SECTION = "examples"
3LICENSE = "MIT"
4LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
5
6SRC_URI = "file://helloworld.c"
7
8S = "${WORKDIR}"
9
10do_compile() {
11 ${CC} ${LDFLAGS} helloworld.c -o helloworld
12}
13
14do_install() {
15 install -d ${D}${bindir}
16 install -m 0755 helloworld ${D}${bindir}
17}
diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
deleted file mode 100644
index c0c8986405..0000000000
--- a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
+++ /dev/null
@@ -1,14 +0,0 @@
1require recipes-graphics/xorg-lib/xorg-lib-common.inc
2
3DESCRIPTION = "X11 Pixmap library"
4LICENSE = "X-BSD"
5LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
6DEPENDS += "libxext"
7PR = "r2"
8PE = "1"
9
10XORG_PN = "libXpm"
11
12PACKAGES =+ "sxpm cxpm"
13FILES_cxpm = "${bindir}/cxpm"
14FILES_sxpm = "${bindir}/sxpm"
diff --git a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
deleted file mode 100644
index 5d05a437a4..0000000000
--- a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
+++ /dev/null
@@ -1,15 +0,0 @@
1DESCRIPTION = "Tools for managing memory technology devices."
2SECTION = "base"
3DEPENDS = "zlib"
4HOMEPAGE = "http://www.linux-mtd.infradead.org/"
5LICENSE = "GPLv2"
6LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
7 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
8
9SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
10
11CFLAGS_prepend = "-I ${S}/include "
12
13do_install() {
14 oe_runmake install DESTDIR=${D}
15}
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 34b26ee3ef..bab284bbfd 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -4,9 +4,15 @@
4FAQ 4FAQ
5*** 5***
6 6
7**Q:** How does Poky differ from :oe_home:`OpenEmbedded <>`? 7.. contents::
8 8
9**A:** The term ``Poky`` refers to the specific reference build 9General questions
10=================
11
12How does Poky differ from OpenEmbedded?
13---------------------------------------
14
15The term ``Poky`` refers to the specific reference build
10system that the Yocto Project provides. Poky is based on 16system that the Yocto Project provides. Poky is based on
11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the 17:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
12generic term used here for the build system is the "OpenEmbedded build 18generic term used here for the build system is the "OpenEmbedded build
@@ -15,19 +21,10 @@ OpenEmbedded, with changes always being merged to OE-Core or BitBake
15first before being pulled back into Poky. This practice benefits both 21first before being pulled back into Poky. This practice benefits both
16projects immediately. 22projects immediately.
17 23
18**Q:** My development system does not meet the required Git, tar, and 24How can you claim Poky / OpenEmbedded-Core is stable?
19Python versions. In particular, I do not have Python 3.5.0 or greater. 25-----------------------------------------------------
20Can I still use the Yocto Project?
21
22**A:** You can get the required tools on your host development system a
23couple different ways (i.e. building a tarball or downloading a
24tarball). See the
25":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
26section for steps on how to update your build tools.
27
28**Q:** How can you claim Poky / OpenEmbedded-Core is stable?
29 26
30**A:** There are three areas that help with stability; 27There are three areas that help with stability;
31 28
32- The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and 29- The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and
33 focused, containing around 830 recipes as opposed to the thousands 30 focused, containing around 830 recipes as opposed to the thousands
@@ -37,95 +34,110 @@ section for steps on how to update your build tools.
37- The Yocto Project team runs manual and automated tests using a small, 34- The Yocto Project team runs manual and automated tests using a small,
38 fixed set of reference hardware as well as emulated targets. 35 fixed set of reference hardware as well as emulated targets.
39 36
40- The Yocto Project uses an autobuilder, which provides continuous 37- The Yocto Project uses an :yocto_ab:`autobuilder <>`, which provides
41 build and integration tests. 38 continuous build and integration tests.
42 39
43**Q:** How do I get support for my board added to the Yocto Project? 40Are there any products built using the OpenEmbedded build system?
41-----------------------------------------------------------------
44 42
45**A:** Support for an additional board is added by creating a Board 43See :yocto_wiki:`Products that use the Yocto Project
46Support Package (BSP) layer for it. For more information on how to 44</Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project
47create a BSP layer, see the 45Wiki. Don't hesitate to contribute to this page if you know other such
48":ref:`dev-manual/common-tasks:understanding and creating layers`" 46products.
49section in the Yocto Project Development Tasks Manual and the
50:doc:`/bsp-guide/index`.
51 47
52Usually, if the board is not completely exotic, adding support in the 48Building environment
53Yocto Project is fairly straightforward. 49====================
54 50
55**Q:** Are there any products built using the OpenEmbedded build system? 51Missing dependencies on the development system?
52-----------------------------------------------
56 53
57**A:** The software running on the `Vernier 54If your development system does not meet the required Git, tar, and
58LabQuest <https://vernier.com/labquest/>`__ is built using the 55Python versions, you can get the required tools on your host development
59OpenEmbedded build system. See the `Vernier 56system in different ways (i.e. building a tarball or downloading a
60LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website 57tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`"
61for more information. There are a number of pre-production devices using 58section for steps on how to update your build tools.
62the OpenEmbedded build system and the Yocto Project team announces them
63as soon as they are released.
64 59
65**Q:** What does the OpenEmbedded build system produce as output? 60How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server?
61-----------------------------------------------------------------------------------------
66 62
67**A:** Because you can use the same set of recipes to create output of 63The way the build system obtains source code is highly
68various formats, the output of an OpenEmbedded build depends on how you 64configurable. You can setup the build system to get source code in most
69start it. Usually, the output is a flashable image ready for the target 65environments if HTTP transport is available.
70device.
71 66
72**Q:** How do I add my package to the Yocto Project? 67When the build system searches for source code, it first tries the local
68download directory. If that location fails, Poky tries
69:term:`PREMIRRORS`, the upstream source, and then
70:term:`MIRRORS` in that order.
73 71
74**A:** To add a package, you need to create a BitBake recipe. For 72Assuming your distribution is "poky", the OpenEmbedded build system uses
75information on how to create a BitBake recipe, see the 73the Yocto Project source :term:`PREMIRRORS` by default for SCM-based
76":ref:`dev-manual/common-tasks:writing a new recipe`" 74sources, upstreams for normal tarballs, and then falls back to a number
77section in the Yocto Project Development Tasks Manual. 75of other mirrors including the Yocto Project source mirror if those
76fail.
77
78As an example, you could add a specific server for the build system to
79attempt before any others by adding something like the following to the
80``local.conf`` configuration file::
78 81
79**Q:** Do I have to reflash my entire board with a new Yocto Project 82 PREMIRRORS:prepend = "\
80image when recompiling a package? 83 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
84 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
85 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
86 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
81 87
82**A:** The OpenEmbedded build system can build packages in various 88These changes cause the build system to intercept Git, FTP, HTTP, and
83formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can 89HTTPS requests and direct them to the ``http://`` sources mirror. You
84then upgrade the packages using the package tools on the device, much 90can use ``file://`` URLs to point to local directories or network shares
85like on a desktop distribution such as Ubuntu or Fedora. However, 91as well.
86package management on the target is entirely optional.
87 92
88**Q:** I see the error 93Another option is to set::
89'``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is
90wrong?
91 94
92**A:** You are probably running the build on an NTFS filesystem. Use 95 BB_NO_NETWORK = "1"
93``ext2``, ``ext3``, or ``ext4`` instead.
94 96
95**Q:** I see lots of 404 responses for files when the OpenEmbedded build 97This statement tells BitBake to issue an error
96system is trying to download sources. Is something wrong? 98instead of trying to access the Internet. This technique is useful if
99you want to ensure code builds only from local sources.
97 100
98**A:** Nothing is wrong. The OpenEmbedded build system checks any 101Here is another technique::
99configured source mirrors before downloading from the upstream sources. 102
100The build system does this searching for both source archives and 103 BB_FETCH_PREMIRRORONLY = "1"
101pre-checked out versions of SCM-managed software. These checks help in
102large installations because it can reduce load on the SCM servers
103themselves. The address above is one of the default mirrors configured
104into the build system. Consequently, if an upstream source disappears,
105the team can place sources there so builds continue to work.
106 104
107**Q:** I have machine-specific data in a package for one machine only 105This statement limits the build system to pulling source from the
108but the package is being marked as machine-specific in all cases, how do 106:term:`PREMIRRORS` only. Again, this technique is useful for reproducing
109I prevent this? 107builds.
110 108
111**A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file 109Here is yet another technique::
112but make sure the package is manually marked as machine-specific for the
113case that needs it. The code that handles
114``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the
115``meta/classes/base.bbclass`` file.
116 110
117**Q:** I'm behind a firewall and need to use a proxy server. How do I do 111 BB_GENERATE_MIRROR_TARBALLS = "1"
118that? 112
113This statement tells the build system to generate mirror tarballs. This
114technique is useful if you want to create a mirror server. If not,
115however, the technique can simply waste time during the build.
119 116
120**A:** Most source fetching by the OpenEmbedded build system is done by 117Finally, consider an example where you are behind an HTTP-only firewall.
118You could make the following changes to the ``local.conf`` configuration
119file as long as the :term:`PREMIRRORS` server is current::
120
121 PREMIRRORS:prepend = "\
122 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
123 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
124 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
125 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
126 BB_FETCH_PREMIRRORONLY = "1"
127
128These changes would cause the build system to successfully fetch source
129over HTTP and any network accesses to anything other than the
130:term:`PREMIRRORS` would fail.
131
132Most source fetching by the OpenEmbedded build system is done by
121``wget`` and you therefore need to specify the proxy settings in a 133``wget`` and you therefore need to specify the proxy settings in a
122``.wgetrc`` file, which can be in your home directory if you are a 134``.wgetrc`` file, which can be in your home directory if you are a
123single user or can be in ``/usr/local/etc/wgetrc`` as a global user 135single user or can be in ``/usr/local/etc/wgetrc`` as a global user
124file. 136file.
125 137
126Following is the applicable code for setting various proxy types in the 138Here is the applicable code for setting various proxy types in the
127``.wgetrc`` file. By default, these settings are disabled with comments. 139``.wgetrc`` file. By default, these settings are disabled with comments.
128To use them, remove the comments: :: 140To use them, remove the comments::
129 141
130 # You can set the default proxies for Wget to use for http, https, and ftp. 142 # You can set the default proxies for Wget to use for http, https, and ftp.
131 # They will override the value in the environment. 143 # They will override the value in the environment.
@@ -136,24 +148,53 @@ To use them, remove the comments: ::
136 # If you do not want to use proxy at all, set this to off. 148 # If you do not want to use proxy at all, set this to off.
137 #use_proxy = on 149 #use_proxy = on
138 150
151The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``,
152and ``all_proxy`` set as to standard shell environment variables to redirect
153requests through proxy servers.
154
139The Yocto Project also includes a 155The Yocto Project also includes a
140``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS 156``meta-poky/conf/templates/default/site.conf.sample`` file that shows
141and Git proxy servers if needed. For more information on setting up 157how to configure CVS and Git proxy servers if needed.
142various proxy types and configuring proxy servers, see the
143":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
144Wiki page.
145 158
146**Q:** What's the difference between target and target\ ``-native``? 159.. note::
147 160
148**A:** The ``*-native`` targets are designed to run on the system being 161 You can find more information on the
149used for the build. These are usually tools that are needed to assist 162 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
150the build in some way such as ``quilt-native``, which is used to apply 163 Wiki page.
151patches. The non-native version is the one that runs on the target 164
152device. 165Using the OpenEmbedded Build system
166===================================
167
168How do I use an external toolchain?
169-----------------------------------
170
171See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`"
172section in the Development Task manual.
173
174Why do I get chmod permission issues?
175-------------------------------------
153 176
154**Q:** I'm seeing random build failures. Help?! 177If you see the error
178``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``,
179you are probably running the build on an NTFS filesystem. Instead,
180run the build system on a partition with a modern Linux filesystem such as
181``ext4``, ``btrfs`` or ``xfs``.
155 182
156**A:** If the same build is failing in totally different and random 183I see many 404 errors trying to download sources. Is anything wrong?
184--------------------------------------------------------------------
185
186Nothing is wrong. The OpenEmbedded build system checks any
187configured source mirrors before downloading from the upstream sources.
188The build system does this searching for both source archives and
189pre-checked out versions of SCM-managed software. These checks help in
190large installations because it can reduce load on the SCM servers
191themselves. This can also allow builds to continue to work if an
192upstream source disappears.
193
194Why do I get random build failures?
195-----------------------------------
196
197If the same build is failing in totally different and random
157ways, the most likely explanation is: 198ways, the most likely explanation is:
158 199
159- The hardware you are running the build on has some problem. 200- The hardware you are running the build on has some problem.
@@ -166,222 +207,139 @@ causes lots of network, disk and CPU activity and is sensitive to even
166single-bit failures in any of these areas. True random failures have 207single-bit failures in any of these areas. True random failures have
167always been traced back to hardware or virtualization issues. 208always been traced back to hardware or virtualization issues.
168 209
169**Q:** When I try to build a native recipe, the build fails with 210Why does the build fail with ``iconv.h`` problems?
170``iconv.h`` problems. 211--------------------------------------------------
171 212
172**A:** If you get an error message that indicates GNU ``libiconv`` is 213When you try to build a native recipe, you may get an error message that
173not in use but ``iconv.h`` has been included from ``libiconv``, you need 214indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been
174to check to see if you have a previously installed version of the header 215included from ``libiconv``::
175file in ``/usr/local/include``.
176::
177 216
178 #error GNU libiconv not in use but included iconv.h is from libiconv 217 #error GNU libiconv not in use but included iconv.h is from libiconv
179 218
180If you find a previously installed 219When this happens, you need to check whether you have a previously
181file, you should either uninstall it or temporarily rename it and try 220installed version of the header file in ``/usr/local/include/``.
182the build again. 221If that's the case, you should either uninstall it or temporarily rename
222it and try the build again.
183 223
184This issue is just a single manifestation of "system leakage" issues 224This issue is just a single manifestation of "system leakage" issues
185caused when the OpenEmbedded build system finds and uses previously 225caused when the OpenEmbedded build system finds and uses previously
186installed files during a native build. This type of issue might not be 226installed files during a native build. This type of issue might not be
187limited to ``iconv.h``. Be sure that leakage cannot occur from 227limited to ``iconv.h``. Make sure that leakage cannot occur from
188``/usr/local/include`` and ``/opt`` locations. 228``/usr/local/include`` and ``/opt`` locations.
189 229
190**Q:** What do we need to ship for license compliance? 230Why don't other recipes find the files provided by my ``*-native`` recipe?
191 231--------------------------------------------------------------------------
192**A:** This is a difficult question and you need to consult your lawyer
193for the answer for your specific case. It is worth bearing in mind that
194for GPL compliance, there needs to be enough information shipped to
195allow someone else to rebuild and produce the same end result you are
196shipping. This means sharing the source code, any patches applied to it,
197and also any configuration information about how that package was
198configured and built.
199
200You can find more information on licensing in the
201":ref:`overview-manual/development-environment:licensing`"
202section in the Yocto
203Project Overview and Concepts Manual and also in the
204":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
205section in the Yocto Project Development Tasks Manual.
206
207**Q:** How do I disable the cursor on my touchscreen device?
208
209**A:** You need to create a form factor file as described in the
210":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
211the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
212the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
213::
214
215 HAVE_TOUCHSCREEN=1
216
217**Q:** How do I make sure connected network interfaces are brought up by
218default?
219
220**A:** The default interfaces file provided by the netbase recipe does
221not automatically bring up network interfaces. Therefore, you will need
222to add a BSP-specific netbase that includes an interfaces file. See the
223":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
224the Yocto Project Board Support Packages (BSP) Developer's Guide for
225information on creating these types of miscellaneous recipe files.
226
227For example, add the following files to your layer: ::
228
229 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
230 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
231
232**Q:** How do I create images with more free space?
233
234**A:** By default, the OpenEmbedded build system creates images that are
2351.3 times the size of the populated root filesystem. To affect the image
236size, you need to set various configurations:
237
238- *Image Size:* The OpenEmbedded build system uses the
239 :term:`IMAGE_ROOTFS_SIZE` variable to define
240 the size of the image in Kbytes. The build system determines the size
241 by taking into account the initial root filesystem size before any
242 modifications such as requested size for the image and any requested
243 additional free disk space to be added to the image.
244
245- *Overhead:* Use the
246 :term:`IMAGE_OVERHEAD_FACTOR` variable
247 to define the multiplier that the build system applies to the initial
248 image size, which is 1.3 by default.
249
250- *Additional Free Space:* Use the
251 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
252 variable to add additional free space to the image. The build system
253 adds this space to the image after it determines its
254 ``IMAGE_ROOTFS_SIZE``.
255
256**Q:** Why don't you support directories with spaces in the pathnames?
257
258**A:** The Yocto Project team has tried to do this before but too many
259of the tools the OpenEmbedded build system depends on, such as
260``autoconf``, break when they find spaces in pathnames. Until that
261situation changes, the team will not support spaces in pathnames.
262
263**Q:** How do I use an external toolchain?
264
265**A:** The toolchain configuration is very flexible and customizable. It
266is primarily controlled with the ``TCMODE`` variable. This variable
267controls which ``tcmode-*.inc`` file to include from the
268``meta/conf/distro/include`` directory within the :term:`Source Directory`.
269
270The default value of ``TCMODE`` is "default", which tells the
271OpenEmbedded build system to use its internally built toolchain (i.e.
272``tcmode-default.inc``). However, other patterns are accepted. In
273particular, "external-\*" refers to external toolchains. One example is
274the Sourcery G++ Toolchain. The support for this toolchain resides in
275the separate ``meta-sourcery`` layer at
276https://github.com/MentorEmbedded/meta-sourcery/.
277
278In addition to the toolchain configuration, you also need a
279corresponding toolchain recipe file. This recipe file needs to package
280up any pre-built objects in the toolchain such as ``libgcc``,
281``libstdcc++``, any locales, and ``libc``.
282
283**Q:** How does the OpenEmbedded build system obtain source code and
284will it work behind my firewall or proxy server?
285 232
286**A:** The way the build system obtains source code is highly 233Files provided by your native recipe could be missing from the native
287configurable. You can setup the build system to get source code in most 234sysroot, your recipe could also be installing to the wrong place, or you
288environments if HTTP transport is available. 235could be getting permission errors during the :ref:`ref-tasks-install`
289 236task in your recipe.
290When the build system searches for source code, it first tries the local
291download directory. If that location fails, Poky tries
292:term:`PREMIRRORS`, the upstream source, and then
293:term:`MIRRORS` in that order.
294
295Assuming your distribution is "poky", the OpenEmbedded build system uses
296the Yocto Project source ``PREMIRRORS`` by default for SCM-based
297sources, upstreams for normal tarballs, and then falls back to a number
298of other mirrors including the Yocto Project source mirror if those
299fail.
300 237
301As an example, you could add a specific server for the build system to 238This situation happens when the build system used by a package does not
302attempt before any others by adding something like the following to the 239recognize the environment variables supplied to it by :term:`BitBake`. The
303``local.conf`` configuration file: :: 240incident that prompted this FAQ entry involved a Makefile that used an
241environment variable named ``BINDIR`` instead of the more standard
242variable ``bindir``. The makefile's hardcoded default value of
243"/usr/bin" worked most of the time, but not for the recipe's ``-native``
244variant. For another example, permission errors might be caused by a
245Makefile that ignores ``DESTDIR`` or uses a different name for that
246environment variable. Check the build system of the package to see if
247these kinds of issues exist.
304 248
305 PREMIRRORS_prepend = "\ 249Can I get rid of build output so I can start over?
306 git://.*/.* http://www.yoctoproject.org/sources/ \n \ 250--------------------------------------------------
307 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
308 http://.*/.* http://www.yoctoproject.org/sources/ \n \
309 https://.*/.* http://www.yoctoproject.org/sources/ \n"
310 251
311These changes cause the build system to intercept Git, FTP, HTTP, and 252Yes --- you can easily do this. When you use BitBake to build an
312HTTPS requests and direct them to the ``http://`` sources mirror. You 253image, all the build output goes into the directory created when you run
313can use ``file://`` URLs to point to local directories or network shares 254the build environment setup script (i.e. :ref:`structure-core-script`).
314as well. 255By default, this :term:`Build Directory` is named ``build`` but can be named
256anything you want.
315 257
316Aside from the previous technique, these options also exist: 258Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the
317:: 259build output yet preserve any source code or downloaded files from
260previous builds, simply remove the ``tmp`` directory.
318 261
319 BB_NO_NETWORK = "1" 262Customizing generated images
263============================
320 264
321This statement tells BitBake to issue an error 265What does the OpenEmbedded build system produce as output?
322instead of trying to access the Internet. This technique is useful if 266----------------------------------------------------------
323you want to ensure code builds only from local sources.
324 267
325Here is another technique: 268Because you can use the same set of recipes to create output of
326:: 269various formats, the output of an OpenEmbedded build depends on how you
270start it. Usually, the output is a flashable image ready for the target
271device.
327 272
328 BB_FETCH_PREMIRRORONLY = "1" 273How do I make the Yocto Project support my board?
274-------------------------------------------------
329 275
330This statement 276Support for an additional board is added by creating a Board
331limits the build system to pulling source from the ``PREMIRRORS`` only. 277Support Package (BSP) layer for it. For more information on how to
332Again, this technique is useful for reproducing builds. 278create a BSP layer, see the
279":ref:`dev-manual/layers:understanding and creating layers`"
280section in the Yocto Project Development Tasks Manual and the
281:doc:`/bsp-guide/index`.
333 282
334Here is another technique: 283Usually, if the board is not completely exotic, adding support in the
335:: 284Yocto Project is fairly straightforward.
336 285
337 BB_GENERATE_MIRROR_TARBALLS = "1" 286How do I make the Yocto Project support my package?
287---------------------------------------------------
338 288
339This 289To add a package, you need to create a BitBake recipe. For
340statement tells the build system to generate mirror tarballs. This 290information on how to create a BitBake recipe, see the
341technique is useful if you want to create a mirror server. If not, 291":ref:`dev-manual/new-recipe:writing a new recipe`"
342however, the technique can simply waste time during the build. 292section in the Yocto Project Development Tasks Manual.
343 293
344Finally, consider an example where you are behind an HTTP-only firewall. 294What do I need to ship for license compliance?
345You could make the following changes to the ``local.conf`` configuration 295----------------------------------------------
346file as long as the ``PREMIRRORS`` server is current: ::
347 296
348 PREMIRRORS_prepend = "\ 297This is a difficult question and you need to consult your lawyer
349 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ 298for the answer for your specific case. It is worth bearing in mind that
350 http://.*/.* http://www.yoctoproject.org/sources/ \n \ 299for GPL compliance, there needs to be enough information shipped to
351 https://.*/.* http://www.yoctoproject.org/sources/ \n" 300allow someone else to rebuild and produce the same end result you are
352 BB_FETCH_PREMIRRORONLY = "1" 301shipping. This means sharing the source code, any patches applied to it,
302and also any configuration information about how that package was
303configured and built.
353 304
354These changes would cause the build system to successfully fetch source 305You can find more information on licensing in the
355over HTTP and any network accesses to anything other than the 306":ref:`overview-manual/development-environment:licensing`"
356``PREMIRRORS`` would fail. 307section in the Yocto Project Overview and Concepts Manual and also in the
308":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`"
309section in the Yocto Project Development Tasks Manual.
357 310
358The build system also honors the standard shell environment variables 311Do I have to make a full reflash after recompiling one package?
359``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to 312---------------------------------------------------------------
360redirect requests through proxy servers.
361 313
362.. note:: 314The OpenEmbedded build system can build packages in various
315formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can
316then upgrade only the modified packages using the package tools on the device,
317much like on a desktop distribution such as Ubuntu or Fedora. However,
318package management on the target is entirely optional.
363 319
364 You can find more information on the 320How to prevent my package from being marked as machine specific?
365 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 321----------------------------------------------------------------
366 Wiki page.
367 322
368**Q:** Can I get rid of build output so I can start over? 323If you have machine-specific data in a package for one machine only
324but the package is being marked as machine-specific in all cases,
325you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file.
326However, but make sure the package is manually marked as machine-specific for the
327case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
328is in the ``meta/classes-global/base.bbclass`` file.
369 329
370**A:** Yes - you can easily do this. When you use BitBake to build an 330What's the difference between ``target`` and ``target-native``?
371image, all the build output goes into the directory created when you run 331---------------------------------------------------------------
372the build environment setup script (i.e.
373:ref:`structure-core-script`). By default, this :term:`Build Directory`
374is named ``build`` but can be named
375anything you want.
376 332
377Within the Build Directory, is the ``tmp`` directory. To remove all the 333The ``*-native`` targets are designed to run on the system being
378build output yet preserve any source code or downloaded files from 334used for the build. These are usually tools that are needed to assist
379previous builds, simply remove the ``tmp`` directory. 335the build in some way such as ``quilt-native``, which is used to apply
336patches. The non-native version is the one that runs on the target
337device.
380 338
381**Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for 339Why do ``${bindir}`` and ``${libdir}`` have strange values for ``-native`` recipes?
382``-native`` recipes? 340-----------------------------------------------------------------------------------
383 341
384**A:** Executables and libraries might need to be used from a directory 342Executables and libraries might need to be used from a directory
385other than the directory into which they were initially installed. 343other than the directory into which they were initially installed.
386Complicating this situation is the fact that sometimes these executables 344Complicating this situation is the fact that sometimes these executables
387and libraries are compiled with the expectation of being run from that 345and libraries are compiled with the expectation of being run from that
@@ -408,20 +366,13 @@ system of that image. Thus, the build system provides a value of
408forth. 366forth.
409 367
410Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. 368Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`.
411However, when the recipe builds a 369However, when the recipe builds a native program (i.e. one that is
412native program (i.e. one that is intended to run on the build machine), 370intended to run on the build machine), that program is never installed
413that program is never installed directly to the build machine's root 371directly to the build machine's root file system. Consequently, the build
414file system. Consequently, the build system uses paths within the Build 372system uses paths within the Build Directory for ``DESTDIR``, ``bindir``
415Directory for ``DESTDIR``, ``bindir`` and related variables. To better 373and related variables. To better understand this, consider the following
416understand this, consider the following two paths where the first is 374two paths (artificially broken across lines for readability) where the
417relatively normal and the second is not: 375first is relatively normal and the second is not::
418
419.. note::
420
421 Due to these lengthy examples, the paths are artificially broken
422 across lines for readability.
423
424::
425 376
426 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 377 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
427 1.2.8-r0/sysroot-destdir/usr/bin 378 1.2.8-r0/sysroot-destdir/usr/bin
@@ -430,35 +381,76 @@ relatively normal and the second is not:
430 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ 381 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
431 build/tmp/sysroots/x86_64-linux/usr/bin 382 build/tmp/sysroots/x86_64-linux/usr/bin
432 383
433Even if the paths look unusual, 384Even if the paths look unusual, they both are correct --- the first for
434they both are correct - the first for a target and the second for a 385a target and the second for a native recipe. These paths are a consequence
435native recipe. These paths are a consequence of the ``DESTDIR`` 386of the ``DESTDIR`` mechanism and while they appear strange, they are correct
436mechanism and while they appear strange, they are correct and in 387and in practice very effective.
437practice very effective.
438 388
439**Q:** The files provided by my ``*-native`` recipe do not appear to be 389How do I create images with more free space?
440available to other recipes. Files are missing from the native sysroot, 390--------------------------------------------
441my recipe is installing to the wrong place, or I am getting permissions
442errors during the do_install task in my recipe! What is wrong?
443 391
444**A:** This situation results when a build system does not recognize the 392By default, the OpenEmbedded build system creates images that are
445environment variables supplied to it by :term:`BitBake`. The 3931.3 times the size of the populated root filesystem. To affect the image
446incident that prompted this FAQ entry involved a Makefile that used an 394size, you need to set various configurations:
447environment variable named ``BINDIR`` instead of the more standard 395
448variable ``bindir``. The makefile's hardcoded default value of 396- *Image Size:* The OpenEmbedded build system uses the
449"/usr/bin" worked most of the time, but not for the recipe's ``-native`` 397 :term:`IMAGE_ROOTFS_SIZE` variable to define
450variant. For another example, permissions errors might be caused by a 398 the size of the image in Kbytes. The build system determines the size
451Makefile that ignores ``DESTDIR`` or uses a different name for that 399 by taking into account the initial root filesystem size before any
452environment variable. Check the the build system to see if these kinds 400 modifications such as requested size for the image and any requested
453of issues exist. 401 additional free disk space to be added to the image.
454 402
455**Q:** I'm adding a binary in a recipe but it's different in the image, what is 403- *Overhead:* Use the
456changing it? 404 :term:`IMAGE_OVERHEAD_FACTOR` variable
457 405 to define the multiplier that the build system applies to the initial
458**A:** The first most obvious change is the system stripping debug symbols from 406 image size, which is 1.3 by default.
459it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being stripped and/or 407
460:term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols being split into a separate 408- *Additional Free Space:* Use the
461file will ensure the binary is unchanged. The other less obvious thing that can 409 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
462happen is prelinking of the image. This is set by default in local.conf via 410 variable to add additional free space to the image. The build system
463:term:`USER_CLASSES` which can contain 'image-prelink'. If you remove that, the 411 adds this space to the image after it determines its
464image will not be prelinked meaning the binaries would be unchanged. 412 :term:`IMAGE_ROOTFS_SIZE`.
413
414Why aren't spaces in path names supported?
415------------------------------------------
416
417The Yocto Project team has tried to do this before but too many
418of the tools the OpenEmbedded build system depends on, such as
419``autoconf``, break when they find spaces in pathnames. Until that
420situation changes, the team will not support spaces in pathnames.
421
422I'm adding a binary in a recipe. Why is it different in the image?
423------------------------------------------------------------------
424
425The first most obvious change is the system stripping debug symbols from
426it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being
427stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols
428being split into a separate file will ensure the binary is unchanged.
429
430Issues on the running system
431============================
432
433How do I disable the cursor on my touchscreen device?
434-----------------------------------------------------
435
436You need to create a form factor file as described in the
437":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
438the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
439the ``HAVE_TOUCHSCREEN`` variable equal to one as follows::
440
441 HAVE_TOUCHSCREEN=1
442
443How to always bring up connected network interfaces?
444----------------------------------------------------
445
446The default interfaces file provided by the netbase recipe does
447not automatically bring up network interfaces. Therefore, you will need
448to add a BSP-specific netbase that includes an interfaces file. See the
449":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
450the Yocto Project Board Support Packages (BSP) Developer's Guide for
451information on creating these types of miscellaneous recipe files.
452
453For example, add the following files to your layer::
454
455 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
456 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index 89c06eb65f..2ea946b31d 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -6,14 +6,14 @@ Features
6 6
7This chapter provides a reference of shipped machine and distro features 7This chapter provides a reference of shipped machine and distro features
8you can include as part of your image, a reference on image features you 8you can include as part of your image, a reference on image features you
9can select, and a reference on feature backfilling. 9can select, and a reference on :ref:`ref-features-backfill`.
10 10
11Features provide a mechanism for working out which packages should be 11Features provide a mechanism for working out which packages should be
12included in the generated images. Distributions can select which 12included in the generated images. Distributions can select which
13features they want to support through the ``DISTRO_FEATURES`` variable, 13features they want to support through the :term:`DISTRO_FEATURES` variable,
14which is set or appended to in a distribution's configuration file such 14which is set or appended to in a distribution's configuration file such
15as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. 15as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth.
16Machine features are set in the ``MACHINE_FEATURES`` variable, which is 16Machine features are set in the :term:`MACHINE_FEATURES` variable, which is
17set in the machine configuration file and specifies the hardware 17set in the machine configuration file and specifies the hardware
18features for a given machine. 18features for a given machine.
19 19
@@ -26,8 +26,7 @@ One method you can use to determine which recipes are checking to see if
26a particular feature is contained or not is to ``grep`` through the 26a particular feature is contained or not is to ``grep`` through the
27:term:`Metadata` for the feature. Here is an example that 27:term:`Metadata` for the feature. Here is an example that
28discovers the recipes whose build is potentially changed based on a 28discovers the recipes whose build is potentially changed based on a
29given feature: 29given feature::
30::
31 30
32 $ cd poky 31 $ cd poky
33 $ git grep 'contains.*MACHINE_FEATURES.*feature' 32 $ git grep 'contains.*MACHINE_FEATURES.*feature'
@@ -53,8 +52,6 @@ Project metadata:
53 52
54- *alsa:* Hardware has ALSA audio drivers 53- *alsa:* Hardware has ALSA audio drivers
55 54
56- *apm:* Hardware uses APM (or APM emulation)
57
58- *bluetooth:* Hardware has integrated BT 55- *bluetooth:* Hardware has integrated BT
59 56
60- *efi:* Support for booting through EFI 57- *efi:* Support for booting through EFI
@@ -63,6 +60,8 @@ Project metadata:
63 60
64- *keyboard:* Hardware has a keyboard 61- *keyboard:* Hardware has a keyboard
65 62
63- *numa:* Hardware has non-uniform memory access
64
66- *pcbios:* Support for booting through BIOS 65- *pcbios:* Support for booting through BIOS
67 66
68- *pci:* Hardware has a PCI bus 67- *pci:* Hardware has a PCI bus
@@ -71,6 +70,8 @@ Project metadata:
71 70
72- *phone:* Mobile phone (voice) support 71- *phone:* Mobile phone (voice) support
73 72
73- *qemu-usermode:* QEMU can support user-mode emulation for this machine
74
74- *qvga:* Machine has a QVGA (320x240) display 75- *qvga:* Machine has a QVGA (320x240) display
75 76
76- *rtc:* Machine has a Real-Time Clock 77- *rtc:* Machine has a Real-Time Clock
@@ -101,7 +102,9 @@ packages, and they can go beyond simply controlling the installation of
101a package or packages. In most cases, the presence or absence of a 102a package or packages. In most cases, the presence or absence of a
102feature translates to the appropriate option supplied to the configure 103feature translates to the appropriate option supplied to the configure
103script during the :ref:`ref-tasks-configure` task for 104script during the :ref:`ref-tasks-configure` task for
104the recipes that optionally support the feature. 105the recipes that optionally support the feature. Appropriate options
106must be supplied, and enabling/disabling :term:`PACKAGECONFIG` for the
107concerned packages is one way of supplying such options.
105 108
106Some distro features are also machine features. These select features 109Some distro features are also machine features. These select features
107make sense to be controlled both at the machine and distribution 110make sense to be controlled both at the machine and distribution
@@ -109,11 +112,22 @@ configuration level. See the
109:term:`COMBINED_FEATURES` variable for more 112:term:`COMBINED_FEATURES` variable for more
110information. 113information.
111 114
115.. note::
116
117 :term:`DISTRO_FEATURES` is normally independent of kernel configuration,
118 so if a feature specified in :term:`DISTRO_FEATURES` also relies on
119 support in the kernel, you will also need to ensure that support is
120 enabled in the kernel configuration.
121
112This list only represents features as shipped with the Yocto Project 122This list only represents features as shipped with the Yocto Project
113metadata: 123metadata, as extra layers can define their own:
124
125- *3g:* Include support for cellular data.
114 126
115- *alsa:* Include ALSA support (OSS compatibility kernel modules 127- *acl:* Include :wikipedia:`Access Control List <Access-control_list>` support.
116 installed if available). 128
129- *alsa:* Include :wikipedia:`Advanced Linux Sound Architecture <Advanced_Linux_Sound_Architecture>`
130 support (OSS compatibility kernel modules installed if available).
117 131
118- *api-documentation:* Enables generation of API documentation during 132- *api-documentation:* Enables generation of API documentation during
119 recipe builds. The resulting documentation is added to SDK tarballs 133 recipe builds. The resulting documentation is added to SDK tarballs
@@ -126,39 +140,84 @@ metadata:
126 140
127- *cramfs:* Include CramFS support. 141- *cramfs:* Include CramFS support.
128 142
143- *debuginfod:* Include support for getting ELF debugging information through
144 a :ref:`debuginfod <dev-manual/debugging:using the debuginfod server method>`
145 server.
146
129- *directfb:* Include DirectFB support. 147- *directfb:* Include DirectFB support.
130 148
131- *ext2:* Include tools for supporting for devices with internal 149- *ext2:* Include tools for supporting for devices with internal
132 HDD/Microdrive for storing files (instead of Flash only devices). 150 HDD/Microdrive for storing files (instead of Flash only devices).
133 151
152- *gobject-introspection-data:* Include data to support
153 `GObject Introspection <https://gi.readthedocs.io/en/latest/>`__.
154
134- *ipsec:* Include IPSec support. 155- *ipsec:* Include IPSec support.
135 156
157- *ipv4:* Include IPv4 support.
158
136- *ipv6:* Include IPv6 support. 159- *ipv6:* Include IPv6 support.
137 160
138- *keyboard:* Include keyboard support (e.g. keymaps will be loaded 161- *keyboard:* Include keyboard support (e.g. keymaps will be loaded
139 during boot). 162 during boot).
140 163
164- *minidebuginfo:* Add minimal debug symbols :ref:`(minidebuginfo)<dev-manual/debugging:enabling minidebuginfo>`
165 to binary files containing, allowing ``coredumpctl`` and ``gdb`` to show symbolicated stack traces.
166
167- *multiarch:* Enable building applications with multiple architecture
168 support.
169
170- *ld-is-gold:* Use the :wikipedia:`gold <Gold_(linker)>`
171 linker instead of the standard GCC linker (bfd).
172
141- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the 173- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the
142 target. 174 target.
143 175
176- *lto:* Enable `Link-Time Optimisation <https://gcc.gnu.org/wiki/LinkTimeOptimization>`__.
177
178- *nfc:* Include support for
179 `Near Field Communication <https://en.wikipedia.org/wiki/Near-field_communication>`__.
180
144- *nfs:* Include NFS client support (for mounting NFS exports on 181- *nfs:* Include NFS client support (for mounting NFS exports on
145 device). 182 device).
146 183
184- *nls:* Include National Language Support (NLS).
185
147- *opengl:* Include the Open Graphics Library, which is a 186- *opengl:* Include the Open Graphics Library, which is a
148 cross-language, multi-platform application programming interface used 187 cross-language, multi-platform application programming interface used
149 for rendering two and three-dimensional graphics. 188 for rendering two and three-dimensional graphics.
150 189
190- *overlayfs:* Include `OverlayFS <https://docs.kernel.org/filesystems/overlayfs.html>`__
191 support.
192
193- *pam:* Include :wikipedia:`Pluggable Authentication Module (PAM) <Pluggable_authentication_module>`
194 support.
195
151- *pci:* Include PCI bus support. 196- *pci:* Include PCI bus support.
152 197
153- *pcmcia:* Include PCMCIA/CompactFlash support. 198- *pcmcia:* Include PCMCIA/CompactFlash support.
154 199
200- *polkit:* Include :wikipedia:`Polkit <Polkit>` support.
201
155- *ppp:* Include PPP dialup support. 202- *ppp:* Include PPP dialup support.
156 203
157- *ptest:* Enables building the package tests where supported by 204- *ptest:* Enables building the package tests where supported by
158 individual recipes. For more information on package tests, see the 205 individual recipes. For more information on package tests, see the
159 ":ref:`dev-manual/common-tasks:testing packages with ptest`" section 206 ":ref:`dev-manual/packages:testing packages with ptest`" section
160 in the Yocto Project Development Tasks Manual. 207 in the Yocto Project Development Tasks Manual.
161 208
209- *pulseaudio:* Include support for
210 `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__.
211
212- *selinux:* Include support for
213 :wikipedia:`Security-Enhanced Linux (SELinux) <Security-Enhanced_Linux>`
214 (requires `meta-selinux <https://layers.openembedded.org/layerindex/layer/meta-selinux/>`__).
215
216- *seccomp:* Enables building applications with
217 :wikipedia:`seccomp <Seccomp>` support, to
218 allow them to strictly restrict the system calls that they are allowed
219 to invoke.
220
162- *smbfs:* Include SMB networks client support (for mounting 221- *smbfs:* Include SMB networks client support (for mounting
163 Samba/Microsoft Windows shares on device). 222 Samba/Microsoft Windows shares on device).
164 223
@@ -167,6 +226,10 @@ metadata:
167 reduced shell overhead, and other features. This ``init`` manager is 226 reduced shell overhead, and other features. This ``init`` manager is
168 used by many distributions. 227 used by many distributions.
169 228
229- *systemd-resolved:* Include support and use ``systemd-resolved`` as the
230 main DNS name resolver in ``glibc`` Name Service Switch. This is a DNS
231 resolver daemon from ``systemd``.
232
170- *usbgadget:* Include USB Gadget Device support (for USB 233- *usbgadget:* Include USB Gadget Device support (for USB
171 networking/serial/storage). 234 networking/serial/storage).
172 235
@@ -177,6 +240,11 @@ metadata:
177 directories into their respective counterparts in the ``/usr`` 240 directories into their respective counterparts in the ``/usr``
178 directory to provide better package and application compatibility. 241 directory to provide better package and application compatibility.
179 242
243- *vfat:* Include :wikipedia:`FAT filesystem <File_Allocation_Table>`
244 support.
245
246- *vulkan:* Include support for the :wikipedia:`Vulkan API <Vulkan>`.
247
180- *wayland:* Include the Wayland display server protocol and the 248- *wayland:* Include the Wayland display server protocol and the
181 library that supports it. 249 library that supports it.
182 250
@@ -184,6 +252,12 @@ metadata:
184 252
185- *x11:* Include the X server and libraries. 253- *x11:* Include the X server and libraries.
186 254
255- *xattr:* Include support for
256 :wikipedia:`extended file attributes <Extended_file_attributes>`.
257
258- *zeroconf:* Include support for
259 `zero configuration networking <https://en.wikipedia.org/wiki/Zero-configuration_networking>`__.
260
187.. _ref-features-image: 261.. _ref-features-image:
188 262
189Image Features 263Image Features
@@ -197,19 +271,21 @@ you can add several different predefined packages such as development
197utilities or packages with debug information needed to investigate 271utilities or packages with debug information needed to investigate
198application problems or profile applications. 272application problems or profile applications.
199 273
200The following image features are available for all images: 274The image features available for all images are:
275
276- *allow-empty-password:* Allows Dropbear and OpenSSH to accept
277 logins from accounts having an empty password string.
201 278
202- *allow-empty-password:* Allows Dropbear and OpenSSH to accept root 279- *allow-root-login:* Allows Dropbear and OpenSSH to accept root logins.
203 logins and logins from accounts having an empty password string.
204 280
205- *dbg-pkgs:* Installs debug symbol packages for all packages installed 281- *dbg-pkgs:* Installs debug symbol packages for all packages installed
206 in a given image. 282 in a given image.
207 283
208- *debug-tweaks:* Makes an image suitable for development (e.g. allows 284- *debug-tweaks:* Makes an image suitable for development (e.g. allows
209 root logins without passwords and enables post-installation logging). 285 root logins, logins without passwords ---including root ones, and enables
210 See the 'allow-empty-password', 'empty-root-password', and 286 post-installation logging). See the ``allow-empty-password``,
211 'post-install-logging' features in this list for additional 287 ``allow-root-login``, ``empty-root-password``, and ``post-install-logging``
212 information. 288 features in this list for additional information.
213 289
214- *dev-pkgs:* Installs development packages (headers and extra library 290- *dev-pkgs:* Installs development packages (headers and extra library
215 links) for all packages installed in a given image. 291 links) for all packages installed in a given image.
@@ -217,8 +293,26 @@ The following image features are available for all images:
217- *doc-pkgs:* Installs documentation packages for all packages 293- *doc-pkgs:* Installs documentation packages for all packages
218 installed in a given image. 294 installed in a given image.
219 295
220- *empty-root-password:* Sets the root password to an empty string, 296- *empty-root-password:* This feature or ``debug-tweaks`` is required if
221 which allows logins with a blank password. 297 you want to allow root login with an empty password. If these features
298 are not present in :term:`IMAGE_FEATURES`, a non-empty password is
299 forced in ``/etc/passwd`` and ``/etc/shadow`` if such files exist.
300
301 .. note::
302 ``empty-root-password`` doesn't set an empty root password by itself.
303 You get an initial empty root password thanks to the
304 :oe_git:`base-passwd </openembedded-core/tree/meta/recipes-core/base-passwd/>`
305 and :oe_git:`shadow </openembedded-core/tree/meta/recipes-extended/shadow/>`
306 recipes, and the presence of ``empty-root-password`` or ``debug-tweaks``
307 just disables the mechanism which forces an non-empty password for the
308 root user.
309
310- *lic-pkgs:* Installs license packages for all packages installed in a
311 given image.
312
313- *overlayfs-etc:* Configures the ``/etc`` directory to be in ``overlayfs``.
314 This allows to store device specific information elsewhere, especially
315 if the root filesystem is configured to be read-only.
222 316
223- *package-management:* Installs package management tools and preserves 317- *package-management:* Installs package management tools and preserves
224 the package manager database. 318 the package manager database.
@@ -236,23 +330,40 @@ The following image features are available for all images:
236 330
237- *read-only-rootfs:* Creates an image whose root filesystem is 331- *read-only-rootfs:* Creates an image whose root filesystem is
238 read-only. See the 332 read-only. See the
239 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" 333 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`"
240 section in the Yocto Project Development Tasks Manual for more 334 section in the Yocto Project Development Tasks Manual for more
241 information. 335 information.
242 336
337- *read-only-rootfs-delayed-postinsts:* when specified in conjunction
338 with ``read-only-rootfs``, specifies that post-install scripts are
339 still permitted (this assumes that the root filesystem will be made
340 writeable for the first boot; this feature does not do anything to
341 ensure that - it just disables the check for post-install scripts.)
342
343- *serial-autologin-root:* when specified in conjunction with
344 ``empty-root-password`` will automatically login as root on the
345 serial console. This of course opens up a security hole if the
346 serial console is potentially accessible to an attacker, so use
347 with caution.
348
243- *splash:* Enables showing a splash screen during boot. By default, 349- *splash:* Enables showing a splash screen during boot. By default,
244 this screen is provided by ``psplash``, which does allow 350 this screen is provided by ``psplash``, which does allow
245 customization. If you prefer to use an alternative splash screen 351 customization. If you prefer to use an alternative splash screen
246 package, you can do so by setting the ``SPLASH`` variable to a 352 package, you can do so by setting the :term:`SPLASH` variable to a
247 different package name (or names) within the image recipe or at the 353 different package name (or names) within the image recipe or at the
248 distro configuration level. 354 distro configuration level.
249 355
356- *stateless-rootfs:*: specifies that the image should be created as
357 stateless - when using ``systemd``, ``systemctl-native`` will not
358 be run on the image, leaving the image for population at runtime by
359 systemd.
360
250- *staticdev-pkgs:* Installs static development packages, which are 361- *staticdev-pkgs:* Installs static development packages, which are
251 static libraries (i.e. ``*.a`` files), for all packages installed in 362 static libraries (i.e. ``*.a`` files), for all packages installed in
252 a given image. 363 a given image.
253 364
254Some image features are available only when you inherit the 365Some image features are available only when you inherit the
255:ref:`core-image <ref-classes-core-image>` class. The current list of 366:ref:`ref-classes-core-image` class. The current list of
256these valid features is as follows: 367these valid features is as follows:
257 368
258- *hwcodecs:* Installs hardware acceleration codecs. 369- *hwcodecs:* Installs hardware acceleration codecs.
@@ -265,15 +376,30 @@ these valid features is as follows:
265 376
266- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. 377- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server.
267 378
379 .. note::
380
381 As of the 4.1 release, the ``ssh-server-dropbear`` feature also
382 recommends the ``openssh-sftp-server`` package, which by default
383 will be pulled into the image. This is because recent versions of
384 the OpenSSH ``scp`` client now use the SFTP protocol, and thus
385 require an SFTP server to be present to connect to. However, if
386 you wish to use the Dropbear ssh server `without` the SFTP server
387 installed, you can either remove ``ssh-server-dropbear`` from
388 ``IMAGE_FEATURES`` and add ``dropbear`` to :term:`IMAGE_INSTALL`
389 instead, or alternatively still use the feature but set
390 :term:`BAD_RECOMMENDATIONS` as follows::
391
392 BAD_RECOMMENDATIONS += "openssh-sftp-server"
393
268- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more 394- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more
269 full-featured than Dropbear. Note that if both the OpenSSH SSH server 395 full-featured than Dropbear. Note that if both the OpenSSH SSH server
270 and the Dropbear minimal SSH server are present in 396 and the Dropbear minimal SSH server are present in
271 ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear 397 :term:`IMAGE_FEATURES`, then OpenSSH will take precedence and Dropbear
272 will not be installed. 398 will not be installed.
273 399
274- *tools-debug:* Installs debugging tools such as ``strace`` and 400- *tools-debug:* Installs debugging tools such as ``strace`` and
275 ``gdb``. For information on GDB, see the 401 ``gdb``. For information on GDB, see the
276 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section 402 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section
277 in the Yocto Project Development Tasks Manual. For information on 403 in the Yocto Project Development Tasks Manual. For information on
278 tracing and profiling, see the :doc:`/profile-manual/index`. 404 tracing and profiling, see the :doc:`/profile-manual/index`.
279 405
@@ -282,6 +408,8 @@ these valid features is as follows:
282- *tools-testapps:* Installs device testing tools (e.g. touchscreen 408- *tools-testapps:* Installs device testing tools (e.g. touchscreen
283 debugging). 409 debugging).
284 410
411- *weston:* Installs Weston (reference Wayland environment).
412
285- *x11:* Installs the X server. 413- *x11:* Installs the X server.
286 414
287- *x11-base:* Installs the X server with a minimal environment. 415- *x11-base:* Installs the X server with a minimal environment.
@@ -293,58 +421,50 @@ these valid features is as follows:
293Feature Backfilling 421Feature Backfilling
294=================== 422===================
295 423
296Sometimes it is necessary in the OpenEmbedded build system to extend 424Sometimes it is necessary in the OpenEmbedded build system to
297:term:`MACHINE_FEATURES` or 425add new functionality to :term:`MACHINE_FEATURES` or
298:term:`DISTRO_FEATURES` to control functionality 426:term:`DISTRO_FEATURES`, but at the same time, allow existing
299that was previously enabled and not able to be disabled. For these 427distributions or machine definitions to opt out of such new
300cases, we need to add an additional feature item to appear in one of 428features, to retain the same overall level of functionality.
301these variables, but we do not want to force developers who have 429
302existing values of the variables in their configuration to add the new 430To make this possible, the OpenEmbedded build system has a mechanism to
303feature in order to retain the same overall level of functionality. 431automatically "backfill" features into existing distro or machine
304Thus, the OpenEmbedded build system has a mechanism to automatically
305"backfill" these added features into existing distro or machine
306configurations. You can see the list of features for which this is done 432configurations. You can see the list of features for which this is done
307by finding the 433by checking the :term:`DISTRO_FEATURES_BACKFILL` and
308:term:`DISTRO_FEATURES_BACKFILL` and 434:term:`MACHINE_FEATURES_BACKFILL` variables in the
309:term:`MACHINE_FEATURES_BACKFILL` 435``meta/conf/bitbake.conf`` file.
310variables in the ``meta/conf/bitbake.conf`` file. 436
311 437These two variables are paired with the
312Because such features are backfilled by default into all configurations
313as described in the previous paragraph, developers who wish to disable
314the new features need to be able to selectively prevent the backfilling
315from occurring. They can do this by adding the undesired feature or
316features to the
317:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 438:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
318or 439and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables
319:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 440which allow distro or machine configuration maintainers to `consider` any
320variables for distro features and machine features respectively. 441added feature, and decide when they wish to keep or exclude such feature,
321 442thus preventing the backfilling from happening.
322Here are two examples to help illustrate feature backfilling: 443
323 444Here are two examples to illustrate feature backfilling:
324- *The "pulseaudio" distro feature option*: Previously, PulseAudio 445
325 support was enabled within the Qt and GStreamer frameworks. Because 446- *The "pulseaudio" distro feature option*: Previously, PulseAudio support was
326 of this, the feature is backfilled and thus enabled for all distros 447 enabled within the Qt and GStreamer frameworks. Because of this, the feature
327 through the ``DISTRO_FEATURES_BACKFILL`` variable in the 448 is now backfilled and thus enabled for all distros through the
328 ``meta/conf/bitbake.conf`` file. However, your distro needs to 449 :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf``
329 disable the feature. You can disable the feature without affecting 450 file. However, if your distro needs to disable the feature, you can do so
330 other existing distro configurations that need PulseAudio support by 451 without affecting other existing distro configurations that need PulseAudio
331 adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in 452 support. You do this by adding "pulseaudio" to
332 your distro's ``.conf`` file. Adding the feature to this variable 453 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf``
333 when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable 454 file. So, adding the feature to this variable when it also exists in the
334 prevents the build system from adding the feature to your 455 :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from
335 configuration's ``DISTRO_FEATURES``, effectively disabling the 456 adding the feature to your configuration's :term:`DISTRO_FEATURES`,
336 feature for that particular distro. 457 effectively disabling the feature for that particular distro.
337 458
338- *The "rtc" machine feature option*: Previously, real time clock (RTC) 459- *The "rtc" machine feature option*: Previously, real time clock (RTC)
339 support was enabled for all target devices. Because of this, the 460 support was enabled for all target devices. Because of this, the
340 feature is backfilled and thus enabled for all machines through the 461 feature is backfilled and thus enabled for all machines through the
341 ``MACHINE_FEATURES_BACKFILL`` variable in the 462 :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf``
342 ``meta/conf/bitbake.conf`` file. However, your target device does not 463 file. However, if your target device does not have this capability, you can
343 have this capability. You can disable RTC support for your device 464 disable RTC support for your device without affecting other machines
344 without affecting other machines that need RTC support by adding the 465 that need RTC support. You do this by adding the "rtc" feature to the
345 feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED`` 466 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf``
346 list in the machine's ``.conf`` file. Adding the feature to this 467 file. So, adding the feature to this variable when it also exists in the
347 variable when it also exists in the ``MACHINE_FEATURES_BACKFILL`` 468 :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from
348 variable prevents the build system from adding the feature to your 469 adding the feature to your configuration's :term:`MACHINE_FEATURES`,
349 configuration's ``MACHINE_FEATURES``, effectively disabling RTC 470 effectively disabling RTC support for that particular machine.
350 support for that particular machine.
diff --git a/documentation/ref-manual/history.rst b/documentation/ref-manual/history.rst
deleted file mode 100644
index dc0a2ae797..0000000000
--- a/documentation/ref-manual/history.rst
+++ /dev/null
@@ -1,74 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3***********************
4Manual Revision History
5***********************
6
7.. list-table::
8 :widths: 10 15 40
9 :header-rows: 1
10
11 * - Revision
12 - Date
13 - Note
14 * - 0.9
15 - November 2010
16 - The initial document released with the Yocto Project 0.9 Release
17 * - 1.0
18 - April 2011
19 - Released with the Yocto Project 1.0 Release.
20 * - 1.1
21 - October 2011
22 - Released with the Yocto Project 1.1 Release.
23 * - 1.2
24 - April 2012
25 - Released with the Yocto Project 1.2 Release.
26 * - 1.3
27 - October 2012
28 - Released with the Yocto Project 1.3 Release.
29 * - 1.4
30 - April 2013
31 - Released with the Yocto Project 1.4 Release.
32 * - 1.5
33 - October 2013
34 - Released with the Yocto Project 1.5 Release.
35 * - 1.6
36 - April 2014
37 - Released with the Yocto Project 1.6 Release.
38 * - 1.7
39 - October 2014
40 - Released with the Yocto Project 1.7 Release.
41 * - 1.8
42 - April 2015
43 - Released with the Yocto Project 1.8 Release.
44 * - 2.0
45 - October 2015
46 - Released with the Yocto Project 2.0 Release.
47 * - 2.1
48 - April 2016
49 - Released with the Yocto Project 2.1 Release.
50 * - 2.2
51 - October 2016
52 - Released with the Yocto Project 2.2 Release.
53 * - 2.3
54 - May 2017
55 - Released with the Yocto Project 2.3 Release.
56 * - 2.4
57 - October 2017
58 - Released with the Yocto Project 2.4 Release.
59 * - 2.5
60 - May 2018
61 - Released with the Yocto Project 2.5 Release.
62 * - 2.6
63 - November 2018
64 - Released with the Yocto Project 2.6 Release.
65 * - 2.7
66 - May 2019
67 - Released with the Yocto Project 2.7 Release.
68 * - 3.0
69 - October 2019
70 - Released with the Yocto Project 3.0 Release.
71 * - 3.1
72 - April 2020
73 - Released with the Yocto Project 3.1 Release.
74
diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst
index cf5cc1109f..c45f9104a9 100644
--- a/documentation/ref-manual/images.rst
+++ b/documentation/ref-manual/images.rst
@@ -14,24 +14,25 @@ image you want.
14 Building an image without GNU General Public License Version 3 14 Building an image without GNU General Public License Version 3
15 (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and 15 (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and
16 the GNU Affero General Public License Version 3 (AGPL-3.0) components 16 the GNU Affero General Public License Version 3 (AGPL-3.0) components
17 is only supported for minimal and base images. Furthermore, if you 17 is only tested for core-image-minimal image. Furthermore, if you would like to
18 are going to build an image using non-GPLv3 and similarly licensed 18 build an image and verify that it does not include GPLv3 and similarly licensed
19 components, you must make the following changes in the ``local.conf`` 19 components, you must make the following changes in the image recipe
20 file before using the BitBake command to build the minimal or base 20 file before using the BitBake command to build the image:
21 image:
22 ::
23 21
24 1. Comment out the EXTRA_IMAGE_FEATURES line 22 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*"
25 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
26 23
24 Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line
25 for all images where the license restriction must apply:
26
27 INCOMPATIBLE_LICENSE:pn-your-image-name = "GPL-3.0* LGPL-3.0*"
27 28
28From within the ``poky`` Git repository, you can use the following 29From within the ``poky`` Git repository, you can use the following
29command to display the list of directories within the :term:`Source Directory` 30command to display the list of directories within the :term:`Source Directory`
30that contain image recipe files: :: 31that contain image recipe files::
31 32
32 $ ls meta*/recipes*/images/*.bb 33 $ ls meta*/recipes*/images/*.bb
33 34
34Following is a list of supported recipes: 35Here is a list of supported recipes:
35 36
36- ``build-appliance-image``: An example virtual machine that contains 37- ``build-appliance-image``: An example virtual machine that contains
37 all the pieces required to run builds using the build system as well 38 all the pieces required to run builds using the build system as well
@@ -47,10 +48,6 @@ Following is a list of supported recipes:
47- ``core-image-base``: A console-only image that fully supports the 48- ``core-image-base``: A console-only image that fully supports the
48 target device hardware. 49 target device hardware.
49 50
50- ``core-image-clutter``: An image with support for the Open GL-based
51 toolkit Clutter, which enables development of rich and animated
52 graphical user interfaces.
53
54- ``core-image-full-cmdline``: A console-only image with more 51- ``core-image-full-cmdline``: A console-only image with more
55 full-featured Linux system functionality installed. 52 full-featured Linux system functionality installed.
56 53
@@ -83,11 +80,11 @@ Following is a list of supported recipes:
83 libraries you can use in a host development environment. 80 libraries you can use in a host development environment.
84 81
85- ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that 82- ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that
86 has the Minimal RAM-based Initial Root Filesystem (initramfs) as part 83 has the Minimal RAM-based Initial Root Filesystem (:term:`Initramfs`) as part
87 of the kernel, which allows the system to find the first "init" 84 of the kernel, which allows the system to find the first "init"
88 program more efficiently. See the 85 program more efficiently. See the
89 :term:`PACKAGE_INSTALL` variable for 86 :term:`PACKAGE_INSTALL` variable for
90 additional information helpful when working with initramfs images. 87 additional information helpful when working with :term:`Initramfs` images.
91 88
92- ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that 89- ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that
93 has support for the Minimal MTD Utilities, which let the user 90 has support for the Minimal MTD Utilities, which let the user
@@ -117,22 +114,22 @@ Following is a list of supported recipes:
117 development headers and libraries to form a complete standalone SDK 114 development headers and libraries to form a complete standalone SDK
118 and is suitable for development using the target. 115 and is suitable for development using the target.
119 116
120- ``core-image-testmaster``: A "master" image designed to be used for 117- ``core-image-testmaster``: A "controller" image designed to be used for
121 automated runtime testing. Provides a "known good" image that is 118 automated runtime testing. Provides a "known good" image that is
122 deployed to a separate partition so that you can boot into it and use 119 deployed to a separate partition so that you can boot into it and use
123 it to deploy a second image to be tested. You can find more 120 it to deploy a second image to be tested. You can find more
124 information about runtime testing in the 121 information about runtime testing in the
125 ":ref:`dev-manual/common-tasks:performing automated runtime testing`" 122 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
126 section in the Yocto Project Development Tasks Manual. 123 section in the Yocto Project Development Tasks Manual.
127 124
128- ``core-image-testmaster-initramfs``: A RAM-based Initial Root 125- ``core-image-testmaster-initramfs``: A RAM-based Initial Root
129 Filesystem (initramfs) image tailored for use with the 126 Filesystem (:term:`Initramfs`) image tailored for use with the
130 ``core-image-testmaster`` image. 127 ``core-image-testmaster`` image.
131 128
132- ``core-image-weston``: A very basic Wayland image with a terminal. 129- ``core-image-weston``: A very basic Wayland image with a terminal.
133 This image provides the Wayland protocol libraries and the reference 130 This image provides the Wayland protocol libraries and the reference
134 Weston compositor. For more information, see the 131 Weston compositor. For more information, see the
135 ":ref:`dev-manual/common-tasks:using wayland and weston`" 132 ":ref:`dev-manual/wayland:using wayland and weston`"
136 section in the Yocto Project Development Tasks Manual. 133 section in the Yocto Project Development Tasks Manual.
137 134
138- ``core-image-x11``: A very basic X11 image with a terminal. 135- ``core-image-x11``: A very basic X11 image with a terminal.
diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst
index deb0383cfc..a746dde492 100644
--- a/documentation/ref-manual/index.rst
+++ b/documentation/ref-manual/index.rst
@@ -13,7 +13,6 @@ Yocto Project Reference Manual
13 system-requirements 13 system-requirements
14 terms 14 terms
15 release-process 15 release-process
16 migration
17 structure 16 structure
18 classes 17 classes
19 tasks 18 tasks
@@ -26,6 +25,5 @@ Yocto Project Reference Manual
26 varlocality 25 varlocality
27 faq 26 faq
28 resources 27 resources
29 history
30 28
31.. include:: /boilerplate.rst 29.. include:: /boilerplate.rst
diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst
index 472820f165..297887805c 100644
--- a/documentation/ref-manual/kickstart.rst
+++ b/documentation/ref-manual/kickstart.rst
@@ -30,10 +30,9 @@ Command: part or partition
30========================== 30==========================
31 31
32Either of these commands creates a partition on the system and uses the 32Either of these commands creates a partition on the system and uses the
33following syntax: 33following syntax::
34::
35 34
36 part [mntpoint] 35 part [mntpoint]
37 partition [mntpoint] 36 partition [mntpoint]
38 37
39If you do not 38If you do not
@@ -55,36 +54,40 @@ must also provide one of the ``--ondrive``, ``--ondisk``, or
55.. note:: 54.. note::
56 55
57 The mount program must understand the PARTUUID syntax you use with 56 The mount program must understand the PARTUUID syntax you use with
58 ``--use-uuid`` and non-root *mountpoint*, including swap. The busybox 57 ``--use-uuid`` and non-root *mountpoint*, including swap. The default
59 versions of these application are currently excluded. 58 configuration of BusyBox in OpenEmbedded supports this, but this may
59 be disabled in custom configurations.
60 60
61Here is an example that uses "/" as the mountpoint. The command uses 61Here is an example that uses "/" as the mountpoint. The command uses
62``--ondisk`` to force the partition onto the ``sdb`` disk: 62``--ondisk`` to force the partition onto the ``sdb`` disk::
63::
64 63
65 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 64 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
66 65
67Here is a list that describes other supported options you can use with 66Here is a list that describes other supported options you can use with
68the ``part`` and ``partition`` commands: 67the ``part`` and ``partition`` commands:
69 68
70- ``--size``: The minimum partition size in MBytes. Specify an 69- ``--size``: The minimum partition size. Specify as an integer value
71 integer value such as 500. Do not append the number with "MB". You do 70 optionally followed by one of the units "k" / "K" for kibibyte,
72 not need this option if you use ``--source``. 71 "M" for mebibyte and "G" for gibibyte. The default unit if none is
72 given is "M". You do not need this option if you use ``--source``.
73 73
74- ``--fixed-size``: The exact partition size in MBytes. You cannot 74- ``--fixed-size``: The exact partition size. Specify as an integer
75 specify with ``--size``. An error occurs when assembling the disk 75 value optionally followed by one of the units "k" / "K" for kibibyte,
76 image if the partition data is larger than ``--fixed-size``. 76 "M" for mebibyte and "G" for gibibyte. The default unit if none is
77 given is "M". Cannot be specify together with ``--size``. An error
78 occurs when assembling the disk image if the partition data is larger
79 than ``--fixed-size``.
77 80
78- ``--source``: This option is a Wic-specific option that names the 81- ``--source``: This option is a Wic-specific option that names the
79 source of the data that populates the partition. The most common 82 source of the data that populates the partition. The most common
80 value for this option is "rootfs", but you can use any value that 83 value for this option is "rootfs", but you can use any value that
81 maps to a valid source plugin. For information on the source plugins, 84 maps to a valid source plugin. For information on the source plugins,
82 see the ":ref:`dev-manual/common-tasks:using the wic plugin interface`" 85 see the ":ref:`dev-manual/wic:using the wic plugin interface`"
83 section in the Yocto Project Development Tasks Manual. 86 section in the Yocto Project Development Tasks Manual.
84 87
85 If you use ``--source rootfs``, Wic creates a partition as large as 88 If you use ``--source rootfs``, Wic creates a partition as large as
86 needed and fills it with the contents of the root filesystem pointed 89 needed and fills it with the contents of the root filesystem pointed
87 to by the ``-r`` command-line option or the equivalent rootfs derived 90 to by the ``-r`` command-line option or the equivalent root filesystem derived
88 from the ``-e`` command-line option. The filesystem type used to 91 from the ``-e`` command-line option. The filesystem type used to
89 create the partition is driven by the value of the ``--fstype`` 92 create the partition is driven by the value of the ``--fstype``
90 option specified for the partition. See the entry on ``--fstype`` 93 option specified for the partition. See the entry on ``--fstype``
@@ -93,7 +96,7 @@ the ``part`` and ``partition`` commands:
93 If you use ``--source plugin-name``, Wic creates a partition as large 96 If you use ``--source plugin-name``, Wic creates a partition as large
94 as needed and fills it with the contents of the partition that is 97 as needed and fills it with the contents of the partition that is
95 generated by the specified plugin name using the data pointed to by 98 generated by the specified plugin name using the data pointed to by
96 the ``-r`` command-line option or the equivalent rootfs derived from 99 the ``-r`` command-line option or the equivalent root filesystem derived from
97 the ``-e`` command-line option. Exactly what those contents are and 100 the ``-e`` command-line option. Exactly what those contents are and
98 filesystem type used are dependent on the given plugin 101 filesystem type used are dependent on the given plugin
99 implementation. 102 implementation.
@@ -108,18 +111,22 @@ the ``part`` and ``partition`` commands:
108- ``--fstype``: Sets the file system type for the partition. Valid 111- ``--fstype``: Sets the file system type for the partition. Valid
109 values are: 112 values are:
110 113
111 - ``ext4`` 114 - ``btrfs``
112 115
113 - ``ext3`` 116 - ``erofs``
114 117
115 - ``ext2`` 118 - ``ext2``
116 119
117 - ``btrfs`` 120 - ``ext3``
121
122 - ``ext4``
118 123
119 - ``squashfs`` 124 - ``squashfs``
120 125
121 - ``swap`` 126 - ``swap``
122 127
128 - ``vfat``
129
123- ``--fsoptions``: Specifies a free-form string of options to be used 130- ``--fsoptions``: Specifies a free-form string of options to be used
124 when mounting the filesystem. This string is copied into the 131 when mounting the filesystem. This string is copied into the
125 ``/etc/fstab`` file of the installed system and should be enclosed in 132 ``/etc/fstab`` file of the installed system and should be enclosed in
@@ -134,10 +141,13 @@ the ``part`` and ``partition`` commands:
134- ``--align (in KBytes)``: This option is a Wic-specific option that 141- ``--align (in KBytes)``: This option is a Wic-specific option that
135 says to start partitions on boundaries given x KBytes. 142 says to start partitions on boundaries given x KBytes.
136 143
137- ``--offset (in KBytes)``: This option is a Wic-specific option that 144- ``--offset``: This option is a Wic-specific option that
138 says to place a partition at exactly the specified offset. If the 145 says to place a partition at exactly the specified offset. If the
139 partition cannot be placed at the specified offset, the image build 146 partition cannot be placed at the specified offset, the image build
140 will fail. 147 will fail. Specify as an integer value optionally followed by one of
148 the units "s" / "S" for 512 byte sector, "k" / "K" for kibibyte, "M"
149 for mebibyte and "G" for gibibyte. The default unit if none is given
150 is "k".
141 151
142- ``--no-table``: This option is a Wic-specific option. Using the 152- ``--no-table``: This option is a Wic-specific option. Using the
143 option reserves space for the partition and causes it to become 153 option reserves space for the partition and causes it to become
@@ -151,7 +161,10 @@ the ``part`` and ``partition`` commands:
151- ``--extra-space``: This option is a Wic-specific option that adds 161- ``--extra-space``: This option is a Wic-specific option that adds
152 extra space after the space filled by the content of the partition. 162 extra space after the space filled by the content of the partition.
153 The final size can exceed the size specified by the ``--size`` 163 The final size can exceed the size specified by the ``--size``
154 option. The default value is 10 Mbytes. 164 option. The default value is 10M. Specify as an integer value
165 optionally followed by one of the units "k" / "K" for kibibyte, "M"
166 for mebibyte and "G" for gibibyte. The default unit if none is given
167 is "M".
155 168
156- ``--overhead-factor``: This option is a Wic-specific option that 169- ``--overhead-factor``: This option is a Wic-specific option that
157 multiplies the size of the partition by the option's value. You must 170 multiplies the size of the partition by the option's value. You must
@@ -164,7 +177,7 @@ the ``part`` and ``partition`` commands:
164- ``--part-type``: This option is a Wic-specific option that 177- ``--part-type``: This option is a Wic-specific option that
165 specifies the partition type globally unique identifier (GUID) for 178 specifies the partition type globally unique identifier (GUID) for
166 GPT partitions. You can find the list of partition type GUIDs at 179 GPT partitions. You can find the list of partition type GUIDs at
167 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs. 180 :wikipedia:`GUID_Partition_Table#Partition_type_GUIDs`.
168 181
169- ``--use-uuid``: This option is a Wic-specific option that causes 182- ``--use-uuid``: This option is a Wic-specific option that causes
170 Wic to generate a random GUID for the partition. The generated 183 Wic to generate a random GUID for the partition. The generated
@@ -198,19 +211,24 @@ supports the following options:
198.. note:: 211.. note::
199 212
200 Bootloader functionality and boot partitions are implemented by the 213 Bootloader functionality and boot partitions are implemented by the
201 various 214 various source plugins that implement bootloader functionality. The bootloader
202 --source
203 plugins that implement bootloader functionality. The bootloader
204 command essentially provides a means of modifying bootloader 215 command essentially provides a means of modifying bootloader
205 configuration. 216 configuration.
206 217
207- ``--timeout``: Specifies the number of seconds before the
208 bootloader times out and boots the default option.
209
210- ``--append``: Specifies kernel parameters. These parameters will be 218- ``--append``: Specifies kernel parameters. These parameters will be
211 added to the syslinux ``APPEND`` or ``grub`` kernel command line. 219 added to the syslinux :term:`APPEND` or ``grub`` kernel command line.
212 220
213- ``--configfile``: Specifies a user-defined configuration file for 221- ``--configfile``: Specifies a user-defined configuration file for
214 the bootloader. You can provide a full pathname for the file or a 222 the bootloader. You can provide a full pathname for the file or a
215 file that exists in the ``canned-wks`` folder. This option overrides 223 file located in the ``canned-wks`` folder. This option overrides
216 all other bootloader options. 224 all other bootloader options.
225
226- ``--ptable``: Specifies the partition table format. Valid values are:
227
228 - ``msdos``
229
230 - ``gpt``
231
232- ``--timeout``: Specifies the number of seconds before the
233 bootloader times out and boots the default option.
234
diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
deleted file mode 100644
index 12e225b149..0000000000
--- a/documentation/ref-manual/migration-1.3.rst
+++ /dev/null
@@ -1,195 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Moving to the Yocto Project 1.3 Release
4=======================================
5
6This section provides migration information for moving to the Yocto
7Project 1.3 Release from the prior release.
8
9.. _1.3-local-configuration:
10
11Local Configuration
12-------------------
13
14Differences include changes for
15:term:`SSTATE_MIRRORS` and ``bblayers.conf``.
16
17.. _migration-1.3-sstate-mirrors:
18
19SSTATE_MIRRORS
20~~~~~~~~~~~~~~
21
22The shared state cache (sstate-cache), as pointed to by
23:term:`SSTATE_DIR`, by default now has two-character
24subdirectories to prevent issues arising from too many files in the same
25directory. Also, native sstate-cache packages, which are built to run on
26the host system, will go into a subdirectory named using the distro ID
27string. If you copy the newly structured sstate-cache to a mirror
28location (either local or remote) and then point to it in
29:term:`SSTATE_MIRRORS`, you need to append "PATH"
30to the end of the mirror URL so that the path used by BitBake before the
31mirror substitution is appended to the path used to access the mirror.
32Here is an example: ::
33
34 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
35
36.. _migration-1.3-bblayers-conf:
37
38bblayers.conf
39~~~~~~~~~~~~~
40
41The ``meta-yocto`` layer consists of two parts that correspond to the
42Poky reference distribution and the reference hardware Board Support
43Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``.
44When running BitBake for the first time after upgrading, your
45``conf/bblayers.conf`` file will be updated to handle this change and
46you will be asked to re-run or restart for the changes to take effect.
47
48.. _1.3-recipes:
49
50Recipes
51-------
52
53Differences include changes for the following:
54
55.. _migration-1.3-python-function-whitespace:
56
57Python Function Whitespace
58~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60All Python functions must now use four spaces for indentation.
61Previously, an inconsistent mix of spaces and tabs existed, which made
62extending these functions using ``_append`` or ``_prepend`` complicated
63given that Python treats whitespace as syntactically significant. If you
64are defining or extending any Python functions (e.g.
65``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in
66custom recipes or classes, you need to ensure you are using consistent
67four-space indentation.
68
69.. _migration-1.3-proto=-in-src-uri:
70
71proto= in SRC_URI
72~~~~~~~~~~~~~~~~~
73
74Any use of ``proto=`` in :term:`SRC_URI` needs to be
75changed to ``protocol=``. In particular, this applies to the following
76URIs:
77
78- ``svn://``
79
80- ``bzr://``
81
82- ``hg://``
83
84- ``osc://``
85
86Other URIs were already using ``protocol=``. This change improves
87consistency.
88
89.. _migration-1.3-nativesdk:
90
91nativesdk
92~~~~~~~~~
93
94The suffix ``nativesdk`` is now implemented as a prefix, which
95simplifies a lot of the packaging code for ``nativesdk`` recipes. All
96custom ``nativesdk`` recipes, which are relocatable packages that are
97native to :term:`SDK_ARCH`, and any references need to
98be updated to use ``nativesdk-*`` instead of ``*-nativesdk``.
99
100.. _migration-1.3-task-recipes:
101
102Task Recipes
103~~~~~~~~~~~~
104
105"Task" recipes are now known as "Package groups" and have been renamed
106from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the
107previous ``task-*`` names should work in most cases as there is an
108automatic upgrade path for most packages. However, you should update
109references in your own recipes and configurations as they could be
110removed in future releases. You should also rename any custom ``task-*``
111recipes to ``packagegroup-*``, and change them to inherit
112``packagegroup`` instead of ``task``, as well as taking the opportunity
113to remove anything now handled by ``packagegroup.bbclass``, such as
114providing ``-dev`` and ``-dbg`` packages, setting
115:term:`LIC_FILES_CHKSUM`, and so forth. See the
116":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for
117further details.
118
119.. _migration-1.3-image-features:
120
121IMAGE_FEATURES
122~~~~~~~~~~~~~~
123
124Image recipes that previously included ``apps-console-core`` in
125:term:`IMAGE_FEATURES` should now include ``splash``
126instead to enable the boot-up splash screen. Retaining
127``apps-console-core`` will still include the splash screen but generates a
128warning. The ``apps-x11-core`` and ``apps-x11-games`` ``IMAGE_FEATURES``
129features have been removed.
130
131.. _migration-1.3-removed-recipes:
132
133Removed Recipes
134~~~~~~~~~~~~~~~
135
136The following recipes have been removed. For most of them, it is
137unlikely that you would have any references to them in your own
138:term:`Metadata`. However, you should check your metadata
139against this list to be sure:
140
141- ``libx11-trim``: Replaced by ``libx11``, which has a negligible
142 size difference with modern Xorg.
143
144- ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible
145 size difference when DRI and GLX modules are not installed.
146
147- ``xserver-kdrive``: Effectively unmaintained for many years.
148
149- ``mesa-xlib``: No longer serves any purpose.
150
151- ``galago``: Replaced by telepathy.
152
153- ``gail``: Functionality was integrated into GTK+ 2.13.
154
155- ``eggdbus``: No longer needed.
156
157- ``gcc-*-intermediate``: The build has been restructured to avoid
158 the need for this step.
159
160- ``libgsmd``: Unmaintained for many years. Functionality now
161 provided by ``ofono`` instead.
162
163- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM
164 application suite. It has been moved to ``meta-gnome`` in
165 ``meta-openembedded``.
166
167In addition to the previously listed changes, the ``meta-demoapps``
168directory has also been removed because the recipes in it were not being
169maintained and many had become obsolete or broken. Additionally, these
170recipes were not parsed in the default configuration. Many of these
171recipes are already provided in an updated and maintained form within
172the OpenEmbedded community layers such as ``meta-oe`` and
173``meta-gnome``. For the remainder, you can now find them in the
174``meta-extras`` repository, which is in the
175:yocto_git:`Source Repositories <>` at
176:yocto_git:`/meta-extras/`.
177
178.. _1.3-linux-kernel-naming:
179
180Linux Kernel Naming
181-------------------
182
183The naming scheme for kernel output binaries has been changed to now
184include :term:`PE` as part of the filename:
185::
186
187 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
188
189Because the ``PE`` variable is not set by default, these binary files
190could result with names that include two dash characters. Here is an
191example: ::
192
193 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
194
195
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
deleted file mode 100644
index 0b7e861176..0000000000
--- a/documentation/ref-manual/migration-1.4.rst
+++ /dev/null
@@ -1,237 +0,0 @@
1Moving to the Yocto Project 1.4 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.4 Release from the prior release.
6
7.. _migration-1.4-bitbake:
8
9BitBake
10-------
11
12Differences include the following:
13
14- *Comment Continuation:* If a comment ends with a line continuation
15 (\\) character, then the next line must also be a comment. Any
16 instance where this is not the case, now triggers a warning. You must
17 either remove the continuation character, or be sure the next line is
18 a comment.
19
20- *Package Name Overrides:* The runtime package specific variables
21 :term:`RDEPENDS`,
22 :term:`RRECOMMENDS`,
23 :term:`RSUGGESTS`,
24 :term:`RPROVIDES`,
25 :term:`RCONFLICTS`,
26 :term:`RREPLACES`, :term:`FILES`,
27 :term:`ALLOW_EMPTY`, and the pre, post, install,
28 and uninstall script functions ``pkg_preinst``, ``pkg_postinst``,
29 ``pkg_prerm``, and ``pkg_postrm`` should always have a package name
30 override. For example, use ``RDEPENDS_${PN}`` for the main package
31 instead of ``RDEPENDS``. BitBake uses more strict checks when it
32 parses recipes.
33
34.. _migration-1.4-build-behavior:
35
36Build Behavior
37--------------
38
39Differences include the following:
40
41- *Shared State Code:* The shared state code has been optimized to
42 avoid running unnecessary tasks. For example, the following no longer
43 populates the target sysroot since that is not necessary:
44 ::
45
46 $ bitbake -c rootfs some-image
47
48 Instead, the system just needs to extract the
49 output package contents, re-create the packages, and construct the
50 root filesystem. This change is unlikely to cause any problems unless
51 you have missing declared dependencies.
52
53- *Scanning Directory Names:* When scanning for files in
54 :term:`SRC_URI`, the build system now uses
55 :term:`FILESOVERRIDES` instead of
56 :term:`OVERRIDES` for the directory names. In
57 general, the values previously in ``OVERRIDES`` are now in
58 ``FILESOVERRIDES`` as well. However, if you relied upon an additional
59 value you previously added to ``OVERRIDES``, you might now need to
60 add it to ``FILESOVERRIDES`` unless you are already adding it through
61 the :term:`MACHINEOVERRIDES` or
62 :term:`DISTROOVERRIDES` variables, as
63 appropriate. For more related changes, see the
64 ":ref:`ref-manual/migration-1.4:variables`" section.
65
66.. _migration-1.4-proxies-and-fetching-source:
67
68Proxies and Fetching Source
69---------------------------
70
71A new ``oe-git-proxy`` script has been added to replace previous methods
72of handling proxies and fetching source from Git. See the
73``meta-yocto/conf/site.conf.sample`` file for information on how to use
74this script.
75
76.. _migration-1.4-custom-interfaces-file-netbase-change:
77
78Custom Interfaces File (netbase change)
79---------------------------------------
80
81If you have created your own custom ``etc/network/interfaces`` file by
82creating an append file for the ``netbase`` recipe, you now need to
83create an append file for the ``init-ifupdown`` recipe instead, which
84you can find in the :term:`Source Directory` at
85``meta/recipes-core/init-ifupdown``. For information on how to use
86append files, see the
87":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
88section in the Yocto Project Development Tasks Manual.
89
90.. _migration-1.4-remote-debugging:
91
92Remote Debugging
93----------------
94
95Support for remote debugging with the Eclipse IDE is now separated into
96an image feature (``eclipse-debug``) that corresponds to the
97``packagegroup-core-eclipse-debug`` package group. Previously, the
98debugging feature was included through the ``tools-debug`` image
99feature, which corresponds to the ``packagegroup-core-tools-debug``
100package group.
101
102.. _migration-1.4-variables:
103
104Variables
105---------
106
107The following variables have changed:
108
109- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
110 ID, which is composed of the host distributor ID followed by the
111 release. Previously,
112 :term:`SANITY_TESTED_DISTROS` was
113 composed of the description field. For example, "Ubuntu 12.10"
114 becomes "Ubuntu-12.10". You do not need to worry about this change if
115 you are not specifically setting this variable, or if you are
116 specifically setting it to "".
117
118- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
119 ``${``\ :term:`PF`\ ``}``,
120 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
121 have been dropped from the default value of the
122 :term:`FILESPATH` variable, which is used as the
123 search path for finding files referred to in
124 :term:`SRC_URI`. If you have a recipe that relied upon
125 these directories, which would be unusual, then you will need to add
126 the appropriate paths within the recipe or, alternatively, rearrange
127 the files. The most common locations are still covered by ``${``\ :term:`BP`\ ``}``,
128 ``${``\ :term:`BPN`\ ``}``, and "files", which all remain in the default value of
129 :term:`FILESPATH`.
130
131.. _migration-target-package-management-with-rpm:
132
133Target Package Management with RPM
134----------------------------------
135
136If runtime package management is enabled and the RPM backend is
137selected, Smart is now installed for package download, dependency
138resolution, and upgrades instead of Zypper. For more information on how
139to use Smart, run the following command on the target:
140::
141
142 smart --help
143
144.. _migration-1.4-recipes-moved:
145
146Recipes Moved
147-------------
148
149The following recipes were moved from their previous locations because
150they are no longer used by anything in the OpenEmbedded-Core:
151
152- ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
153
154- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
155
156- ``gthumb``: Now resides in the ``meta-gnome`` layer.
157
158- ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
159
160- ``gupnp``: Now resides in the ``meta-multimedia`` layer.
161
162- ``gypsy``: Now resides in the ``meta-oe`` layer.
163
164- ``libcanberra``: Now resides in the ``meta-gnome`` layer.
165
166- ``libgdata``: Now resides in the ``meta-gnome`` layer.
167
168- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
169
170- ``metacity``: Now resides in the ``meta-gnome`` layer.
171
172- ``polkit``: Now resides in the ``meta-oe`` layer.
173
174- ``zeroconf``: Now resides in the ``meta-networking`` layer.
175
176.. _migration-1.4-removals-and-renames:
177
178Removals and Renames
179--------------------
180
181The following list shows what has been removed or renamed:
182
183- ``evieext``: Removed because it has been removed from ``xserver``
184 since 2008.
185
186- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
187 supports it as of version 2.18.
188
189- ``libxfontcache / xfontcacheproto``: Removed because they were
190 removed from the Xorg server in 2008.
191
192- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
193 because the XPrint server was removed from Xorg in 2008.
194
195- ``libxtrap / xtrapproto``: Removed because their functionality was
196 broken upstream.
197
198- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
199 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
200 of the release.
201
202- ``lsbsetup``: Removed with functionality now provided by
203 ``lsbtest``.
204
205- ``matchbox-stroke``: Removed because it was never more than a
206 proof-of-concept.
207
208- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
209 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
210 are still provided.
211
212- ``mesa-dri``: Renamed to ``mesa``.
213
214- ``mesa-xlib``: Removed because it was no longer useful.
215
216- ``mutter``: Removed because nothing ever uses it and the recipe is
217 very old.
218
219- ``orinoco-conf``: Removed because it has become obsolete.
220
221- ``update-modules``: Removed because it is no longer used. The
222 kernel module ``postinstall`` and ``postrm`` scripts can now do the
223 same task without the use of this script.
224
225- ``web``: Removed because it is not maintained. Superseded by
226 ``web-webkit``.
227
228- ``xf86bigfontproto``: Removed because upstream it has been disabled
229 by default since 2007. Nothing uses ``xf86bigfontproto``.
230
231- ``xf86rushproto``: Removed because its dependency in ``xserver``
232 was spurious and it was removed in 2005.
233
234- ``zypper / libzypp / sat-solver``: Removed and been functionally
235 replaced with Smart (``python-smartpm``) when RPM packaging is used
236 and package management is enabled on the target.
237
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
deleted file mode 100644
index 2716bc9cfd..0000000000
--- a/documentation/ref-manual/migration-1.5.rst
+++ /dev/null
@@ -1,353 +0,0 @@
1Moving to the Yocto Project 1.5 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.5 Release from the prior release.
6
7.. _migration-1.5-host-dependency-changes:
8
9Host Dependency Changes
10-----------------------
11
12The OpenEmbedded build system now has some additional requirements on
13the host system:
14
15- Python 2.7.3+
16
17- Tar 1.24+
18
19- Git 1.7.8+
20
21- Patched version of Make if you are using 3.82. Most distributions
22 that provide Make 3.82 use the patched version.
23
24If the Linux distribution you are using on your build host does not
25provide packages for these, you can install and use the Buildtools
26tarball, which provides an SDK-like environment containing them.
27
28For more information on this requirement, see the
29":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
30section.
31
32.. _migration-1.5-atom-pc-bsp:
33
34``atom-pc`` Board Support Package (BSP)
35---------------------------------------
36
37The ``atom-pc`` hardware reference BSP has been replaced by a
38``genericx86`` BSP. This BSP is not necessarily guaranteed to work on
39all x86 hardware, but it will run on a wider range of systems than the
40``atom-pc`` did.
41
42.. note::
43
44 Additionally, a ``genericx86-64`` BSP has been added for 64-bit Atom
45 systems.
46
47.. _migration-1.5-bitbake:
48
49BitBake
50-------
51
52The following changes have been made that relate to BitBake:
53
54- BitBake now supports a ``_remove`` operator. The addition of this
55 operator means you will have to rename any items in recipe space
56 (functions, variables) whose names currently contain ``_remove_`` or
57 end with ``_remove`` to avoid unexpected behavior.
58
59- BitBake's global method pool has been removed. This method is not
60 particularly useful and led to clashes between recipes containing
61 functions that had the same name.
62
63- The "none" server backend has been removed. The "process" server
64 backend has been serving well as the default for a long time now.
65
66- The ``bitbake-runtask`` script has been removed.
67
68- ``${``\ :term:`P`\ ``}`` and
69 ``${``\ :term:`PF`\ ``}`` are no longer added to
70 :term:`PROVIDES` by default in ``bitbake.conf``.
71 These version-specific ``PROVIDES`` items were seldom used.
72 Attempting to use them could result in two versions being built
73 simultaneously rather than just one version due to the way BitBake
74 resolves dependencies.
75
76.. _migration-1.5-qa-warnings:
77
78QA Warnings
79-----------
80
81The following changes have been made to the package QA checks:
82
83- If you have customized :term:`ERROR_QA` or
84 :term:`WARN_QA` values in your configuration, check
85 that they contain all of the issues that you wish to be reported.
86 Previous Yocto Project versions contained a bug that meant that any
87 item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as
88 a warning. Consequently, several important items were not already in
89 the default value of ``WARN_QA``. All of the possible QA checks are
90 now documented in the ":ref:`insane.bbclass <ref-classes-insane>`"
91 section.
92
93- An additional QA check has been added to check if
94 ``/usr/share/info/dir`` is being installed. Your recipe should delete
95 this file within :ref:`ref-tasks-install` if "make
96 install" is installing it.
97
98- If you are using the ``buildhistory`` class, the check for the package
99 version going backwards is now controlled using a standard QA check.
100 Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
101 and still wish to have this check performed, you should add
102 "version-going-backwards" to your value for one or the other
103 variables depending on how you wish it to be handled. See the
104 documented QA checks in the
105 ":ref:`insane.bbclass <ref-classes-insane>`" section.
106
107.. _migration-1.5-directory-layout-changes:
108
109Directory Layout Changes
110------------------------
111
112The following directory changes exist:
113
114- Output SDK installer files are now named to include the image name
115 and tuning architecture through the :term:`SDK_NAME`
116 variable.
117
118- Images and related files are now installed into a directory that is
119 specific to the machine, instead of a parent directory containing
120 output files for multiple machines. The
121 :term:`DEPLOY_DIR_IMAGE` variable continues
122 to point to the directory containing images for the current
123 :term:`MACHINE` and should be used anywhere there is a
124 need to refer to this directory. The ``runqemu`` script now uses this
125 variable to find images and kernel binaries and will use BitBake to
126 determine the directory. Alternatively, you can set the
127 ``DEPLOY_DIR_IMAGE`` variable in the external environment.
128
129- When buildhistory is enabled, its output is now written under the
130 :term:`Build Directory` rather than
131 :term:`TMPDIR`. Doing so makes it easier to delete
132 ``TMPDIR`` and preserve the build history. Additionally, data for
133 produced SDKs is now split by :term:`IMAGE_NAME`.
134
135- The ``pkgdata`` directory produced as part of the packaging process
136 has been collapsed into a single machine-specific directory. This
137 directory is located under ``sysroots`` and uses a machine-specific
138 name (i.e. ``tmp/sysroots/machine/pkgdata``).
139
140.. _migration-1.5-shortened-git-srcrev-values:
141
142Shortened Git ``SRCREV`` Values
143-------------------------------
144
145BitBake will now shorten revisions from Git repositories from the normal
14640 characters down to 10 characters within :term:`SRCPV`
147for improved usability in path and file names. This change should be
148safe within contexts where these revisions are used because the chances
149of spatially close collisions is very low. Distant collisions are not a
150major issue in the way the values are used.
151
152.. _migration-1.5-image-features:
153
154``IMAGE_FEATURES``
155------------------
156
157The following changes have been made that relate to
158:term:`IMAGE_FEATURES`:
159
160- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid
161 feature items are not added. Some users mistakenly add package names
162 to this variable instead of using
163 :term:`IMAGE_INSTALL` in order to have the
164 package added to the image, which does not work. This change is
165 intended to catch those kinds of situations. Valid ``IMAGE_FEATURES``
166 are drawn from ``PACKAGE_GROUP`` definitions,
167 :term:`COMPLEMENTARY_GLOB` and a new
168 "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag
169 change allows additional features to be added if they are not
170 provided using the previous two mechanisms.
171
172- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item
173 is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you
174 wish to have the splash screen enabled, since this is all that
175 apps-console-core was doing.
176
177.. _migration-1.5-run:
178
179``/run``
180--------
181
182The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has
183been introduced. You can find some of the implications for this change
184:oe_git:`here </openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`.
185The change also means that recipes that install files to ``/var/run``
186must be changed. You can find a guide on how to make these changes
187`here <https://www.mail-archive.com/openembedded-devel@lists.openembedded.org/msg31649.html>`__.
188
189.. _migration-1.5-removal-of-package-manager-database-within-image-recipes:
190
191Removal of Package Manager Database Within Image Recipes
192--------------------------------------------------------
193
194The image ``core-image-minimal`` no longer adds
195``remove_packaging_data_files`` to
196:term:`ROOTFS_POSTPROCESS_COMMAND`.
197This addition is now handled automatically when "package-management" is
198not in :term:`IMAGE_FEATURES`. If you have custom
199image recipes that make this addition, you should remove the lines, as
200they are not needed and might interfere with correct operation of
201postinstall scripts.
202
203.. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time:
204
205Images Now Rebuild Only on Changes Instead of Every Time
206--------------------------------------------------------
207
208The :ref:`ref-tasks-rootfs` and other related image
209construction tasks are no longer marked as "nostamp". Consequently, they
210will only be re-executed when their inputs have changed. Previous
211versions of the OpenEmbedded build system always rebuilt the image when
212requested rather when necessary.
213
214.. _migration-1.5-task-recipes:
215
216Task Recipes
217------------
218
219The previously deprecated ``task.bbclass`` has now been dropped. For
220recipes that previously inherited from this class, you should rename
221them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup
222instead.
223
224For more information, see the
225":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section.
226
227.. _migration-1.5-busybox:
228
229BusyBox
230-------
231
232By default, we now split BusyBox into two binaries: one that is suid
233root for those components that need it, and another for the rest of the
234components. Splitting BusyBox allows for optimization that eliminates
235the ``tinylogin`` recipe as recommended by upstream. You can disable
236this split by setting
237:term:`BUSYBOX_SPLIT_SUID` to "0".
238
239.. _migration-1.5-automated-image-testing:
240
241Automated Image Testing
242-----------------------
243
244A new automated image testing framework has been added through the
245:ref:`testimage.bbclass <ref-classes-testimage*>` class. This
246framework replaces the older ``imagetest-qemu`` framework.
247
248You can learn more about performing automated image tests in the
249":ref:`dev-manual/common-tasks:performing automated runtime testing`"
250section in the Yocto Project Development Tasks Manual.
251
252.. _migration-1.5-build-history:
253
254Build History
255-------------
256
257Following are changes to Build History:
258
259- Installed package sizes: ``installed-package-sizes.txt`` for an image
260 now records the size of the files installed by each package instead
261 of the size of each compressed package archive file.
262
263- The dependency graphs (``depends*.dot``) now use the actual package
264 names instead of replacing dashes, dots and plus signs with
265 underscores.
266
267- The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs``
268 utilities have improved command-line handling. Use the ``--help``
269 option for each utility for more information on the new syntax.
270
271For more information on Build History, see the
272":ref:`dev-manual/common-tasks:maintaining build output quality`"
273section in the Yocto Project Development Tasks Manual.
274
275.. _migration-1.5-udev:
276
277``udev``
278--------
279
280Following are changes to ``udev``:
281
282- ``udev`` no longer brings in ``udev-extraconf`` automatically through
283 :term:`RRECOMMENDS`, since this was originally
284 intended to be optional. If you need the extra rules, then add
285 ``udev-extraconf`` to your image.
286
287- ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids``
288 through ``RRECOMMENDS``. These are not needed by ``udev`` itself and
289 removing them saves around 350KB.
290
291.. _migration-1.5-removed-renamed-recipes:
292
293Removed and Renamed Recipes
294---------------------------
295
296- The ``linux-yocto`` 3.2 kernel has been removed.
297
298- ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
299
300- ``tinylogin`` has been removed. It has been replaced by a suid
301 portion of Busybox. See the "`BusyBox <#busybox>`__"
302 section for more information.
303
304- ``external-python-tarball`` has been renamed to
305 ``buildtools-tarball``.
306
307- ``web-webkit`` has been removed. It has been functionally replaced by
308 ``midori``.
309
310- ``imake`` has been removed. It is no longer needed by any other
311 recipe.
312
313- ``transfig-native`` has been removed. It is no longer needed by any
314 other recipe.
315
316- ``anjuta-remote-run`` has been removed. Anjuta IDE integration has
317 not been officially supported for several releases.
318
319.. _migration-1.5-other-changes:
320
321Other Changes
322-------------
323
324Following is a list of short entries describing other changes:
325
326- ``run-postinsts``: Make this generic.
327
328- ``base-files``: Remove the unnecessary ``media/``\ xxx directories.
329
330- ``alsa-state``: Provide an empty ``asound.conf`` by default.
331
332- ``classes/image``: Ensure
333 :term:`BAD_RECOMMENDATIONS` supports
334 pre-renamed package names.
335
336- ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM.
337
338- ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in
339 :term:`DISTRO_FEATURES`.
340
341- ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is
342 present and ``sysvinit`` is not a distro feature.
343
344- ``libpam``: Deny all services for the ``OTHER`` entries.
345
346- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
347 with ``multilib``. See :yocto_bugs:`YOCTO #4993 </show_bug.cgi?id=4993>`
348 in Bugzilla for more information.
349
350- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
351
352- ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool.
353
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
deleted file mode 100644
index ed155d0df9..0000000000
--- a/documentation/ref-manual/migration-1.6.rst
+++ /dev/null
@@ -1,416 +0,0 @@
1Moving to the Yocto Project 1.6 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.6 Release from the prior release.
6
7.. _migration-1.6-archiver-class:
8
9``archiver`` Class
10------------------
11
12The :ref:`archiver <ref-classes-archiver>` class has been rewritten
13and its configuration has been simplified. For more details on the
14source archiver, see the
15":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
16section in the Yocto Project Development Tasks Manual.
17
18.. _migration-1.6-packaging-changes:
19
20Packaging Changes
21-----------------
22
23The following packaging changes have been made:
24
25- The ``binutils`` recipe no longer produces a ``binutils-symlinks``
26 package. ``update-alternatives`` is now used to handle the preferred
27 ``binutils`` variant on the target instead.
28
29- The tc (traffic control) utilities have been split out of the main
30 ``iproute2`` package and put into the ``iproute2-tc`` package.
31
32- The ``gtk-engines`` schemas have been moved to a dedicated
33 ``gtk-engines-schemas`` package.
34
35- The ``armv7a`` with thumb package architecture suffix has changed.
36 The suffix for these packages with the thumb optimization enabled is
37 "t2" as it should be. Use of this suffix was not the case in the 1.5
38 release. Architecture names will change within package feeds as a
39 result.
40
41.. _migration-1.6-bitbake:
42
43BitBake
44-------
45
46The following changes have been made to :term:`BitBake`.
47
48.. _migration-1.6-matching-branch-requirement-for-git-fetching:
49
50Matching Branch Requirement for Git Fetching
51~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52
53When fetching source from a Git repository using
54:term:`SRC_URI`, BitBake will now validate the
55:term:`SRCREV` value against the branch. You can specify
56the branch using the following form:
57::
58
59 SRC_URI = "git://server.name/repository;branch=branchname"
60
61If you do not specify a branch, BitBake looks in the default "master" branch.
62
63Alternatively, if you need to bypass this check (e.g. if you are
64fetching a revision corresponding to a tag that is not on any branch),
65you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
66
67.. _migration-1.6-bitbake-deps:
68
69Python Definition substitutions
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72BitBake had some previously deprecated Python definitions within its
73``bb`` module removed. You should use their sub-module counterparts
74instead:
75
76- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``.
77
78- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``.
79
80- ``bb.decodeurl``: Use ``bb.fetch.decodeurl``
81
82- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``.
83
84- ``bb.movefile``: Use ``bb.utils.movefile``.
85
86- ``bb.copyfile``: Use ``bb.utils.copyfile``.
87
88- ``bb.which``: Use ``bb.utils.which``.
89
90- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``.
91
92- ``bb.vercmp``: Use ``bb.utils.vercmp``.
93
94.. _migration-1.6-bitbake-fetcher:
95
96SVK Fetcher
97~~~~~~~~~~~
98
99The SVK fetcher has been removed from BitBake.
100
101.. _migration-1.6-bitbake-console-output:
102
103Console Output Error Redirection
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106The BitBake console UI will now output errors to ``stderr`` instead of
107``stdout``. Consequently, if you are piping or redirecting the output of
108``bitbake`` to somewhere else, and you wish to retain the errors, you
109will need to add ``2>&1`` (or something similar) to the end of your
110``bitbake`` command line.
111
112.. _migration-1.6-task-taskname-overrides:
113
114``task-``\ taskname Overrides
115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116
117``task-``\ taskname overrides have been adjusted so that tasks whose
118names contain underscores have the underscores replaced by hyphens for
119the override so that they now function properly. For example, the task
120override for :ref:`ref-tasks-populate_sdk` is
121``task-populate-sdk``.
122
123.. _migration-1.6-variable-changes:
124
125Changes to Variables
126--------------------
127
128The following variables have changed. For information on the
129OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chapter.
130
131.. _migration-1.6-variable-changes-TMPDIR:
132
133``TMPDIR``
134~~~~~~~~~~
135
136:term:`TMPDIR` can no longer be on an NFS mount. NFS does
137not offer full POSIX locking and inode consistency and can cause
138unexpected issues if used to store ``TMPDIR``.
139
140The check for this occurs on startup. If ``TMPDIR`` is detected on an
141NFS mount, an error occurs.
142
143.. _migration-1.6-variable-changes-PRINC:
144
145``PRINC``
146~~~~~~~~~
147
148The ``PRINC`` variable has been deprecated and triggers a warning if
149detected during a build. For :term:`PR` increments on changes,
150use the PR service instead. You can find out more about this service in
151the ":ref:`dev-manual/common-tasks:working with a pr service`"
152section in the Yocto Project Development Tasks Manual.
153
154.. _migration-1.6-variable-changes-IMAGE_TYPES:
155
156``IMAGE_TYPES``
157~~~~~~~~~~~~~~~
158
159The "sum.jffs2" option for :term:`IMAGE_TYPES` has
160been replaced by the "jffs2.sum" option, which fits the processing
161order.
162
163.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST:
164
165``COPY_LIC_MANIFEST``
166~~~~~~~~~~~~~~~~~~~~~
167
168The :term:`COPY_LIC_MANIFEST` variable must now
169be set to "1" rather than any value in order to enable it.
170
171.. _migration-1.6-variable-changes-COPY_LIC_DIRS:
172
173``COPY_LIC_DIRS``
174~~~~~~~~~~~~~~~~~
175
176The :term:`COPY_LIC_DIRS` variable must now be set
177to "1" rather than any value in order to enable it.
178
179.. _migration-1.6-variable-changes-PACKAGE_GROUP:
180
181``PACKAGE_GROUP``
182~~~~~~~~~~~~~~~~~
183
184The ``PACKAGE_GROUP`` variable has been renamed to
185:term:`FEATURE_PACKAGES` to more accurately
186reflect its purpose. You can still use ``PACKAGE_GROUP`` but the
187OpenEmbedded build system produces a warning message when it encounters
188the variable.
189
190.. _migration-1.6-variable-changes-variable-entry-behavior:
191
192Preprocess and Post Process Command Variable Behavior
193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
195The following variables now expect a semicolon separated list of
196functions to call and not arbitrary shell commands:
197
198 - :term:`ROOTFS_PREPROCESS_COMMAND`
199 - :term:`ROOTFS_POSTPROCESS_COMMAND`
200 - :term:`SDK_POSTPROCESS_COMMAND`
201 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
202 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
203 - :term:`IMAGE_POSTPROCESS_COMMAND`
204 - :term:`IMAGE_PREPROCESS_COMMAND`
205 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
206 - :term:`ROOTFS_POSTINSTALL_COMMAND`
207
208For
209migration purposes, you can simply wrap shell commands in a shell
210function and then call the function. Here is an example: ::
211
212 my_postprocess_function() {
213 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
214 }
215 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
216
217.. _migration-1.6-package-test-ptest:
218
219Package Test (ptest)
220--------------------
221
222Package Tests (ptest) are built but not installed by default. For
223information on using Package Tests, see the
224":ref:`dev-manual/common-tasks:testing packages with ptest`"
225section in the Yocto Project Development Tasks Manual. For information on the
226``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
227section.
228
229.. _migration-1.6-build-changes:
230
231Build Changes
232-------------
233
234Separate build and source directories have been enabled by default for
235selected recipes where it is known to work (a whitelist) and for all
236recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In
237future releases the :ref:`autotools <ref-classes-autotools>` class
238will enable a separate build directory by default as well. Recipes
239building Autotools-based software that fails to build with a separate
240build directory should be changed to inherit from the
241:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
242the ``autotools`` or ``autotools_stage``\ classes.
243
244.. _migration-1.6-building-qemu-native:
245
246``qemu-native``
247---------------
248
249``qemu-native`` now builds without SDL-based graphical output support by
250default. The following additional lines are needed in your
251``local.conf`` to enable it:
252::
253
254 PACKAGECONFIG_pn-qemu-native = "sdl"
255 ASSUME_PROVIDED += "libsdl-native"
256
257.. note::
258
259 The default ``local.conf`` contains these statements. Consequently, if you
260 are building a headless system and using a default ``local.conf``
261 file, you will need comment these two lines out.
262
263.. _migration-1.6-core-image-basic:
264
265``core-image-basic``
266--------------------
267
268``core-image-basic`` has been renamed to ``core-image-full-cmdline``.
269
270In addition to ``core-image-basic`` being renamed,
271``packagegroup-core-basic`` has been renamed to
272``packagegroup-core-full-cmdline`` to match.
273
274.. _migration-1.6-licensing:
275
276Licensing
277---------
278
279The top-level ``LICENSE`` file has been changed to better describe the
280license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
281the licensing itself remains unchanged.
282
283Normally, this change would not cause any side-effects. However, some
284recipes point to this file within
285:term:`LIC_FILES_CHKSUM` (as
286``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
287changed from 3f40d7994397109285ec7b81fdeb3b58 to
2884d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
289``LIC_FILES_CHKSUM`` point to a file describing the license that is
290distributed with the source that the recipe is building, if possible,
291rather than pointing to ``${COREBASE}/LICENSE``.
292
293.. _migration-1.6-cflags-options:
294
295``CFLAGS`` Options
296------------------
297
298The "-fpermissive" option has been removed from the default
299:term:`CFLAGS` value. You need to take action on
300individual recipes that fail when building with this option. You need to
301either patch the recipes to fix the issues reported by the compiler, or
302you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
303
304.. _migration-1.6-custom-images:
305
306Custom Image Output Types
307-------------------------
308
309Custom image output types, as selected using
310:term:`IMAGE_FSTYPES`, must declare their
311dependencies on other image types (if any) using a new
312:term:`IMAGE_TYPEDEP` variable.
313
314.. _migration-1.6-do-package-write-task:
315
316Tasks
317-----
318
319The ``do_package_write`` task has been removed. The task is no longer
320needed.
321
322.. _migration-1.6-update-alternatives-provider:
323
324``update-alternative`` Provider
325-------------------------------
326
327The default ``update-alternatives`` provider has been changed from
328``opkg`` to ``opkg-utils``. This change resolves some troublesome
329circular dependencies. The runtime package has also been renamed from
330``update-alternatives-cworth`` to ``update-alternatives-opkg``.
331
332.. _migration-1.6-virtclass-overrides:
333
334``virtclass`` Overrides
335-----------------------
336
337The ``virtclass`` overrides are now deprecated. Use the equivalent class
338overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.)
339
340.. _migration-1.6-removed-renamed-recipes:
341
342Removed and Renamed Recipes
343---------------------------
344
345The following recipes have been removed:
346
347- ``packagegroup-toolset-native`` - This recipe is largely unused.
348
349- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been
350 dropped. Support for the 3.10 and 3.14 kernels have been added with
351 the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes.
352
353- ``ocf-linux`` - This recipe has been functionally replaced using
354 ``cryptodev-linux``.
355
356- ``genext2fs`` - ``genext2fs`` is no longer used by the build system
357 and is unmaintained upstream.
358
359- ``js`` - This provided an ancient version of Mozilla's javascript
360 engine that is no longer needed.
361
362- ``zaurusd`` - The recipe has been moved to the ``meta-handheld``
363 layer.
364
365- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe.
366
367- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``.
368
369- ``external-sourcery-toolchain`` - this recipe is now maintained in
370 the ``meta-sourcery`` layer.
371
372- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the
373 ``linux-libc-headers`` by default.
374
375- ``meta-toolchain-gmae`` - This recipe is obsolete.
376
377- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete.
378
379- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is
380 obsolete.
381
382.. _migration-1.6-removed-classes:
383
384Removed Classes
385---------------
386
387The following classes have become obsolete and have been removed:
388
389- ``module_strip``
390
391- ``pkg_metainfo``
392
393- ``pkg_distribute``
394
395- ``image-empty``
396
397.. _migration-1.6-reference-bsps:
398
399Reference Board Support Packages (BSPs)
400---------------------------------------
401
402The following reference BSPs changes occurred:
403
404- The BeagleBoard (``beagleboard``) ARM reference hardware has been
405 replaced by the BeagleBone (``beaglebone``) hardware.
406
407- The RouterStation Pro (``routerstationpro``) MIPS reference hardware
408 has been replaced by the EdgeRouter Lite (``edgerouter``) hardware.
409
410The previous reference BSPs for the ``beagleboard`` and
411``routerstationpro`` machines are still available in a new
412``meta-yocto-bsp-old`` layer in the
413:yocto_git:`Source Repositories <>` at
414:yocto_git:`/meta-yocto-bsp-old/`.
415
416
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
deleted file mode 100644
index 54544e4798..0000000000
--- a/documentation/ref-manual/migration-1.7.rst
+++ /dev/null
@@ -1,223 +0,0 @@
1Moving to the Yocto Project 1.7 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.7 Release from the prior release.
6
7.. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
8
9Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf``
10-------------------------------------------------------------------
11
12The QEMU recipe now uses a number of
13:term:`PACKAGECONFIG` options to enable various
14optional features. The method used to set defaults for these options
15means that existing ``local.conf`` files will need to be be modified to
16append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
17instead of setting it. In other words, to enable graphical output for
18QEMU, you should now have these lines in ``local.conf``:
19::
20
21 PACKAGECONFIG_append_pn-qemu-native = " sdl"
22 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
23
24.. _migration-1.7-minimum-git-version:
25
26Minimum Git version
27-------------------
28
29The minimum :ref:`overview-manual/development-environment:git`
30version required on the
31build host is now 1.7.8 because the ``--list`` option is now required by
32BitBake's Git fetcher. As always, if your host distribution does not
33provide a version of Git that meets this requirement, you can use the
34``buildtools-tarball`` that does. See the
35":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
36section for more information.
37
38.. _migration-1.7-autotools-class-changes:
39
40Autotools Class Changes
41-----------------------
42
43The following :ref:`autotools <ref-classes-autotools>` class changes
44occurred:
45
46- *A separate build directory is now used by default:* The
47 ``autotools`` class has been changed to use a directory for building
48 (:term:`B`), which is separate from the source directory
49 (:term:`S`). This is commonly referred to as ``B != S``, or
50 an out-of-tree build.
51
52 If the software being built is already capable of building in a
53 directory separate from the source, you do not need to do anything.
54 However, if the software is not capable of being built in this
55 manner, you will need to either patch the software so that it can
56 build separately, or you will need to change the recipe to inherit
57 the :ref:`autotools-brokensep <ref-classes-autotools>` class
58 instead of the ``autotools`` or ``autotools_stage`` classes.
59
60- The ``--foreign`` option is no longer passed to ``automake`` when
61 running ``autoconf``: This option tells ``automake`` that a
62 particular software package does not follow the GNU standards and
63 therefore should not be expected to distribute certain files such as
64 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
65 upstream software packages already tell ``automake`` to enable
66 foreign mode themselves, the option is mostly superfluous. However,
67 some recipes will need patches for this change. You can easily make
68 the change by patching ``configure.ac`` so that it passes "foreign"
69 to ``AM_INIT_AUTOMAKE()``. See :oe_git:`this
70 commit </openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`
71 for an example showing how to make the patch.
72
73.. _migration-1.7-binary-configuration-scripts-disabled:
74
75Binary Configuration Scripts Disabled
76-------------------------------------
77
78Some of the core recipes that package binary configuration scripts now
79disable the scripts due to the scripts previously requiring error-prone
80path substitution. Software that links against these libraries using
81these scripts should use the much more robust ``pkg-config`` instead.
82The list of recipes changed in this version (and their configuration
83scripts) is as follows:
84::
85
86 directfb (directfb-config)
87 freetype (freetype-config)
88 gpgme (gpgme-config)
89 libassuan (libassuan-config)
90 libcroco (croco-6.0-config)
91 libgcrypt (libgcrypt-config)
92 libgpg-error (gpg-error-config)
93 libksba (ksba-config)
94 libpcap (pcap-config)
95 libpcre (pcre-config)
96 libpng (libpng-config, libpng16-config)
97 libsdl (sdl-config)
98 libusb-compat (libusb-config)
99 libxml2 (xml2-config)
100 libxslt (xslt-config)
101 ncurses (ncurses-config)
102 neon (neon-config)
103 npth (npth-config)
104 pth (pth-config)
105 taglib (taglib-config)
106
107Additionally, support for ``pkg-config`` has been added to some recipes in the
108previous list in the rare cases where the upstream software package does
109not already provide it.
110
111.. _migration-1.7-glibc-replaces-eglibc:
112
113``eglibc 2.19`` Replaced with ``glibc 2.20``
114--------------------------------------------
115
116Because ``eglibc`` and ``glibc`` were already fairly close, this
117replacement should not require any significant changes to other software
118that links to ``eglibc``. However, there were a number of minor changes
119in ``glibc 2.20`` upstream that could require patching some software
120(e.g. the removal of the ``_BSD_SOURCE`` feature test macro).
121
122``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel.
123Thus, older kernels will no longer be usable in conjunction with it.
124
125For full details on the changes in ``glibc 2.20``, see the upstream
126release notes
127`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__.
128
129.. _migration-1.7-kernel-module-autoloading:
130
131Kernel Module Autoloading
132-------------------------
133
134The :term:`module_autoload_* <module_autoload>` variable is now
135deprecated and a new
136:term:`KERNEL_MODULE_AUTOLOAD` variable
137should be used instead. Also, :term:`module_conf_* <module_conf>`
138must now be used in conjunction with a new
139:term:`KERNEL_MODULE_PROBECONF` variable.
140The new variables no longer require you to specify the module name as
141part of the variable name. This change not only simplifies usage but
142also allows the values of these variables to be appropriately
143incorporated into task signatures and thus trigger the appropriate tasks
144to re-execute when changed. You should replace any references to
145``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
146modules for which ``module_conf_*`` is specified to
147``KERNEL_MODULE_PROBECONF``.
148
149.. _migration-1.7-qa-check-changes:
150
151QA Check Changes
152----------------
153
154The following changes have occurred to the QA check process:
155
156- Additional QA checks ``file-rdeps`` and ``build-deps`` have been
157 added in order to verify that file dependencies are satisfied (e.g.
158 package contains a script requiring ``/bin/bash``) and build-time
159 dependencies are declared, respectively. For more information, please
160 see the ":doc:`/ref-manual/qa-checks`" chapter.
161
162- Package QA checks are now performed during a new
163 :ref:`ref-tasks-package_qa` task rather than being
164 part of the :ref:`ref-tasks-package` task. This allows
165 more parallel execution. This change is unlikely to be an issue
166 except for highly customized recipes that disable packaging tasks
167 themselves by marking them as ``noexec``. For those packages, you
168 will need to disable the ``do_package_qa`` task as well.
169
170- Files being overwritten during the
171 :ref:`ref-tasks-populate_sysroot` task now
172 trigger an error instead of a warning. Recipes should not be
173 overwriting files written to the sysroot by other recipes. If you
174 have these types of recipes, you need to alter them so that they do
175 not overwrite these files.
176
177 You might now receive this error after changes in configuration or
178 metadata resulting in orphaned files being left in the sysroot. If
179 you do receive this error, the way to resolve the issue is to delete
180 your :term:`TMPDIR` or to move it out of the way and
181 then re-start the build. Anything that has been fully built up to
182 that point and does not need rebuilding will be restored from the
183 shared state cache and the rest of the build will be able to proceed
184 as normal.
185
186.. _migration-1.7-removed-recipes:
187
188Removed Recipes
189---------------
190
191The following recipes have been removed:
192
193- ``x-load``: This recipe has been superseded by U-Boot SPL for all
194 Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
195 contains a maintained recipe, should be used instead.
196
197- ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has
198 been added to functionally replace it.
199
200- ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been
201 dropped. Support for the 3.10 and 3.14 kernels remains, while support
202 for version 3.17 has been added.
203
204- ``eglibc`` has been removed in favor of ``glibc``. See the
205 ":ref:`migration-1.7-glibc-replaces-eglibc`" section for more information.
206
207.. _migration-1.7-miscellaneous-changes:
208
209Miscellaneous Changes
210---------------------
211
212The following miscellaneous change occurred:
213
214- The build history feature now writes ``build-id.txt`` instead of
215 ``build-id``. Additionally, ``build-id.txt`` now contains the full
216 build header as printed by BitBake upon starting the build. You
217 should manually remove old "build-id" files from your existing build
218 history repositories to avoid confusion. For information on the build
219 history feature, see the
220 ":ref:`dev-manual/common-tasks:maintaining build output quality`"
221 section in the Yocto Project Development Tasks Manual.
222
223
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
deleted file mode 100644
index 73789bd518..0000000000
--- a/documentation/ref-manual/migration-1.8.rst
+++ /dev/null
@@ -1,183 +0,0 @@
1Moving to the Yocto Project 1.8 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 1.8 Release from the prior release.
6
7.. _migration-1.8-removed-recipes:
8
9Removed Recipes
10---------------
11
12The following recipes have been removed:
13
14- ``owl-video``: Functionality replaced by ``gst-player``.
15
16- ``gaku``: Functionality replaced by ``gst-player``.
17
18- ``gnome-desktop``: This recipe is now available in ``meta-gnome`` and
19 is no longer needed.
20
21- ``gsettings-desktop-schemas``: This recipe is now available in
22 ``meta-gnome`` and is no longer needed.
23
24- ``python-argparse``: The ``argparse`` module is already provided in
25 the default Python distribution in a package named
26 ``python-argparse``. Consequently, the separate ``python-argparse``
27 recipe is no longer needed.
28
29- ``telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control``:
30 All these recipes have moved to ``meta-oe`` and are consequently no
31 longer needed by any recipes in OpenEmbedded-Core.
32
33- ``linux-yocto_3.10`` and ``linux-yocto_3.17``: Support for the
34 linux-yocto 3.10 and 3.17 kernels has been dropped. Support for the
35 3.14 kernel remains, while support for 3.19 kernel has been added.
36
37- ``poky-feed-config-opkg``: This recipe has become obsolete and is no
38 longer needed. Use ``distro-feed-config`` from ``meta-oe`` instead.
39
40- ``libav 0.8.x``: ``libav 9.x`` is now used.
41
42- ``sed-native``: No longer needed. A working version of ``sed`` is
43 expected to be provided by the host distribution.
44
45.. _migration-1.8-bluez:
46
47BlueZ 4.x / 5.x Selection
48-------------------------
49
50Proper built-in support for selecting BlueZ 5.x in preference to the
51default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your
52:term:`DISTRO_FEATURES` value. If you had
53previously added append files (``*.bbappend``) to make this selection,
54you can now remove them.
55
56Additionally, a ``bluetooth`` class has been added to make selection of
57the appropriate bluetooth support within a recipe a little easier. If
58you wish to make use of this class in a recipe, add something such as
59the following: ::
60
61 inherit bluetooth
62 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
63 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
64 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
65
66.. _migration-1.8-kernel-build-changes:
67
68Kernel Build Changes
69--------------------
70
71The kernel build process was changed to place the source in a common
72shared work area and to place build artifacts separately in the source
73code tree. In theory, migration paths have been provided for most common
74usages in kernel recipes but this might not work in all cases. In
75particular, users need to ensure that ``${S}`` (source files) and
76``${B}`` (build artifacts) are used correctly in functions such as
77:ref:`ref-tasks-configure` and
78:ref:`ref-tasks-install`. For kernel recipes that do not
79inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might
80wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the
81kinds of changes you need to make. For reference, here is the
82:oe_git:`commit </meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`
83where the ``linux.inc`` file in ``meta-oe`` was updated.
84
85Recipes that rely on the kernel source code and do not inherit the
86module classes might need to add explicit dependencies on the
87``do_shared_workdir`` kernel task, for example: ::
88
89 do_configure[depends] += "virtual/kernel:do_shared_workdir"
90
91.. _migration-1.8-ssl:
92
93SSL 3.0 is Now Disabled in OpenSSL
94----------------------------------
95
96SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids
97any lingering instances of the POODLE vulnerability. If you feel you
98must re-enable SSL 3.0, then you can add an append file (``*.bbappend``)
99for the ``openssl`` recipe to remove "-no-ssl3" from
100:term:`EXTRA_OECONF`.
101
102.. _migration-1.8-default-sysroot-poisoning:
103
104Default Sysroot Poisoning
105-------------------------
106
107``gcc's`` default sysroot and include directories are now "poisoned". In
108other words, the sysroot and include directories are being redirected to
109a non-existent location in order to catch when host directories are
110being used due to the correct options not being passed. This poisoning
111applies both to the cross-compiler used within the build and to the
112cross-compiler produced in the SDK.
113
114If this change causes something in the build to fail, it almost
115certainly means the various compiler flags and commands are not being
116passed correctly to the underlying piece of software. In such cases, you
117need to take corrective steps.
118
119.. _migration-1.8-rebuild-improvements:
120
121Rebuild Improvements
122--------------------
123
124Changes have been made to the :ref:`base <ref-classes-base>`,
125:ref:`autotools <ref-classes-autotools>`, and
126:ref:`cmake <ref-classes-cmake>` classes to clean out generated files
127when the :ref:`ref-tasks-configure` task needs to be
128re-executed.
129
130One of the improvements is to attempt to run "make clean" during the
131``do_configure`` task if a ``Makefile`` exists. Some software packages
132do not provide a working clean target within their make files. If you
133have such recipes, you need to set
134:term:`CLEANBROKEN` to "1" within the recipe, for example: ::
135
136 CLEANBROKEN = "1"
137
138.. _migration-1.8-qa-check-and-validation-changes:
139
140QA Check and Validation Changes
141-------------------------------
142
143The following QA Check and Validation Changes have occurred:
144
145- Usage of ``PRINC`` previously triggered a warning. It now triggers an
146 error. You should remove any remaining usage of ``PRINC`` in any
147 recipe or append file.
148
149- An additional QA check has been added to detect usage of ``${D}`` in
150 :term:`FILES` values where :term:`D` values
151 should not be used at all. The same check ensures that ``$D`` is used
152 in ``pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm`` functions
153 instead of ``${D}``.
154
155- :term:`S` now needs to be set to a valid value within a
156 recipe. If ``S`` is not set in the recipe, the directory is not
157 automatically created. If ``S`` does not point to a directory that
158 exists at the time the :ref:`ref-tasks-unpack` task
159 finishes, a warning will be shown.
160
161- :term:`LICENSE` is now validated for correct
162 formatting of multiple licenses. If the format is invalid (e.g.
163 multiple licenses are specified with no operators to specify how the
164 multiple licenses interact), then a warning will be shown.
165
166.. _migration-1.8-miscellaneous-changes:
167
168Miscellaneous Changes
169---------------------
170
171The following miscellaneous changes have occurred:
172
173- The ``send-error-report`` script now expects a "-s" option to be
174 specified before the server address. This assumes a server address is
175 being specified.
176
177- The ``oe-pkgdata-util`` script now expects a "-p" option to be
178 specified before the ``pkgdata`` directory, which is now optional. If
179 the ``pkgdata`` directory is not specified, the script will run
180 BitBake to query :term:`PKGDATA_DIR` from the
181 build environment.
182
183
diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst
deleted file mode 100644
index 4eea94887b..0000000000
--- a/documentation/ref-manual/migration-2.0.rst
+++ /dev/null
@@ -1,281 +0,0 @@
1Moving to the Yocto Project 2.0 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.0 Release from the prior release.
6
7.. _migration-2.0-gcc-5:
8
9GCC 5
10-----
11
12The default compiler is now GCC 5.2. This change has required fixes for
13compilation errors in a number of other recipes.
14
15One important example is a fix for when the Linux kernel freezes at boot
16time on ARM when built with GCC 5. If you are using your own kernel
17recipe or source tree and building for ARM, you will likely need to
18apply this
19`patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__.
20The standard ``linux-yocto`` kernel source tree already has a workaround
21for the same issue.
22
23For further details, see https://gcc.gnu.org/gcc-5/changes.html
24and the porting guide at
25https://gcc.gnu.org/gcc-5/porting_to.html.
26
27Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
28``GCCVERSION`` in your configuration, as follows:
29::
30
31 GCCVERSION = "4.9%"
32
33.. _migration-2.0-Gstreamer-0.10-removed:
34
35Gstreamer 0.10 Removed
36----------------------
37
38Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of
39the change, recipes for Gstreamer 0.10 and related software are now
40located in ``meta-multimedia``. This change results in Qt4 having Phonon
41and Gstreamer support in QtWebkit disabled by default.
42
43.. _migration-2.0-removed-recipes:
44
45Removed Recipes
46---------------
47
48The following recipes have been moved or removed:
49
50- ``bluez4``: The recipe is obsolete and has been moved due to
51 ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now
52 resides in ``meta-oe``.
53
54- ``gamin``: The recipe is obsolete and has been removed.
55
56- ``gnome-icon-theme``: The recipe's functionally has been replaced by
57 ``adwaita-icon-theme``.
58
59- Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed
60 in favor of the recipes for Gstreamer 1.x.
61
62- ``insserv``: The recipe is obsolete and has been removed.
63
64- ``libunique``: The recipe is no longer used and has been moved to
65 ``meta-oe``.
66
67- ``midori``: The recipe's functionally has been replaced by
68 ``epiphany``.
69
70- ``python-gst``: The recipe is obsolete and has been removed since it
71 only contains bindings for Gstreamer 0.10.
72
73- ``qt-mobility``: The recipe is obsolete and has been removed since it
74 requires ``Gstreamer 0.10``, which has been replaced.
75
76- ``subversion``: All 1.6.x versions of this recipe have been removed.
77
78- ``webkit-gtk``: The older 1.8.3 version of this recipe has been
79 removed in favor of ``webkitgtk``.
80
81.. _migration-2.0-bitbake-datastore-improvements:
82
83BitBake datastore improvements
84------------------------------
85
86The method by which BitBake's datastore handles overrides has changed.
87Overrides are now applied dynamically and ``bb.data.update_data()`` is
88now a no-op. Thus, ``bb.data.update_data()`` is no longer required in
89order to apply the correct overrides. In practice, this change is
90unlikely to require any changes to Metadata. However, these minor
91changes in behavior exist:
92
93- All potential overrides are now visible in the variable history as
94 seen when you run the following:
95 ::
96
97 $ bitbake -e
98
99- ``d.delVar('VARNAME')`` and
100 ``d.setVar('VARNAME', None)`` result in the variable and all
101 of its overrides being cleared out. Before the change, only the
102 non-overridden values were cleared.
103
104.. _migration-2.0-shell-message-function-changes:
105
106Shell Message Function Changes
107------------------------------
108
109The shell versions of the BitBake message functions (i.e. ``bbdebug``,
110``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are
111now connected through to their BitBake equivalents ``bb.debug()``,
112``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and
113``bb.fatal()``, respectively. Thus, those message functions that you
114would expect to be printed by the BitBake UI are now actually printed.
115In practice, this change means two things:
116
117- If you now see messages on the console that you did not previously
118 see as a result of this change, you might need to clean up the calls
119 to ``bbwarn``, ``bberror``, and so forth. Or, you might want to
120 simply remove the calls.
121
122- The ``bbfatal`` message function now suppresses the full error log in
123 the UI, which means any calls to ``bbfatal`` where you still wish to
124 see the full error log should be replaced by ``die`` or
125 ``bbfatal_log``.
126
127.. _migration-2.0-extra-development-debug-package-cleanup:
128
129Extra Development/Debug Package Cleanup
130---------------------------------------
131
132The following recipes have had extra ``dev/dbg`` packages removed:
133
134- ``acl``
135
136- ``apmd``
137
138- ``aspell``
139
140- ``attr``
141
142- ``augeas``
143
144- ``bzip2``
145
146- ``cogl``
147
148- ``curl``
149
150- ``elfutils``
151
152- ``gcc-target``
153
154- ``libgcc``
155
156- ``libtool``
157
158- ``libxmu``
159
160- ``opkg``
161
162- ``pciutils``
163
164- ``rpm``
165
166- ``sysfsutils``
167
168- ``tiff``
169
170- ``xz``
171
172All of the above recipes now conform to the standard packaging scheme
173where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per
174recipe.
175
176.. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core:
177
178Recipe Maintenance Tracking Data Moved to OE-Core
179-------------------------------------------------
180
181Maintenance tracking data for recipes that was previously part of
182``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change
183includes ``package_regex.inc`` and ``distro_alias.inc``, which are
184typically enabled when using the ``distrodata`` class. Additionally, the
185contents of ``upstream_tracking.inc`` has now been split out to the
186relevant recipes.
187
188.. _migration-2.0-automatic-stale-sysroot-file-cleanup:
189
190Automatic Stale Sysroot File Cleanup
191------------------------------------
192
193Stale files from recipes that no longer exist in the current
194configuration are now automatically removed from sysroot as well as
195removed from any other place managed by shared state. This automatic
196cleanup means that the build system now properly handles situations such
197as renaming the build system side of recipes, removal of layers from
198``bblayers.conf``, and :term:`DISTRO_FEATURES`
199changes.
200
201Additionally, work directories for old versions of recipes are now
202pruned. If you wish to disable pruning old work directories, you can set
203the following variable in your configuration:
204::
205
206 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
207
208.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source:
209
210``linux-yocto`` Kernel Metadata Repository Now Split from Source
211----------------------------------------------------------------
212
213The ``linux-yocto`` tree has up to now been a combined set of kernel
214changes and configuration (meta) data carried in a single tree. While
215this format is effective at keeping kernel configuration and source
216modifications synchronized, it is not always obvious to developers how
217to manipulate the Metadata as compared to the source.
218
219Metadata processing has now been removed from the
220:ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external
221Metadata repository ``yocto-kernel-cache``, which has always been used
222to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto``
223cache repository is now the primary location for this data. Due to this
224change, ``linux-yocto`` is no longer able to process combined trees.
225Thus, if you need to have your own combined kernel repository, you must
226do the split there as well and update your recipes accordingly. See the
227``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example.
228
229.. _migration-2.0-additional-qa-checks:
230
231Additional QA checks
232--------------------
233
234The following QA checks have been added:
235
236- Added a "host-user-contaminated" check for ownership issues for
237 packaged files outside of ``/home``. The check looks for files that
238 are incorrectly owned by the user that ran BitBake instead of owned
239 by a valid user in the target system.
240
241- Added an "invalid-chars" check for invalid (non-UTF8) characters in
242 recipe metadata variable values (i.e.
243 :term:`DESCRIPTION`,
244 :term:`SUMMARY`, :term:`LICENSE`, and
245 :term:`SECTION`). Some package managers do not support
246 these characters.
247
248- Added an "invalid-packageconfig" check for any options specified in
249 :term:`PACKAGECONFIG` that do not match any
250 ``PACKAGECONFIG`` option defined for the recipe.
251
252.. _migration-2.0-miscellaneous:
253
254Miscellaneous Changes
255---------------------
256
257These additional changes exist:
258
259- ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``.
260
261- The ``tools-profile`` :term:`IMAGE_FEATURES`
262 item as well as its corresponding packagegroup and
263 ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``.
264 Bringing in ``oprofile`` was originally added to aid compilation on
265 resource-constrained targets. However, this aid has not been widely
266 used and is not likely to be used going forward due to the more
267 powerful target platforms and the existence of better
268 cross-compilation tools.
269
270- The :term:`IMAGE_FSTYPES` variable's default
271 value now specifies ``ext4`` instead of ``ext3``.
272
273- All support for the ``PRINC`` variable has been removed.
274
275- The ``packagegroup-core-full-cmdline`` packagegroup no longer brings
276 in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not
277 really in line with the packagegroup's purpose, which is to add full
278 versions of command-line tools that by default are provided by
279 ``busybox``.
280
281
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
deleted file mode 100644
index 861d04861b..0000000000
--- a/documentation/ref-manual/migration-2.1.rst
+++ /dev/null
@@ -1,436 +0,0 @@
1Moving to the Yocto Project 2.1 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.1 Release from the prior release.
6
7.. _migration-2.1-variable-expansion-in-python-functions:
8
9Variable Expansion in Python Functions
10--------------------------------------
11
12Variable expressions, such as ``${VARNAME}`` no longer expand
13automatically within Python functions. Suppressing expansion was done to
14allow Python functions to construct shell scripts or other code for
15situations in which you do not want such expressions expanded. For any
16existing code that relies on these expansions, you need to change the
17expansions to expand the value of individual variables through
18``d.getVar()``. To alternatively expand more complex expressions, use
19``d.expand()``.
20
21.. _migration-2.1-overrides-must-now-be-lower-case:
22
23Overrides Must Now be Lower-Case
24--------------------------------
25
26The convention for overrides has always been for them to be lower-case
27characters. This practice is now a requirement as BitBake's datastore
28now assumes lower-case characters in order to give a slight performance
29boost during parsing. In practical terms, this requirement means that
30anything that ends up in :term:`OVERRIDES` must now
31appear in lower-case characters (e.g. values for ``MACHINE``,
32``TARGET_ARCH``, ``DISTRO``, and also recipe names if
33``_pn-``\ recipename overrides are to be effective).
34
35.. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory:
36
37Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory
38----------------------------------------------------------------------
39
40The expand parameter to ``getVar()`` and ``getVarFlag()`` previously
41defaulted to False if not specified. Now, however, no default exists so
42one must be specified. You must change any ``getVar()`` calls that do
43not specify the final expand parameter to calls that do specify the
44parameter. You can run the following ``sed`` command at the base of a
45layer to make this change:
46::
47
48 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
49 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
50
51.. note::
52
53 The reason for this change is that it prepares the way for changing
54 the default to True in a future Yocto Project release. This future
55 change is a much more sensible default than False. However, the
56 change needs to be made gradually as a sudden change of the default
57 would potentially cause side-effects that would be difficult to
58 detect.
59
60.. _migration-2.1-makefile-environment-changes:
61
62Makefile Environment Changes
63----------------------------
64
65:term:`EXTRA_OEMAKE` now defaults to "" instead of
66"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default
67was a historical accident that has required many classes (e.g.
68``autotools``, ``module``) and recipes to override this default in order
69to work with sensible build systems. When upgrading to the release, you
70must edit any recipe that relies upon this old default by either setting
71``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any
72required variable value overrides using ``EXTRA_OEMAKE``, which is
73typically only needed when a Makefile sets a default value for a
74variable that is inappropriate for cross-compilation using the "="
75operator rather than the "?=" operator.
76
77.. _migration-2.1-libexecdir-reverted-to-prefix-libexec:
78
79``libexecdir`` Reverted to ``${prefix}/libexec``
80------------------------------------------------
81
82The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as
83compared to all other mainstream distributions, which either uses
84``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the
85GNU Coding Standards (i.e.
86https://www.gnu.org/prep/standards/html_node/Directory-Variables.html)
87that suggest ``${prefix}/libexec`` and also notes that any
88package-specific nesting should be done by the package itself. Finally,
89having ``libexecdir`` change between recipes makes it very difficult for
90different recipes to invoke binaries that have been installed into
91``libexecdir``. The Filesystem Hierarchy Standard (i.e.
92https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now
93recognizes the use of ``${prefix}/libexec/``, giving distributions the
94choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without
95breaking FHS.
96
97.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files:
98
99``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files
100--------------------------------------------------------
101
102For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
103class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for
104``autoconf``. The reason for this change is because the
105``ac_cv_sizeof_off_t`` value is not necessarily static per architecture
106as was previously assumed. Rather, the value changes based on whether
107large file support is enabled. For most software that uses ``autoconf``,
108this change should not be a problem. However, if you have a recipe that
109bypasses the standard :ref:`ref-tasks-configure` task
110from the ``autotools`` class and the software the recipe is building
111uses a very old version of ``autoconf``, the recipe might be incapable
112of determining the correct size of ``off_t`` during ``do_configure``.
113
114The best course of action is to patch the software as necessary to allow
115the default implementation from the ``autotools`` class to work such
116that ``autoreconf`` succeeds and produces a working configure script,
117and to remove the overridden ``do_configure`` task such that the default
118implementation does get used.
119
120.. _migration-2.1-image-generation-split-out-from-filesystem-generation:
121
122Image Generation is Now Split Out from Filesystem Generation
123------------------------------------------------------------
124
125Previously, for image recipes the :ref:`ref-tasks-rootfs`
126task assembled the filesystem and then from that filesystem generated
127images. With this Yocto Project release, image generation is split into
128separate :ref:`ref-tasks-image` tasks for clarity both in
129operation and in the code.
130
131For most cases, this change does not present any problems. However, if
132you have made customizations that directly modify the ``do_rootfs`` task
133or that mention ``do_rootfs``, you might need to update those changes.
134In particular, if you had added any tasks after ``do_rootfs``, you
135should make edits so that those tasks are after the
136:ref:`ref-tasks-image-complete` task rather than
137after ``do_rootfs`` so that the your added tasks run at the correct
138time.
139
140A minor part of this restructuring is that the post-processing
141definitions and functions have been moved from the
142:ref:`image <ref-classes-image>` class to the
143:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally,
144however, they remain unchanged.
145
146.. _migration-2.1-removed-recipes:
147
148Removed Recipes
149---------------
150
151The following recipes have been removed in the 2.1 release:
152
153- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain.
154
155- ``qt4``: All support for Qt 4.x has been moved out to a separate
156 ``meta-qt4`` layer because Qt 4 is no longer supported upstream.
157
158- ``x11vnc``: Moved to the ``meta-oe`` layer.
159
160- ``linux-yocto-3.14``: No longer supported.
161
162- ``linux-yocto-3.19``: No longer supported.
163
164- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe.
165
166- ``pth``: Became obsolete.
167
168- ``liboil``: Recipe is no longer needed and has been moved to the
169 ``meta-multimedia`` layer.
170
171- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved
172 to the ``meta-gnome`` layer.
173
174- ``gnome-mime-data``: Recipe is no longer needed and has been moved to
175 the ``meta-gnome`` layer.
176
177- ``udev``: Replaced by the ``eudev`` recipe for compatibility when
178 using ``sysvinit`` with newer kernels.
179
180- ``python-pygtk``: Recipe became obsolete.
181
182- ``adt-installer``: Recipe became obsolete. See the "`ADT
183 Removed <#adt-removed>`__" section for more
184 information.
185
186.. _migration-2.1-class-changes:
187
188Class Changes
189-------------
190
191The following classes have changed:
192
193- ``autotools_stage``: Removed because the
194 :ref:`autotools <ref-classes-autotools>` class now provides its
195 functionality. Recipes that inherited from ``autotools_stage`` should
196 now inherit from ``autotools`` instead.
197
198- ``boot-directdisk``: Merged into the ``image-vm`` class. The
199 ``boot-directdisk`` class was rarely directly used. Consequently,
200 this change should not cause any issues.
201
202- ``bootimg``: Merged into the
203 :ref:`image-live <ref-classes-image-live>` class. The ``bootimg``
204 class was rarely directly used. Consequently, this change should not
205 cause any issues.
206
207- ``packageinfo``: Removed due to its limited use by the Hob UI, which
208 has itself been removed.
209
210.. _migration-2.1-build-system-ui-changes:
211
212Build System User Interface Changes
213-----------------------------------
214
215The following changes have been made to the build system user interface:
216
217- *Hob GTK+-based UI*: Removed because it is unmaintained and based on
218 the outdated GTK+ 2 library. The Toaster web-based UI is much more
219 capable and is actively maintained. See the
220 ":ref:`toaster-manual/setup-and-use:using the toaster web interface`"
221 section in the Toaster User Manual for more information on this
222 interface.
223
224- *"puccho" BitBake UI*: Removed because is unmaintained and no longer
225 useful.
226
227.. _migration-2.1-adt-removed:
228
229ADT Removed
230-----------
231
232The Application Development Toolkit (ADT) has been removed because its
233functionality almost completely overlapped with the :ref:`standard
234SDK <sdk-manual/using:using the standard sdk>` and the
235:ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For
236information on these SDKs and how to build and use them, see the
237:doc:`/sdk-manual/index` manual.
238
239.. note::
240
241 The Yocto Project Eclipse IDE Plug-in is still supported and is not
242 affected by this change.
243
244.. _migration-2.1-poky-reference-distribution-changes:
245
246Poky Reference Distribution Changes
247-----------------------------------
248
249The following changes have been made for the Poky distribution:
250
251- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better
252 match its purpose, which is to provide the Poky reference
253 distribution. The ``meta-yocto-bsp`` layer retains its original name
254 since it provides reference machines for the Yocto Project and it is
255 otherwise unrelated to Poky. References to ``meta-yocto`` in your
256 ``conf/bblayers.conf`` should automatically be updated, so you should
257 not need to change anything unless you are relying on this naming
258 elsewhere.
259
260- The :ref:`uninative <ref-classes-uninative>` class is now enabled
261 by default in Poky. This class attempts to isolate the build system
262 from the host distribution's C library and makes re-use of native
263 shared state artifacts across different host distributions practical.
264 With this class enabled, a tarball containing a pre-built C library
265 is downloaded at the start of the build.
266
267 The ``uninative`` class is enabled through the
268 ``meta/conf/distro/include/yocto-uninative.inc`` file, which for
269 those not using the Poky distribution, can include to easily enable
270 the same functionality.
271
272 Alternatively, if you wish to build your own ``uninative`` tarball,
273 you can do so by building the ``uninative-tarball`` recipe, making it
274 available to your build machines (e.g. over HTTP/HTTPS) and setting a
275 similar configuration as the one set by ``yocto-uninative.inc``.
276
277- Static library generation, for most cases, is now disabled by default
278 in the Poky distribution. Disabling this generation saves some build
279 time as well as the size used for build output artifacts.
280
281 Disabling this library generation is accomplished through a
282 ``meta/conf/distro/include/no-static-libs.inc``, which for those not
283 using the Poky distribution can easily include to enable the same
284 functionality.
285
286 Any recipe that needs to opt-out of having the "--disable-static"
287 option specified on the configure command line either because it is
288 not a supported option for the configure script or because static
289 libraries are needed should set the following variable:
290 ::
291
292 DISABLE_STATIC = ""
293
294- The separate ``poky-tiny`` distribution now uses the musl C library
295 instead of a heavily pared down ``glibc``. Using musl results in a
296 smaller distribution and facilitates much greater maintainability
297 because musl is designed to have a small footprint.
298
299 If you have used ``poky-tiny`` and have customized the ``glibc``
300 configuration you will need to redo those customizations with musl
301 when upgrading to the new release.
302
303.. _migration-2.1-packaging-changes:
304
305Packaging Changes
306-----------------
307
308The following changes have been made to packaging:
309
310- The ``runuser`` and ``mountpoint`` binaries, which were previously in
311 the main ``util-linux`` package, have been split out into the
312 ``util-linux-runuser`` and ``util-linux-mountpoint`` packages,
313 respectively.
314
315- The ``python-elementtree`` package has been merged into the
316 ``python-xml`` package.
317
318.. _migration-2.1-tuning-file-changes:
319
320Tuning File Changes
321-------------------
322
323The following changes have been made to the tuning files:
324
325- The "no-thumb-interwork" tuning feature has been dropped from the ARM
326 tune include files. Because interworking is required for ARM EABI,
327 attempting to disable it through a tuning feature no longer makes
328 sense.
329
330 .. note::
331
332 Support for ARM OABI was deprecated in gcc 4.7.
333
334- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been
335 removed because they are poorly tested. Until the OpenEmbedded build
336 system officially gains support for CPUs without an MMU, these tuning
337 files would probably be better maintained in a separate layer if
338 needed.
339
340.. _migration-2.1-supporting-gobject-introspection:
341
342Supporting GObject Introspection
343--------------------------------
344
345This release supports generation of GLib Introspective Repository (GIR)
346files through GObject introspection, which is the standard mechanism for
347accessing GObject-based software from runtime environments. You can
348enable, disable, and test the generation of this data. See the
349":ref:`dev-manual/common-tasks:enabling gobject introspection support`"
350section in the Yocto Project Development Tasks Manual for more
351information.
352
353.. _migration-2.1-miscellaneous-changes:
354
355Miscellaneous Changes
356---------------------
357
358These additional changes exist:
359
360- The minimum Git version has been increased to 1.8.3.1. If your host
361 distribution does not provide a sufficiently recent version, you can
362 install the buildtools, which will provide it. See the
363 :ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
364 section for more information on the buildtools tarball.
365
366- The buggy and incomplete support for the RPM version 4 package
367 manager has been removed. The well-tested and maintained support for
368 RPM version 5 remains.
369
370- Previously, the following list of packages were removed if
371 package-management was not in
372 :term:`IMAGE_FEATURES`, regardless of any
373 dependencies:
374 ::
375
376 update-rc.d
377 base-passwd
378 shadow
379 update-alternatives
380 run-postinsts
381
382 With the Yocto Project 2.1 release, these packages are
383 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
384 they might still be needed for a read-write image even in the absence
385 of a package manager (e.g. if users need to be added, modified, or
386 removed at runtime).
387
388- The
389 :ref:`devtool modify <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
390 command now defaults to extracting the source since that is most
391 commonly expected. The "-x" or "--extract" options are now no-ops. If
392 you wish to provide your own existing source tree, you will now need
393 to specify either the "-n" or "--no-extract" options when running
394 ``devtool modify``.
395
396- If the formfactor for a machine is either not supplied or does not
397 specify whether a keyboard is attached, then the default is to assume
398 a keyboard is attached rather than assume no keyboard. This change
399 primarily affects the Sato UI.
400
401- The ``.debug`` directory packaging is now automatic. If your recipe
402 builds software that installs binaries into directories other than
403 the standard ones, you no longer need to take care of setting
404 ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories
405 as these directories are automatically found and added.
406
407- Inaccurate disk and CPU percentage data has been dropped from
408 ``buildstats`` output. This data has been replaced with
409 ``getrusage()`` data and corrected IO statistics. You will probably
410 need to update any custom code that reads the ``buildstats`` data.
411
412- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated.
413 The contents of this file have been moved to individual recipes.
414
415 .. note::
416
417 Because this file will likely be removed in a future Yocto Project
418 release, it is suggested that you remove any references to the
419 file that might be in your configuration.
420
421- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and
422 ``genericx86-64`` reference machines, which are provided by the
423 ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this
424 file and it only adds kernel error messages during startup. If you do
425 still need to support ``uvesafb``, you can simply add ``v86d`` to
426 your image.
427
428- Build sysroot paths are now removed from debug symbol files. Removing
429 these paths means that remote GDB using an unstripped build system
430 sysroot will no longer work (although this was never documented to
431 work). The supported method to accomplish something similar is to set
432 ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug
433 image containing unstripped binaries and associated debug sources
434 alongside the image.
435
436
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
deleted file mode 100644
index 5c6fecf328..0000000000
--- a/documentation/ref-manual/migration-2.2.rst
+++ /dev/null
@@ -1,450 +0,0 @@
1Moving to the Yocto Project 2.2 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.2 Release from the prior release.
6
7.. _migration-2.2-minimum-kernel-version:
8
9Minimum Kernel Version
10----------------------
11
12The minimum kernel version for the target system and for SDK is now
133.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for
14AArch64-based targets the version is 3.14. For Nios II-based targets,
15the minimum kernel version is 3.19.
16
17.. note::
18
19 For x86 and x86_64, you can reset :term:`OLDEST_KERNEL`
20 to anything down to 2.6.32 if desired.
21
22.. _migration-2.2-staging-directories-in-sysroot-simplified:
23
24Staging Directories in Sysroot Has Been Simplified
25--------------------------------------------------
26
27The way directories are staged in sysroot has been simplified and
28introduces the new :term:`SYSROOT_DIRS`,
29:term:`SYSROOT_DIRS_NATIVE`, and
30:term:`SYSROOT_DIRS_BLACKLIST`. See the
31:oe_lists:`v2 patch series on the OE-Core Mailing List
32</pipermail/openembedded-core/2016-May/121365.html>`
33for additional information.
34
35.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
36
37Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
38-------------------------------------------------------------------
39
40Removal of old images and other files in ``tmp/deploy/`` is now enabled
41by default due to a new staging method used for those files. As a result
42of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
43
44.. _migration-2.2-python-changes:
45
46Python Changes
47--------------
48
49The following changes for Python occurred:
50
51.. _migration-2.2-bitbake-now-requires-python-3.4:
52
53BitBake Now Requires Python 3.4+
54~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55
56BitBake requires Python 3.4 or greater.
57
58.. _migration-2.2-utf-8-locale-required-on-build-host:
59
60UTF-8 Locale Required on Build Host
61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63A UTF-8 locale is required on the build host due to Python 3. Since
64C.UTF-8 is not a standard, the default is en_US.UTF-8.
65
66.. _migration-2.2-metadata-now-must-use-python-3-syntax:
67
68Metadata Must Now Use Python 3 Syntax
69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71The metadata is now required to use Python 3 syntax. For help preparing
72metadata, see any of the many Python 3 porting guides available.
73Alternatively, you can reference the conversion commits for Bitbake and
74you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
75particular areas of interest:
76
77 - subprocess command-line pipes needing locale decoding
78
79 - the syntax for octal values changed
80
81 - the ``iter*()`` functions changed name
82
83 - iterators now return views, not lists
84
85 - changed names for Python modules
86
87.. _migration-2.2-target-python-recipes-switched-to-python-3:
88
89Target Python Recipes Switched to Python 3
90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92Most target Python recipes have now been switched to Python 3.
93Unfortunately, systems using RPM as a package manager and providing
94online package-manager support through SMART still require Python 2.
95
96.. note::
97
98 Python 2 and recipes that use it can still be built for the target as
99 with previous versions.
100
101.. _migration-2.2-buildtools-tarball-includes-python-3:
102
103``buildtools-tarball`` Includes Python 3
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106``buildtools-tarball`` now includes Python 3.
107
108.. _migration-2.2-uclibc-replaced-by-musl:
109
110uClibc Replaced by musl
111-----------------------
112
113uClibc has been removed in favor of musl. Musl has matured, is better
114maintained, and is compatible with a wider range of applications as
115compared to uClibc.
116
117.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
118
119``${B}`` No Longer Default Working Directory for Tasks
120------------------------------------------------------
121
122``${``\ :term:`B`\ ``}`` is no longer the default working
123directory for tasks. Consequently, any custom tasks you define now need
124to either have the
125``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag
126set, or the task needs to change into the appropriate working directory
127manually (e.g using ``cd`` for a shell task).
128
129.. note::
130
131 The preferred method is to use the
132 [dirs]
133 flag.
134
135.. _migration-2.2-runqemu-ported-to-python:
136
137``runqemu`` Ported to Python
138----------------------------
139
140``runqemu`` has been ported to Python and has changed behavior in some
141cases. Previous usage patterns continue to be supported.
142
143The new ``runqemu`` is a Python script. Machine knowledge is no longer
144hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
145configuration file to define the BSP's own arguments and to make it
146bootable with ``runqemu``. If you use a configuration file, use the
147following form:
148::
149
150 image-name-machine.qemuboot.conf
151
152The configuration file
153enables fine-grained tuning of options passed to QEMU without the
154``runqemu`` script hard-coding any knowledge about different machines.
155Using a configuration file is particularly convenient when trying to use
156QEMU with machines other than the ``qemu*`` machines in
157:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the
158``qemuboot`` class when the root filesystem is being build (i.e. build
159rootfs). QEMU boot arguments can be set in BSP's configuration file and
160the ``qemuboot`` class will save them to ``qemuboot.conf``.
161
162If you want to use ``runqemu`` without a configuration file, use the
163following command form:
164::
165
166 $ runqemu machine rootfs kernel [options]
167
168Supported machines are as follows:
169
170 - qemuarm
171 - qemuarm64
172 - qemux86
173 - qemux86-64
174 - qemuppc
175 - qemumips
176 - qemumips64
177 - qemumipsel
178 - qemumips64el
179
180Consider the
181following example, which uses the ``qemux86-64`` machine, provides a
182root filesystem, provides an image, and uses the ``nographic`` option: ::
183
184 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
185
186Following is a list of variables that can be set in configuration files
187such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
188
189.. note::
190
191 "QB" means "QEMU Boot".
192
193::
194
195 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
196 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
197 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
198 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
199 QB_MEM: Memory (e.g. "-m 512")
200 QB_MACHINE: QEMU machine (e.g. "-machine virt")
201 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
202 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
203 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
204 option (e.g. "console=ttyS0 console=tty")
205 QB_DTB: QEMU dtb name
206 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
207 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
208 when QB_AUDIO_DRV is set.
209 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
210 QB_TAP_OPT: Network option for 'tap' mode (e.g.
211 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
212 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
213 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
214 QB_ROOTFS_OPT: Used as rootfs (e.g.
215 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
216 runqemu will replace "@ROOTFS@" with the one which is used, such as
217 core-image-minimal-qemuarm64.ext4.
218 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
219 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
220 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
221 runqemu will replace "@PORT@" with the port number which is used.
222
223To use ``runqemu``, set :term:`IMAGE_CLASSES` as
224follows and run ``runqemu``:
225
226.. note::
227
228 For command-line syntax, use ``runqemu help``.
229
230::
231
232 IMAGE_CLASSES += "qemuboot"
233
234.. _migration-2.2-default-linker-hash-style-changed:
235
236Default Linker Hash Style Changed
237---------------------------------
238
239The default linker hash style for ``gcc-cross`` is now "sysv" in order
240to catch recipes that are building software without using the
241OpenEmbedded :term:`LDFLAGS`. This change could result in
242seeing some "No GNU_HASH in the elf binary" QA issues when building such
243recipes. You need to fix these recipes so that they use the expected
244``LDFLAGS``. Depending on how the software is built, the build system
245used by the software (e.g. a Makefile) might need to be patched.
246However, sometimes making this fix is as simple as adding the following
247to the recipe:
248::
249
250 TARGET_CC_ARCH += "${LDFLAGS}"
251
252.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
253
254``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
255--------------------------------------------------------------
256
257The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
258:term:`KERNEL_IMAGETYPE` variable to create the
259image's base name. Because the OpenEmbedded build system can now build
260multiple kernel image types, this part of the kernel image base name as
261been removed leaving only the following:
262::
263
264 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
265
266If you have recipes or
267classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
268update the references to ensure they continue to work.
269
270.. _migration-2.2-bitbake-changes:
271
272BitBake Changes
273---------------
274
275The following changes took place for BitBake:
276
277- The "goggle" UI and standalone image-writer tool have been removed as
278 they both require GTK+ 2.0 and were not being maintained.
279
280- The Perforce fetcher now supports :term:`SRCREV` for
281 specifying the source revision to use, be it
282 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
283 p4date, or label, in preference to separate
284 :term:`SRC_URI` parameters to specify these. This
285 change is more in-line with how the other fetchers work for source
286 control systems. Recipes that fetch from Perforce will need to be
287 updated to use ``SRCREV`` in place of specifying the source revision
288 within ``SRC_URI``.
289
290- Some of BitBake's internal code structures for accessing the recipe
291 cache needed to be changed to support the new multi-configuration
292 functionality. These changes will affect external tools that use
293 BitBake's tinfoil module. For information on these changes, see the
294 changes made to the scripts supplied with OpenEmbedded-Core:
295 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`
296 and
297 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`.
298
299- The task management code has been rewritten to avoid using ID
300 indirection in order to improve performance. This change is unlikely
301 to cause any problems for most users. However, the setscene
302 verification function as pointed to by
303 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
304 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
305 has been added allowing multiple versions of BitBake to work with
306 suitably written metadata, which includes OpenEmbedded-Core and Poky.
307 Anyone with custom BitBake task scheduler code might also need to
308 update the code to handle the new structure.
309
310.. _migration-2.2-swabber-has-been-removed:
311
312Swabber has Been Removed
313------------------------
314
315Swabber, a tool that was intended to detect host contamination in the
316build process, has been removed, as it has been unmaintained and unused
317for some time and was never particularly effective. The OpenEmbedded
318build system has since incorporated a number of mechanisms including
319enhanced QA checks that mean that there is less of a need for such a
320tool.
321
322.. _migration-2.2-removed-recipes:
323
324Removed Recipes
325---------------
326
327The following recipes have been removed:
328
329- ``augeas``: No longer needed and has been moved to ``meta-oe``.
330
331- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
332
333- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
334
335- ``gnome-doc-utils``: No longer needed.
336
337- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
338
339- ``gtk-engines``: No longer needed and has been moved to
340 ``meta-gnome``.
341
342- ``gtk-sato-engine``: Became obsolete.
343
344- ``libglade``: No longer needed and has been moved to ``meta-oe``.
345
346- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
347 ``libmad`` has been moved to ``meta-oe``.
348
349- ``libowl``: Became obsolete.
350
351- ``libxsettings-client``: No longer needed.
352
353- ``oh-puzzles``: Functionally replaced by ``puzzles``.
354
355- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
356 by perf.
357
358- ``packagegroup-core-directfb.bb``: Removed.
359
360- ``core-image-directfb.bb``: Removed.
361
362- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
363
364- ``python-imaging``: No longer needed and moved to ``meta-python``
365
366- ``python-pyrex``: No longer needed and moved to ``meta-python``.
367
368- ``sato-icon-theme``: Became obsolete.
369
370- ``swabber-native``: Swabber has been removed. See the `entry on
371 Swabber <#swabber-has-been-removed>`__.
372
373- ``tslib``: No longer needed and has been moved to ``meta-oe``.
374
375- ``uclibc``: Removed in favor of musl.
376
377- ``xtscal``: No longer needed and moved to ``meta-oe``
378
379.. _migration-2.2-removed-classes:
380
381Removed Classes
382---------------
383
384The following classes have been removed:
385
386- ``distutils-native-base``: No longer needed.
387
388- ``distutils3-native-base``: No longer needed.
389
390- ``sdl``: Only set :term:`DEPENDS` and
391 :term:`SECTION`, which are better set within the
392 recipe instead.
393
394- ``sip``: Mostly unused.
395
396- ``swabber``: See the `entry on
397 Swabber <#swabber-has-been-removed>`__.
398
399.. _migration-2.2-minor-packaging-changes:
400
401Minor Packaging Changes
402-----------------------
403
404The following minor packaging changes have occurred:
405
406- ``grub``: Split ``grub-editenv`` into its own package.
407
408- ``systemd``: Split container and vm related units into a new package,
409 systemd-container.
410
411- ``util-linux``: Moved ``prlimit`` to a separate
412 ``util-linux-prlimit`` package.
413
414.. _migration-2.2-miscellaneous-changes:
415
416Miscellaneous Changes
417---------------------
418
419The following miscellaneous changes have occurred:
420
421- ``package_regex.inc``: Removed because the definitions
422 ``package_regex.inc`` previously contained have been moved to their
423 respective recipes.
424
425- Both ``devtool add`` and ``recipetool create`` now use a fixed
426 :term:`SRCREV` by default when fetching from a Git
427 repository. You can override this in either case to use
428 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
429 ``-a`` or ``DASHDASHautorev`` command-line option
430
431- ``distcc``: GTK+ UI is now disabled by default.
432
433- ``packagegroup-core-tools-testapps``: Removed Piglit.
434
435- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
436 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
437 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
438 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
439 variable names will still work in the 2.2 release but metadata that
440 does not need to be backwards-compatible should be changed to use the
441 new names as the ``COMPRESS*`` ones will be removed in a future
442 release.
443
444- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
445 However, some old software might not be capable of using the current
446 version of ``gtk-doc`` to build documentation. You need to change
447 recipes that build such software so that they explicitly disable
448 building documentation with ``gtk-doc``.
449
450
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
deleted file mode 100644
index 04b11daa7d..0000000000
--- a/documentation/ref-manual/migration-2.3.rst
+++ /dev/null
@@ -1,523 +0,0 @@
1Moving to the Yocto Project 2.3 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.3 Release from the prior release.
6
7.. _migration-2.3-recipe-specific-sysroots:
8
9Recipe-specific Sysroots
10------------------------
11
12The OpenEmbedded build system now uses one sysroot per recipe to resolve
13long-standing issues with configuration script auto-detection of
14undeclared dependencies. Consequently, you might find that some of your
15previously written custom recipes are missing declared dependencies,
16particularly those dependencies that are incidentally built earlier in a
17typical build process and thus are already likely to be present in the
18shared sysroot in previous releases.
19
20Consider the following:
21
22- *Declare Build-Time Dependencies:* Because of this new feature, you
23 must explicitly declare all build-time dependencies for your recipe.
24 If you do not declare these dependencies, they are not populated into
25 the sysroot for the recipe.
26
27- *Specify Pre-Installation and Post-Installation Native Tool
28 Dependencies:* You must specifically specify any special native tool
29 dependencies of ``pkg_preinst`` and ``pkg_postinst`` scripts by using
30 the :term:`PACKAGE_WRITE_DEPS` variable.
31 Specifying these dependencies ensures that these tools are available
32 if these scripts need to be run on the build host during the
33 :ref:`ref-tasks-rootfs` task.
34
35 As an example, see the ``dbus`` recipe. You will see that this recipe
36 has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in
37 :term:`DISTRO_FEATURES`. In the example,
38 ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``,
39 which is also conditional on "systemd" being in ``DISTRO_FEATURES``.
40
41- Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to
42 examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine
43 steps to take.
44
45 Functions added to ``SSTATEPOSTINSTFUNCS`` are still called as they
46 were in previous Yocto Project releases. However, since a separate
47 sysroot is now being populated for every recipe and if existing
48 functions being called through ``SSTATEPOSTINSTFUNCS`` are doing
49 relocation, then you will need to change these to use a
50 post-installation script that is installed by a function added to
51 :term:`SYSROOT_PREPROCESS_FUNCS`.
52
53 For an example, see the ``pixbufcache`` class in ``meta/classes/`` in
54 the :ref:`overview-manual/development-environment:yocto project source repositories`.
55
56 .. note::
57
58 The
59 SSTATEPOSTINSTFUNCS
60 variable itself is now deprecated in favor of the
61 do_populate_sysroot[postfuncs]
62 task. Consequently, if you do still have any function or functions
63 that need to be called after the sysroot component is created for
64 a recipe, then you would be well advised to take steps to use a
65 post installation script as described previously. Taking these
66 steps prepares your code for when
67 SSTATEPOSTINSTFUNCS
68 is removed in a future Yocto Project release.
69
70- *Specify the Sysroot when Using Certain External Scripts:* Because
71 the shared sysroot is now gone, the scripts
72 ``oe-find-native-sysroot`` and ``oe-run-native`` have been changed
73 such that you need to specify which recipe's
74 :term:`STAGING_DIR_NATIVE` is used.
75
76.. note::
77
78 You can find more information on how recipe-specific sysroots work in
79 the ":ref:`ref-classes-staging`" section.
80
81.. _migration-2.3-path-variable:
82
83``PATH`` Variable
84-----------------
85
86Within the environment used to run build tasks, the environment variable
87``PATH`` is now sanitized such that the normal native binary paths
88(``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a
89directory containing symbolic links linking only to the binaries from
90the host mentioned in the :term:`HOSTTOOLS` and
91:term:`HOSTTOOLS_NONFATAL` variables is added
92to ``PATH``.
93
94Consequently, any native binaries provided by the host that you need to
95call needs to be in one of these two variables at the configuration
96level.
97
98Alternatively, you can add a native recipe (i.e. ``-native``) that
99provides the binary to the recipe's :term:`DEPENDS`
100value.
101
102.. note::
103
104 PATH
105 is not sanitized in the same way within ``devshell``.
106 If it were, you would have difficulty running host tools for
107 development and debugging within the shell.
108
109.. _migration-2.3-scripts:
110
111Changes to Scripts
112------------------
113
114The following changes to scripts took place:
115
116- ``oe-find-native-sysroot``: The usage for the
117 ``oe-find-native-sysroot`` script has changed to the following:
118 ::
119
120 $ . oe-find-native-sysroot recipe
121
122 You must now supply a recipe for recipe
123 as part of the command. Prior to the Yocto Project 2.3 release, it
124 was not necessary to provide the script with the command.
125
126- ``oe-run-native``: The usage for the ``oe-run-native`` script has
127 changed to the following:
128 ::
129
130 $ oe-run-native native_recipe tool
131
132 You must
133 supply the name of the native recipe and the tool you want to run as
134 part of the command. Prior to the Yocto Project 2.3 release, it
135 was not necessary to provide the native recipe with the command.
136
137- ``cleanup-workdir``: The ``cleanup-workdir`` script has been
138 removed because the script was found to be deleting files it should
139 not have, which lead to broken build trees. Rather than trying to
140 delete portions of :term:`TMPDIR` and getting it wrong,
141 it is recommended that you delete ``TMPDIR`` and have it restored
142 from shared state (sstate) on subsequent builds.
143
144- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
145 it is no longer needed with recipe-specific sysroots.
146
147.. _migration-2.3-functions:
148
149Changes to Functions
150--------------------
151
152The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``,
153and related functions have been removed in favor of ``d.getVar()``,
154``d.setVar()``, and so forth.
155
156You need to fix any references to these old functions.
157
158.. _migration-2.3-bitbake-changes:
159
160BitBake Changes
161---------------
162
163The following changes took place for BitBake:
164
165- *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's
166 graphical dependency explorer UI ``depexp`` was replaced by
167 ``taskexp`` ("Task Explorer"), which provides a graphical way of
168 exploring the ``task-depends.dot`` file. The data presented by Task
169 Explorer is much more accurate than the data that was presented by
170 ``depexp``. Being able to visualize the data is an often requested
171 feature as standard ``*.dot`` file viewers cannot usual cope with the
172 size of the ``task-depends.dot`` file.
173
174- *BitBake "-g" Output Changes:* The ``package-depends.dot`` and
175 ``pn-depends.dot`` files as previously generated using the
176 ``bitbake -g`` command have been removed. A ``recipe-depends.dot``
177 file is now generated as a collapsed version of ``task-depends.dot``
178 instead.
179
180 The reason for this change is because ``package-depends.dot`` and
181 ``pn-depends.dot`` largely date back to a time before task-based
182 execution and do not take into account task-level dependencies
183 between recipes, which could be misleading.
184
185- *Mirror Variable Splitting Changes:* Mirror variables including
186 :term:`MIRRORS`, :term:`PREMIRRORS`,
187 and :term:`SSTATE_MIRRORS` can now separate
188 values entirely with spaces. Consequently, you no longer need "\\n".
189 BitBake looks for pairs of values, which simplifies usage. There
190 should be no change required to existing mirror variable values
191 themselves.
192
193- *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an
194 "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter
195 instead of an "rsh" parameter. This new optional parameter is used
196 when the "protocol" parameter is set to "svn+ssh". You can only use
197 the new parameter to specify the ``ssh`` program used by SVN. The SVN
198 fetcher passes the new parameter through the ``SVN_SSH`` environment
199 variable during the :ref:`ref-tasks-fetch` task.
200
201 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:subversion (svn) fetcher (\`\`svn://\`\`)`"
202 section in the BitBake
203 User Manual for additional information.
204
205- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
206 Removed: Because the mechanism they were part of is no longer
207 necessary with recipe-specific sysroots, the
208 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
209 variables have been removed.
210
211.. _migration-2.3-absolute-symlinks:
212
213Absolute Symbolic Links
214-----------------------
215
216Absolute symbolic links (symlinks) within staged files are no longer
217permitted and now trigger an error. Any explicit creation of symlinks
218can use the ``lnr`` script, which is a replacement for ``ln -r``.
219
220If the build scripts in the software that the recipe is building are
221creating a number of absolute symlinks that need to be corrected, you
222can inherit ``relative_symlinks`` within the recipe to turn those
223absolute symlinks into relative symlinks.
224
225.. _migration-2.3-gplv2-and-gplv3-moves:
226
227GPLv2 Versions of GPLv3 Recipes Moved
228-------------------------------------
229
230Older GPLv2 versions of GPLv3 recipes have moved to a separate
231``meta-gplv2`` layer.
232
233If you use :term:`INCOMPATIBLE_LICENSE` to
234exclude GPLv3 or set :term:`PREFERRED_VERSION`
235to substitute a GPLv2 version of a GPLv3 recipe, then you must add the
236``meta-gplv2`` layer to your configuration.
237
238.. note::
239
240 You can ``find meta-gplv2`` layer in the OpenEmbedded layer index at
241 :oe_layer:`/meta-gplv2`.
242
243These relocated GPLv2 recipes do not receive the same level of
244maintenance as other core recipes. The recipes do not get security fixes
245and upstream no longer maintains them. In fact, the upstream community
246is actively hostile towards people that use the old versions of the
247recipes. Moving these recipes into a separate layer both makes the
248different needs of the recipes clearer and clearly identifies the number
249of these recipes.
250
251.. note::
252
253 The long-term solution might be to move to BSD-licensed replacements
254 of the GPLv3 components for those that need to exclude GPLv3-licensed
255 components from the target system. This solution will be investigated
256 for future Yocto Project releases.
257
258.. _migration-2.3-package-management-changes:
259
260Package Management Changes
261--------------------------
262
263The following package management changes took place:
264
265- Smart package manager is replaced by DNF package manager. Smart has
266 become unmaintained upstream, is not ported to Python 3.x.
267 Consequently, Smart needed to be replaced. DNF is the only feasible
268 candidate.
269
270 The change in functionality is that the on-target runtime package
271 management from remote package feeds is now done with a different
272 tool that has a different set of command-line options. If you have
273 scripts that call the tool directly, or use its API, they need to be
274 fixed.
275
276 For more information, see the `DNF
277 Documentation <https://dnf.readthedocs.io/en/latest/>`__.
278
279- Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons:
280
281 - DNF is API-incompatible with Rpm 5.x and porting it and
282 maintaining the port is non-trivial.
283
284 - Rpm 5.x itself has limited maintenance upstream, and the Yocto
285 Project is one of the very few remaining users.
286
287- Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default:
288
289 - Version 6.x of Berkeley DB has largely been rejected by the open
290 source community due to its AGPLv3 license. As a result, most
291 mainstream open source projects that require DB are still
292 developed and tested with DB 5.x.
293
294 - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x.
295 Thus, no reason exists to continue carrying DB 6.x in OE-core.
296
297- ``createrepo`` is replaced with ``createrepo_c``.
298
299 ``createrepo_c`` is the current incarnation of the tool that
300 generates remote repository metadata. It is written in C as compared
301 to ``createrepo``, which is written in Python. ``createrepo_c`` is
302 faster and is maintained.
303
304- Architecture-independent RPM packages are "noarch" instead of "all".
305
306 This change was made because too many places in DNF/RPM4 stack
307 already make that assumption. Only the filenames and the architecture
308 tag has changed. Nothing else has changed in OE-core system,
309 particularly in the :ref:`allarch.bbclass <ref-classes-allarch>`
310 class.
311
312- Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not
313 currently supported. This issue will be fully addressed in a future
314 Yocto Project release. See :yocto_bugs:`defect 11209 </show_bug.cgi?id=11209>`
315 for more information on a solution to package feed signing with RPM
316 in the Yocto Project 2.3 release.
317
318- OPKG now uses the libsolv backend for resolving package dependencies
319 by default. This is vastly superior to OPKG's internal ad-hoc solver
320 that was previously used. This change does have a small impact on
321 disk (around 500 KB) and memory footprint.
322
323 .. note::
324
325 For further details on this change, see the
326 :yocto_git:`commit message </poky/commit/?id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81>`.
327
328.. _migration-2.3-removed-recipes:
329
330Removed Recipes
331---------------
332
333The following recipes have been removed:
334
335- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1
336 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present.
337
338- ``python-smartpm``: Functionally replaced by ``dnf``.
339
340- ``createrepo``: Replaced by the ``createrepo-c`` recipe.
341
342- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM
343 itself is used instead.
344
345- ``gstreamer``: Removed the GStreamer Git version recipes as they
346 have been stale. ``1.10.``\ x recipes are still present.
347
348- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound``
349 depended on both. Essentially, no way existed to install only one of
350 these.
351
352- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis
353 decoding is not needed by current hardware. Thus, GStreamer's ivorbis
354 plugin has been disabled by default eliminating the need for the
355 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`.
356
357- ``gummiboot``: Replaced by ``systemd-boot``.
358
359.. _migration-2.3-wic-changes:
360
361Wic Changes
362-----------
363
364The following changes have been made to Wic:
365
366.. note::
367
368 For more information on Wic, see the
369 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
370 section in the Yocto Project Development Tasks Manual.
371
372- *Default Output Directory Changed:* Wic's default output directory is
373 now the current directory by default instead of the unusual
374 ``/var/tmp/wic``.
375
376 The "-o" and "--outdir" options remain unchanged and are used to
377 specify your preferred output directory if you do not want to use the
378 default directory.
379
380- *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as
381 it duplicates functionality of the rawcopy plugin.
382
383.. _migration-2.3-qa-changes:
384
385QA Changes
386----------
387
388The following QA checks have changed:
389
390- ``unsafe-references-in-binaries``: The
391 ``unsafe-references-in-binaries`` QA check, which was disabled by
392 default, has now been removed. This check was intended to detect
393 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have
394 the case where the user has ``/usr`` on a separate filesystem to
395 ``/``.
396
397 The removed QA check was buggy. Additionally, ``/usr`` residing on a
398 separate partition from ``/`` is now a rare configuration.
399 Consequently, ``unsafe-references-in-binaries`` was removed.
400
401- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by
402 default instead of a warning. Because it is an error instead of a
403 warning, you need to address missing runtime dependencies.
404
405 For additional information, see the
406 :ref:`insane <ref-classes-insane>` class and the
407 ":ref:`ref-manual/qa-checks:errors and warnings`" section.
408
409.. _migration-2.3-miscellaneous-changes:
410
411Miscellaneous Changes
412---------------------
413
414The following miscellaneous changes have occurred:
415
416- In this release, a number of recipes have been changed to ignore the
417 ``largefile`` :term:`DISTRO_FEATURES` item,
418 enabling large file support unconditionally. This feature has always
419 been enabled by default. Disabling the feature has not been widely
420 tested.
421
422 .. note::
423
424 Future releases of the Yocto Project will remove entirely the
425 ability to disable the
426 largefile
427 feature, which would make it unconditionally enabled everywhere.
428
429- If the :term:`DISTRO_VERSION` value contains
430 the value of the :term:`DATE` variable, which is the
431 default between Poky releases, the ``DATE`` value is explicitly
432 excluded from ``/etc/issue`` and ``/etc/issue.net``, which is
433 displayed at the login prompt, in order to avoid conflicts with
434 Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the
435 ``base-files`` recipe is restored from shared state (sstate) rather
436 than rebuilt.
437
438 If you need the build date recorded in ``/etc/issue*`` or anywhere
439 else in your image, a better method is to define a post-processing
440 function to do it and have the function called from
441 :term:`ROOTFS_POSTPROCESS_COMMAND`.
442 Doing so ensures the value is always up-to-date with the created
443 image.
444
445- Dropbear's ``init`` script now disables DSA host keys by default.
446 This change is in line with the systemd service file, which supports
447 RSA keys only, and with recent versions of OpenSSH, which deprecates
448 DSA host keys.
449
450- The :ref:`buildhistory <ref-classes-buildhistory>` class now
451 correctly uses tabs as separators between all columns in
452 ``installed-package-sizes.txt`` in order to aid import into other
453 tools.
454
455- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
456 ``DISTRO_FEATURES`` feature. Distributions that previously set:
457 ::
458
459 USE_LDCONFIG = "0"
460
461 should now instead use the following:
462
463 ::
464
465 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
466
467- The default value of
468 :term:`COPYLEFT_LICENSE_INCLUDE` now
469 includes all versions of AGPL licenses in addition to GPL and LGPL.
470
471 .. note::
472
473 The default list is not intended to be guaranteed as a complete
474 safe list. You should seek legal advice based on what you are
475 distributing if you are unsure.
476
477- Kernel module packages are now suffixed with the kernel version in
478 order to allow module packages from multiple kernel versions to
479 co-exist on a target system. If you wish to return to the previous
480 naming scheme that does not include the version suffix, use the
481 following:
482 ::
483
484 KERNEL_MODULE_PACKAGE_SUFFIX = ""
485
486- Removal of ``libtool`` ``*.la`` files is now enabled by default. The
487 ``*.la`` files are not actually needed on Linux and relocating them
488 is an unnecessary burden.
489
490 If you need to preserve these ``.la`` files (e.g. in a custom
491 distribution), you must change
492 :term:`INHERIT_DISTRO` such that
493 "remove-libtool" is not included in the value.
494
495- Extensible SDKs built for GCC 5+ now refuse to install on a
496 distribution where the host GCC version is 4.8 or 4.9. This change
497 resulted from the fact that the installation is known to fail due to
498 the way the ``uninative`` shared state (sstate) package is built. See
499 the :ref:`uninative <ref-classes-uninative>` class for additional
500 information.
501
502- All native and nativesdk recipes now use a separate
503 ``DISTRO_FEATURES`` value instead of sharing the value used by
504 recipes for the target, in order to avoid unnecessary rebuilds.
505
506 The ``DISTRO_FEATURES`` for ``native`` recipes is
507 :term:`DISTRO_FEATURES_NATIVE` added to
508 an intersection of ``DISTRO_FEATURES`` and
509 :term:`DISTRO_FEATURES_FILTER_NATIVE`.
510
511 For nativesdk recipes, the corresponding variables are
512 :term:`DISTRO_FEATURES_NATIVESDK`
513 and
514 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`.
515
516- The ``FILESDIR`` variable, which was previously deprecated and rarely
517 used, has now been removed. You should change any recipes that set
518 ``FILESDIR`` to set :term:`FILESPATH` instead.
519
520- The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no
521 longer needed with recipe-specific sysroots.
522
523
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
deleted file mode 100644
index 260b3204b6..0000000000
--- a/documentation/ref-manual/migration-2.4.rst
+++ /dev/null
@@ -1,327 +0,0 @@
1Moving to the Yocto Project 2.4 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.4 Release from the prior release.
6
7.. _migration-2.4-memory-resident-mode:
8
9Memory Resident Mode
10--------------------
11
12A persistent mode is now available in BitBake's default operation,
13replacing its previous "memory resident mode" (i.e.
14``oe-init-build-env-memres``). Now you only need to set
15:term:`BB_SERVER_TIMEOUT` to a timeout (in
16seconds) and BitBake's server stays resident for that amount of time
17between invocations. The ``oe-init-build-env-memres`` script has been
18removed since a separate environment setup script is no longer needed.
19
20.. _migration-2.4-packaging-changes:
21
22Packaging Changes
23-----------------
24
25This section provides information about packaging changes that have
26occurred:
27
28- ``python3`` Changes:
29
30 - The main "python3" package now brings in all of the standard
31 Python 3 distribution rather than a subset. This behavior matches
32 what is expected based on traditional Linux distributions. If you
33 wish to install a subset of Python 3, specify ``python-core`` plus
34 one or more of the individual packages that are still produced.
35
36 - ``python3``: The ``bz2.py``, ``lzma.py``, and
37 ``_compression.py`` scripts have been moved from the
38 ``python3-misc`` package to the ``python3-compression`` package.
39
40- ``binutils``: The ``libbfd`` library is now packaged in a separate
41 "libbfd" package. This packaging saves space when certain tools (e.g.
42 ``perf``) are installed. In such cases, the tools only need
43 ``libbfd`` rather than all the packages in ``binutils``.
44
45- ``util-linux`` Changes:
46
47 - The ``su`` program is now packaged in a separate "util-linux-su"
48 package, which is only built when "pam" is listed in the
49 :term:`DISTRO_FEATURES` variable.
50 ``util-linux`` should not be installed unless it is needed because
51 ``su`` is normally provided through the shadow file format. The
52 main ``util-linux`` package has runtime dependencies (i.e.
53 :term:`RDEPENDS`) on the ``util-linux-su`` package
54 when "pam" is in ``DISTRO_FEATURES``.
55
56 - The ``switch_root`` program is now packaged in a separate
57 "util-linux-switch-root" package for small initramfs images that
58 do not need the whole ``util-linux`` package or the busybox
59 binary, which are both much larger than ``switch_root``. The main
60 ``util-linux`` package has a recommended runtime dependency (i.e.
61 :term:`RRECOMMENDS`) on the
62 ``util-linux-switch-root`` package.
63
64 - The ``ionice`` program is now packaged in a separate
65 "util-linux-ionice" package. The main ``util-linux`` package has a
66 recommended runtime dependency (i.e. ``RRECOMMENDS``) on the
67 ``util-linux-ionice`` package.
68
69- ``initscripts``: The ``sushell`` program is now packaged in a
70 separate "initscripts-sushell" package. This packaging change allows
71 systems to pull ``sushell`` in when ``selinux`` is enabled. The
72 change also eliminates needing to pull in the entire ``initscripts``
73 package. The main ``initscripts`` package has a runtime dependency
74 (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in
75 ``DISTRO_FEATURES``.
76
77- ``glib-2.0``: The ``glib-2.0`` package now has a recommended
78 runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info``
79 package, since large portions of GIO are not useful without the MIME
80 database. You can remove the dependency by using the
81 :term:`BAD_RECOMMENDATIONS` variable if
82 ``shared-mime-info`` is too large and is not required.
83
84- *Go Standard Runtime:* The Go standard runtime has been split out
85 from the main ``go`` recipe into a separate ``go-runtime`` recipe.
86
87.. _migration-2.4-removed-recipes:
88
89Removed Recipes
90---------------
91
92The following recipes have been removed:
93
94- ``acpitests``: This recipe is not maintained.
95
96- ``autogen-native``: No longer required by Grub, oe-core, or
97 meta-oe.
98
99- ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It
100 has moved to meta-oe.
101
102- ``byacc``: This recipe was only needed by rpm 5.x and has moved to
103 meta-oe.
104
105- ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 /
106 7.2.
107
108- ``gnome-common``: Deprecated upstream and no longer needed.
109
110- ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this
111 recipe has been removed.
112
113- ``guile``: This recipe was only needed by ``autogen-native`` and
114 ``remake``. The recipe is no longer needed by either of these
115 programs.
116
117- ``libclass-isa-perl``: This recipe was previously needed for LSB 4,
118 no longer needed.
119
120- ``libdumpvalue-perl``: This recipe was previously needed for LSB 4,
121 no longer needed.
122
123- ``libenv-perl``: This recipe was previously needed for LSB 4, no
124 longer needed.
125
126- ``libfile-checktree-perl``: This recipe was previously needed for
127 LSB 4, no longer needed.
128
129- ``libi18n-collate-perl``: This recipe was previously needed for LSB
130 4, no longer needed.
131
132- ``libiconv``: This recipe was only needed for ``uclibc``, which was
133 removed in the previous release. ``glibc`` and ``musl`` have their
134 own implementations. ``meta-mingw`` still needs ``libiconv``, so it
135 has been moved to ``meta-mingw``.
136
137- ``libpng12``: This recipe was previously needed for LSB. The
138 current ``libpng`` is 1.6.x.
139
140- ``libpod-plainer-perl``: This recipe was previously needed for LSB
141 4, no longer needed.
142
143- ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4,
144 4.9, 4.10 and 4.12.
145
146- ``mailx``: This recipe was previously only needed for LSB
147 compatibility, and upstream is defunct.
148
149- ``mesa (git version only)``: The git version recipe was stale with
150 respect to the release version.
151
152- ``ofono (git version only)``: The git version recipe was stale with
153 respect to the release version.
154
155- ``portmap``: This recipe is obsolete and is superseded by
156 ``rpcbind``.
157
158- ``python3-pygpgme``: This recipe is old and unmaintained. It was
159 previously required by ``dnf``, which has switched to official
160 ``gpgme`` Python bindings.
161
162- ``python-async``: This recipe has been removed in favor of the
163 Python 3 version.
164
165- ``python-gitdb``: This recipe has been removed in favor of the
166 Python 3 version.
167
168- ``python-git``: This recipe was removed in favor of the Python 3
169 version.
170
171- ``python-mako``: This recipe was removed in favor of the Python 3
172 version.
173
174- ``python-pexpect``: This recipe was removed in favor of the Python
175 3 version.
176
177- ``python-ptyprocess``: This recipe was removed in favor of Python
178 the 3 version.
179
180- ``python-pycurl``: Nothing is using this recipe in
181 OpenEmbedded-Core (i.e. ``meta-oe``).
182
183- ``python-six``: This recipe was removed in favor of the Python 3
184 version.
185
186- ``python-smmap``: This recipe was removed in favor of the Python 3
187 version.
188
189- ``remake``: Using ``remake`` as the provider of ``virtual/make`` is
190 broken. Consequently, this recipe is not needed in OpenEmbedded-Core.
191
192.. _migration-2.4-kernel-device-tree-move:
193
194Kernel Device Tree Move
195-----------------------
196
197Kernel Device Tree support is now easier to enable in a kernel recipe.
198The Device Tree code has moved to a
199:ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class.
200Functionality is automatically enabled for any recipe that inherits the
201:ref:`kernel <ref-classes-kernel>` class and sets the
202:term:`KERNEL_DEVICETREE` variable. The
203previous mechanism for doing this,
204``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid
205breakage, but triggers a deprecation warning. Future releases of the
206Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``.
207It is advisable to remove any ``require`` statements that request
208``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel
209recipes you might have. This will avoid breakage in post 2.4 releases.
210
211.. _migration-2.4-package-qa-changes:
212
213Package QA Changes
214------------------
215
216The following package QA changes took place:
217
218- The "unsafe-references-in-scripts" QA check has been removed.
219
220- If you refer to ``${COREBASE}/LICENSE`` within
221 :term:`LIC_FILES_CHKSUM` you receive a
222 warning because this file is a description of the license for
223 OE-Core. Use ``${COMMON_LICENSE_DIR}/MIT`` if your recipe is
224 MIT-licensed and you cannot use the preferred method of referring to
225 a file within the source tree.
226
227.. _migration-2.4-readme-changes:
228
229``README`` File Changes
230-----------------------
231
232The following are changes to ``README`` files:
233
234- The main Poky ``README`` file has been moved to the ``meta-poky``
235 layer and has been renamed ``README.poky``. A symlink has been
236 created so that references to the old location work.
237
238- The ``README.hardware`` file has been moved to ``meta-yocto-bsp``. A
239 symlink has been created so that references to the old location work.
240
241- A ``README.qemu`` file has been created with coverage of the
242 ``qemu*`` machines.
243
244.. _migration-2.4-miscellaneous-changes:
245
246Miscellaneous Changes
247---------------------
248
249The following are additional changes:
250
251- The ``ROOTFS_PKGMANAGE_BOOTSTRAP`` variable and any references to it
252 have been removed. You should remove this variable from any custom
253 recipes.
254
255- The ``meta-yocto`` directory has been removed.
256
257 .. note::
258
259 In the Yocto Project 2.1 release
260 meta-yocto
261 was renamed to
262 meta-poky
263 and the
264 meta-yocto
265 subdirectory remained to avoid breaking existing configurations.
266
267- The ``maintainers.inc`` file, which tracks maintainers by listing a
268 primary person responsible for each recipe in OE-Core, has been moved
269 from ``meta-poky`` to OE-Core (i.e. from
270 ``meta-poky/conf/distro/include`` to ``meta/conf/distro/include``).
271
272- The :ref:`buildhistory <ref-classes-buildhistory>` class now makes
273 a single commit per build rather than one commit per subdirectory in
274 the repository. This behavior assumes the commits are enabled with
275 :term:`BUILDHISTORY_COMMIT` = "1", which
276 is typical. Previously, the ``buildhistory`` class made one commit
277 per subdirectory in the repository in order to make it easier to see
278 the changes for a particular subdirectory. To view a particular
279 change, specify that subdirectory as the last parameter on the
280 ``git show`` or ``git diff`` commands.
281
282- The ``x86-base.inc`` file, which is included by all x86-based machine
283 configurations, now sets :term:`IMAGE_FSTYPES`
284 using ``?=`` to "live" rather than appending with ``+=``. This change
285 makes the default easier to override.
286
287- BitBake fires multiple "BuildStarted" events when multiconfig is
288 enabled (one per configuration). For more information, see the
289 ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User
290 Manual.
291
292- By default, the ``security_flags.inc`` file sets a
293 :term:`GCCPIE` variable with an option to enable
294 Position Independent Executables (PIE) within ``gcc``. Enabling PIE
295 in the GNU C Compiler (GCC), makes Return Oriented Programming (ROP)
296 attacks much more difficult to execute.
297
298- OE-Core now provides a ``bitbake-layers`` plugin that implements a
299 "create-layer" subcommand. The implementation of this subcommand has
300 resulted in the ``yocto-layer`` script being deprecated and will
301 likely be removed in the next Yocto Project release.
302
303- The ``vmdk``, ``vdi``, and ``qcow2`` image file types are now used in
304 conjunction with the "wic" image type through ``CONVERSION_CMD``.
305 Consequently, the equivalent image types are now ``wic.vmdk``,
306 ``wic.vdi``, and ``wic.qcow2``, respectively.
307
308- ``do_image_<type>[depends]`` has replaced ``IMAGE_DEPENDS_<type>``.
309 If you have your own classes that implement custom image types, then
310 you need to update them.
311
312- OpenSSL 1.1 has been introduced. However, the default is still 1.0.x
313 through the :term:`PREFERRED_VERSION`
314 variable. This preference is set is due to the remaining
315 compatibility issues with other software. The
316 :term:`PROVIDES` variable in the openssl 1.0 recipe
317 now includes "openssl10" as a marker that can be used in
318 :term:`DEPENDS` within recipes that build software
319 that still depend on OpenSSL 1.0.
320
321- To ensure consistent behavior, BitBake's "-r" and "-R" options (i.e.
322 prefile and postfile), which are used to read or post-read additional
323 configuration files from the command line, now only affect the
324 current BitBake command. Before these BitBake changes, these options
325 would "stick" for future executions.
326
327
diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst
deleted file mode 100644
index 9f45ffce76..0000000000
--- a/documentation/ref-manual/migration-2.5.rst
+++ /dev/null
@@ -1,310 +0,0 @@
1Moving to the Yocto Project 2.5 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.5 Release from the prior release.
6
7.. _migration-2.5-packaging-changes:
8
9Packaging Changes
10-----------------
11
12This section provides information about packaging changes that have
13occurred:
14
15- ``bind-libs``: The libraries packaged by the bind recipe are in a
16 separate ``bind-libs`` package.
17
18- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a
19 separate ``libfm-gtk`` package.
20
21- ``flex-libfl``: The flex recipe splits out libfl into a separate
22 ``flex-libfl`` package to avoid too many dependencies being pulled in
23 where only the library is needed.
24
25- ``grub-efi``: The ``grub-efi`` configuration is split into a
26 separate ``grub-bootconf`` recipe. However, the dependency
27 relationship from ``grub-efi`` is through a virtual/grub-bootconf
28 provider making it possible to have your own recipe provide the
29 dependency. Alternatively, you can use a BitBake append file to bring
30 the configuration back into the ``grub-efi`` recipe.
31
32- *armv7a Legacy Package Feed Support:* Legacy support is removed for
33 transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package
34 feeds, which was previously enabled by setting
35 ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active
36 package feeds should by now be updated to the new naming.
37
38.. _migration-2.5-removed-recipes:
39
40Removed Recipes
41---------------
42
43The following recipes have been removed:
44
45- ``gcc``: The version 6.4 recipes are replaced by 7.x.
46
47- ``gst-player``: Renamed to ``gst-examples`` as per upstream.
48
49- ``hostap-utils``: This software package is obsolete.
50
51- ``latencytop``: This recipe is no longer maintained upstream. The
52 last release was in 2009.
53
54- ``libpfm4``: The only file that requires this recipe is
55 ``oprofile``, which has been removed.
56
57- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been
58 removed. Versions 4.12, 4.14, and 4.15 remain.
59
60- ``man``: This recipe has been replaced by modern ``man-db``
61
62- ``mkelfimage``: This tool has been removed in the upstream coreboot
63 project, and is no longer needed with the removal of the ELF image
64 type.
65
66- ``nativesdk-postinst-intercept``: This recipe is not maintained.
67
68- ``neon``: This software package is no longer maintained upstream
69 and is no longer needed by anything in OpenEmbedded-Core.
70
71- ``oprofile``: The functionality of this recipe is replaced by
72 ``perf`` and keeping compatibility on an ongoing basis with ``musl``
73 is difficult.
74
75- ``pax``: This software package is obsolete.
76
77- ``stat``: This software package is not maintained upstream.
78 ``coreutils`` provides a modern stat binary.
79
80- ``zisofs-tools-native``: This recipe is no longer needed because
81 the compressed ISO image feature has been removed.
82
83.. _migration-2.5-scripts-and-tools-changes:
84
85Scripts and Tools Changes
86-------------------------
87
88The following are changes to scripts and tools:
89
90- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The
91 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts
92 previously shipped with poky but not in OpenEmbedded-Core have been
93 removed. These scripts are not maintained and are outdated. In many
94 cases, they are also limited in scope. The
95 ``bitbake-layers create-layer`` command is a direct replacement for
96 ``yocto-layer``. See the documentation to create a BSP or kernel
97 recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section.
98
99- ``devtool finish``: ``devtool finish`` now exits with an error if
100 there are uncommitted changes or a rebase/am in progress in the
101 recipe's source repository. If this error occurs, there might be
102 uncommitted changes that will not be included in updates to the
103 patches applied by the recipe. A -f/--force option is provided for
104 situations that the uncommitted changes are inconsequential and you
105 want to proceed regardless.
106
107- ``scripts/oe-setup-rpmrepo`` script: The functionality of
108 ``scripts/oe-setup-rpmrepo`` is replaced by
109 ``bitbake package-index``.
110
111- ``scripts/test-dependencies.sh`` script: The script is largely made
112 obsolete by the recipe-specific sysroots functionality introduced in
113 the previous release.
114
115.. _migration-2.5-bitbake-changes:
116
117BitBake Changes
118---------------
119
120The following are BitBake changes:
121
122- The ``--runall`` option has changed. There are two different
123 behaviors people might want:
124
125 - *Behavior A:* For a given target (or set of targets) look through
126 the task graph and run task X only if it is present and will be
127 built.
128
129 - *Behavior B:* For a given target (or set of targets) look through
130 the task graph and run task X if any recipe in the taskgraph has
131 such a target, even if it is not in the original task graph.
132
133 The ``--runall`` option now performs "Behavior B". Previously
134 ``--runall`` behaved like "Behavior A". A ``--runonly`` option has
135 been added to retain the ability to perform "Behavior A".
136
137- Several explicit "run this task for all recipes in the dependency
138 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
139 and the ``*all`` tasks provided by the ``distrodata`` and
140 ``archiver`` classes). There is a BitBake option to complete this for
141 any arbitrary task. For example:
142 ::
143
144 bitbake <target> -c fetchall
145
146 should now be replaced with:
147 ::
148
149 bitbake <target> --runall=fetch
150
151.. _migration-2.5-python-and-python3-changes:
152
153Python and Python 3 Changes
154---------------------------
155
156The following are auto-packaging changes to Python and Python 3:
157
158The script-managed ``python-*-manifest.inc`` files that were previously
159used to generate Python and Python 3 packages have been replaced with a
160JSON-based file that is easier to read and maintain. A new task is
161available for maintainers of the Python recipes to update the JSON file
162when upgrading to new Python versions. You can now edit the file
163directly instead of having to edit a script and run it to update the
164file.
165
166One particular change to note is that the Python recipes no longer have
167build-time provides for their packages. This assumes ``python-foo`` is
168one of the packages provided by the Python recipe. You can no longer run
169``bitbake python-foo`` or have a
170:term:`DEPENDS` on ``python-foo``,
171but doing either of the following causes the package to work as
172expected: ::
173
174 IMAGE_INSTALL_append = " python-foo"
175
176or ::
177
178 RDEPENDS_${PN} = "python-foo"
179
180The earlier build-time provides behavior was a quirk of the
181way the Python manifest file was created. For more information on this
182change please see :yocto_git:`this commit
183</poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`.
184
185.. _migration-2.5-miscellaneous-changes:
186
187Miscellaneous Changes
188---------------------
189
190The following are additional changes:
191
192- The ``kernel`` class supports building packages for multiple kernels.
193 If your kernel recipe or ``.bbappend`` file mentions packaging at
194 all, you should replace references to the kernel in package names
195 with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable
196 automatic installation of the kernel image using
197 ``RDEPENDS_kernel-base = ""`` you can avoid warnings using
198 ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead.
199
200- The ``buildhistory`` class commits changes to the repository by
201 default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``.
202 If you want to disable commits you need to set
203 ``BUILDHISTORY_COMMIT = "0"`` in your configuration.
204
205- The ``beaglebone`` reference machine has been renamed to
206 ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference
207 implementation using only mainline components available in
208 OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments
209 maintains a full-featured BSP in the ``meta-ti`` layer. This rename
210 avoids the previous name clash that existed between the two BSPs.
211
212- The ``update-alternatives`` class no longer works with SysV ``init``
213 scripts because this usage has been problematic. Also, the
214 ``sysklogd`` recipe no longer uses ``update-alternatives`` because it
215 is incompatible with other implementations.
216
217- By default, the :ref:`cmake <ref-classes-cmake>` class uses
218 ``ninja`` instead of ``make`` for building. This improves build
219 performance. If a recipe is broken with ``ninja``, then the recipe
220 can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to
221 ``make``.
222
223- The previously deprecated ``base_*`` functions have been removed in
224 favor of their replacements in ``meta/lib/oe`` and
225 ``bitbake/lib/bb``. These are typically used from recipes and
226 classes. Any references to the old functions must be updated. The
227 following table shows the removed functions and their replacements:
228
229 +------------------------------+----------------------------------------------------------+
230 | *Removed* | *Replacement* |
231 +==============================+==========================================================+
232 | base_path_join() | oe.path.join() |
233 +------------------------------+----------------------------------------------------------+
234 | base_path_relative() | oe.path.relative() |
235 +------------------------------+----------------------------------------------------------+
236 | base_path_out() | oe.path.format_display() |
237 +------------------------------+----------------------------------------------------------+
238 | base_read_file() | oe.utils.read_file() |
239 +------------------------------+----------------------------------------------------------+
240 | base_ifelse() | oe.utils.ifelse() |
241 +------------------------------+----------------------------------------------------------+
242 | base_conditional() | oe.utils.conditional() |
243 +------------------------------+----------------------------------------------------------+
244 | base_less_or_equal() | oe.utils.less_or_equal() |
245 +------------------------------+----------------------------------------------------------+
246 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
247 +------------------------------+----------------------------------------------------------+
248 | base_contains() | bb.utils.contains() |
249 +------------------------------+----------------------------------------------------------+
250 | base_both_contain() | oe.utils.both_contain() |
251 +------------------------------+----------------------------------------------------------+
252 | base_prune_suffix() | oe.utils.prune_suffix() |
253 +------------------------------+----------------------------------------------------------+
254 | oe_filter() | oe.utils.str_filter() |
255 +------------------------------+----------------------------------------------------------+
256 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
257 +------------------------------+----------------------------------------------------------+
258
259- Using ``exit 1`` to explicitly defer a postinstall script until first
260 boot is now deprecated since it is not an obvious mechanism and can
261 mask actual errors. If you want to explicitly defer a postinstall to
262 first boot on the target rather than at ``rootfs`` creation time, use
263 ``pkg_postinst_ontarget()`` or call
264 ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
265 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
266 will trigger a warning during ``do_rootfs``.
267
268 For more information, see the
269 ":ref:`dev-manual/common-tasks:post-installation scripts`"
270 section in the Yocto Project Development Tasks Manual.
271
272- The ``elf`` image type has been removed. This image type was removed
273 because the ``mkelfimage`` tool that was required to create it is no
274 longer provided by coreboot upstream and required updating every time
275 ``binutils`` updated.
276
277- Support for .iso image compression (previously enabled through
278 ``COMPRESSISO = "1"``) has been removed. The userspace tools
279 (``zisofs-tools``) are unmaintained and ``squashfs`` provides better
280 performance and compression. In order to build a live image with
281 squashfs+lz4 compression enabled you should now set
282 ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
283 ``IMAGE_FSTYPES``.
284
285- Recipes with an unconditional dependency on ``libpam`` are only
286 buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
287 truly optional then it is recommended that the dependency be
288 conditional upon ``pam`` being in ``DISTRO_FEATURES``.
289
290- For EFI-based machines, the bootloader (``grub-efi`` by default) is
291 installed into the image at /boot. Wic can be used to split the
292 bootloader into separate boot and rootfs partitions if necessary.
293
294- Patches whose context does not match exactly (i.e. where patch
295 reports "fuzz" when applying) will generate a warning. For an example
296 of this see :yocto_git:`this commit
297 </poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`.
298
299- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match
300 the version(s) of OpenEmbedded-Core they are compatible with. This is
301 specified as codenames using spaces to separate multiple values (e.g.
302 "rocko sumo"). If a layer does not set
303 ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer
304 sets a value that does not include the current version ("sumo" for
305 the 2.5 release), then an error will be produced.
306
307- The ``TZ`` environment variable is set to "UTC" within the build
308 environment in order to fix reproducibility problems in some recipes.
309
310
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
deleted file mode 100644
index 5d524f3817..0000000000
--- a/documentation/ref-manual/migration-2.6.rst
+++ /dev/null
@@ -1,457 +0,0 @@
1Moving to the Yocto Project 2.6 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.6 Release from the prior release.
6
7.. _migration-2.6-gcc-changes:
8
9GCC 8.2 is Now Used by Default
10------------------------------
11
12The GNU Compiler Collection version 8.2 is now used by default for
13compilation. For more information on what has changed in the GCC 8.x
14release, see https://gcc.gnu.org/gcc-8/changes.html.
15
16If you still need to compile with version 7.x, GCC 7.3 is also provided.
17You can select this version by setting the and can be selected by
18setting the :term:`GCCVERSION` variable to "7.%" in
19your configuration.
20
21.. _migration-2.6-removed-recipes:
22
23Removed Recipes
24---------------
25
26The following recipes have been removed:
27
28- *beecrypt*: No longer needed since moving to RPM 4.
29- *bigreqsproto*: Replaced by ``xorgproto``.
30- *calibrateproto*: Removed in favor of ``xinput``.
31- *compositeproto*: Replaced by ``xorgproto``.
32- *damageproto*: Replaced by ``xorgproto``.
33- *dmxproto*: Replaced by ``xorgproto``.
34- *dri2proto*: Replaced by ``xorgproto``.
35- *dri3proto*: Replaced by ``xorgproto``.
36- *eee-acpi-scripts*: Became obsolete.
37- *fixesproto*: Replaced by ``xorgproto``.
38- *fontsproto*: Replaced by ``xorgproto``.
39- *fstests*: Became obsolete.
40- *gccmakedep*: No longer used.
41- *glproto*: Replaced by ``xorgproto``.
42- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``.
43- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016.
44- *inputproto*: Replaced by ``xorgproto``.
45- *kbproto*: Replaced by ``xorgproto``.
46- *libusb-compat*: Became obsolete.
47- *libuser*: Became obsolete.
48- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated.
49- *libxcalibrate*: No longer needed with ``xinput``
50- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``.
51- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``.
52- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time.
53- *pcmciautils*: Became obsolete.
54- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression.
55- *presentproto*: Replaced by ``xorgproto``.
56- *randrproto*: Replaced by ``xorgproto``.
57- *recordproto*: Replaced by ``xorgproto``.
58- *renderproto*: Replaced by ``xorgproto``.
59- *resourceproto*: Replaced by ``xorgproto``.
60- *scrnsaverproto*: Replaced by ``xorgproto``.
61- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally.
62- *videoproto*: Replaced by ``xorgproto``.
63- *wireless-tools*: Became obsolete. Superseded by ``iw``.
64- *xcmiscproto*: Replaced by ``xorgproto``.
65- *xextproto*: Replaced by ``xorgproto``.
66- *xf86dgaproto*: Replaced by ``xorgproto``.
67- *xf86driproto*: Replaced by ``xorgproto``.
68- *xf86miscproto*: Replaced by ``xorgproto``.
69- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead.
70- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead.
71- *xf86vidmodeproto*: Replaced by ``xorgproto``.
72- *xineramaproto*: Replaced by ``xorgproto``.
73- *xproto*: Replaced by ``xorgproto``.
74- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``.
75
76.. _migration-2.6-packaging-changes:
77
78Packaging Changes
79-----------------
80
81The following packaging changes have been made:
82
83- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to
84 the main package.
85
86- *iptables*: The ``iptables`` modules have been split into
87 separate packages.
88
89- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package
90 instead of ``libasound``.
91
92- *glibc*: ``libnss-db`` is now in its own package along with a
93 ``/var/db/makedbs.sh`` script to update databases.
94
95- *python and python3*: The main package has been removed from
96 the recipe. You must install specific packages or ``python-modules``
97 / ``python3-modules`` for everything.
98
99- *systemtap*: Moved ``systemtap-exporter`` into its own package.
100
101.. _migration-2.6-xorg-protocol-dependencies:
102
103XOrg Protocol dependencies
104--------------------------
105
106The ``*proto`` upstream repositories have been combined into one
107"xorgproto" repository. Thus, the corresponding recipes have also been
108combined into a single ``xorgproto`` recipe. Any recipes that depend
109upon the older ``*proto`` recipes need to be changed to depend on the
110newer ``xorgproto`` recipe instead.
111
112For names of recipes removed because of this repository change, see the
113`Removed Recipes <#removed-recipes>`__ section.
114
115.. _migration-2.6-distutils-distutils3-fetching-dependencies:
116
117``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task
118---------------------------------------------------------------------------------------------------
119
120Previously, it was possible for Python recipes that inherited the
121:ref:`distutils <ref-classes-distutils>` and
122:ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
123during the :ref:`ref-tasks-configure` task to satisfy
124dependencies mentioned in ``setup.py`` if those dependencies were not
125provided in the sysroot (i.e. recipes providing the dependencies were
126missing from :term:`DEPENDS`).
127
128.. note::
129
130 This change affects classes beyond just the two mentioned (i.e.
131 ``distutils`` and ``distutils3``). Any recipe that inherits ``distutils*``
132 classes are affected. For example, the ``setuptools`` and ``setuptools3``
133 recipes are affected since they inherit the ``distutils*`` classes.
134
135Fetching these types of dependencies that are not provided in the
136sysroot negatively affects the ability to reproduce builds. This type of
137fetching is now explicitly disabled. Consequently, any missing
138dependencies in Python recipes that use these classes now result in an
139error during the ``do_configure`` task.
140
141.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported:
142
143``linux-yocto`` Configuration Audit Issues Now Correctly Reported
144-----------------------------------------------------------------
145
146Due to a bug, the kernel configuration audit functionality was not
147writing out any resulting warnings during the build. This issue is now
148corrected. You might notice these warnings now if you have a custom
149kernel configuration with a ``linux-yocto`` style kernel recipe.
150
151.. _migration-2.6-image-kernel-artifact-naming-changes:
152
153Image/Kernel Artifact Naming Changes
154------------------------------------
155
156The following changes have been made:
157
158- Name variables (e.g. :term:`IMAGE_NAME`) use a new
159 ``IMAGE_VERSION_SUFFIX`` variable instead of
160 :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
161 allows easier and more direct changes.
162
163 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
164 configuration file as follows:
165 ::
166
167 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
168
169- Several variables have changed names for consistency:
170 ::
171
172 Old Variable Name New Variable Name
173 ========================================================
174 KERNEL_IMAGE_BASE_NAME KERNEL_IMAGE_NAME
175 KERNEL_IMAGE_SYMLINK_NAME KERNEL_IMAGE_LINK_NAME
176 MODULE_TARBALL_BASE_NAME MODULE_TARBALL_NAME
177 MODULE_TARBALL_SYMLINK_NAME MODULE_TARBALL_LINK_NAME
178 INITRAMFS_BASE_NAME INITRAMFS_NAME
179
180- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
181 tarball name is now controlled directly with the
182 :term:`MODULE_TARBALL_NAME` variable.
183
184- The :term:`KERNEL_DTB_NAME` and
185 :term:`KERNEL_DTB_LINK_NAME` variables
186 have been introduced to control kernel Device Tree Binary (DTB)
187 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
188
189- The :term:`KERNEL_FIT_NAME` and
190 :term:`KERNEL_FIT_LINK_NAME` variables
191 have been introduced to specify the name of flattened image tree
192 (FIT) kernel images similar to other deployed artifacts.
193
194- The :term:`MODULE_TARBALL_NAME` and
195 :term:`MODULE_TARBALL_LINK_NAME`
196 variable values no longer include the "module-" prefix or ".tgz"
197 suffix. These parts are now hardcoded so that the values are
198 consistent with other artifact naming variables.
199
200- Added the :term:`INITRAMFS_LINK_NAME`
201 variable so that the symlink can be controlled similarly to other
202 artifact types.
203
204- :term:`INITRAMFS_NAME` now uses
205 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
206 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
207 with other variables.
208
209.. _migration-2.6-serial-console-deprecated:
210
211``SERIAL_CONSOLE`` Deprecated
212-----------------------------
213
214The :term:`SERIAL_CONSOLE` variable has been
215functionally replaced by the
216:term:`SERIAL_CONSOLES` variable for some time.
217With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
218officially deprecated.
219
220``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
221However, for the sake of future compatibility, it is recommended that
222you replace all instances of ``SERIAL_CONSOLE`` with
223``SERIAL_CONSOLES``.
224
225.. note::
226
227 The only difference in usage is that ``SERIAL_CONSOLES``
228 expects entries to be separated using semicolons as compared to
229 ``SERIAL_CONSOLE``, which expects spaces.
230
231.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
232
233Configure Script Reports Unknown Options as Errors
234--------------------------------------------------
235
236If the configure script reports an unknown option, this now triggers a
237QA error instead of a warning. Any recipes that previously got away with
238specifying such unknown options now need to be fixed.
239
240.. _migration-2.6-override-changes:
241
242Override Changes
243----------------
244
245The following changes have occurred:
246
247- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
248 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
249 overrides have been deprecated since 2012 in favor of
250 ``class-native`` and ``class-nativesdk``, respectively. Both
251 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
252
253 .. note::
254
255 The ``virtclass-multilib-`` overrides for multilib are still valid.
256
257- The ``forcevariable`` Override Now Has a Higher Priority Than
258 ``libc`` Overrides: The ``forcevariable`` override is documented to
259 be the highest priority override. However, due to a long-standing
260 quirk of how :term:`OVERRIDES` is set, the ``libc``
261 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
262 erroneously had a higher priority. This issue is now corrected.
263
264 It is likely this change will not cause any problems. However, it is
265 possible with some unusual configurations that you might see a change
266 in behavior if you were relying on the previous behavior. Be sure to
267 check how you use ``forcevariable`` and ``libc-*`` overrides in your
268 custom layers and configuration files to ensure they make sense.
269
270- The ``build-${BUILD_OS}`` Override Has Been Removed: The
271 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
272 has been removed because building on a host operating system other
273 than a recent version of Linux is neither supported nor recommended.
274 Dropping the override avoids giving the impression that other host
275 operating systems might be supported.
276
277- The "_remove" operator now preserves whitespace. Consequently, when
278 specifying list items to remove, be aware that leading and trailing
279 whitespace resulting from the removal is retained.
280
281 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`"
282 section in the BitBake User Manual for a detailed example.
283
284.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
285
286``systemd`` Configuration is Now Split Into ``systemd-conf``
287------------------------------------------------------------
288
289The configuration for the ``systemd`` recipe has been moved into a
290``system-conf`` recipe. Moving this configuration to a separate recipe
291avoids the ``systemd`` recipe from becoming machine-specific for cases
292where machine-specific configurations need to be applied (e.g. for
293``qemu*`` machines).
294
295Currently, the new recipe packages the following files:
296::
297
298 ${sysconfdir}/machine-id
299 ${sysconfdir}/systemd/coredump.conf
300 ${sysconfdir}/systemd/journald.conf
301 ${sysconfdir}/systemd/logind.conf
302 ${sysconfdir}/systemd/system.conf
303 ${sysconfdir}/systemd/user.conf
304
305If you previously used bbappend files to append the ``systemd`` recipe to
306change any of the listed files, you must do so for the ``systemd-conf``
307recipe instead.
308
309.. _migration-2.6-automatic-testing-changes:
310
311Automatic Testing Changes
312-------------------------
313
314This section provides information about automatic testing changes:
315
316- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
317 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
318 successfully built images. The ``TEST_IMAGE`` variable no longer
319 exists and has been replaced by the
320 :term:`TESTIMAGE_AUTO` variable.
321
322- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
323 practices now dictate that you use the
324 :term:`IMAGE_CLASSES` variable rather than the
325 :term:`INHERIT` variable when you inherit the
326 :ref:`testimage <ref-classes-testimage*>` and
327 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
328 testing.
329
330.. _migration-2.6-openssl-changes:
331
332OpenSSL Changes
333---------------
334
335`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
3361.1. By default, this upgrade could cause problems for recipes that have
337both versions in their dependency chains. The problem is that both
338versions cannot be installed together at build time.
339
340.. note::
341
342 It is possible to have both versions of the library at runtime.
343
344.. _migration-2.6-bitbake-changes:
345
346BitBake Changes
347---------------
348
349The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
350the :term:`Build Directory` instead of the current
351directory.
352
353.. _migration-2.6-security-changes:
354
355Security Changes
356----------------
357
358The Poky distribution now uses security compiler flags by default.
359Inclusion of these flags could cause new failures due to stricter
360checking for various potential security issues in code.
361
362.. _migration-2.6-post-installation-changes:
363
364Post Installation Changes
365-------------------------
366
367You must explicitly mark post installs to defer to the target. If you
368want to explicitly defer a postinstall to first boot on the target
369rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
370call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
371Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
372an error during the :ref:`ref-tasks-rootfs` task.
373
374For more information on post-installation behavior, see the
375":ref:`dev-manual/common-tasks:post-installation scripts`"
376section in the Yocto Project Development Tasks Manual.
377
378.. _migration-2.6-python-3-profile-guided-optimizations:
379
380Python 3 Profile-Guided Optimization
381------------------------------------
382
383The ``python3`` recipe now enables profile-guided optimization. Using
384this optimization requires a little extra build time in exchange for
385improved performance on the target at runtime. Additionally, the
386optimization is only enabled if the current
387:term:`MACHINE` has support for user-mode emulation in
388QEMU (i.e. "qemu-usermode" is in
389:term:`MACHINE_FEATURES`, which it is by
390default).
391
392If you wish to disable Python profile-guided optimization regardless of
393the value of ``MACHINE_FEATURES``, then ensure that
394:term:`PACKAGECONFIG` for the ``python3`` recipe
395does not contain "pgo". You could accomplish the latter using the
396following at the configuration level:
397::
398
399 PACKAGECONFIG_remove_pn-python3 = "pgo"
400
401Alternatively, you can set ``PACKAGECONFIG`` using an append file
402for the ``python3`` recipe.
403
404.. _migration-2.6-miscellaneous-changes:
405
406Miscellaneous Changes
407---------------------
408
409The following miscellaneous changes occurred:
410
411- Default to using the Thumb-2 instruction set for armv7a and above. If
412 you have any custom recipes that build software that needs to be
413 built with the ARM instruction set, change the recipe to set the
414 instruction set as follows:
415 ::
416
417 ARM_INSTRUCTION_SET = "arm"
418
419- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
420 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
421 remains unchanged.
422
423- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
424 control building ``*.iso`` and ``*.hddimg`` image types directly by
425 using the :term:`IMAGE_FSTYPES` variable.
426
427- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
428 Wic.
429
430- ``kernel-modules`` has been removed from
431 :term:`RRECOMMENDS` for ``qemumips`` and
432 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
433 file.
434
435 .. note::
436
437 ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
438 the ``RRECOMMENDS`` variable setting.
439
440- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
441 are setting this variable in your configuration, set or append it to
442 the ``WHITELIST_GPL-3.0`` variable instead.
443
444- ``${ASNEEDED}`` is now included in the
445 :term:`TARGET_LDFLAGS` variable directly. The
446 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
447 have been moved to corresponding recipes.
448
449- Support for DSA host keys has been dropped from the OpenSSH recipes.
450 If you are still using DSA keys, you must switch over to a more
451 secure algorithm as recommended by OpenSSH upstream.
452
453- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
454 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
455 ``dhcpd.conf``, which is now reserved for IPv4.
456
457
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
deleted file mode 100644
index 5af5947fff..0000000000
--- a/documentation/ref-manual/migration-2.7.rst
+++ /dev/null
@@ -1,180 +0,0 @@
1Moving to the Yocto Project 2.7 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.7 Release from the prior release.
6
7.. _migration-2.7-bitbake-changes:
8
9BitBake Changes
10---------------
11
12The following changes have been made to BitBake:
13
14- BitBake now checks anonymous Python functions and pure Python
15 functions (e.g. ``def funcname:``) in the metadata for tab
16 indentation. If found, BitBake produces a warning.
17
18- Bitbake now checks
19 :term:`BBFILE_COLLECTIONS` for duplicate
20 entries and triggers an error if any are found.
21
22.. _migration-2.7-eclipse-support-dropped:
23
24Eclipse Support Removed
25-----------------------
26
27Support for the Eclipse IDE has been removed. Support continues for
28those releases prior to 2.7 that did include support. The 2.7 release
29does not include the Eclipse Yocto plugin.
30
31.. _migration-2.7-qemu-native-splits-system-and-user-mode-parts:
32
33``qemu-native`` Splits the System and User-Mode Parts
34-----------------------------------------------------
35
36The system and user-mode parts of ``qemu-native`` are now split.
37``qemu-native`` provides the user-mode components and
38``qemu-system-native`` provides the system components. If you have
39recipes that depend on QEMU's system emulation functionality at build
40time, they should now depend upon ``qemu-system-native`` instead of
41``qemu-native``.
42
43.. _migration-2.7-upstream-tracking.inc-removed:
44
45The ``upstream-tracking.inc`` File Has Been Removed
46---------------------------------------------------
47
48The previously deprecated ``upstream-tracking.inc`` file is now removed.
49Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding
50recipes instead.
51
52Remove any references you have to the ``upstream-tracking.inc`` file in
53your configuration.
54
55.. _migration-2.7-distro-features-libc-removed:
56
57The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed
58------------------------------------------------------
59
60The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to
61configure glibc using kconfig has been removed for quite some time
62making the ``libc-*`` features set no longer effective.
63
64Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own
65layers.
66
67.. _migration-2.7-license-values:
68
69License Value Corrections
70-------------------------
71
72The following corrections have been made to the
73:term:`LICENSE` values set by recipes:
74
75- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+".
76- *libgfortran*: Set license to "GPL-3.0-with-GCC-exception".
77- *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries
78
79.. _migration-2.7-packaging-changes:
80
81Packaging Changes
82-----------------
83
84This section provides information about packaging changes.
85
86- ``bind``: The ``nsupdate`` binary has been moved to the
87 ``bind-utils`` package.
88
89- Debug split: The default debug split has been changed to create
90 separate source packages (i.e. package_name\ ``-dbg`` and
91 package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in
92 :term:`IMAGE_FEATURES` to bring in debug
93 symbols and you still need the sources, you must now also add
94 ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the
95 target portion of the SDK by default, unless you have set your own
96 value for :term:`SDKIMAGE_FEATURES` that
97 does not include ``src-pkgs``.
98
99- Mount all using ``util-linux``: ``/etc/default/mountall`` has moved
100 into the -mount sub-package.
101
102- Splitting binaries using ``util-linux``: ``util-linux`` now splits
103 each binary into its own package for fine-grained control. The main
104 ``util-linux`` package pulls in the individual binary packages using
105 the :term:`RRECOMMENDS` and
106 :term:`RDEPENDS` variables. As a result, existing
107 images should not see any changes assuming
108 :term:`NO_RECOMMENDATIONS` is not set.
109
110- ``netbase/base-files``: ``/etc/hosts`` has moved from ``netbase`` to
111 ``base-files``.
112
113- ``tzdata``: The main package has been converted to an empty meta
114 package that pulls in all ``tzdata`` packages by default.
115
116- ``lrzsz``: This package has been removed from
117 ``packagegroup-self-hosted`` and
118 ``packagegroup-core-tools-testapps``. The X/Y/ZModem support is less
119 likely to be needed on modern systems. If you are relying on these
120 packagegroups to include the ``lrzsz`` package in your image, you now
121 need to explicitly add the package.
122
123.. _migration-2.7-removed-recipes:
124
125Removed Recipes
126---------------
127
128The following recipes have been removed:
129
130- *gcc*: Drop version 7.3 recipes. Version 8.3 now remains.
131- *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
132- *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
133- *xvideo-tests*: Became obsolete.
134- *libart-lgpl*: Became obsolete.
135- *gtk-icon-utils-native*: These tools are now provided by gtk+3-native
136- *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
137- *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
138- *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe.
139
140.. _migration-2.7-removed-classes:
141
142Removed Classes
143---------------
144
145The following classes have been removed:
146
147- *distutils-tools*: This class was never used.
148- *bugzilla.bbclass*: Became obsolete.
149- *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation.
150
151.. _migration-2.7-miscellaneous-changes:
152
153Miscellaneous Changes
154---------------------
155
156The following miscellaneous changes occurred:
157
158- The ``distro`` subdirectory of the Poky repository has been removed
159 from the top-level ``scripts`` directory.
160
161- Perl now builds for the target using
162 `perl-cross <https://arsv.github.io/perl-cross/>`_ for better
163 maintainability and improved build performance. This change should
164 not present any problems unless you have heavily customized your Perl
165 recipe.
166
167- ``arm-tunes``: Removed the "-march" option if mcpu is already added.
168
169- ``update-alternatives``: Convert file renames to
170 :term:`PACKAGE_PREPROCESS_FUNCS`
171
172- ``base/pixbufcache``: Obsolete ``sstatecompletions`` code has been
173 removed.
174
175- :ref:`native <ref-classes-native>` class:
176 :term:`RDEPENDS` handling has been enabled.
177
178- ``inetutils``: This recipe has rsh disabled.
179
180
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst
deleted file mode 100644
index 7ef2742f8b..0000000000
--- a/documentation/ref-manual/migration-3.0.rst
+++ /dev/null
@@ -1,320 +0,0 @@
1Moving to the Yocto Project 3.0 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.0 Release from the prior release.
6
7.. _migration-3.0-init-system-selection:
8
9Init System Selection
10---------------------
11
12Changing the init system manager previously required setting a number of
13different variables. You can now change the manager by setting the
14``INIT_MANAGER`` variable and the corresponding include files (i.e.
15``conf/distro/include/init-manager-*.conf``). Include files are provided
16for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The
17default value, "none", for ``INIT_MANAGER`` should allow your current
18settings to continue working. However, it is advisable to explicitly set
19``INIT_MANAGER``.
20
21.. _migration-3.0-lsb-support-removed:
22
23LSB Support Removed
24-------------------
25
26Linux Standard Base (LSB) as a standard is not current, and is not well
27suited for embedded applications. Support can be continued in a separate
28layer if needed. However, presently LSB support has been removed from
29the core.
30
31As a result of this change, the ``poky-lsb`` derivative distribution
32configuration that was also used for testing alternative configurations
33has been replaced with a ``poky-altcfg`` distribution that has LSB parts
34removed.
35
36.. _migration-3.0-removed-recipes:
37
38Removed Recipes
39---------------
40
41The following recipes have been removed.
42
43- ``core-image-lsb-dev``: Part of removed LSB support.
44
45- ``core-image-lsb``: Part of removed LSB support.
46
47- ``core-image-lsb-sdk``: Part of removed LSB support.
48
49- ``cve-check-tool``: Functionally replaced by the ``cve-update-db``
50 recipe and ``cve-check`` class.
51
52- ``eglinfo``: No longer maintained. ``eglinfo`` from ``mesa-demos`` is
53 an adequate and maintained alternative.
54
55- ``gcc-8.3``: Version 8.3 removed. Replaced by 9.2.
56
57- ``gnome-themes-standard``: Only needed by gtk+ 2.x, which has been
58 removed.
59
60- ``gtk+``: GTK+ 2 is obsolete and has been replaced by gtk+3.
61
62- ``irda-utils``: Has become obsolete. IrDA support has been removed
63 from the Linux kernel in version 4.17 and later.
64
65- ``libnewt-python``: ``libnewt`` Python support merged into main
66 ``libnewt`` recipe.
67
68- ``libsdl``: Replaced by newer ``libsdl2``.
69
70- ``libx11-diet``: Became obsolete.
71
72- ``libxx86dga``: Removed obsolete client library.
73
74- ``libxx86misc``: Removed. Library is redundant.
75
76- ``linux-yocto``: Version 5.0 removed, which is now redundant (5.2 /
77 4.19 present).
78
79- ``lsbinitscripts``: Part of removed LSB support.
80
81- ``lsb``: Part of removed LSB support.
82
83- ``lsbtest``: Part of removed LSB support.
84
85- ``openssl10``: Replaced by newer ``openssl`` version 1.1.
86
87- ``packagegroup-core-lsb``: Part of removed LSB support.
88
89- ``python-nose``: Removed the Python 2.x version of the recipe.
90
91- ``python-numpy``: Removed the Python 2.x version of the recipe.
92
93- ``python-scons``: Removed the Python 2.x version of the recipe.
94
95- ``source-highlight``: No longer needed.
96
97- ``stress``: Replaced by ``stress-ng``.
98
99- ``vulkan``: Split into ``vulkan-loader``, ``vulkan-headers``, and
100 ``vulkan-tools``.
101
102- ``weston-conf``: Functionality moved to ``weston-init``.
103
104.. _migration-3.0-packaging-changes:
105
106Packaging Changes
107-----------------
108
109The following packaging changes have occurred.
110
111- The `Epiphany <https://en.wikipedia.org/wiki/GNOME_Web>`__ browser
112 has been dropped from ``packagegroup-self-hosted`` as it has not been
113 needed inside ``build-appliance-image`` for quite some time and was
114 causing resource problems.
115
116- ``libcap-ng`` Python support has been moved to a separate
117 ``libcap-ng-python`` recipe to streamline the build process when the
118 Python bindings are not needed.
119
120- ``libdrm`` now packages the file ``amdgpu.ids`` into a separate
121 ``libdrm-amdgpu`` package.
122
123- ``python3``: The ``runpy`` module is now in the ``python3-core``
124 package as it is required to support the common "python3 -m" command
125 usage.
126
127- ``distcc`` now provides separate ``distcc-client`` and
128 ``distcc-server`` packages as typically one or the other are needed,
129 rather than both.
130
131- ``python*-setuptools`` recipes now separately package the
132 ``pkg_resources`` module in a ``python-pkg-resources`` /
133 ``python3-pkg-resources`` package as the module is useful independent
134 of the rest of the setuptools package. The main ``python-setuptools``
135 / ``python3-setuptools`` package depends on this new package so you
136 should only need to update dependencies unless you want to take
137 advantage of the increased granularity.
138
139.. _migration-3.0-cve-checking:
140
141CVE Checking
142------------
143
144``cve-check-tool`` has been functionally replaced by a new
145``cve-update-db`` recipe and functionality built into the ``cve-check``
146class. The result uses NVD JSON data feeds rather than the deprecated
147XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring,
148and makes other improvements.
149
150Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced
151by ``CVE_CHECK_WHITELIST``.
152
153.. _migration-3.0-bitbake-changes:
154
155Bitbake Changes
156---------------
157
158The following BitBake changes have occurred.
159
160- ``addtask`` statements now properly validate dependent tasks.
161 Previously, an invalid task was silently ignored. With this change,
162 the invalid task generates a warning.
163
164- Other invalid ``addtask`` and ``deltask`` usages now trigger these
165 warnings: "multiple target tasks arguments with addtask / deltask",
166 and "multiple before/after clauses".
167
168- The "multiconfig" prefix is now shortened to "mc". "multiconfig" will
169 continue to work, however it may be removed in a future release.
170
171- The ``bitbake -g`` command no longer generates a
172 ``recipe-depends.dot`` file as the contents (i.e. a reprocessed
173 version of ``task-depends.dot``) were confusing.
174
175- The ``bb.build.FuncFailed`` exception, previously raised by
176 ``bb.build.exec_func()`` when certain other exceptions have occurred,
177 has been removed. The real underlying exceptions will be raised
178 instead. If you have calls to ``bb.build.exec_func()`` in custom
179 classes or ``tinfoil-using`` scripts, any references to
180 ``bb.build.FuncFailed`` should be cleaned up.
181
182- Additionally, the ``bb.build.exec_func()`` no longer accepts the
183 "pythonexception" parameter. The function now always raises
184 exceptions. Remove this argument in any calls to
185 ``bb.build.exec_func()`` in custom classes or scripts.
186
187- The
188 :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2`
189 is no longer used. In the unlikely event that you have any references
190 to it, they should be removed.
191
192- The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events
193 have been removed since setscene tasks are now executed as part of
194 the normal runqueue. Any event handling code in custom classes or
195 scripts that handles these two events need to be updated.
196
197- The arguments passed to functions used with
198 :term:`bitbake:BB_HASHCHECK_FUNCTION`
199 have changed. If you are using your own custom hash check function,
200 see :yocto_git:`/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725`
201 for details.
202
203- Task specifications in ``BB_TASKDEPDATA`` and class implementations
204 used in signature generator classes now use "<fn>:<task>" everywhere
205 rather than the "." delimiter that was being used in some places.
206 This change makes it consistent with all areas in the code. Custom
207 signature generator classes and code that reads ``BB_TASKDEPDATA``
208 need to be updated to use ':' as a separator rather than '.'.
209
210.. _migration-3.0-sanity-checks:
211
212Sanity Checks
213-------------
214
215The following sanity check changes occurred.
216
217- :term:`SRC_URI` is now checked for usage of two
218 problematic items:
219
220 - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is
221 used. You must fix the issue regardless of whether multiconfig or
222 anything else that would cause prefixing/suffixing to happen.
223
224 - Github archive tarballs - these are not guaranteed to be stable.
225 Consequently, it is likely that the tarballs will be refreshed and
226 thus the SRC_URI checksums will fail to apply. It is recommended
227 that you fetch either an official release tarball or a specific
228 revision from the actual Git repository instead.
229
230 Either one of these items now trigger a warning by default. If you
231 wish to disable this check, remove ``src-uri-bad`` from
232 :term:`WARN_QA`.
233
234- The ``file-rdeps`` runtime dependency check no longer expands
235 :term:`RDEPENDS` recursively as there is no mechanism
236 to ensure they can be fully computed, and thus races sometimes result
237 in errors either showing up or not. Thus, you might now see errors
238 for missing runtime dependencies that were previously satisfied
239 recursively. Here is an example: package A contains a shell script
240 starting with ``#!/bin/bash`` but has no dependency on bash. However,
241 package A depends on package B, which does depend on bash. You need
242 to add the missing dependency or dependencies to resolve the warning.
243
244- Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now
245 triggers an error. The error is triggered because
246 :term:`DEPENDS` is not a package-specific variable
247 unlike RDEPENDS. You should set ``DEPENDS`` instead.
248
249- systemd currently does not work well with the musl C library because
250 only upstream officially supports linking the library with glibc.
251 Thus, a warning is shown when building systemd in conjunction with
252 musl.
253
254.. _migration-3.0-miscellaneous-changes:
255
256Miscellaneous Changes
257---------------------
258
259The following miscellaneous changes have occurred.
260
261- The ``gnome`` class has been removed because it now does very little.
262 You should update recipes that previously inherited this class to do
263 the following: inherit gnomebase gtk-icon-cache gconf mime
264
265- The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been
266 removed. This file was previously deprecated in favor of setting
267 :term:`KERNEL_DEVICETREE` in any kernel
268 recipe and only produced a warning. Remove any ``include`` or
269 ``require`` statements pointing to this file.
270
271- :term:`TARGET_CFLAGS`,
272 :term:`TARGET_CPPFLAGS`,
273 :term:`TARGET_CXXFLAGS`, and
274 :term:`TARGET_LDFLAGS` are no longer exported
275 to the external environment. This change did not require any changes
276 to core recipes, which is a good indicator that no changes will be
277 required. However, if for some reason the software being built by one
278 of your recipes is expecting these variables to be set, then building
279 the recipe will fail. In such cases, you must either export the
280 variable or variables in the recipe or change the scripts so that
281 exporting is not necessary.
282
283- You must change the host distro identifier used in
284 :term:`NATIVELSBSTRING` to use all lowercase
285 characters even if it does not contain a version number. This change
286 is necessary only if you are not using ``uninative`` and
287 :term:`SANITY_TESTED_DISTROS`.
288
289- In the ``base-files`` recipe, writing the hostname into
290 ``/etc/hosts`` and ``/etc/hostname`` is now done within the main
291 :ref:`ref-tasks-install` function rather than in the
292 ``do_install_basefilesissue`` function. The reason for the change is
293 because ``do_install_basefilesissue`` is more easily overridden
294 without having to duplicate the hostname functionality. If you have
295 done the latter (e.g. in a ``base-files`` bbappend), then you should
296 remove it from your customized ``do_install_basefilesissue``
297 function.
298
299- The ``wic --expand`` command now uses commas to separate "key:value"
300 pairs rather than hyphens.
301
302 .. note::
303
304 The wic command-line help is not updated.
305
306 You must update any scripts or commands where you use
307 ``wic --expand`` with multiple "key:value" pairs.
308
309- UEFI image variable settings have been moved from various places to a
310 central ``conf/image-uefi.conf``. This change should not influence
311 any existing configuration as the ``meta/conf/image-uefi.conf`` in
312 the core metadata sets defaults that can be overridden in the same
313 manner as before.
314
315- ``conf/distro/include/world-broken.inc`` has been removed. For cases
316 where certain recipes need to be disabled when using the musl C
317 library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set
318 with a comment that explains why.
319
320
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
deleted file mode 100644
index 4fcd2490d3..0000000000
--- a/documentation/ref-manual/migration-3.1.rst
+++ /dev/null
@@ -1,276 +0,0 @@
1Moving to the Yocto Project 3.1 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.1 Release from the prior release.
6
7.. _migration-3.1-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12The following versions / requirements of build host components have been
13updated:
14
15- gcc 5.0
16
17- python 3.5
18
19- tar 1.28
20
21- ``rpcgen`` is now required on the host (part of the ``libc-dev-bin``
22 package on Ubuntu, Debian and related distributions, and the
23 ``glibc`` package on RPM-based distributions).
24
25Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer*
26required on the host.
27
28.. _migration-3.1-mpc8315e-rdb-removed:
29
30mpc8315e-rdb machine removed
31----------------------------
32
33The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given
34the maintenance burden the ``mpc8315e-rdb`` machine configuration that
35supported it has been removed in this release. The removal does leave a
36gap in official PowerPC reference hardware support; this may change in
37future if a suitable machine with accompanying support resources is
38found.
39
40.. _migration-3.1-python-2-removed:
41
42Python 2 removed
43----------------
44
45Due to the expiration of upstream support in January 2020, support for
46Python 2 has now been removed; it is recommended that you use Python 3
47instead. If absolutely needed there is a meta-python2 community layer
48containing Python 2, related classes and various Python 2-based modules,
49however it should not be considered as supported.
50
51.. _migration-3.1-reproducible-builds:
52
53Reproducible builds now enabled by default
54------------------------------------------
55
56In order to avoid unnecessary differences in output files (aiding binary
57reproducibility), the Poky distribution configuration
58(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by
59default.
60
61.. _migration-3.1-ptest-feature-impact:
62
63Impact of ptest feature is now more significant
64-----------------------------------------------
65
66The Poky distribution configuration (``DISTRO = "poky"``) enables ptests
67by default to enable runtime testing of various components. In this
68release, a dependency needed to be added that has resulted in a
69significant increase in the number of components that will be built just
70when building a simple image such as core-image-minimal. If you do not
71need runtime tests enabled for core components, then it is recommended
72that you remove "ptest" from
73:term:`DISTRO_FEATURES` to save a significant
74amount of build time e.g. by adding the following in your configuration:
75::
76
77 DISTRO_FEATURES_remove = "ptest"
78
79.. _migration-3.1-removed-recipes:
80
81Removed recipes
82---------------
83
84The following recipes have been removed:
85
86- ``chkconfig``: obsolete
87
88- ``console-tools``: obsolete
89
90- ``enchant``: replaced by ``enchant2``
91
92- ``foomatic-filters``: obsolete
93
94- ``libidn``: no longer needed, moved to meta-oe
95
96- ``libmodulemd``: replaced by ``libmodulemd-v1``
97
98- ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided)
99
100- ``nspr``: no longer needed, moved to meta-oe
101
102- ``nss``: no longer needed, moved to meta-oe
103
104- ``python``: Python 2 removed (Python 3 preferred)
105
106- ``python-setuptools``: Python 2 version removed (python3-setuptools
107 preferred)
108
109- ``sysprof``: no longer needed, moved to meta-oe
110
111- ``texi2html``: obsolete
112
113- ``u-boot-fw-utils``: functionally replaced by ``libubootenv``
114
115.. _migration-3.1-features-check:
116
117features_check class replaces distro_features_check
118---------------------------------------------------
119
120The ``distro_features_check`` class has had its functionality expanded,
121now supporting ``ANY_OF_MACHINE_FEATURES``,
122``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``,
123``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``,
124``CONFLICT_COMBINED_FEATURES``. As a result the class has now been
125renamed to ``features_check``; the ``distro_features_check`` class still
126exists but generates a warning and redirects to the new class. In
127preparation for a future removal of the old class it is recommended that
128you update recipes currently inheriting ``distro_features_check`` to
129inherit ``features_check`` instead.
130
131.. _migration-3.1-removed-classes:
132
133Removed classes
134---------------
135
136The following classes have been removed:
137
138- ``distutils-base``: moved to meta-python2
139
140- ``distutils``: moved to meta-python2
141
142- ``libc-common``: merged into the glibc recipe as nothing else used
143 it.
144
145- ``python-dir``: moved to meta-python2
146
147- ``pythonnative``: moved to meta-python2
148
149- ``setuptools``: moved to meta-python2
150
151- ``tinderclient``: dropped as it was obsolete.
152
153.. _migration-3.1-src-uri-checksums:
154
155SRC_URI checksum behaviour
156--------------------------
157
158Previously, recipes by tradition included both SHA256 and MD5 checksums
159for remotely fetched files in :term:`SRC_URI`, even
160though only one is actually mandated. However, the MD5 checksum does not
161add much given its inherent weakness; thus when a checksum fails only
162the SHA256 sum will now be printed. The md5sum will still be verified if
163it is specified.
164
165.. _migration-3.1-npm:
166
167npm fetcher changes
168-------------------
169
170The npm fetcher has been completely reworked in this release. The npm
171fetcher now only fetches the package source itself and no longer the
172dependencies; there is now also an npmsw fetcher which explicitly
173fetches the shrinkwrap file and the dependencies. This removes the
174slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which
175pointed to local files; the lockdown file is no longer needed at all.
176Additionally, the package name in ``npm://`` entries in
177:term:`SRC_URI` is now specified using a ``package``
178parameter instead of the earlier ``name`` which overlapped with the
179generic ``name`` parameter. All recipes using the npm fetcher will need
180to be changed as a result.
181
182An example of the new scheme: ::
183
184 SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
185 npmsw://${THISDIR}/npm-shrinkwrap.json"
186
187Another example where the sources are fetched from git rather than an npm repository: ::
188
189 SRC_URI = "git://github.com/foo/bar.git;protocol=https \
190 npmsw://${THISDIR}/npm-shrinkwrap.json"
191
192devtool and recipetool have also been updated to match with the npm
193fetcher changes. Other than producing working and more complete recipes
194for npm sources, there is also a minor change to the command line for
195devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as
196it is npm-specific.
197
198.. _migration-3.1-packaging-changes:
199
200Packaging changes
201-----------------
202
203- ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is
204 rarely needed to build modern software - gettext can do most of the
205 things it used to be needed for. ``intltool`` has also been removed
206 from ``packagegroup-core-self-hosted`` as it is not needed to for
207 standard builds.
208
209- git: ``git-am``, ``git-difftool``, ``git-submodule``, and
210 ``git-request-pull`` are no longer perl-based, so are now installed
211 with the main ``git`` package instead of within ``git-perltools``.
212
213- The ``ldconfig`` binary built as part of glibc has now been moved to
214 its own ``ldconfig`` package (note no ``glibc-`` prefix). This
215 package is in the :term:`RRECOMMENDS` of the main
216 ``glibc`` package if ``ldconfig`` is present in
217 :term:`DISTRO_FEATURES`.
218
219- ``libevent`` now splits each shared library into its own package (as
220 Debian does). Since these are shared libraries and will be pulled in
221 through the normal shared library dependency handling, there should
222 be no impact to existing configurations other than less unnecessary
223 libraries being installed in some cases.
224
225- linux-firmware now has a new package for ``bcm4366c`` and includes
226 available NVRAM config files into the ``bcm43340``, ``bcm43362``,
227 ``bcm43430`` and ``bcm4356-pcie`` packages.
228
229- ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library
230 into its own package to reduce the main package size in cases where
231 ``libharfbuzz-subset.so`` is not needed.
232
233.. _migration-3.1-package-qa-warnings:
234
235Additional warnings
236-------------------
237
238Warnings will now be shown at ``do_package_qa`` time in the following
239circumstances:
240
241- A recipe installs ``.desktop`` files containing ``MimeType`` keys but
242 does not inherit the new ``mime-xdg`` class
243
244- A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
245 but does not inherit the ``mime`` class
246
247.. _migration-3.1-x86-live-wic:
248
249``wic`` image type now used instead of ``live`` by default for x86
250------------------------------------------------------------------
251
252``conf/machine/include/x86-base.inc`` (inherited by most x86 machine
253configurations) now specifies ``wic`` instead of ``live`` by default in
254:term:`IMAGE_FSTYPES`. The ``live`` image type will
255likely be removed in a future release so it is recommended that you use
256``wic`` instead.
257
258.. _migration-3.1-misc:
259
260Miscellaneous changes
261---------------------
262
263- The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
264 removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
265 dynamically set based upon license files found in
266 ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
267
268- The tune definition for big-endian microblaze machines is now
269 ``microblaze`` instead of ``microblazeeb``.
270
271- ``newlib`` no longer has built-in syscalls. ``libgloss`` should then
272 provide the syscalls, ``crt0.o`` and other functions that are no
273 longer part of ``newlib`` itself. If you are using
274 ``TCLIBC = "newlib"`` this now means that you must link applications
275 with both ``newlib`` and ``libgloss``, whereas before ``newlib``
276 would run in many configurations by itself.
diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
deleted file mode 100644
index 65a9ff4cac..0000000000
--- a/documentation/ref-manual/migration-3.2.rst
+++ /dev/null
@@ -1,313 +0,0 @@
1Moving to the Yocto Project 3.2 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.2 Release from the prior release.
6
7.. _migration-3.2-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12``gcc`` version 6.0 is now required at minimum on the build host. For older
13host distributions where this is not available, you can use the
14``buildtools-extended-tarball`` (easily installable using
15``scripts/install-buildtools``).
16
17
18.. _migration-3.2-removed-recipes:
19
20Removed recipes
21---------------
22
23The following recipes have been removed:
24
25- ``bjam-native``: replaced by ``boost-build-native``
26- ``avahi-ui``: folded into the main ``avahi`` recipe - the GTK UI can be disabled using :term:`PACKAGECONFIG` for ``avahi``.
27- ``build-compare``: no longer needed with the removal of the ``packagefeed-stability`` class
28- ``dhcp``: obsolete, functionally replaced by ``dhcpcd`` and ``kea``
29- ``libmodulemd-v1``: replaced by ``libmodulemd``
30- ``packagegroup-core-device-devel``: obsolete
31
32
33.. _migration-3.2-removed-classes:
34
35Removed classes
36---------------
37
38The following classes (.bbclass files) have been removed:
39
40- ``spdx``: obsolete - the Yocto Project is a strong supporter of SPDX, but this class was old code using a dated approach and had the potential to be misleading. The ``meta-sdpxscanner`` layer is a much more modern and active approach to handling this and is recommended as a replacement.
41
42- ``packagefeed-stability``: this class had become obsolete with the advent of hash equivalence and reproducible builds.
43
44
45pseudo path filtering and mismatch behaviour
46--------------------------------------------
47
48pseudo now operates on a filtered subset of files. This is a significant change
49to the way pseudo operates within OpenEmbedded - by default, pseudo monitors and
50logs (adds to its database) any file created or modified whilst in a ``fakeroot``
51environment. However, there are large numbers of files that we simply don't care
52about the permissions of whilst in that ``fakeroot`` context, for example ${:term:`S`}, ${:term:`B`}, ${:term:`T`},
53${:term:`SSTATE_DIR`}, the central sstate control directories, and others.
54
55As of this release, new functionality in pseudo is enabled to ignore these
56directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable)
57resulting in a cleaner database with less chance of "stray" mismatches if files
58are modified outside pseudo context. It also should reduce some overhead from
59pseudo as the interprocess round trip to the server is avoided.
60
61There is a possible complication where some existing recipe may break, for
62example, a recipe was found to be writing to ``${B}/install`` for
63``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked,
64there were errors trying to ``chown root`` for files in this location. Another
65example was the ``tcl`` recipe where the source directory ``S`` is set to a
66subdirectory of the source tree but files were written out to the directory
67structure above that subdirectory. For these types of cases in your own recipes,
68extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not
69be monitoring.
70
71In addition, pseudo's behaviour on mismatches has now been changed - rather
72than doing what turns out to be a rather dangerous "fixup" if it sees a file
73with a different path but the same inode as another file it has previously seen,
74pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </Pseudo_Abort>`
75that explains how to deal with this.
76
77
78.. _migration-3.2-multilib-mlprefix:
79
80``MLPREFIX`` now required for multilib when runtime dependencies conditionally added
81------------------------------------------------------------------------------------
82
83In order to solve some previously intractable problems with runtime
84dependencies and multilib, a change was made that now requires the :term:`MLPREFIX`
85value to be explicitly prepended to package names being added as
86dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values)
87where the dependency is conditionally added.
88
89If you have anonymous python or in-line python conditionally adding
90dependencies in your custom recipes, and you intend for those recipes to
91work with multilib, then you will need to ensure that ``${MLPREFIX}``
92is prefixed on the package names in the dependencies, for example
93(from the ``glibc`` recipe): ::
94
95 RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
96
97This also applies when conditionally adding packages to :term:`PACKAGES` where
98those packages have dependencies, for example (from the ``alsa-plugins`` recipe): ::
99
100 PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
101 ...
102 RDEPENDS_${PN}-pulseaudio-conf += "\
103 ${MLPREFIX}libasound-module-conf-pulse \
104 ${MLPREFIX}libasound-module-ctl-pulse \
105 ${MLPREFIX}libasound-module-pcm-pulse \
106 "
107
108
109.. _migration-3.2-packagegroup-core-device-devel:
110
111packagegroup-core-device-devel no longer included in images built for qemu* machines
112------------------------------------------------------------------------------------
113
114``packagegroup-core-device-devel`` was previously added automatically to
115images built for ``qemu*`` machines, however the purpose of the group and what
116it should contain is no longer clear, and in general, adding userspace
117development items to images is best done at the image/class level; thus this
118packagegroup was removed.
119
120This packagegroup previously pulled in the following:
121
122- ``distcc-config``
123- ``nfs-export-root``
124- ``bash``
125- ``binutils-symlinks``
126
127If you still need any of these in your image built for a ``qemu*`` machine
128then you will add them explicitly to :term:`IMAGE_INSTALL` or another
129appropriate place in the dependency chain for your image (if you have not
130already done so).
131
132
133.. _migration-3.2-dhcp:
134
135DHCP server/client replaced
136---------------------------
137
138The ``dhcp`` software package has become unmaintained and thus has been
139functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will
140need to replace references to the recipe/package names as appropriate - most
141commonly, at the package level ``dhcp-client`` should be replaced by
142``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any
143custom configuration files for these they will need to be adapted - refer to
144the upstream documentation for ``dhcpcd`` and ``kea`` for further details.
145
146
147.. _migration-3.2-packaging-changes:
148
149Packaging changes
150-----------------
151
152- ``python3``: the ``urllib`` python package has now moved into the core package, as it is used more commonly than just netclient (e.g. email, xml, mimetypes, pydoc). In addition, the ``pathlib`` module is now also part of the core package.
153
154- ``iptables``: ``iptables-apply`` and ``ip6tables-apply`` have been split out to their own package to avoid a bash dependency in the main ``iptables`` package
155
156
157.. _migration-3.2-package-qa-checks:
158
159Package QA check changes
160------------------------
161
162Previously, the following package QA checks triggered warnings, however they can
163be indicators of genuine underlying problems and are therefore now treated as
164errors:
165
166- :ref:`already-stripped <qa-check-already-stripped>`
167- :ref:`compile-host-path <qa-check-compile-host-path>`
168- :ref:`installed-vs-shipped <qa-check-installed-vs-shipped>`
169- :ref:`ldflags <qa-check-ldflags>`
170- :ref:`pn-overrides <qa-check-pn-overrides>`
171- :ref:`rpaths <qa-check-rpaths>`
172- :ref:`staticdev <qa-check-staticdev>`
173- :ref:`unknown-configure-option <qa-check-unknown-configure-option>`
174- :ref:`useless-rpaths <qa-check-useless-rpaths>`
175
176In addition, the following new checks were added and default to triggering an error:
177
178- :ref:`shebang-size <qa-check-shebang-size>`: Check for shebang (#!) lines longer than 128 characters, which can give an error at runtime depending on the operating system.
179
180- :ref:`unhandled-features-check <qa-check-unhandled-features-check>`: Check if any of the variables supported by the :ref:`features_check <ref-classes-features_check>` class is set while not inheriting the class itself.
181
182- :ref:`missing-update-alternatives <qa-check-missing-update-alternatives>`: Check if the recipe sets the :term:`ALTERNATIVE` variable for any of its packages, and does not inherit the :ref:`update-alternatives <ref-classes-update-alternatives>` class.
183
184- A trailing slash or duplicated slashes in the value of :term:`S` or :term:`B` will now trigger a warning so that they can be removed and path comparisons can be more reliable - remove any instances of these in your recipes if the warning is displayed.
185
186
187.. _migration-3.2-src-uri-file-globbing:
188
189Globbing no longer supported in ``file://`` entries in ``SRC_URI``
190------------------------------------------------------------------
191
192Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI`
193did not properly support file checksums, thus changes to the source files
194would not always change the do_fetch task checksum, and consequently would
195not ensure that the changed files would be incorporated in subsequent builds.
196
197Unfortunately it is not practical to make globbing work generically here, so
198the decision was taken to remove support for globs in ``file://`` URLs.
199If you have any usage of these in your recipes, then you will now need to
200either add each of the files that you expect to match explicitly, or
201alternatively if you still need files to be pulled in dynamically, put the
202files into a subdirectory and reference that instead.
203
204
205.. _migration-3.2-deploydir-clean:
206
207deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
208----------------------------------------------------------
209
210``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of ``DEPLOYDIR`` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
211
212Most recipes and classes that inherit the ``deploy`` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` - these should be refactored to use ``do_deploy_prepend`` instead.
213
214
215.. _migration-3.2-nativesdk-sdk-provides-dummy:
216
217Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy``
218-------------------------------------------------------------------------------
219
220All ``nativesdk`` packages require ``/bin/sh`` due to their postinstall scriptlets, thus this package has to be dummy-provided within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have a custom SDK recipe (or your own SDK-style recipe similar to e.g. ``buildtools-tarball``), you will need to ensure ``nativesdk-sdk-provides-dummy`` or an equivalent is included in :term:`TOOLCHAIN_HOST_TASK`.
221
222
223``ld.so.conf`` now moved back to main ``glibc`` package
224-------------------------------------------------------
225
226There are cases where one doesn't want ``ldconfig`` on target (e.g. for
227read-only root filesystems, it's rather pointless), yet one still
228needs ``/etc/ld.so.conf`` to be present at image build time:
229
230When some recipe installs libraries to a non-standard location, and
231therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
232need ``/etc/ld.so.conf`` containing: ::
233
234 include /etc/ld.so.conf.d/*.conf
235
236in order to get those other locations picked up.
237
238Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that
239there's always an ``ld.so.conf`` present when the build-time ``ldconfig``
240runs towards the end of image construction.
241
242The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up
243significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they
244might be needed in case ``ldconfig`` is installable, so they are left
245in place after the image is built. Technically it would be possible to
246remove them if desired, though it would not be trivial if you still
247wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND`
248will not work as ``ldconfig`` is run after the functions referred to
249by that variable).
250
251
252.. _migration-3.2-virgl:
253
254Host DRI drivers now used for GL support within ``runqemu``
255-----------------------------------------------------------
256
257``runqemu`` now uses the mesa-native libraries everywhere virgl is used
258(i.e. when ``gl``, ``gl-es`` or ``egl-headless`` options are specified),
259but instructs them to load DRI drivers from the host. Unfortunately this
260may not work well with proprietary graphics drivers such as those from
261Nvidia; if you are using such drivers then you may need to switch to an
262alternative (such as Nouveau in the case of Nvidia hardware) or avoid
263using the GL options.
264
265
266.. _migration-3.2-initramfs-suffix:
267
268initramfs images now use a blank suffix
269---------------------------------------
270
271The reference initramfs images (``core-image-minimal-initramfs``,
272``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now
273set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults
274to ``".rootfs"``. These images aren't root filesystems and thus the rootfs
275label didn't make sense. If you are looking for the output files generated
276by these image recipes directly then you will need to adapt to the new
277naming without the ``.rootfs`` part.
278
279
280.. _migration-3.2-image-artifact-names:
281
282Image artifact name variables now centralised in image-artifact-names class
283---------------------------------------------------------------------------
284
285The defaults for the following image artifact name variables have been moved
286from bitbake.conf to a new ``image-artifact-names`` class:
287
288- :term:`IMAGE_BASENAME`
289- :term:`IMAGE_LINK_NAME`
290- :term:`IMAGE_NAME`
291- :term:`IMAGE_NAME_SUFFIX`
292- :term:`IMAGE_VERSION_SUFFIX`
293
294Image-related classes now inherit this class, and typically these variables
295are only referenced within image recipes so those will be unaffected by this
296change. However if you have references to these variables in either a recipe
297that is not an image or a class that is enabled globally, then those will
298now need to be changed to ``inherit image-artifact-names``.
299
300
301.. _migration-3.2-misc:
302
303Miscellaneous changes
304---------------------
305
306- Support for the long-deprecated ``PACKAGE_GROUP`` variable has now been removed - replace any remaining instances with :term:`FEATURE_PACKAGES`.
307- The ``FILESPATHPKG`` variable, having been previously deprecated, has now been removed. Replace any remaining references with appropriate use of :term:`FILESEXTRAPATHS`.
308- Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored.
309- ptest support has been removed from the ``kbd`` recipe, as upstream has moved to autotest which is difficult to work with in a cross-compilation environment.
310- ``oe.utils.is_machine_specific()`` and ``oe.utils.machine_paths()`` have been removed as their utility was questionable. In the unlikely event that you have references to these in your own code, then the code will need to be reworked.
311- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in busybox then add ``CONFIG_I2CTRANSFER=y`` to your custom busybox configuration.
312- In the ``Upstream-Status`` header convention for patches, ``Accepted`` has been replaced with ``Backport`` as these almost always mean the same thing i.e. the patch is already upstream and may need to be removed in a future recipe upgrade. If you are adding these headers to your own patches then use ``Backport`` to indicate that the patch has been sent upstream.
313- The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works.
diff --git a/documentation/ref-manual/migration-general.rst b/documentation/ref-manual/migration-general.rst
deleted file mode 100644
index 182482ec43..0000000000
--- a/documentation/ref-manual/migration-general.rst
+++ /dev/null
@@ -1,54 +0,0 @@
1General Migration Considerations
2================================
3
4Some considerations are not tied to a specific Yocto Project release.
5This section presents information you should consider when migrating to
6any new Yocto Project release.
7
8- *Dealing with Customized Recipes*:
9
10 Issues could arise if you take
11 older recipes that contain customizations and simply copy them
12 forward expecting them to work after you migrate to new Yocto Project
13 metadata. For example, suppose you have a recipe in your layer that
14 is a customized version of a core recipe copied from the earlier
15 release, rather than through the use of an append file. When you
16 migrate to a newer version of Yocto Project, the metadata (e.g.
17 perhaps an include file used by the recipe) could have changed in a
18 way that would break the build. Say, for example, a function is
19 removed from an include file and the customized recipe tries to call
20 that function.
21
22 You could "forward-port" all your customizations in your recipe so
23 that everything works for the new release. However, this is not the
24 optimal solution as you would have to repeat this process with each
25 new release if changes occur that give rise to problems.
26
27 The better solution (where practical) is to use append files
28 (``*.bbappend``) to capture any customizations you want to make to a
29 recipe. Doing so, isolates your changes from the main recipe making
30 them much more manageable. However, sometimes it is not practical to
31 use an append file. A good example of this is when introducing a
32 newer or older version of a recipe in another layer.
33
34- *Updating Append Files*:
35
36 Since append files generally only contain
37 your customizations, they often do not need to be adjusted for new
38 releases. However, if the ``.bbappend`` file is specific to a
39 particular version of the recipe (i.e. its name does not use the %
40 wildcard) and the version of the recipe to which it is appending has
41 changed, then you will at a minimum need to rename the append file to
42 match the name of the recipe file. A mismatch between an append file
43 and its corresponding recipe file (``.bb``) will trigger an error
44 during parsing.
45
46 Depending on the type of customization the append file applies, other
47 incompatibilities might occur when you upgrade. For example, if your
48 append file applies a patch and the recipe to which it is appending
49 is updated to a newer version, the patch might no longer apply. If
50 this is the case and assuming the patch is still needed, you must
51 modify the patch file so that it does apply.
52
53
54
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst
deleted file mode 100644
index 8d64a7daab..0000000000
--- a/documentation/ref-manual/migration.rst
+++ /dev/null
@@ -1,31 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3******************************************
4Migrating to a Newer Yocto Project Release
5******************************************
6
7This chapter provides information you can use to migrate work to a newer
8Yocto Project release. You can find the same information in the release
9notes for a given release.
10
11.. toctree::
12
13 migration-general
14 migration-1.3
15 migration-1.4
16 migration-1.5
17 migration-1.6
18 migration-1.7
19 migration-1.8
20 migration-2.0
21 migration-2.1
22 migration-2.2
23 migration-2.3
24 migration-2.4
25 migration-2.5
26 migration-2.6
27 migration-2.7
28 migration-3.0
29 migration-3.1
30 migration-3.2
31
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 6cb767d934..58526a0e57 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -28,7 +28,7 @@ error form along with an explanation.
28.. note:: 28.. note::
29 29
30 - At the end of each message, the name of the associated QA test (as 30 - At the end of each message, the name of the associated QA test (as
31 listed in the ":ref:`insane.bbclass <ref-classes-insane>`" 31 listed in the ":ref:`ref-classes-insane`"
32 section) appears within square brackets. 32 section) appears within square brackets.
33 33
34 - As mentioned, this list of error and warning messages is for QA 34 - As mentioned, this list of error and warning messages is for QA
@@ -88,7 +88,7 @@ Errors and Warnings
88 A file-level dependency has been identified from the specified 88 A file-level dependency has been identified from the specified
89 package on the specified files, but there is no explicit 89 package on the specified files, but there is no explicit
90 corresponding entry in :term:`RDEPENDS`. If 90 corresponding entry in :term:`RDEPENDS`. If
91 particular files are required at runtime then ``RDEPENDS`` should be 91 particular files are required at runtime then :term:`RDEPENDS` should be
92 declared in the recipe to ensure the packages providing them are 92 declared in the recipe to ensure the packages providing them are
93 built. 93 built.
94 94
@@ -97,14 +97,14 @@ Errors and Warnings
97 97
98- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]`` 98- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
99 99
100 A runtime dependency exists between the two specified packages, but 100 There is a runtime dependency between the two specified packages, but
101 there is nothing explicit within the recipe to enable the 101 there is nothing explicit within the recipe to enable the
102 OpenEmbedded build system to ensure that dependency is satisfied. 102 OpenEmbedded build system to ensure that dependency is satisfied.
103 This condition is usually triggered by an 103 This condition is usually triggered by an
104 :term:`RDEPENDS` value being added at the packaging 104 :term:`RDEPENDS` value being added at the packaging
105 stage rather than up front, which is usually automatic based on the 105 stage rather than up front, which is usually automatic based on the
106 contents of the package. In most cases, you should change the recipe 106 contents of the package. In most cases, you should change the recipe
107 to add an explicit ``RDEPENDS`` for the dependency. 107 to add an explicit :term:`RDEPENDS` for the dependency.
108 108
109   109  
110.. _qa-check-dev-so: 110.. _qa-check-dev-so:
@@ -151,10 +151,19 @@ Errors and Warnings
151 occur if you add a path which contains a ``.debug`` directory and do 151 occur if you add a path which contains a ``.debug`` directory and do
152 not explicitly add the ``.debug`` directory to the ``-dbg`` package. 152 not explicitly add the ``.debug`` directory to the ``-dbg`` package.
153 If this is the case, add the ``.debug`` directory explicitly to 153 If this is the case, add the ``.debug`` directory explicitly to
154 ``FILES_${PN}-dbg``. See :term:`FILES` for additional 154 ``FILES:${PN}-dbg``. See :term:`FILES` for additional
155 information on ``FILES``. 155 information on :term:`FILES`.
156
157.. _qa-check-empty-dirs:
158
159- ``<packagename> installs files in <path>, but it is expected to be empty [empty-dirs]``
160
161 The specified package is installing files into a directory that is
162 normally expected to be empty (such as ``/tmp``). These files may
163 be more appropriately installed to a different location, or
164 perhaps alternatively not installed at all, usually by updating the
165 :ref:`ref-tasks-install` task/function.
156 166
157  
158.. _qa-check-arch: 167.. _qa-check-arch:
159 168
160- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]`` 169- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
@@ -221,10 +230,9 @@ Errors and Warnings
221 Typically, the way to solve this performance issue is to add "-fPIC" 230 Typically, the way to solve this performance issue is to add "-fPIC"
222 or "-fpic" to the compiler command-line options. For example, given 231 or "-fpic" to the compiler command-line options. For example, given
223 software that reads :term:`CFLAGS` when you build it, 232 software that reads :term:`CFLAGS` when you build it,
224 you could add the following to your recipe: 233 you could add the following to your recipe::
225 ::
226 234
227 CFLAGS_append = " -fPIC " 235 CFLAGS:append = " -fPIC "
228 236
229 For more information on text relocations at runtime, see 237 For more information on text relocations at runtime, see
230 https://www.akkadia.org/drepper/textrelocs.html. 238 https://www.akkadia.org/drepper/textrelocs.html.
@@ -236,12 +244,11 @@ Errors and Warnings
236 244
237 This indicates that binaries produced when building the recipe have 245 This indicates that binaries produced when building the recipe have
238 not been linked with the :term:`LDFLAGS` options 246 not been linked with the :term:`LDFLAGS` options
239 provided by the build system. Check to be sure that the ``LDFLAGS`` 247 provided by the build system. Check to be sure that the :term:`LDFLAGS`
240 variable is being passed to the linker command. A common workaround 248 variable is being passed to the linker command. A common workaround
241 for this situation is to pass in ``LDFLAGS`` using 249 for this situation is to pass in :term:`LDFLAGS` using
242 :term:`TARGET_CC_ARCH` within the recipe as 250 :term:`TARGET_CC_ARCH` within the recipe as
243 follows: 251 follows::
244 ::
245 252
246 TARGET_CC_ARCH += "${LDFLAGS}" 253 TARGET_CC_ARCH += "${LDFLAGS}"
247 254
@@ -265,8 +272,7 @@ Errors and Warnings
265 272
266 The ``/usr/share/info/dir`` should not be packaged. Add the following 273 The ``/usr/share/info/dir`` should not be packaged. Add the following
267 line to your :ref:`ref-tasks-install` task or to your 274 line to your :ref:`ref-tasks-install` task or to your
268 ``do_install_append`` within the recipe as follows: 275 ``do_install:append`` within the recipe as follows::
269 ::
270 276
271 rm ${D}${infodir}/dir 277 rm ${D}${infodir}/dir
272   278  
@@ -306,7 +312,7 @@ Errors and Warnings
306 312
307- ``<packagename> rdepends on <debug_packagename> [debug-deps]`` 313- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
308 314
309 A dependency exists between the specified non-dbg package (i.e. a 315 There is a dependency between the specified non-dbg package (i.e. a
310 package whose name does not end in ``-dbg``) and a package that is a 316 package whose name does not end in ``-dbg``) and a package that is a
311 ``dbg`` package. The ``dbg`` packages contain debug symbols and are 317 ``dbg`` package. The ``dbg`` packages contain debug symbols and are
312 brought in using several different methods: 318 brought in using several different methods:
@@ -329,7 +335,7 @@ Errors and Warnings
329 335
330- ``<packagename> rdepends on <dev_packagename> [dev-deps]`` 336- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
331 337
332 A dependency exists between the specified non-dev package (a package 338 There is a dependency between the specified non-dev package (a package
333 whose name does not end in ``-dev``) and a package that is a ``dev`` 339 whose name does not end in ``-dev``) and a package that is a ``dev``
334 package. The ``dev`` packages contain development headers and are 340 package. The ``dev`` packages contain development headers and are
335 usually brought in using several different methods: 341 usually brought in using several different methods:
@@ -350,7 +356,7 @@ Errors and Warnings
350   356  
351.. _qa-check-dep-cmp: 357.. _qa-check-dep-cmp:
352 358
353- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]`` 359- ``<var>:<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
354 360
355 If you are adding a versioned dependency relationship to one of the 361 If you are adding a versioned dependency relationship to one of the
356 dependency variables (:term:`RDEPENDS`, 362 dependency variables (:term:`RDEPENDS`,
@@ -406,7 +412,7 @@ Errors and Warnings
406 If your recipe name does not match this, or you add packages to 412 If your recipe name does not match this, or you add packages to
407 :term:`PACKAGES` that do not conform to the 413 :term:`PACKAGES` that do not conform to the
408 convention, then you will receive this error. Rename your recipe. Or, 414 convention, then you will receive this error. Rename your recipe. Or,
409 if you have added a non-conforming package name to ``PACKAGES``, 415 if you have added a non-conforming package name to :term:`PACKAGES`,
410 change the package name appropriately. 416 change the package name appropriately.
411 417
412   418  
@@ -434,13 +440,13 @@ Errors and Warnings
434 440
435 The specified recipe has a name (:term:`PN`) value that 441 The specified recipe has a name (:term:`PN`) value that
436 appears in :term:`OVERRIDES`. If a recipe is named 442 appears in :term:`OVERRIDES`. If a recipe is named
437 such that its ``PN`` value matches something already in ``OVERRIDES`` 443 such that its :term:`PN` value matches something already in :term:`OVERRIDES`
438 (e.g. ``PN`` happens to be the same as :term:`MACHINE` 444 (e.g. :term:`PN` happens to be the same as :term:`MACHINE`
439 or :term:`DISTRO`), it can have unexpected 445 or :term:`DISTRO`), it can have unexpected
440 consequences. For example, assignments such as 446 consequences. For example, assignments such as
441 ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. 447 ``FILES:${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
442 Rename your recipe (or if ``PN`` is being set explicitly, change the 448 Rename your recipe (or if :term:`PN` is being set explicitly, change the
443 ``PN`` value) so that the conflict does not occur. See 449 :term:`PN` value) so that the conflict does not occur. See
444 :term:`FILES` for additional information. 450 :term:`FILES` for additional information.
445 451
446   452  
@@ -457,17 +463,17 @@ Errors and Warnings
457 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and 463 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
458 :term:`ALLOW_EMPTY`) should always be set specific 464 :term:`ALLOW_EMPTY`) should always be set specific
459 to a package (i.e. they should be set with a package name override 465 to a package (i.e. they should be set with a package name override
460 such as ``RDEPENDS_${PN} = "value"`` rather than 466 such as ``RDEPENDS:${PN} = "value"`` rather than
461 ``RDEPENDS = "value"``). If you receive this error, correct any 467 ``RDEPENDS = "value"``). If you receive this error, correct any
462 assignments to these variables within your recipe. 468 assignments to these variables within your recipe.
463 469
464 470
465- ``recipe uses DEPENDS_${PN}, should use DEPENDS [pkgvarcheck]`` 471- ``recipe uses DEPENDS:${PN}, should use DEPENDS [pkgvarcheck]``
466 472
467 This check looks for instances of setting ``DEPENDS_${PN}`` 473 This check looks for instances of setting ``DEPENDS:${PN}``
468 which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus 474 which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
469 it is not correct to specify it for a particular package, nor will such 475 it is not correct to specify it for a particular package, nor will such
470 an assignment actually work.) Set ``DEPENDS`` instead. 476 an assignment actually work.) Set :term:`DEPENDS` instead.
471 477
472 478
473.. _qa-check-already-stripped: 479.. _qa-check-already-stripped:
@@ -502,7 +508,7 @@ Errors and Warnings
502 508
503 Package names must appear only once in the 509 Package names must appear only once in the
504 :term:`PACKAGES` variable. You might receive this 510 :term:`PACKAGES` variable. You might receive this
505 error if you are attempting to add a package to ``PACKAGES`` that is 511 error if you are attempting to add a package to :term:`PACKAGES` that is
506 already in the variable's value. 512 already in the variable's value.
507 513
508   514  
@@ -526,11 +532,11 @@ Errors and Warnings
526 in an image later on in the build process. You need to do one of the 532 in an image later on in the build process. You need to do one of the
527 following: 533 following:
528 534
529 - Add the files to ``FILES`` for the package you want them to appear 535 - Add the files to :term:`FILES` for the package you want them to appear
530 in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main 536 in (e.g. ``FILES:${``\ :term:`PN`\ ``}`` for the main
531 package). 537 package).
532 538
533 - Delete the files at the end of the ``do_install`` task if the 539 - Delete the files at the end of the :ref:`ref-tasks-install` task if the
534 files are not needed in any package. 540 files are not needed in any package.
535 541
536   542  
@@ -542,18 +548,18 @@ Errors and Warnings
542 when a recipe has been renamed. However, if that is not the case, the 548 when a recipe has been renamed. However, if that is not the case, the
543 message might indicate that a private version of a library is being 549 message might indicate that a private version of a library is being
544 erroneously picked up as the provider for a common library. If that 550 erroneously picked up as the provider for a common library. If that
545 is the case, you should add the library's ``.so`` file name to 551 is the case, you should add the library's ``.so`` filename to
546 :term:`PRIVATE_LIBS` in the recipe that provides 552 :term:`PRIVATE_LIBS` in the recipe that provides
547 the private version of the library. 553 the private version of the library.
548 554
549 555
550.. _qa-check-unlisted-pkg-lics: 556.. _qa-check-unlisted-pkg-lics:
551 557
552- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]`` 558- ``LICENSE:<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
553 559
554 The :term:`LICENSE` of the recipe should be a superset 560 The :term:`LICENSE` of the recipe should be a superset
555 of all the licenses of all packages produced by this recipe. In other 561 of all the licenses of all packages produced by this recipe. In other
556 words, any license in ``LICENSE_*`` should also appear in 562 words, any license in ``LICENSE:*`` should also appear in
557 :term:`LICENSE`. 563 :term:`LICENSE`.
558 564
559 565
@@ -573,10 +579,10 @@ Errors and Warnings
573- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]`` 579- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]``
574 580
575 The specified package contains mime type files (``.xml`` files in 581 The specified package contains mime type files (``.xml`` files in
576 ``${datadir}/mime/packages``) and yet does not inherit the mime 582 ``${datadir}/mime/packages``) and yet does not inherit the
577 class which will ensure that these get properly installed. Either 583 :ref:`ref-classes-mime` class which will ensure that these get
578 add ``inherit mime`` to the recipe or remove the files at the 584 properly installed. Either add ``inherit mime`` to the recipe or remove the
579 ``do_install`` step if they are not needed. 585 files at the :ref:`ref-tasks-install` step if they are not needed.
580 586
581 587
582.. _qa-check-mime-xdg: 588.. _qa-check-mime-xdg:
@@ -584,10 +590,10 @@ Errors and Warnings
584- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]`` 590- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``
585 591
586 The specified package contains a .desktop file with a 'MimeType' key 592 The specified package contains a .desktop file with a 'MimeType' key
587 present, but does not inherit the mime-xdg class that is required in 593 present, but does not inherit the :ref:`ref-classes-mime-xdg`
588 order for that to be activated. Either add ``inherit mime`` to the 594 class that is required in order for that to be activated. Either add
589 recipe or remove the files at the ``do_install`` step if they are not 595 ``inherit mime`` to the recipe or remove the files at the
590 needed. 596 :ref:`ref-tasks-install` step if they are not needed.
591 597
592 598
593.. _qa-check-src-uri-bad: 599.. _qa-check-src-uri-bad:
@@ -596,7 +602,7 @@ Errors and Warnings
596 602
597 GitHub provides "archive" tarballs, however these can be re-generated 603 GitHub provides "archive" tarballs, however these can be re-generated
598 on the fly and thus the file's signature will not necessarily match that 604 on the fly and thus the file's signature will not necessarily match that
599 in the SRC_URI checksums in future leading to build failures. It is 605 in the :term:`SRC_URI` checksums in future leading to build failures. It is
600 recommended that you use an official release tarball or switch to 606 recommended that you use an official release tarball or switch to
601 pulling the corresponding revision in the actual git repository instead. 607 pulling the corresponding revision in the actual git repository instead.
602 608
@@ -607,26 +613,28 @@ Errors and Warnings
607 so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change 613 so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
608 for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND` 614 for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
609 or multilib are being used. This check will fail if a reference to ``${PN}`` 615 or multilib are being used. This check will fail if a reference to ``${PN}``
610 is found within the ``SRC_URI`` value - change it to ``${BPN}`` instead. 616 is found within the :term:`SRC_URI` value --- change it to ``${BPN}`` instead.
611 617
612 618
613.. _qa-check-unhandled-features-check: 619.. _qa-check-unhandled-features-check:
614 620
615- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]`` 621- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]``
616 622
617 This check ensures that if one of the variables that the :ref:`features_check <ref-classes-features_check>` 623 This check ensures that if one of the variables that the
618 class supports (e.g. :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe 624 :ref:`ref-classes-features_check` class supports (e.g.
619 inherits ``features_check`` in order for the requirement to actually work. If 625 :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe
620 you are seeing this message, either add ``inherit features_check`` to your recipe 626 inherits :ref:`ref-classes-features_check` in order for
621 or remove the reference to the variable if it is not needed. 627 the requirement to actually work. If you are seeing this message, either
628 add ``inherit features_check`` to your recipe or remove the reference to
629 the variable if it is not needed.
622 630
623 631
624.. _qa-check-missing-update-alternatives: 632.. _qa-check-missing-update-alternatives:
625 633
626- ``<recipename>: recipe defines ALTERNATIVE_<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]`` 634- ``<recipename>: recipe defines ALTERNATIVE:<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]``
627 635
628 This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the 636 This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the
629 recipe also inherits :ref:`update-alternatives <ref-classes-update-alternatives>` such 637 recipe also inherits :ref:`ref-classes-update-alternatives` such
630 that the alternative will be correctly set up. If you are seeing this message, either 638 that the alternative will be correctly set up. If you are seeing this message, either
631 add ``inherit update-alternatives`` to your recipe or remove the reference to the variable 639 add ``inherit update-alternatives`` to your recipe or remove the reference to the variable
632 if it is not needed. 640 if it is not needed.
@@ -647,7 +655,7 @@ Errors and Warnings
647- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]`` 655- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]``
648 656
649 ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be 657 ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be
650 installed by any distribution packages. The :ref:`cpan <ref-classes-cpan>` class 658 installed by any distribution packages. The :ref:`ref-classes-cpan` class
651 already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes, 659 already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes,
652 but if a recipe is using ``MakeMaker`` directly then they might not be doing this 660 but if a recipe is using ``MakeMaker`` directly then they might not be doing this
653 correctly. This check ensures that perllocal.pod is not in any package in order to 661 correctly. This check ensures that perllocal.pod is not in any package in order to
@@ -661,8 +669,8 @@ Errors and Warnings
661 669
662 If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package 670 If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
663 installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this 671 installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
664 message, it indicates that the ``do_install`` step (or perhaps the build process that 672 message, it indicates that the :ref:`ref-tasks-install` step (or perhaps the build process that
665 ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead 673 :ref:`ref-tasks-install` is calling into, e.g. ``make install`` is using hardcoded paths instead
666 of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be 674 of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
667 changed so that it does. 675 changed so that it does.
668 676
@@ -671,11 +679,11 @@ Errors and Warnings
671 679
672- ``Fuzz detected: <patch output> [patch-fuzz]`` 680- ``Fuzz detected: <patch output> [patch-fuzz]``
673 681
674 This check looks for evidence of "fuzz" when applying patches within the ``do_patch`` 682 This check looks for evidence of "fuzz" when applying patches within the :ref:`ref-tasks-patch`
675 task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context 683 task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
676 lines in order to apply the patch. Consider this example: 684 lines in order to apply the patch. Consider this example:
677 685
678 Patch to be applied: :: 686 Patch to be applied::
679 687
680 --- filename 688 --- filename
681 +++ filename 689 +++ filename
@@ -687,7 +695,7 @@ Errors and Warnings
687 context line 5 695 context line 5
688 context line 6 696 context line 6
689 697
690 Original source code: :: 698 Original source code::
691 699
692 different context line 1 700 different context line 1
693 different context line 2 701 different context line 2
@@ -696,7 +704,7 @@ Errors and Warnings
696 different context line 5 704 different context line 5
697 different context line 6 705 different context line 6
698 706
699 Outcome (after applying patch with fuzz): :: 707 Outcome (after applying patch with fuzz)::
700 708
701 different context line 1 709 different context line 1
702 different context line 2 710 different context line 2
@@ -716,14 +724,14 @@ Errors and Warnings
716 *How to eliminate patch fuzz warnings* 724 *How to eliminate patch fuzz warnings*
717 725
718 Use the ``devtool`` command as explained by the warning. First, unpack the 726 Use the ``devtool`` command as explained by the warning. First, unpack the
719 source into devtool workspace: :: 727 source into devtool workspace::
720 728
721 devtool modify <recipe> 729 devtool modify <recipe>
722 730
723 This will apply all of the patches, and create new commits out of them in 731 This will apply all of the patches, and create new commits out of them in
724 the workspace - with the patch context updated. 732 the workspace --- with the patch context updated.
725 733
726 Then, replace the patches in the recipe layer: :: 734 Then, replace the patches in the recipe layer::
727 735
728 devtool finish --force-patch-refresh <recipe> <layer_path> 736 devtool finish --force-patch-refresh <recipe> <layer_path>
729 737
@@ -742,6 +750,56 @@ Errors and Warnings
742 other things in the patches, those can be discarded. 750 other things in the patches, those can be discarded.
743 751
744 752
753.. _qa-check-patch-status:
754
755- ``Missing Upstream-Status in patch <patchfile> Please add according to <url> [patch-status-core/patch-status-noncore]``
756
757 The ``Upstream-Status`` value is missing in the specified patch file's header.
758 This value is intended to track whether or not the patch has been sent
759 upstream, whether or not it has been merged, etc.
760
761 There are two options for this same check - ``patch-status-core`` (for
762 recipes in OE-Core) and ``patch-status-noncore`` (for recipes in any other
763 layer).
764
765 For more information, see the
766 ":ref:`contributor-guide/recipe-style-guide:patch upstream status`"
767 section in the Yocto Project and OpenEmbedded Contributor Guide.
768
769- ``Malformed Upstream-Status in patch <patchfile> Please correct according to <url> [patch-status-core/patch-status-noncore]``
770
771 The ``Upstream-Status`` value in the specified patch file's header is invalid -
772 it must be a specific format. See the "Missing Upstream-Status" entry above
773 for more information.
774
775
776.. _qa-check-buildpaths:
777
778- ``File <filename> in package <packagename> contains reference to TMPDIR [buildpaths]``
779
780 This check ensures that build system paths (including :term:`TMPDIR`) do not
781 appear in output files, which not only leaks build system configuration into
782 the target, but also hinders binary reproducibility as the output will change
783 if the build system configuration changes.
784
785 Typically these paths will enter the output through some mechanism in the
786 configuration or compilation of the software being built by the recipe. To
787 resolve this issue you will need to determine how the detected path is
788 entering the output. Sometimes it may require adjusting scripts or code to
789 use a relative path rather than an absolute one, or to pick up the path from
790 runtime configuration or environment variables.
791
792.. _qa-check-unimplemented-ptest:
793
794- ``<tool> tests detected [unimplemented-ptest]``
795
796 This check will detect if the source of the package contains some
797 upstream-provided tests and, if so, that ptests are implemented for this
798 recipe. See the ":ref:`dev-manual/packages:testing packages with ptest`"
799 section in the Yocto Project Development Tasks Manual. See also the
800 ":ref:`ref-classes-ptest`" section.
801
802
745 803
746Configuring and Disabling QA Checks 804Configuring and Disabling QA Checks
747=================================== 805===================================
@@ -752,10 +810,10 @@ either raise a warning or an error message, using the
752variables, respectively. You can also disable checks within a particular 810variables, respectively. You can also disable checks within a particular
753recipe using :term:`INSANE_SKIP`. For information on 811recipe using :term:`INSANE_SKIP`. For information on
754how to work with the QA checks, see the 812how to work with the QA checks, see the
755":ref:`insane.bbclass <ref-classes-insane>`" section. 813":ref:`ref-classes-insane`" section.
756 814
757.. note:: 815.. note::
758 816
759 Please keep in mind that the QA checks exist in order to detect real 817 Please keep in mind that the QA checks are meant to detect real
760 or potential problems in the packaged output. So exercise caution 818 or potential problems in the packaged output. So exercise caution
761 when disabling these checks. 819 when disabling these checks.
diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
index ed5a09a55d..920794679d 100644
--- a/documentation/ref-manual/release-process.rst
+++ b/documentation/ref-manual/release-process.rst
@@ -14,14 +14,13 @@ Major and Minor Release Cadence
14 14
15The Yocto Project delivers major releases (e.g. &DISTRO;) using a six 15The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
16month cadence roughly timed each April and October of the year. 16month cadence roughly timed each April and October of the year.
17Following are examples of some major YP releases with their codenames 17Here are examples of some major YP releases with their codenames
18also shown. See the "`Major Release 18also shown. See the ":ref:`ref-manual/release-process:major release codenames`"
19Codenames <#major-release-codenames>`__" section for information on 19section for information on codenames used with major releases.
20codenames used with major releases.
21 20
22 - 2.2 (Morty) 21 - 4.1 ("Langdale")
23 - 2.1 (Krogoth) 22 - 4.0 ("Kirkstone")
24 - 2.0 (Jethro) 23 - 3.4 ("Honister")
25 24
26While the cadence is never perfect, this timescale facilitates 25While the cadence is never perfect, this timescale facilitates
27regular releases that have strong QA cycles while not overwhelming users 26regular releases that have strong QA cycles while not overwhelming users
@@ -30,12 +29,12 @@ major holidays in various geographies.
30 29
31The Yocto project delivers minor (point) releases on an unscheduled 30The Yocto project delivers minor (point) releases on an unscheduled
32basis and are usually driven by the accumulation of enough significant 31basis and are usually driven by the accumulation of enough significant
33fixes or enhancements to the associated major release. Following are 32fixes or enhancements to the associated major release.
34some example past point releases: 33Some example past point releases are:
35 34
36 - 2.1.1 35 - 4.1.3
37 - 2.1.2 36 - 4.0.8
38 - 2.2.1 37 - 3.4.4
39 38
40The point release 39The point release
41indicates a point in the major release branch where a full QA cycle and 40indicates a point in the major release branch where a full QA cycle and
@@ -63,8 +62,10 @@ codename are likely to be compatible and thus work together.
63 62
64Releases are given a nominal release version as well but the codename is 63Releases are given a nominal release version as well but the codename is
65used in repositories for this reason. You can find information on Yocto 64used in repositories for this reason. You can find information on Yocto
66Project releases and codenames at 65Project releases and codenames at :yocto_wiki:`/Releases`.
67:yocto_wiki:`/Releases`. 66
67Our :doc:`/migration-guides/index` detail how to migrate from one release of
68the Yocto Project to the next.
68 69
69Stable Release Process 70Stable Release Process
70====================== 71======================
@@ -83,18 +84,54 @@ stable release.
83 bug fixes and security fixes only. Policy dictates that features are 84 bug fixes and security fixes only. Policy dictates that features are
84 not backported to a stable release. This policy means generic recipe 85 not backported to a stable release. This policy means generic recipe
85 version upgrades are unlikely to be accepted for backporting. The 86 version upgrades are unlikely to be accepted for backporting. The
86 exception to this policy occurs when a strong reason exists such as 87 exception to this policy occurs when there is a strong reason such as
87 the fix happens to also be the preferred upstream approach. 88 the fix happens to also be the preferred upstream approach.
88 89
89Stable release branches have strong maintenance for about a year after 90.. _ref-long-term-support-releases:
90their initial release. Should significant issues be found for any 91
91release regardless of its age, fixes could be backported to older 92Long Term Support Releases
92releases. For issues that are not backported given an older release, 93==========================
93Community LTS trees and branches exist where community members share 94
94patches for older releases. However, these types of patches do not go 95While stable releases are supported for a duration of seven months,
95through the same release process as do point releases. You can find more 96some specific ones are now supported for a longer period by the Yocto
96information about stable branch maintenance at 97Project, and are called Long Term Support (:term:`LTS`) releases.
97:yocto_wiki:`/Stable_branch_maintenance`. 98
99When significant issues are found, :term:`LTS` releases allow to publish
100fixes not only for the current stable release, but also to the
101:term:`LTS` releases that are still supported. Older stable releases which
102have reached their End of Life (EOL) won't receive such updates.
103
104This started with version 3.1 ("Dunfell"), released in April 2020, which
105the project initially committed to supporting for two years, but this duration
106was later extended to four years. Similarly, the following :term:`LTS` release,
107version 4.0 ("Kirkstone"), was released two years later in May 2022 and the
108project committed to supporting it for four years too.
109
110Therefore, a new :term:`LTS` release is made every two years and is supported
111for four years. This offers more stability to project users and leaves more
112time to upgrade to the following :term:`LTS` release.
113
114See :yocto_wiki:`/Stable_Release_and_LTS` for details about the management
115of stable and :term:`LTS` releases.
116
117.. image:: svg/releases.*
118 :width: 100%
119
120.. note::
121
122 In some circumstances, a layer can be created by the community in order to
123 add a specific feature or support a new version of some package for an :term:`LTS`
124 release. This is called a :term:`Mixin` layer. These are thin and specific
125 purpose layers which can be stacked with an :term:`LTS` release to "mix" a specific
126 feature into that build. These are created on an as-needed basis and
127 maintained by the people who need them.
128
129 Policies on testing these layers depend on how widespread their usage is and
130 determined on a case-by-case basis. You can find some :term:`Mixin` layers in the
131 :yocto_git:`meta-lts-mixins </meta-lts-mixins>` repository. While the Yocto
132 Project provides hosting for those repositories, it does not provides
133 testing on them. Other :term:`Mixin` layers may be released elsewhere by the wider
134 community.
98 135
99Testing and Quality Assurance 136Testing and Quality Assurance
100============================= 137=============================
@@ -106,7 +143,7 @@ Additionally, because the test strategies are visible to you as a
106developer, you can validate your projects. This section overviews the 143developer, you can validate your projects. This section overviews the
107available test infrastructure used in the Yocto Project. For information 144available test infrastructure used in the Yocto Project. For information
108on how to run available tests on your projects, see the 145on how to run available tests on your projects, see the
109":ref:`dev-manual/common-tasks:performing automated runtime testing`" 146":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
110section in the Yocto Project Development Tasks Manual. 147section in the Yocto Project Development Tasks Manual.
111 148
112The QA/testing infrastructure is woven into the project to the point 149The QA/testing infrastructure is woven into the project to the point
@@ -116,58 +153,49 @@ consists of the following pieces:
116- ``bitbake-selftest``: A standalone command that runs unit tests on 153- ``bitbake-selftest``: A standalone command that runs unit tests on
117 key pieces of BitBake and its fetchers. 154 key pieces of BitBake and its fetchers.
118 155
119- :ref:`sanity.bbclass <ref-classes-sanity>`: This automatically 156- :ref:`ref-classes-sanity`: This automatically
120 included class checks the build environment for missing tools (e.g. 157 included class checks the build environment for missing tools (e.g.
121 ``gcc``) or common misconfigurations such as 158 ``gcc``) or common misconfigurations such as
122 :term:`MACHINE` set incorrectly. 159 :term:`MACHINE` set incorrectly.
123 160
124- :ref:`insane.bbclass <ref-classes-insane>`: This class checks the 161- :ref:`ref-classes-insane`: This class checks the
125 generated output from builds for sanity. For example, if building for 162 generated output from builds for sanity. For example, if building for
126 an ARM target, did the build produce ARM binaries. If, for example, 163 an ARM target, did the build produce ARM binaries. If, for example,
127 the build produced PPC binaries then there is a problem. 164 the build produced PPC binaries then there is a problem.
128 165
129- :ref:`testimage.bbclass <ref-classes-testimage*>`: This class 166- :ref:`ref-classes-testimage`: This class
130 performs runtime testing of images after they are built. The tests 167 performs runtime testing of images after they are built. The tests
131 are usually used with :doc:`QEMU </dev-manual/qemu>` 168 are usually used with :doc:`QEMU </dev-manual/qemu>`
132 to boot the images and check the combined runtime result boot 169 to boot the images and check the combined runtime result boot
133 operation and functions. However, the test can also use the IP 170 operation and functions. However, the test can also use the IP
134 address of a machine to test. 171 address of a machine to test.
135 172
136- :ref:`ptest <dev-manual/common-tasks:testing packages with ptest>`: 173- :ref:`ptest <dev-manual/packages:testing packages with ptest>`:
137 Runs tests against packages produced during the build for a given 174 Runs tests against packages produced during the build for a given
138 piece of software. The test allows the packages to be be run within a 175 piece of software. The test allows the packages to be run within a
139 target image. 176 target image.
140 177
141- ``oe-selftest``: Tests combination BitBake invocations. These tests 178- ``oe-selftest``: Tests combinations of BitBake invocations. These tests
142 operate outside the OpenEmbedded build system itself. The 179 operate outside the OpenEmbedded build system itself. The
143 ``oe-selftest`` can run all tests by default or can run selected 180 ``oe-selftest`` can run all tests by default or can run selected
144 tests or test suites. 181 tests or test suites.
145 182
146 .. note::
147
148 Running ``oe-selftest`` requires host packages beyond the "Essential"
149 grouping. See the :ref:`ref-manual/system-requirements:required packages for the build host`
150 section for more information.
151
152Originally, much of this testing was done manually. However, significant 183Originally, much of this testing was done manually. However, significant
153effort has been made to automate the tests so that more people can use 184effort has been made to automate the tests so that more people can use
154them and the Yocto Project development team can run them faster and more 185them and the Yocto Project development team can run them faster and more
155efficiently. 186efficiently.
156 187
157The Yocto Project's main Autobuilder (&YOCTO_AB_URL;) 188The Yocto Project's main Autobuilder (&YOCTO_AB_URL;) publicly tests each Yocto
158publicly tests each Yocto Project release's code in the 189Project release's code in the :oe_git:`openembedded-core </openembedded-core>`,
159:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing 190:yocto_git:`poky </poky>` and :oe_git:`bitbake </bitbake>` repositories. The
160occurs for both the current state of the "master" branch and also for 191testing occurs for both the current state of the "master" branch and also for
161submitted patches. Testing for submitted patches usually occurs in the 192submitted patches. Testing for submitted patches usually occurs in the
162"ross/mut" branch in the ``poky-contrib`` repository (i.e. the 193in the "master-next" branch in the :yocto_git:`poky </poky>` repository.
163master-under-test branch) or in the "master-next" branch in the ``poky``
164repository.
165 194
166.. note:: 195.. note::
167 196
168 You can find all these branches in the Yocto Project 197 You can find all these branches in the
169 Source Repositories 198 :ref:`overview-manual/development-environment:yocto project source repositories`.
170 .
171 199
172Testing within these public branches ensures in a publicly visible way 200Testing within these public branches ensures in a publicly visible way
173that all of the main supposed architectures and recipes in OE-Core 201that all of the main supposed architectures and recipes in OE-Core
diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst
index 7554164d11..8e54ac87c9 100644
--- a/documentation/ref-manual/resources.rst
+++ b/documentation/ref-manual/resources.rst
@@ -10,7 +10,7 @@ Introduction
10============ 10============
11 11
12The Yocto Project team is happy for people to experiment with the Yocto 12The Yocto Project team is happy for people to experiment with the Yocto
13Project. A number of places exist to find help if you run into 13Project. There is a number of places where you can find help if you run into
14difficulties or find bugs. This presents information about contributing 14difficulties or find bugs. This presents information about contributing
15and participating in the Yocto Project. 15and participating in the Yocto Project.
16 16
@@ -23,8 +23,7 @@ The Yocto Project gladly accepts contributions. You can submit changes
23to the project either by creating and sending pull requests, or by 23to the project either by creating and sending pull requests, or by
24submitting patches through email. For information on how to do both as 24submitting patches through email. For information on how to do both as
25well as information on how to identify the maintainer for each area of 25well as information on how to identify the maintainer for each area of
26code, see the ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" section in the 26code, see the :doc:`../contributor-guide/index`.
27Yocto Project Development Tasks Manual.
28 27
29.. _resources-bugtracker: 28.. _resources-bugtracker:
30 29
@@ -43,12 +42,11 @@ the Yocto Project itself (e.g. when discovering an issue with some
43component of the build system that acts contrary to the documentation or 42component of the build system that acts contrary to the documentation or
44your expectations). 43your expectations).
45 44
46A general procedure and guidelines exist for when you use Bugzilla to 45For a general procedure and guidelines on how to use Bugzilla to submit a bug
47submit a bug. For information on how to use Bugzilla to submit a bug
48against the Yocto Project, see the following: 46against the Yocto Project, see the following:
49 47
50- The ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`" 48- The ":doc:`../contributor-guide/report-defect`"
51 section in the Yocto Project Development Tasks Manual. 49 section in the Yocto Project and OpenEmbedded Contributor Guide.
52 50
53- The Yocto Project :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>` 51- The Yocto Project :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
54 52
@@ -59,44 +57,46 @@ For information on Bugzilla in general, see https://www.bugzilla.org/about/.
59Mailing lists 57Mailing lists
60============= 58=============
61 59
62A number of mailing lists maintained by the Yocto Project exist as well 60There are multiple mailing lists maintained by the Yocto Project as well
63as related OpenEmbedded mailing lists for discussion, patch submission 61as related OpenEmbedded mailing lists for discussion, patch submission
64and announcements. To subscribe to one of the following mailing lists, 62and announcements. To subscribe to one of the following mailing lists,
65click on the appropriate URL in the following list and follow the 63click on the appropriate URL in the following list and follow the
66instructions: 64instructions:
67 65
68- :yocto_lists:`/g/yocto` - General Yocto Project 66- :yocto_lists:`/g/yocto` --- general Yocto Project
69 discussion mailing list. 67 discussion mailing list.
70 68
71- :oe_lists:`/g/openembedded-core` - Discussion mailing 69- :oe_lists:`/g/openembedded-core` --- discussion mailing
72 list about OpenEmbedded-Core (the core metadata). 70 list about OpenEmbedded-Core (the core metadata).
73 71
74- :oe_lists:`/g/openembedded-devel` - Discussion 72- :oe_lists:`/g/openembedded-devel` --- discussion
75 mailing list about OpenEmbedded. 73 mailing list about OpenEmbedded.
76 74
77- :oe_lists:`/g/bitbake-devel` - Discussion mailing 75- :oe_lists:`/g/bitbake-devel` --- discussion mailing
78 list about the :term:`BitBake` build tool. 76 list about the :term:`BitBake` build tool.
79 77
80- :yocto_lists:`/g/poky` - Discussion mailing list 78- :yocto_lists:`/g/poky` --- discussion mailing list
81 about :term:`Poky`. 79 about :term:`Poky`.
82 80
83- :yocto_lists:`/g/yocto-announce` - Mailing list to 81- :yocto_lists:`/g/yocto-announce` --- mailing list to
84 receive official Yocto Project release and milestone announcements. 82 receive official Yocto Project release and milestone announcements.
85 83
86For more Yocto Project-related mailing lists, see the 84- :yocto_lists:`/g/docs` --- discussion mailing list about the Yocto Project
87:yocto_home:`Yocto Project Website <>`. 85 documentation.
86
87See also :yocto_home:`the description of all mailing lists </community/mailing-lists/>`.
88 88
89.. _resources-irc: 89.. _resources-irc:
90 90
91Internet Relay Chat (IRC) 91Internet Relay Chat (IRC)
92========================= 92=========================
93 93
94Two IRC channels on freenode are available for the Yocto Project and 94Two IRC channels on `Libera Chat <https://libera.chat/>`__
95Poky discussions: 95are available for the Yocto Project and OpenEmbedded discussions:
96 96
97- ``#yocto`` 97- ``#yocto``
98 98
99- ``#poky`` 99- ``#oe``
100 100
101.. _resources-links-and-related-documentation: 101.. _resources-links-and-related-documentation:
102 102
@@ -105,93 +105,96 @@ Links and Related Documentation
105 105
106Here is a list of resources you might find helpful: 106Here is a list of resources you might find helpful:
107 107
108- :yocto_home:`The Yocto Project Website <>`\ *:* The home site 108- :yocto_home:`The Yocto Project Website <>`: The home site
109 for the Yocto Project. 109 for the Yocto Project.
110 110
111- :yocto_wiki:`The Yocto Project Main Wiki Page <>`\ *:* The main wiki page for 111- :yocto_wiki:`The Yocto Project Main Wiki Page <>`: The main wiki page for
112 the Yocto Project. This page contains information about project 112 the Yocto Project. This page contains information about project
113 planning, release engineering, QA & automation, a reference site map, 113 planning, release engineering, QA & automation, a reference site map,
114 and other resources related to the Yocto Project. 114 and other resources related to the Yocto Project.
115 115
116- :oe_home:`OpenEmbedded <>`\ *:* The build system used by the 116- :oe_home:`OpenEmbedded <>`: The build system used by the
117 Yocto Project. This project is the upstream, generic, embedded 117 Yocto Project. This project is the upstream, generic, embedded
118 distribution from which the Yocto Project derives its build system 118 distribution from which the Yocto Project derives its build system
119 (Poky) and to which it contributes. 119 (Poky) and to which it contributes.
120 120
121- :oe_wiki:`BitBake </BitBake>`\ *:* The tool used to process metadata. 121- :oe_wiki:`BitBake </BitBake>`: The tool used to process metadata.
122 122
123- :doc:`BitBake User Manual <bitbake:index>`\ *:* A comprehensive 123- :doc:`BitBake User Manual <bitbake:index>`: A comprehensive
124 guide to the BitBake tool. If you want information on BitBake, see 124 guide to the BitBake tool. If you want information on BitBake, see
125 this manual. 125 this manual.
126 126
127- :doc:`/brief-yoctoprojectqs/index` *:* This 127- :doc:`/brief-yoctoprojectqs/index`: This
128 short document lets you experience building an image using the Yocto 128 short document lets you experience building an image using the Yocto
129 Project without having to understand any concepts or details. 129 Project without having to understand any concepts or details.
130 130
131- :doc:`/overview-manual/index` *:* This manual provides overview 131- :doc:`/overview-manual/index`: This manual provides overview
132 and conceptual information about the Yocto Project. 132 and conceptual information about the Yocto Project.
133 133
134- :doc:`/dev-manual/index` *:* This manual is a "how-to" guide 134- :doc:`/dev-manual/index`: This manual is a "how-to" guide
135 that presents procedures useful to both application and system 135 that presents procedures useful to both application and system
136 developers who use the Yocto Project. 136 developers who use the Yocto Project.
137 137
138- :doc:`/sdk-manual/index` *manual :* This 138- :doc:`/sdk-manual/index` manual: This
139 guide provides information that lets you get going with the standard 139 guide provides information that lets you get going with the standard
140 or extensible SDK. An SDK, with its cross-development toolchains, 140 or extensible SDK. An SDK, with its cross-development toolchains,
141 allows you to develop projects inside or outside of the Yocto Project 141 allows you to develop projects inside or outside of the Yocto Project
142 environment. 142 environment.
143 143
144- :doc:`/bsp-guide/bsp` *:* This guide defines the structure 144- :doc:`/bsp-guide/bsp`: This guide defines the structure
145 for BSP components. Having a commonly understood structure encourages 145 for BSP components. Having a commonly understood structure encourages
146 standardization. 146 standardization.
147 147
148- :doc:`/kernel-dev/index` *:* This manual describes 148- :doc:`/kernel-dev/index`: This manual describes
149 how to work with Linux Yocto kernels as well as provides a bit of 149 how to work with Linux Yocto kernels as well as provides a bit of
150 conceptual information on the construction of the Yocto Linux kernel 150 conceptual information on the construction of the Yocto Linux kernel
151 tree. 151 tree.
152 152
153- :doc:`/ref-manual/index` *:* This 153- :doc:`/ref-manual/index`: This
154 manual provides reference material such as variable, task, and class 154 manual provides reference material such as variable, task, and class
155 descriptions. 155 descriptions.
156 156
157- :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual 157- :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`: This manual
158 is simply a single HTML file comprised of the bulk of the Yocto 158 is simply a single HTML file comprised of the bulk of the Yocto
159 Project manuals. The Mega-Manual primarily exists as a vehicle by 159 Project manuals. It makes it easy to search for phrases and terms used
160 which you can easily search for phrases and terms used in the Yocto 160 in the Yocto Project documentation set.
161 Project documentation set.
162 161
163- :doc:`/profile-manual/index` *:* This manual presents a set of 162- :doc:`/profile-manual/index`: This manual presents a set of
164 common and generally useful tracing and profiling schemes along with 163 common and generally useful tracing and profiling schemes along with
165 their applications (as appropriate) to each tool. 164 their applications (as appropriate) to each tool.
166 165
167- :doc:`/toaster-manual/index` *:* This manual 166- :doc:`/toaster-manual/index`: This manual
168 introduces and describes how to set up and use Toaster. Toaster is an 167 introduces and describes how to set up and use Toaster. Toaster is an
169 Application Programming Interface (API) and web-based interface to 168 Application Programming Interface (API) and web-based interface to
170 the :term:`OpenEmbedded Build System`, which uses 169 the :term:`OpenEmbedded Build System`, which uses
171 BitBake, that reports build information. 170 BitBake, that reports build information.
172 171
173- :yocto_wiki:`FAQ </FAQ>`\ *:* A list of commonly asked 172- `Yocto Project BitBake extension for VSCode
173 <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__:
174 This extension provides a rich feature set when working with BitBake recipes
175 within the Visual Studio Code IDE.
176
177- :yocto_wiki:`FAQ </FAQ>`: A list of commonly asked
174 questions and their answers. 178 questions and their answers.
175 179
176- *Release Notes:* Features, updates and known issues for the current 180- :doc:`Release Information </migration-guides/index>`:
177 release of the Yocto Project. To access the Release Notes, go to the 181 Migration guides, release notes, new features, updates and known issues
178 :yocto_home:`Downloads </software-overview/downloads>` page on 182 for the current and past releases of the Yocto Project.
179 the Yocto Project website and click on the "RELEASE INFORMATION" link
180 for the appropriate release.
181 183
182- :yocto_bugs:`Bugzilla <>`\ *:* The bug tracking application 184- :yocto_bugs:`Bugzilla <>`: The bug tracking application
183 the Yocto Project uses. If you find problems with the Yocto Project, 185 the Yocto Project uses. If you find problems with the Yocto Project,
184 you should report them using this application. 186 you should report them using this application.
185 187
186- :yocto_wiki:`Bugzilla Configuration and Bug Tracking Wiki Page 188- :yocto_wiki:`Bugzilla Configuration and Bug Tracking Wiki Page
187 </Bugzilla_Configuration_and_Bug_Tracking>`\ *:* 189 </Bugzilla_Configuration_and_Bug_Tracking>`:
188 Information on how to get set up and use the Yocto Project 190 Information on how to get set up and use the Yocto Project
189 implementation of Bugzilla for logging and tracking Yocto Project 191 implementation of Bugzilla for logging and tracking Yocto Project
190 defects. 192 defects.
191 193
192- *Internet Relay Chat (IRC):* Two IRC channels on freenode are 194- Internet Relay Chat (IRC): Two IRC channels on
193 available for Yocto Project and Poky discussions: ``#yocto`` and 195 `Libera Chat <https://libera.chat/>`__ are
194 ``#poky``, respectively. 196 available for Yocto Project and OpenEmbeddded discussions: ``#yocto`` and
197 ``#oe``, respectively.
195 198
196- `Quick EMUlator (QEMU) <https://wiki.qemu.org/Index.html>`__\ *:* An 199- `Quick EMUlator (QEMU) <https://wiki.qemu.org/Index.html>`__: An
197 open-source machine emulator and virtualizer. 200 open-source machine emulator and virtualizer.
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index ad3f4ab44a..e4d8b54bb9 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -38,7 +38,7 @@ usually matches the current stable BitBake release from the BitBake
38project. BitBake, a :term:`Metadata` interpreter, reads the 38project. BitBake, a :term:`Metadata` interpreter, reads the
39Yocto Project Metadata and runs the tasks defined by that data. Failures 39Yocto Project Metadata and runs the tasks defined by that data. Failures
40are usually caused by errors in your Metadata and not from BitBake 40are usually caused by errors in your Metadata and not from BitBake
41itself; consequently, most users do not need to worry about BitBake. 41itself.
42 42
43When you run the ``bitbake`` command, the main BitBake executable (which 43When you run the ``bitbake`` command, the main BitBake executable (which
44resides in the ``bitbake/bin/`` directory) starts. Sourcing the 44resides in the ``bitbake/bin/`` directory) starts. Sourcing the
@@ -57,9 +57,8 @@ For more information on BitBake, see the :doc:`BitBake User Manual
57This directory contains user configuration files and the output 57This directory contains user configuration files and the output
58generated by the OpenEmbedded build system in its standard configuration 58generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory` 59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source`` 60is created initially when you ``source`` the OpenEmbedded build environment
61the OpenEmbedded build environment setup script (i.e. 61setup script (i.e. :ref:`structure-core-script`).
62:ref:`structure-core-script`).
63 62
64It is also possible to place output and configuration files in a 63It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by 64directory separate from the :term:`Source Directory` by
@@ -68,6 +67,9 @@ information on separating output from your local Source Directory files
68(commonly described as an "out of tree" build), see the 67(commonly described as an "out of tree" build), see the
69":ref:`structure-core-script`" section. 68":ref:`structure-core-script`" section.
70 69
70See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details
71about the contents of the :term:`Build Directory`.
72
71.. _handbook: 73.. _handbook:
72 74
73``documentation/`` 75``documentation/``
@@ -150,11 +152,10 @@ BitBake commands. The script uses other scripts within the ``scripts``
150directory to do the bulk of the work. 152directory to do the bulk of the work.
151 153
152When you run this script, your Yocto Project environment is set up, a 154When you run this script, your Yocto Project environment is set up, a
153:term:`Build Directory` is created, your working 155:term:`Build Directory` is created, your working directory becomes the
154directory becomes the Build Directory, and you are presented with some 156:term:`Build Directory`, and you are presented with some simple
155simple suggestions as to what to do next, including a list of some 157suggestions as to what to do next, including a list of some possible
156possible targets to build. Here is an example: 158targets to build. Here is an example::
157::
158 159
159 $ source oe-init-build-env 160 $ source oe-init-build-env
160 161
@@ -168,32 +169,33 @@ possible targets to build. Here is an example:
168 meta-toolchain 169 meta-toolchain
169 meta-ide-support 170 meta-ide-support
170 171
171 You can also run generated qemu images with a command like 'runqemu qemux86-64' 172 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
172 173
173The default output of the ``oe-init-build-env`` script is from the 174The default output of the ``oe-init-build-env`` script is from the
174``conf-notes.txt`` file, which is found in the ``meta-poky`` directory 175``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the ``meta-poky`` directory
175within the :term:`Source Directory`. If you design a 176within the :term:`Source Directory`. If you design a
176custom distribution, you can include your own version of this 177custom distribution, you can include your own versions of these
177configuration file to mention the targets defined by your distribution. 178configuration files where you can provide a brief summary and detailed usage
179notes, such as a list of the targets defined by your distribution.
178See the 180See the
179":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" 181":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
180section in the Yocto Project Development Tasks Manual for more 182section in the Yocto Project Development Tasks Manual for more
181information. 183information.
182 184
183By default, running this script without a Build Directory argument 185By default, running this script without a :term:`Build Directory` argument
184creates the ``build/`` directory in your current working directory. If 186creates the ``build/`` directory in your current working directory. If
185you provide a Build Directory argument when you ``source`` the script, 187you provide a :term:`Build Directory` argument when you ``source`` the script,
186you direct the OpenEmbedded build system to create a Build Directory of 188you direct the OpenEmbedded build system to create a :term:`Build Directory` of
187your choice. For example, the following command creates a Build 189your choice. For example, the following command creates a
188Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: 190:term:`Build Directory` named ``mybuilds/`` that is outside of the
189:: 191:term:`Source Directory`::
190 192
191 $ source oe-init-build-env ~/mybuilds 193 $ source oe-init-build-env ~/mybuilds
192 194
193The OpenEmbedded build system uses the template configuration files, which 195The OpenEmbedded build system uses the template configuration files, which
194are found by default in the ``meta-poky/conf/`` directory in the Source 196are found by default in the ``meta-poky/conf/templates/default`` directory in the Source
195Directory. See the 197Directory. See the
196":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" 198":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
197section in the Yocto Project Development Tasks Manual for more 199section in the Yocto Project Development Tasks Manual for more
198information. 200information.
199 201
@@ -215,14 +217,13 @@ These files are standard top-level files.
215 217
216.. _structure-build: 218.. _structure-build:
217 219
218The Build Directory - ``build/`` 220The Build Directory --- ``build/``
219================================ 221==================================
220 222
221The OpenEmbedded build system creates the :term:`Build Directory` 223The OpenEmbedded build system creates the :term:`Build Directory` when you run
222when you run the build environment setup 224the build environment setup script :ref:`structure-core-script`. If you do not
223script :ref:`structure-core-script`. If you do not give the Build 225give the :term:`Build Directory` a specific name when you run the setup script,
224Directory a specific name when you run the setup script, the name 226the name defaults to ``build/``.
225defaults to ``build/``.
226 227
227For subsequent parsing and processing, the name of the Build directory 228For subsequent parsing and processing, the name of the Build directory
228is available via the :term:`TOPDIR` variable. 229is available via the :term:`TOPDIR` variable.
@@ -233,12 +234,24 @@ is available via the :term:`TOPDIR` variable.
233----------------------- 234-----------------------
234 235
235The OpenEmbedded build system creates this directory when you enable 236The OpenEmbedded build system creates this directory when you enable
236build history via the ``buildhistory`` class file. The directory 237build history via the :ref:`ref-classes-buildhistory` class file. The directory
237organizes build information into image, packages, and SDK 238organizes build information into image, packages, and SDK
238subdirectories. For information on the build history feature, see the 239subdirectories. For information on the build history feature, see the
239":ref:`dev-manual/common-tasks:maintaining build output quality`" 240":ref:`dev-manual/build-quality:maintaining build output quality`"
240section in the Yocto Project Development Tasks Manual. 241section in the Yocto Project Development Tasks Manual.
241 242
243.. _structure-build-cache:
244
245``build/cache/``
246----------------
247
248This directory contains several internal files used by the OpenEmbedded
249build system.
250
251It also contains ``sanity_info``, a text file keeping track of important
252build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`,
253as well as the name and version of the host distribution.
254
242.. _structure-build-conf-local.conf: 255.. _structure-build-conf-local.conf:
243 256
244``build/conf/local.conf`` 257``build/conf/local.conf``
@@ -253,9 +266,9 @@ variables are hard-coded for various reasons but such variables are
253relatively rare. 266relatively rare.
254 267
255At a minimum, you would normally edit this file to select the target 268At a minimum, you would normally edit this file to select the target
256``MACHINE``, which package types you wish to use 269:term:`MACHINE`, which package types you wish to use
257(:term:`PACKAGE_CLASSES`), and the location from 270(:term:`PACKAGE_CLASSES`), and the location from
258which you want to access downloaded files (``DL_DIR``). 271which you want to access downloaded files (:term:`DL_DIR`).
259 272
260If ``local.conf`` is not present when you start the build, the 273If ``local.conf`` is not present when you start the build, the
261OpenEmbedded build system creates it from ``local.conf.sample`` when you 274OpenEmbedded build system creates it from ``local.conf.sample`` when you
@@ -263,16 +276,15 @@ OpenEmbedded build system creates it from ``local.conf.sample`` when you
263:ref:`structure-core-script`. 276:ref:`structure-core-script`.
264 277
265The source ``local.conf.sample`` file used depends on the 278The source ``local.conf.sample`` file used depends on the
266``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` 279:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default``
267when you are building from the Yocto Project development environment, 280when you are building from the Yocto Project development environment,
268and to ``meta/conf/`` when you are building from the OpenEmbedded-Core 281and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core
269environment. Because the script variable points to the source of the 282environment. Because the script variable points to the source of the
270``local.conf.sample`` file, this implies that you can configure your 283``local.conf.sample`` file, this implies that you can configure your
271build environment from any layer by setting the variable in the 284build environment from any layer by setting the variable in the
272top-level build environment setup script as follows: 285top-level build environment setup script as follows::
273::
274 286
275 TEMPLATECONF=your_layer/conf 287 TEMPLATECONF=your_layer/conf/templates/your_template_name
276 288
277Once the build process gets the sample 289Once the build process gets the sample
278file, it uses ``sed`` to substitute final 290file, it uses ``sed`` to substitute final
@@ -281,10 +293,10 @@ file, it uses ``sed`` to substitute final
281 293
282.. note:: 294.. note::
283 295
284 You can see how the ``TEMPLATECONF`` variable is used by looking at the 296 You can see how the :term:`TEMPLATECONF` variable is used by looking at the
285 ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`. 297 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
286 You can find the Yocto Project version of the ``local.conf.sample`` file in 298 You can find the Yocto Project version of the ``local.conf.sample`` file in
287 the ``meta-poky/conf`` directory. 299 the ``meta-poky/conf/templates/default`` directory.
288 300
289.. _structure-build-conf-bblayers.conf: 301.. _structure-build-conf-bblayers.conf:
290 302
@@ -292,7 +304,7 @@ file, it uses ``sed`` to substitute final
292---------------------------- 304----------------------------
293 305
294This configuration file defines 306This configuration file defines
295:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`, 307:ref:`layers <dev-manual/layers:understanding and creating layers>`,
296which are directory trees, traversed (or walked) by BitBake. The 308which are directory trees, traversed (or walked) by BitBake. The
297``bblayers.conf`` file uses the :term:`BBLAYERS` 309``bblayers.conf`` file uses the :term:`BBLAYERS`
298variable to list the layers BitBake tries to find. 310variable to list the layers BitBake tries to find.
@@ -303,35 +315,26 @@ you ``source`` the top-level build environment setup script (i.e.
303:ref:`structure-core-script`). 315:ref:`structure-core-script`).
304 316
305As with the ``local.conf`` file, the source ``bblayers.conf.sample`` 317As with the ``local.conf`` file, the source ``bblayers.conf.sample``
306file used depends on the ``$TEMPLATECONF`` script variable, which 318file used depends on the :term:`TEMPLATECONF` script variable, which
307defaults to ``meta-poky/conf/`` when you are building from the Yocto 319defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto
308Project development environment, and to ``meta/conf/`` when you are 320Project development environment, and to ``meta/conf/templates/default`` when you are
309building from the OpenEmbedded-Core environment. Because the script 321building from the OpenEmbedded-Core environment. Because the script
310variable points to the source of the ``bblayers.conf.sample`` file, this 322variable points to the source of the ``bblayers.conf.sample`` file, this
311implies that you can base your build from any layer by setting the 323implies that you can base your build from any layer by setting the
312variable in the top-level build environment setup script as follows: 324variable in the top-level build environment setup script as follows::
313::
314 325
315 TEMPLATECONF=your_layer/conf 326 TEMPLATECONF=your_layer/conf/templates/your_template_name
316 327
317Once the build process gets the sample file, it uses ``sed`` to substitute final 328Once the build process gets the sample file, it uses ``sed`` to substitute final
318``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. 329``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
319 330
320.. note:: 331.. note::
321 332
322 You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir`` 333 You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir``
323 script in the :term:`Source Directory`. You can find the Yocto Project 334 script in the :term:`Source Directory`. You can find the Yocto Project
324 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/`` 335 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
325 directory. 336 directory.
326 337
327.. _structure-build-conf-sanity_info:
328
329``build/cache/sanity_info``
330---------------------------
331
332This file indicates the state of the sanity checks and is created during
333the build.
334
335.. _structure-build-downloads: 338.. _structure-build-downloads:
336 339
337``build/downloads/`` 340``build/downloads/``
@@ -340,7 +343,7 @@ the build.
340This directory contains downloaded upstream source tarballs. You can 343This directory contains downloaded upstream source tarballs. You can
341reuse the directory for multiple builds or move the directory to another 344reuse the directory for multiple builds or move the directory to another
342location. You can control the location of this directory through the 345location. You can control the location of this directory through the
343``DL_DIR`` variable. 346:term:`DL_DIR` variable.
344 347
345.. _structure-build-sstate-cache: 348.. _structure-build-sstate-cache:
346 349
@@ -350,7 +353,7 @@ location. You can control the location of this directory through the
350This directory contains the shared state cache. You can reuse the 353This directory contains the shared state cache. You can reuse the
351directory for multiple builds or move the directory to another location. 354directory for multiple builds or move the directory to another location.
352You can control the location of this directory through the 355You can control the location of this directory through the
353``SSTATE_DIR`` variable. 356:term:`SSTATE_DIR` variable.
354 357
355.. _structure-build-tmp: 358.. _structure-build-tmp:
356 359
@@ -370,14 +373,15 @@ remove the ``build/sstate-cache`` directory.
370.. _structure-build-tmp-buildstats: 373.. _structure-build-tmp-buildstats:
371 374
372``build/tmp/buildstats/`` 375``build/tmp/buildstats/``
373------------------------- 376~~~~~~~~~~~~~~~~~~~~~~~~~
374 377
375This directory stores the build statistics. 378This directory stores the build statistics as generated by the
379:ref:`ref-classes-buildstats` class.
376 380
377.. _structure-build-tmp-cache: 381.. _structure-build-tmp-cache:
378 382
379``build/tmp/cache/`` 383``build/tmp/cache/``
380-------------------- 384~~~~~~~~~~~~~~~~~~~~
381 385
382When BitBake parses the metadata (recipes and configuration files), it 386When BitBake parses the metadata (recipes and configuration files), it
383caches the results in ``build/tmp/cache/`` to speed up future builds. 387caches the results in ``build/tmp/cache/`` to speed up future builds.
@@ -393,7 +397,7 @@ cache is reused. If the file has changed, it is reparsed.
393.. _structure-build-tmp-deploy: 397.. _structure-build-tmp-deploy:
394 398
395``build/tmp/deploy/`` 399``build/tmp/deploy/``
396--------------------- 400~~~~~~~~~~~~~~~~~~~~~
397 401
398This directory contains any "end result" output from the OpenEmbedded 402This directory contains any "end result" output from the OpenEmbedded
399build process. The :term:`DEPLOY_DIR` variable points 403build process. The :term:`DEPLOY_DIR` variable points
@@ -406,7 +410,7 @@ Project Overview and Concepts Manual.
406.. _structure-build-tmp-deploy-deb: 410.. _structure-build-tmp-deploy-deb:
407 411
408``build/tmp/deploy/deb/`` 412``build/tmp/deploy/deb/``
409------------------------- 413^^^^^^^^^^^^^^^^^^^^^^^^^
410 414
411This directory receives any ``.deb`` packages produced by the build 415This directory receives any ``.deb`` packages produced by the build
412process. The packages are sorted into feeds for different architecture 416process. The packages are sorted into feeds for different architecture
@@ -415,7 +419,7 @@ types.
415.. _structure-build-tmp-deploy-rpm: 419.. _structure-build-tmp-deploy-rpm:
416 420
417``build/tmp/deploy/rpm/`` 421``build/tmp/deploy/rpm/``
418------------------------- 422^^^^^^^^^^^^^^^^^^^^^^^^^
419 423
420This directory receives any ``.rpm`` packages produced by the build 424This directory receives any ``.rpm`` packages produced by the build
421process. The packages are sorted into feeds for different architecture 425process. The packages are sorted into feeds for different architecture
@@ -424,27 +428,27 @@ types.
424.. _structure-build-tmp-deploy-ipk: 428.. _structure-build-tmp-deploy-ipk:
425 429
426``build/tmp/deploy/ipk/`` 430``build/tmp/deploy/ipk/``
427------------------------- 431^^^^^^^^^^^^^^^^^^^^^^^^^
428 432
429This directory receives ``.ipk`` packages produced by the build process. 433This directory receives ``.ipk`` packages produced by the build process.
430 434
431.. _structure-build-tmp-deploy-licenses: 435.. _structure-build-tmp-deploy-licenses:
432 436
433``build/tmp/deploy/licenses/`` 437``build/tmp/deploy/licenses/``
434------------------------------ 438^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
435 439
436This directory receives package licensing information. For example, the 440This directory receives package licensing information. For example, the
437directory contains sub-directories for ``bash``, ``busybox``, and 441directory contains sub-directories for ``bash``, ``busybox``, and
438``glibc`` (among others) that in turn contain appropriate ``COPYING`` 442``glibc`` (among others) that in turn contain appropriate ``COPYING``
439license files with other licensing information. For information on 443license files with other licensing information. For information on
440licensing, see the 444licensing, see the
441":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" 445":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`"
442section in the Yocto Project Development Tasks Manual. 446section in the Yocto Project Development Tasks Manual.
443 447
444.. _structure-build-tmp-deploy-images: 448.. _structure-build-tmp-deploy-images:
445 449
446``build/tmp/deploy/images/`` 450``build/tmp/deploy/images/``
447---------------------------- 451^^^^^^^^^^^^^^^^^^^^^^^^^^^^
448 452
449This directory is populated with the basic output objects of the build 453This directory is populated with the basic output objects of the build
450(think of them as the "generated artifacts" of the build process), 454(think of them as the "generated artifacts" of the build process),
@@ -463,8 +467,7 @@ image again.
463If you do accidentally delete files here, you will need to force them to 467If you do accidentally delete files here, you will need to force them to
464be re-created. In order to do that, you will need to know the target 468be re-created. In order to do that, you will need to know the target
465that produced them. For example, these commands rebuild and re-create 469that produced them. For example, these commands rebuild and re-create
466the kernel files: 470the kernel files::
467::
468 471
469 $ bitbake -c clean virtual/kernel 472 $ bitbake -c clean virtual/kernel
470 $ bitbake virtual/kernel 473 $ bitbake virtual/kernel
@@ -472,7 +475,7 @@ the kernel files:
472.. _structure-build-tmp-deploy-sdk: 475.. _structure-build-tmp-deploy-sdk:
473 476
474``build/tmp/deploy/sdk/`` 477``build/tmp/deploy/sdk/``
475------------------------- 478^^^^^^^^^^^^^^^^^^^^^^^^^
476 479
477The OpenEmbedded build system creates this directory to hold toolchain 480The OpenEmbedded build system creates this directory to hold toolchain
478installer scripts which, when executed, install the sysroot that matches 481installer scripts which, when executed, install the sysroot that matches
@@ -484,7 +487,7 @@ Software Development Kit (eSDK) manual.
484.. _structure-build-tmp-sstate-control: 487.. _structure-build-tmp-sstate-control:
485 488
486``build/tmp/sstate-control/`` 489``build/tmp/sstate-control/``
487----------------------------- 490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
488 491
489The OpenEmbedded build system uses this directory for the shared state 492The OpenEmbedded build system uses this directory for the shared state
490manifest files. The shared state code uses these files to record the 493manifest files. The shared state code uses these files to record the
@@ -497,7 +500,7 @@ another.
497.. _structure-build-tmp-sysroots-components: 500.. _structure-build-tmp-sysroots-components:
498 501
499``build/tmp/sysroots-components/`` 502``build/tmp/sysroots-components/``
500---------------------------------- 503~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
501 504
502This directory is the location of the sysroot contents that the task 505This directory is the location of the sysroot contents that the task
503:ref:`ref-tasks-prepare_recipe_sysroot` 506:ref:`ref-tasks-prepare_recipe_sysroot`
@@ -512,11 +515,11 @@ should be automatic, and recipes should not directly reference
512.. _structure-build-tmp-sysroots: 515.. _structure-build-tmp-sysroots:
513 516
514``build/tmp/sysroots/`` 517``build/tmp/sysroots/``
515----------------------- 518~~~~~~~~~~~~~~~~~~~~~~~
516 519
517Previous versions of the OpenEmbedded build system used to create a 520Previous versions of the OpenEmbedded build system used to create a
518global shared sysroot per machine along with a native sysroot. Beginning 521global shared sysroot per machine along with a native sysroot. Since
519with the 2.3 version of the Yocto Project, sysroots exist in 522the 2.3 version of the Yocto Project, there are sysroots in
520recipe-specific :term:`WORKDIR` directories. Thus, the 523recipe-specific :term:`WORKDIR` directories. Thus, the
521``build/tmp/sysroots/`` directory is unused. 524``build/tmp/sysroots/`` directory is unused.
522 525
@@ -530,13 +533,12 @@ recipe-specific :term:`WORKDIR` directories. Thus, the
530.. _structure-build-tmp-stamps: 533.. _structure-build-tmp-stamps:
531 534
532``build/tmp/stamps/`` 535``build/tmp/stamps/``
533--------------------- 536~~~~~~~~~~~~~~~~~~~~~
534 537
535This directory holds information that BitBake uses for accounting 538This directory holds information that BitBake uses for accounting
536purposes to track what tasks have run and when they have run. The 539purposes to track what tasks have run and when they have run. The
537directory is sub-divided by architecture, package name, and version. 540directory is sub-divided by architecture, package name, and version.
538Following is an example: 541Here is an example::
539::
540 542
541 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do 543 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
542 544
@@ -551,17 +553,17 @@ section in the Yocto Project Overview and Concepts Manual.
551.. _structure-build-tmp-log: 553.. _structure-build-tmp-log:
552 554
553``build/tmp/log/`` 555``build/tmp/log/``
554------------------ 556~~~~~~~~~~~~~~~~~~
555 557
556This directory contains general logs that are not otherwise placed using 558This directory contains general logs that are not otherwise placed using
557the package's ``WORKDIR``. Examples of logs are the output from the 559the package's :term:`WORKDIR`. Examples of logs are the output from the
558``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not 560``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
559necessarily mean this directory is created. 561necessarily mean this directory is created.
560 562
561.. _structure-build-tmp-work: 563.. _structure-build-tmp-work:
562 564
563``build/tmp/work/`` 565``build/tmp/work/``
564------------------- 566~~~~~~~~~~~~~~~~~~~
565 567
566This directory contains architecture-specific work sub-directories for 568This directory contains architecture-specific work sub-directories for
567packages built by BitBake. All tasks execute from the appropriate work 569packages built by BitBake. All tasks execute from the appropriate work
@@ -575,15 +577,15 @@ It is worth considering the structure of a typical work directory. As an
575example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` 577example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
576built within the Yocto Project. For this package, a work directory of 578built within the Yocto Project. For this package, a work directory of
577``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred 579``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
578to as the ``WORKDIR``, is created. Within this directory, the source is 580to as the :term:`WORKDIR`, is created. Within this directory, the source is
579unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. 581unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
580(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in 582(See the ":ref:`dev-manual/quilt:using quilt in your workflow`" section in
581the Yocto Project Development Tasks Manual for more information.) Within 583the Yocto Project Development Tasks Manual for more information.) Within
582the ``linux-qemux86-standard-build`` directory, standard Quilt 584the ``linux-qemux86-standard-build`` directory, standard Quilt
583directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and 585directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
584standard Quilt commands can be used. 586standard Quilt commands can be used.
585 587
586There are other directories generated within ``WORKDIR``. The most 588There are other directories generated within :term:`WORKDIR`. The most
587important directory is ``WORKDIR/temp/``, which has log files for each 589important directory is ``WORKDIR/temp/``, which has log files for each
588task (``log.do_*.pid``) and contains the scripts BitBake runs for each 590task (``log.do_*.pid``) and contains the scripts BitBake runs for each
589task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make 591task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
@@ -593,9 +595,9 @@ install" places its output that is then split into sub-packages within
593.. _structure-build-tmp-work-tunearch-recipename-version: 595.. _structure-build-tmp-work-tunearch-recipename-version:
594 596
595``build/tmp/work/tunearch/recipename/version/`` 597``build/tmp/work/tunearch/recipename/version/``
596----------------------------------------------- 598^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
597 599
598The recipe work directory - ``${WORKDIR}``. 600The recipe work directory --- ``${WORKDIR}``.
599 601
600As described earlier in the 602As described earlier in the
601":ref:`structure-build-tmp-sysroots`" section, 603":ref:`structure-build-tmp-sysroots`" section,
@@ -607,7 +609,7 @@ constructed using the architecture of the given build (e.g.
607name, and the version of the recipe (i.e. 609name, and the version of the recipe (i.e.
608:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). 610:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
609 611
610A number of key subdirectories exist within each recipe work directory: 612Here are key subdirectories within each recipe work directory:
611 613
612- ``${WORKDIR}/temp``: Contains the log files of each task executed for 614- ``${WORKDIR}/temp``: Contains the log files of each task executed for
613 this recipe, the "run" files for each executed task, which contain 615 this recipe, the "run" files for each executed task, which contain
@@ -629,8 +631,8 @@ A number of key subdirectories exist within each recipe work directory:
629 split into individual packages. 631 split into individual packages.
630 632
631- ``${WORKDIR}/packages-split``: Contains the output of the 633- ``${WORKDIR}/packages-split``: Contains the output of the
632 ``do_package`` task after the output has been split into individual 634 :ref:`ref-tasks-package` task after the output has been split into individual
633 packages. Subdirectories exist for each individual package created by 635 packages. There are subdirectories for each individual package created by
634 the recipe. 636 the recipe.
635 637
636- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target 638- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
@@ -651,7 +653,7 @@ A number of key subdirectories exist within each recipe work directory:
651.. _structure-build-work-shared: 653.. _structure-build-work-shared:
652 654
653``build/tmp/work-shared/`` 655``build/tmp/work-shared/``
654-------------------------- 656~~~~~~~~~~~~~~~~~~~~~~~~~~
655 657
656For efficiency, the OpenEmbedded build system creates and uses this 658For efficiency, the OpenEmbedded build system creates and uses this
657directory to hold recipes that share a work directory with other 659directory to hold recipes that share a work directory with other
@@ -660,29 +662,30 @@ recipes. In practice, this is only used for ``gcc`` and its variants
660 662
661.. _structure-meta: 663.. _structure-meta:
662 664
663The Metadata - ``meta/`` 665The Metadata --- ``meta/``
664======================== 666==========================
665 667
666As mentioned previously, :term:`Metadata` is the core of the 668As mentioned previously, :term:`Metadata` is the core of the
667Yocto Project. Metadata has several important subdivisions: 669Yocto Project. Metadata has several important subdivisions:
668 670
669.. _structure-meta-classes: 671.. _structure-meta-classes:
670 672
671``meta/classes/`` 673``meta/classes*/``
672----------------- 674------------------
673 675
674This directory contains the ``*.bbclass`` files. Class files are used to 676These directories contain the ``*.bbclass`` files. Class files are used to
675abstract common code so it can be reused by multiple packages. Every 677abstract common code so it can be reused by multiple packages. Every
676package inherits the ``base.bbclass`` file. Examples of other important 678package inherits the :ref:`ref-classes-base` file. Examples of other important
677classes are ``autotools.bbclass``, which in theory allows any 679classes are :ref:`ref-classes-autotools`, which in theory allows any
678Autotool-enabled package to work with the Yocto Project with minimal 680Autotool-enabled package to work with the Yocto Project with minimal
679effort. Another example is ``kernel.bbclass`` that contains common code 681effort. Another example is :ref:`ref-classes-kernel` that contains common code
680and functions for working with the Linux kernel. Functions like image 682and functions for working with the Linux kernel. Functions like image
681generation or packaging also have their specific class files such as 683generation or packaging also have their specific class files such as
682``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. 684:ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and
685:ref:`package*.bbclass <ref-classes-package>`.
683 686
684For reference information on classes, see the 687For reference information on classes, see the
685":ref:`ref-manual/classes:Classes`" chapter. 688":doc:`/ref-manual/classes`" chapter.
686 689
687.. _structure-meta-conf: 690.. _structure-meta-conf:
688 691
@@ -700,7 +703,7 @@ distribution configuration file.
700.. _structure-meta-conf-machine: 703.. _structure-meta-conf-machine:
701 704
702``meta/conf/machine/`` 705``meta/conf/machine/``
703---------------------- 706~~~~~~~~~~~~~~~~~~~~~~
704 707
705This directory contains all the machine configuration files. If you set 708This directory contains all the machine configuration files. If you set
706``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a 709``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a
@@ -711,11 +714,11 @@ support for a new machine to the Yocto Project, look in this directory.
711.. _structure-meta-conf-distro: 714.. _structure-meta-conf-distro:
712 715
713``meta/conf/distro/`` 716``meta/conf/distro/``
714--------------------- 717~~~~~~~~~~~~~~~~~~~~~
715 718
716The contents of this directory controls any distribution-specific 719The contents of this directory controls any distribution-specific
717configurations. For the Yocto Project, the ``defaultsetup.conf`` is the 720configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
718main file here. This directory includes the versions and the ``SRCDATE`` 721main file here. This directory includes the versions and the :term:`SRCDATE`
719definitions for applications that are configured here. An example of an 722definitions for applications that are configured here. An example of an
720alternative configuration might be ``poky-bleeding.conf``. Although this 723alternative configuration might be ``poky-bleeding.conf``. Although this
721file mainly inherits its configuration from Poky. 724file mainly inherits its configuration from Poky.
@@ -723,7 +726,7 @@ file mainly inherits its configuration from Poky.
723.. _structure-meta-conf-machine-sdk: 726.. _structure-meta-conf-machine-sdk:
724 727
725``meta/conf/machine-sdk/`` 728``meta/conf/machine-sdk/``
726-------------------------- 729~~~~~~~~~~~~~~~~~~~~~~~~~~
727 730
728The OpenEmbedded build system searches this directory for configuration 731The OpenEmbedded build system searches this directory for configuration
729files that correspond to the value of 732files that correspond to the value of
@@ -748,7 +751,9 @@ and lists of files and directories with known permissions.
748------------- 751-------------
749 752
750This directory contains OpenEmbedded Python library code used during the 753This directory contains OpenEmbedded Python library code used during the
751build process. 754build process. It is enabled via the ``addpylib`` directive in
755``meta/conf/local.conf``. For more information, see
756:ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`.
752 757
753.. _structure-meta-recipes-bsp: 758.. _structure-meta-recipes-bsp:
754 759
@@ -789,7 +794,7 @@ system. The tools, however, can also be used on targets.
789 794
790This directory contains non-essential applications that add features 795This directory contains non-essential applications that add features
791compared to the alternatives in core. You might need this directory for 796compared to the alternatives in core. You might need this directory for
792full tool functionality or for Linux Standard Base (LSB) compliance. 797full tool functionality.
793 798
794.. _structure-meta-recipes-gnome: 799.. _structure-meta-recipes-gnome:
795 800
@@ -815,14 +820,6 @@ libraries.
815This directory contains the kernel and generic applications and 820This directory contains the kernel and generic applications and
816libraries that have strong kernel dependencies. 821libraries that have strong kernel dependencies.
817 822
818.. _structure-meta-recipes-lsb4:
819
820``meta/recipes-lsb4/``
821----------------------
822
823This directory contains recipes specifically added to support the Linux
824Standard Base (LSB) version 4.x.
825
826.. _structure-meta-recipes-multimedia: 823.. _structure-meta-recipes-multimedia:
827 824
828``meta/recipes-multimedia/`` 825``meta/recipes-multimedia/``
diff --git a/documentation/ref-manual/svg/releases.svg b/documentation/ref-manual/svg/releases.svg
new file mode 100644
index 0000000000..198d4632b1
--- /dev/null
+++ b/documentation/ref-manual/svg/releases.svg
@@ -0,0 +1,1744 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<svg
3 version="1.1"
4 id="svg2"
5 width="2040.0006"
6 height="624.30518"
7 viewBox="0 0 2040.0006 624.30515"
8 sodipodi:docname="releases.svg"
9 inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
10 xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
11 xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
12 xmlns="http://www.w3.org/2000/svg"
13 xmlns:svg="http://www.w3.org/2000/svg"
14 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
15 xmlns:cc="http://creativecommons.org/ns#"
16 xmlns:dc="http://purl.org/dc/elements/1.1/">
17 <title
18 id="title8568">Yocto Project Release Timeline</title>
19 <metadata
20 id="metadata8">
21 <rdf:RDF>
22 <cc:Work
23 rdf:about="">
24 <dc:format>image/svg+xml</dc:format>
25 <dc:type
26 rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
27 <cc:license
28 rdf:resource="http://artlibre.org/licence/lal" />
29 <dc:title>Yocto Project Release Timeline</dc:title>
30 <dc:creator>
31 <cc:Agent>
32 <dc:title>The Yocto Project</dc:title>
33 </cc:Agent>
34 </dc:creator>
35 </cc:Work>
36 <cc:License
37 rdf:about="http://creativecommons.org/licenses/by-sa/4.0/">
38 <cc:permits
39 rdf:resource="http://creativecommons.org/ns#Reproduction" />
40 <cc:permits
41 rdf:resource="http://creativecommons.org/ns#Distribution" />
42 <cc:requires
43 rdf:resource="http://creativecommons.org/ns#Notice" />
44 <cc:requires
45 rdf:resource="http://creativecommons.org/ns#Attribution" />
46 <cc:permits
47 rdf:resource="http://creativecommons.org/ns#DerivativeWorks" />
48 <cc:requires
49 rdf:resource="http://creativecommons.org/ns#ShareAlike" />
50 </cc:License>
51 </rdf:RDF>
52 </metadata>
53 <defs
54 id="defs6">
55 <inkscape:path-effect
56 effect="powerstroke"
57 id="path-effect6121"
58 is_visible="true"
59 lpeversion="1"
60 offset_points="0,0.5"
61 sort_points="true"
62 interpolator_type="CubicBezierJohan"
63 interpolator_beta="0.2"
64 start_linecap_type="zerowidth"
65 linejoin_type="extrp_arc"
66 miter_limit="4"
67 scale_width="1"
68 end_linecap_type="zerowidth"
69 not_jump="false" />
70 <marker
71 style="overflow:visible"
72 id="marker5783"
73 refX="0"
74 refY="0"
75 orient="auto"
76 inkscape:stockid="Arrow2Mend"
77 inkscape:isstock="true">
78 <path
79 transform="scale(-0.6)"
80 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
81 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
82 id="path5781" />
83 </marker>
84 <marker
85 style="overflow:visible"
86 id="marker5623"
87 refX="0"
88 refY="0"
89 orient="auto"
90 inkscape:stockid="Arrow2Mend"
91 inkscape:isstock="true">
92 <path
93 transform="scale(-0.6)"
94 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
95 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
96 id="path5621" />
97 </marker>
98 <marker
99 style="overflow:visible"
100 id="marker5487"
101 refX="0"
102 refY="0"
103 orient="auto"
104 inkscape:stockid="Arrow2Mend"
105 inkscape:isstock="true">
106 <path
107 transform="scale(-0.6)"
108 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
109 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
110 id="path5485" />
111 </marker>
112 <marker
113 style="overflow:visible"
114 id="marker5285"
115 refX="0"
116 refY="0"
117 orient="auto"
118 inkscape:stockid="Arrow2Mstart"
119 inkscape:isstock="true">
120 <path
121 transform="scale(0.6)"
122 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
123 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
124 id="path5283" />
125 </marker>
126 <marker
127 style="overflow:visible"
128 id="marker5161"
129 refX="0"
130 refY="0"
131 orient="auto"
132 inkscape:stockid="Arrow2Mend"
133 inkscape:isstock="true">
134 <path
135 transform="scale(-0.6)"
136 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
137 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
138 id="path5159" />
139 </marker>
140 <marker
141 style="overflow:visible"
142 id="marker4860"
143 refX="0"
144 refY="0"
145 orient="auto"
146 inkscape:stockid="Arrow2Mend"
147 inkscape:isstock="true">
148 <path
149 transform="scale(-0.6)"
150 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
151 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
152 id="path4858" />
153 </marker>
154 <marker
155 style="overflow:visible"
156 id="marker4504"
157 refX="0"
158 refY="0"
159 orient="auto"
160 inkscape:stockid="Arrow2Mend"
161 inkscape:isstock="true">
162 <path
163 transform="scale(-0.6)"
164 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
165 style="fill:#ffa348;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
166 id="path4502" />
167 </marker>
168 <marker
169 style="overflow:visible"
170 id="Arrow1Mend"
171 refX="0"
172 refY="0"
173 orient="auto"
174 inkscape:stockid="Arrow1Mend"
175 inkscape:isstock="true">
176 <path
177 transform="matrix(-0.4,0,0,-0.4,-4,0)"
178 style="fill:#62a0ea;fill-opacity:1;fill-rule:evenodd;stroke:#62a0ea;stroke-width:1pt;stroke-opacity:1"
179 d="M 0,0 5,-5 -12.5,0 5,5 Z"
180 id="path3318" />
181 </marker>
182 <marker
183 style="overflow:visible"
184 id="marker4174"
185 refX="0"
186 refY="0"
187 orient="auto"
188 inkscape:stockid="Arrow2Mstart"
189 inkscape:isstock="true">
190 <path
191 transform="scale(0.6)"
192 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
193 style="fill:#62a0ea;fill-opacity:1;fill-rule:evenodd;stroke:#62a0ea;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
194 id="path4172" />
195 </marker>
196 <marker
197 style="overflow:visible"
198 id="Arrow2Mend"
199 refX="0"
200 refY="0"
201 orient="auto"
202 inkscape:stockid="Arrow2Mend"
203 inkscape:isstock="true">
204 <path
205 transform="scale(-0.6)"
206 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
207 style="fill:#ffa348;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
208 id="path3336" />
209 </marker>
210 <marker
211 style="overflow:visible"
212 id="Arrow1Mstart"
213 refX="0"
214 refY="0"
215 orient="auto"
216 inkscape:stockid="Arrow1Mstart"
217 inkscape:isstock="true">
218 <path
219 transform="matrix(0.4,0,0,0.4,4,0)"
220 style="fill:#ff7800;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:1pt;stroke-opacity:1"
221 d="M 0,0 5,-5 -12.5,0 5,5 Z"
222 id="path3315" />
223 </marker>
224 <marker
225 style="overflow:visible"
226 id="Arrow2Lstart"
227 refX="0"
228 refY="0"
229 orient="auto"
230 inkscape:stockid="Arrow2Lstart"
231 inkscape:isstock="true">
232 <path
233 transform="matrix(1.1,0,0,1.1,1.1,0)"
234 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
235 style="fill:#ff7800;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
236 id="path3327" />
237 </marker>
238 <marker
239 style="overflow:visible"
240 id="Arrow1Lstart"
241 refX="0"
242 refY="0"
243 orient="auto"
244 inkscape:stockid="Arrow1Lstart"
245 inkscape:isstock="true">
246 <path
247 transform="matrix(0.8,0,0,0.8,10,0)"
248 style="fill:#ff7800;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:1pt;stroke-opacity:1"
249 d="M 0,0 5,-5 -12.5,0 5,5 Z"
250 id="path3309" />
251 </marker>
252 <linearGradient
253 id="linearGradient921"
254 inkscape:swatch="solid">
255 <stop
256 style="stop-color:#deddda;stop-opacity:1;"
257 offset="0"
258 id="stop919" />
259 </linearGradient>
260 <linearGradient
261 id="linearGradient6035-4">
262 <stop
263 id="stop6037-2"
264 style="stop-color:#ffffff"
265 offset="0" />
266 <stop
267 id="stop6039-9"
268 style="stop-color:#ffffff;stop-opacity:0"
269 offset="1" />
270 </linearGradient>
271 <marker
272 style="overflow:visible"
273 id="Arrow2Mstart-4"
274 refX="0"
275 refY="0"
276 orient="auto"
277 inkscape:stockid="Arrow2Mstart"
278 inkscape:isstock="true">
279 <path
280 transform="scale(0.6)"
281 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
282 style="fill:#ffa348;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
283 id="path3333-2" />
284 </marker>
285 <marker
286 style="overflow:visible"
287 id="Arrow2Mend-2"
288 refX="0"
289 refY="0"
290 orient="auto"
291 inkscape:stockid="Arrow2Mend"
292 inkscape:isstock="true">
293 <path
294 transform="scale(-0.6)"
295 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
296 style="fill:#ffa348;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
297 id="path3336-7" />
298 </marker>
299 <marker
300 style="overflow:visible"
301 id="marker5623-2"
302 refX="0"
303 refY="0"
304 orient="auto"
305 inkscape:stockid="Arrow2Mend"
306 inkscape:isstock="true">
307 <path
308 transform="scale(-0.6)"
309 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
310 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
311 id="path5621-3" />
312 </marker>
313 <marker
314 style="overflow:visible"
315 id="Arrow2Mend-4"
316 refX="0"
317 refY="0"
318 orient="auto"
319 inkscape:stockid="Arrow2Mend"
320 inkscape:isstock="true">
321 <path
322 transform="scale(-0.6)"
323 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
324 style="fill:#ffa348;fill-opacity:1;fill-rule:evenodd;stroke:#ffa348;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
325 id="path3336-3" />
326 </marker>
327 <marker
328 style="overflow:visible"
329 id="marker5285-1"
330 refX="0"
331 refY="0"
332 orient="auto"
333 inkscape:stockid="Arrow2Mstart"
334 inkscape:isstock="true">
335 <path
336 transform="scale(0.6)"
337 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
338 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
339 id="path5283-7" />
340 </marker>
341 <marker
342 style="overflow:visible"
343 id="marker5161-4"
344 refX="0"
345 refY="0"
346 orient="auto"
347 inkscape:stockid="Arrow2Mend"
348 inkscape:isstock="true">
349 <path
350 transform="scale(-0.6)"
351 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
352 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
353 id="path5159-3" />
354 </marker>
355 <marker
356 style="overflow:visible"
357 id="marker5285-1-4"
358 refX="0"
359 refY="0"
360 orient="auto"
361 inkscape:stockid="Arrow2Mstart"
362 inkscape:isstock="true">
363 <path
364 transform="scale(0.6)"
365 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
366 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
367 id="path5283-7-6" />
368 </marker>
369 <marker
370 style="overflow:visible"
371 id="marker5161-4-9"
372 refX="0"
373 refY="0"
374 orient="auto"
375 inkscape:stockid="Arrow2Mend"
376 inkscape:isstock="true">
377 <path
378 transform="scale(-0.6)"
379 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
380 style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
381 id="path5159-3-4" />
382 </marker>
383 <marker
384 style="overflow:visible"
385 id="marker4174-8"
386 refX="0"
387 refY="0"
388 orient="auto"
389 inkscape:stockid="Arrow2Mstart"
390 inkscape:isstock="true">
391 <path
392 transform="scale(0.6)"
393 d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
394 style="fill:#62a0ea;fill-opacity:1;fill-rule:evenodd;stroke:#62a0ea;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
395 id="path4172-8" />
396 </marker>
397 </defs>
398 <sodipodi:namedview
399 pagecolor="#ffffff"
400 bordercolor="#666666"
401 borderopacity="1"
402 objecttolerance="10"
403 gridtolerance="10"
404 guidetolerance="10"
405 inkscape:pageopacity="0"
406 inkscape:pageshadow="2"
407 inkscape:window-width="1920"
408 inkscape:window-height="1043"
409 id="namedview4"
410 showgrid="true"
411 inkscape:zoom="1.4472045"
412 inkscape:cx="736.24703"
413 inkscape:cy="312.32629"
414 inkscape:window-x="1728"
415 inkscape:window-y="0"
416 inkscape:window-maximized="1"
417 inkscape:current-layer="g10"
418 inkscape:document-rotation="0"
419 inkscape:snap-perpendicular="true"
420 fit-margin-top="30"
421 lock-margins="true"
422 fit-margin-left="30"
423 fit-margin-right="30"
424 fit-margin-bottom="30"
425 inkscape:pagecheckerboard="0">
426 <inkscape:grid
427 type="xygrid"
428 id="grid1257"
429 originx="-289.99936"
430 originy="325" />
431 </sodipodi:namedview>
432 <g
433 inkscape:groupmode="layer"
434 inkscape:label="Image"
435 id="g10"
436 transform="translate(-289.99936,325.00004)">
437 <path
438 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
439 d="m 1080,220.00003 v -515.00007 0 0"
440 id="path207708" />
441 <path
442 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
443 d="m 1200,220.00003 v -515.00007 0 0"
444 id="path207708-4" />
445 <path
446 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
447 d="m 1320,220.00003 v -515.00007 0 0"
448 id="path207708-4-3" />
449 <path
450 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
451 d="m 1440,219.99998 v -515.00002 0 0"
452 id="path207708-4-3-6" />
453 <path
454 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
455 d="m 1560,219.99998 v -515.00001 0 0"
456 id="path207708-4-3-6-2" />
457 <path
458 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
459 d="m 1680,219.99998 v -515.00002 0 0"
460 id="path207708-4-3-6-2-8" />
461 <path
462 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
463 d="m 1800,219.99998 v -515.00002 0 0"
464 id="path207708-4-3-6-2-8-4" />
465 <path
466 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
467 d="m 1920,219.99998 v -515.00002 0 0"
468 id="path207708-4-3-6-2-8-4-3" />
469 <path
470 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
471 d="m 2040,219.99997 v -460.00002 0 0"
472 id="path207708-4-3-6-2-8-4-3-8" />
473 <path
474 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
475 d="m 2040,219.99998 v -515.00002 0 0"
476 id="path207708-4-3-6-2-8-4-3-8-0" />
477 <path
478 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
479 d="m 2159.954,219.99997 v -514.99999 0 0"
480 id="path207708-4-3-6-2-8-4-3-8-4" />
481 <path
482 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
483 d="m 2280,219.99997 v -514.99999 0 0"
484 id="path207708-4-3-6-2-8-4-3-8-4-0" />
485 <path
486 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
487 d="m 960,220.00003 v -515.00007 0 0"
488 id="path207708-9" />
489 <path
490 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
491 d="m 840,220.00001 v -375 0 0"
492 id="path207708-9-6" />
493 <path
494 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
495 d="m 840,220.00002 v -515.00004 0 0"
496 id="path207708-9-6-2" />
497 <path
498 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
499 d="m 720,220.00003 v -515.00007 0 0"
500 id="path207708-9-6-2-5" />
501 <path
502 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
503 d="m 600,220.00003 v -515.00007 0 0"
504 id="path207708-9-6-2-5-9" />
505 <path
506 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
507 d="m 480,220.00003 v -515.00007 0 0"
508 id="path207708-9-6-2-5-9-0" />
509 <path
510 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
511 d="m 360,220.00003 v -515.00007 0 0"
512 id="path207708-9-6-2-5-9-0-5" />
513 <text
514 xml:space="preserve"
515 style="font-weight:bold;font-size:42.5884px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
516 x="142.22464"
517 y="565.10297"
518 id="text907"><tspan
519 sodipodi:role="line"
520 id="tspan905"
521 x="142.22464"
522 y="565.10297" /></text>
523 <text
524 xml:space="preserve"
525 style="font-weight:bold;font-size:42.5884px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
526 x="98.363503"
527 y="637.8432"
528 id="text911"><tspan
529 sodipodi:role="line"
530 id="tspan909"
531 x="98.363503"
532 y="637.8432" /></text>
533 <text
534 xml:space="preserve"
535 style="font-weight:bold;font-size:42.5884px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
536 x="-59.575905"
537 y="580.05695"
538 id="text915"><tspan
539 sodipodi:role="line"
540 id="tspan913"
541 x="-59.575905"
542 y="580.05695" /></text>
543 <rect
544 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
545 id="rect917-0-0"
546 width="980"
547 height="45.000004"
548 x="360"
549 y="154.99997"
550 ry="2.2558987" />
551 <text
552 xml:space="preserve"
553 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
554 x="420.52835"
555 y="174.12433"
556 id="text1185-3-55-4"><tspan
557 sodipodi:role="line"
558 x="420.52835"
559 y="174.12433"
560 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
561 id="tspan957-2-8">Dunfell (LTS)</tspan><tspan
562 sodipodi:role="line"
563 x="420.52835"
564 y="192.121"
565 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
566 id="tspan10317">3.1</tspan></text>
567 <rect
568 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
569 id="rect917-0-0-4"
570 width="140.00002"
571 height="45.000004"
572 x="480"
573 y="99.999969"
574 ry="2.2558987" />
575 <text
576 xml:space="preserve"
577 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
578 x="534.10651"
579 y="118.94971"
580 id="text1185-3-55-4-0"><tspan
581 sodipodi:role="line"
582 x="534.10651"
583 y="118.94971"
584 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
585 id="tspan957-2-8-6">Gatesgarth</tspan><tspan
586 sodipodi:role="line"
587 x="534.10651"
588 y="136.94638"
589 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
590 id="tspan10317-2">3.2</tspan></text>
591 <rect
592 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
593 id="rect917-0-0-4-4"
594 width="260"
595 height="45.000004"
596 x="599.99994"
597 y="45.000011"
598 ry="2.2558987" />
599 <rect
600 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
601 id="rect917-0-0-4-4-9"
602 width="160.00002"
603 height="45.000004"
604 x="720"
605 y="-9.9999905"
606 ry="2.2558987" />
607 <text
608 xml:space="preserve"
609 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
610 x="766.10297"
611 y="9.57586"
612 id="text1185-3-55-4-0-0"><tspan
613 sodipodi:role="line"
614 x="766.10297"
615 y="9.57586"
616 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
617 id="tspan957-2-8-6-3">Honister</tspan><tspan
618 sodipodi:role="line"
619 x="766.10297"
620 y="27.57254"
621 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
622 id="tspan10317-2-9">3.4</tspan></text>
623 <rect
624 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
625 id="rect917-0-0-4-4-9-4"
626 width="160.00002"
627 height="45.000004"
628 x="959.99994"
629 y="-120"
630 ry="2.2558987" />
631 <text
632 xml:space="preserve"
633 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
634 x="1008.4941"
635 y="-100.605"
636 id="text1185-3-55-4-0-0-0"><tspan
637 sodipodi:role="line"
638 x="1008.4941"
639 y="-100.605"
640 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
641 id="tspan957-2-8-6-3-9">Langdale</tspan><tspan
642 sodipodi:role="line"
643 x="1008.4941"
644 y="-82.608322"
645 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
646 id="tspan10317-2-9-1">4.1</tspan></text>
647 <rect
648 style="opacity:1;fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
649 id="rect917-0-0-4-4-9-4-5"
650 width="140.00003"
651 height="45.000004"
652 x="1100"
653 y="-175.00003"
654 ry="2.2558987" />
655 <text
656 xml:space="preserve"
657 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
658 x="1156.057"
659 y="-155.49881"
660 id="text1185-3-55-4-0-0-0-1"><tspan
661 sodipodi:role="line"
662 x="1156.057"
663 y="-155.49881"
664 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
665 id="tspan957-2-8-6-3-9-7">Mickledore</tspan><tspan
666 sodipodi:role="line"
667 x="1156.057"
668 y="-137.50214"
669 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
670 id="tspan10317-2-9-1-4">4.2</tspan></text>
671 <g
672 id="g1379">
673 <rect
674 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
675 id="rect917-0-0-4-4-9-4-5-38"
676 width="140.00003"
677 height="45.000004"
678 x="1220"
679 y="-230.00005"
680 ry="2.2558987" />
681 <text
682 xml:space="preserve"
683 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
684 x="1269.2329"
685 y="-210.32925"
686 id="text1185-3-55-4-0-0-0-1-1"><tspan
687 sodipodi:role="line"
688 x="1269.2329"
689 y="-210.32925"
690 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
691 id="tspan957-2-8-6-3-9-7-4">Nanbield</tspan><tspan
692 sodipodi:role="line"
693 x="1269.2329"
694 y="-192.33258"
695 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
696 id="tspan10317-2-9-1-4-6">4.3</tspan></text>
697 </g>
698 <rect
699 style="opacity:0.75;fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
700 id="rect917-0-0-4-4-9-4-5-3-9"
701 width="979.99994"
702 height="45.000004"
703 x="1320"
704 y="-285.00003"
705 ry="2.2558987" />
706 <text
707 xml:space="preserve"
708 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
709 x="1373.233"
710 y="-265.32928"
711 id="text1185-3-55-4-0-0-0-1-1-6"><tspan
712 sodipodi:role="line"
713 x="1373.233"
714 y="-265.32928"
715 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
716 id="tspan957-2-8-6-3-9-7-4-2">Scarthgap</tspan><tspan
717 sodipodi:role="line"
718 x="1373.233"
719 y="-247.33261"
720 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
721 id="tspan10317-2-9-1-4-6-5">5.0</tspan></text>
722 <rect
723 style="fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:2;stroke-opacity:1"
724 id="rect917-0-0-4-4-9-9"
725 width="960.00012"
726 height="45.000004"
727 x="859.99994"
728 y="-64.999992"
729 ry="2.2558987" />
730 <text
731 xml:space="preserve"
732 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
733 x="928.49872"
734 y="-45.648258"
735 id="text1185-3-55-4-0-0-9"><tspan
736 sodipodi:role="line"
737 x="928.49872"
738 y="-45.648258"
739 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
740 id="tspan957-2-8-6-3-6">Kirkstone (LTS)</tspan><tspan
741 sodipodi:role="line"
742 x="928.49872"
743 y="-27.651579"
744 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
745 id="tspan10317-2-9-0">4.0</tspan></text>
746 <text
747 xml:space="preserve"
748 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
749 x="653.72168"
750 y="64.866302"
751 id="text1185-3-55-4-0-0-7"><tspan
752 sodipodi:role="line"
753 x="653.72168"
754 y="64.866302"
755 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
756 id="tspan957-2-8-6-3-2">Hardknott </tspan><tspan
757 sodipodi:role="line"
758 x="653.72168"
759 y="82.862984"
760 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans Bold';text-align:center;text-anchor:middle;fill:#fffefe;fill-opacity:1;stroke:none"
761 id="tspan10317-2-9-8">3.3</tspan></text>
762 <g
763 id="g1125-0"
764 transform="matrix(0.42240595,0,0,0.41654472,354.53445,-399.96314)"
765 style="stroke:none;stroke-width:2.38399">
766 <rect
767 style="opacity:1;fill:#333333;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:4.76797;stroke-opacity:1"
768 id="rect1061-9"
769 width="452.00439"
770 height="192.0562"
771 x="11.609296"
772 y="276.44562"
773 ry="4.0176301" />
774 <g
775 id="g1109-1"
776 transform="translate(-2.7615661,-1.7576335)"
777 style="stroke:none;stroke-width:2.38399">
778 <path
779 id="path14-9"
780 class="st0"
781 d="m 439.74452,358.11274 c 0,4.22 -3.41,7.64 -7.64,7.64 -4.22,0 -7.63,-3.42 -7.63,-7.64 0,-4.22 3.41,-7.64 7.63,-7.64 4.23,0 7.64,3.42 7.64,7.64 v 0"
782 style="fill:#4a97d2;fill-opacity:1;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
783 <path
784 id="path16-6"
785 class="st1"
786 d="m 114.56452,324.94274 -11.13,-6.3 -22.409996,45.41 -23.9,-45.41 -11.27,6.3 28.41,53.38 c -0.21,0.51 -0.86,1.9 -1.95,4.22 -1.11,2.21 -2.25,4.41 -3.46,6.62 -2.11,3.81 -4.26,6.91 -6.46,9.32 -2.21,2.51 -4.46,4.51 -6.78,6.02 -2.3,1.51 -4.7,2.65 -7.21,3.46 -2.41,0.8 -4.87,1.45 -7.38,1.95 l 5.12,10.68 c 1.6,-0.21 3.75,-0.71 6.46,-1.51 2.81,-0.7 5.86,-2.06 9.17,-4.06 3.3,-2 6.67,-4.86 10.07,-8.57 3.52,-3.71 6.78,-8.62 9.78,-14.73 l 32.939996,-66.78"
787 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
788 <path
789 id="path18-2"
790 class="st1"
791 d="m 175.39452,358.18274 c 0,3.51 -0.6,6.76 -1.81,9.78 -1.21,3 -2.86,5.62 -4.95,7.81 -2.01,2.11 -4.41,3.81 -7.22,5.12 -2.71,1.19 -5.67,1.8 -8.87,1.8 -3.21,0 -6.22,-0.6 -9.02,-1.8 -2.81,-1.31 -5.27,-3.01 -7.38,-5.12 -2,-2.19 -3.6,-4.81 -4.81,-7.81 -1.21,-3.01 -1.81,-6.27 -1.81,-9.78 0,-3.51 0.6,-6.76 1.81,-9.77 1.21,-3 2.81,-5.61 4.81,-7.82 2.11,-2.21 4.57,-3.92 7.38,-5.11 2.8,-1.32 5.81,-1.97 9.02,-1.97 3.21,0 6.16,0.65 8.87,1.97 2.81,1.19 5.21,2.9 7.22,5.11 2.1,2.21 3.75,4.81 4.95,7.82 1.2,3.01 1.81,6.26 1.81,9.77 m 13.98,0 c 0,-5.21 -0.95,-10.08 -2.86,-14.59 -1.81,-4.51 -4.36,-8.42 -7.67,-11.73 -3.32,-3.3 -7.22,-5.86 -11.73,-7.67 -4.51,-1.9 -9.38,-2.86 -14.59,-2.86 -5.21,0 -10.08,0.95 -14.59,2.86 -4.51,1.81 -8.43,4.36 -11.73,7.67 -3.3,3.31 -5.92,7.22 -7.82,11.73 -1.9,4.51 -2.86,9.38 -2.86,14.59 0,5.21 0.95,10.08 2.86,14.59 1.9,4.41 4.52,8.27 7.82,11.57 3.3,3.32 7.22,5.92 11.73,7.82 4.51,1.81 9.38,2.71 14.59,2.71 5.21,0 10.08,-0.9 14.59,-2.71 4.51,-1.91 8.41,-4.51 11.73,-7.82 3.3,-3.3 5.86,-7.16 7.67,-11.57 1.91,-4.51 2.86,-9.38 2.86,-14.59"
792 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
793 <path
794 id="path20-5"
795 class="st1"
796 d="m 373.22452,358.18274 c 0,3.51 -0.6,6.76 -1.81,9.78 -1.21,3 -2.86,5.62 -4.97,7.81 -2,2.11 -4.4,3.81 -7.21,5.12 -2.71,1.19 -5.67,1.8 -8.87,1.8 -3.21,0 -6.22,-0.6 -9.03,-1.8 -2.8,-1.31 -5.26,-3.01 -7.37,-5.12 -2,-2.19 -3.61,-4.81 -4.81,-7.81 -1.21,-3.01 -1.81,-6.27 -1.81,-9.78 0,-3.51 0.6,-6.76 1.81,-9.77 1.21,-3 2.81,-5.61 4.81,-7.82 2.11,-2.21 4.57,-3.92 7.37,-5.11 2.81,-1.32 5.82,-1.97 9.03,-1.97 3.21,0 6.16,0.65 8.87,1.97 2.81,1.19 5.21,2.9 7.21,5.11 2.11,2.21 3.76,4.81 4.97,7.82 1.21,3.01 1.81,6.26 1.81,9.77 m 13.98,0 c 0,-5.21 -0.95,-10.08 -2.86,-14.59 -1.81,-4.51 -4.36,-8.42 -7.67,-11.73 -3.32,-3.3 -7.22,-5.86 -11.73,-7.67 -4.51,-1.9 -9.38,-2.86 -14.59,-2.86 -5.22,0 -10.08,0.95 -14.59,2.86 -4.51,1.81 -8.43,4.36 -11.73,7.67 -3.3,3.31 -5.92,7.22 -7.82,11.73 -1.9,4.51 -2.86,9.38 -2.86,14.59 0,5.21 0.95,10.08 2.86,14.59 1.9,4.41 4.52,8.27 7.82,11.57 3.3,3.32 7.22,5.92 11.73,7.82 4.51,1.81 9.37,2.71 14.59,2.71 5.21,0 10.08,-0.9 14.59,-2.71 4.51,-1.91 8.41,-4.51 11.73,-7.82 3.3,-3.3 5.86,-7.16 7.67,-11.57 1.91,-4.51 2.86,-9.38 2.86,-14.59"
797 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
798 <path
799 id="path22-4"
800 class="st1"
801 d="m 288.05452,298.59274 -13.39,7.52 v 16.45 h -36.21 c -26.15,0 -41.9,12.74 -41.9,35.95 0,36.04 37.55,42.84 64.25,29.96 l -5.63,-10.92 c -21.13,9.23 -44.53,5.3 -44.53,-19.28 0,-15.86 8.26,-24.54 27.49,-24.54 h 36.54 v 43.82 c 0,19.37 22.19,19.81 35.95,11.86 l -5.29,-10.45 c -8.85,4.48 -17.26,5.06 -17.26,-3.53 v -41.7 h 18.32 v -11.17 h -18.32 l -0.02,-23.97 v 0"
802 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
803 <path
804 id="path24-4"
805 class="st1"
806 d="m 136.79452,428.30274 h 3.35 c 1.69,-0.01 3.34,1.19 3.34,2.9 0,2.87 -3.23,3.3 -3.23,3.3 l -3.46,0.02 z m -4.84,-4.1 v 25.3 h 4.83 l 0.06,-10.67 c 8.62,0.54 11.84,-2.46 11.84,-7.75 0,-4.75 -4.26,-6.88 -8.34,-6.88 h -8.39 v 0"
807 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
808 <path
809 id="path26-9"
810 class="st1"
811 d="m 224.38452,436.87274 c 0,1.23 -0.23,2.39 -0.69,3.46 -0.42,1.04 -1.02,1.95 -1.81,2.74 -0.78,0.78 -1.7,1.4 -2.75,1.86 -1.04,0.42 -2.17,0.64 -3.38,0.64 -1.22,0 -2.35,-0.22 -3.39,-0.64 -1.05,-0.46 -1.96,-1.07 -2.75,-1.86 -0.76,-0.78 -1.36,-1.7 -1.81,-2.74 -0.46,-1.07 -0.69,-2.23 -0.69,-3.46 0,-1.23 0.23,-2.37 0.69,-3.42 0.45,-1.06 1.05,-1.99 1.81,-2.77 0.78,-0.78 1.7,-1.39 2.75,-1.82 1.04,-0.45 2.17,-0.67 3.39,-0.67 1.21,0 2.34,0.23 3.38,0.67 1.05,0.43 1.96,1.04 2.75,1.82 0.78,0.78 1.39,1.71 1.81,2.77 0.46,1.05 0.69,2.19 0.69,3.42 m 4.9,0 c 0,-1.81 -0.35,-3.5 -1.06,-5.06 -0.69,-1.59 -1.65,-2.97 -2.89,-4.12 -1.21,-1.17 -2.64,-2.09 -4.3,-2.75 -1.64,-0.69 -3.41,-1.04 -5.3,-1.04 -1.9,0 -3.69,0.35 -5.35,1.04 -1.64,0.66 -3.06,1.58 -4.27,2.75 -1.22,1.16 -2.17,2.53 -2.89,4.12 -0.69,1.57 -1.03,3.25 -1.03,5.06 0,1.83 0.34,3.53 1.03,5.1 0.72,1.57 1.68,2.94 2.89,4.12 1.21,1.17 2.63,2.09 4.27,2.75 1.66,0.66 3.45,1 5.35,1 1.89,0 3.67,-0.34 5.3,-1 1.66,-0.66 3.1,-1.58 4.3,-2.75 1.24,-1.18 2.21,-2.55 2.89,-4.12 0.71,-1.56 1.06,-3.26 1.06,-5.1"
812 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
813 <path
814 id="path28-9"
815 class="st1"
816 d="m 249.02452,424.25274 v 19.18 c 0,0.77 -0.57,1.63 -1.51,1.65 l -1.51,0.06 0.08,4.7 1.41,0.02 c 4.73,0.07 6.36,-4.37 6.36,-6.45 v -19.13"
817 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
818 <path
819 id="path30-3"
820 class="st1"
821 d="m 290.20452,424.19274 h -16.13 v 25.22 h 16.2 l -0.07,-4.06 h -11.28 v -6.58 h 9.44 v -4.06 h -9.44 v -6.38 h 11.21 l 0.07,-4.14"
822 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
823 <path
824 id="path32-6"
825 class="st1"
826 d="m 327.39452,430.24274 c -8.26,-4.53 -16.39,-1.78 -16.39,6.52 0,6.69 6.43,11.84 17,6.31 l 1.53,4.13 c -10.15,5.58 -23.51,1.6 -23.51,-10.44 0,-10.91 11.85,-16.59 23.36,-10.61 l -1.99,4.09"
827 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
828 <path
829 id="path34-0"
830 class="st1"
831 d="m 366.07452,424.19274 0.01,4.13 h -8.05 v 21.16 h -4.85 v -21.15 h -7.73 l 0.11,-4.13 h 20.51"
832 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
833 <path
834 id="path36-5"
835 class="st1"
836 d="m 172.67452,428.30274 h 3.35 c 1.69,-0.01 3.34,1.19 3.34,2.9 0,2.87 -3.23,3.3 -3.23,3.3 l -3.46,0.02 z m -4.82,-4.1 v 25.3 h 4.82 v -10.89 h 3.2 l 5.59,10.89 h 5.5 l -6.67,-12.2 c 2.64,-1.18 4.01,-3.26 4.01,-6.22 0,-4.94 -4.33,-6.88 -9.09,-6.88 h -7.36 v 0"
837 style="fill:#ffffff;stroke:none;stroke-width:0.238399;stroke-opacity:1" />
838 </g>
839 </g>
840 <text
841 xml:space="preserve"
842 style="font-weight:bold;font-size:42.5884px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
843 x="313.46567"
844 y="412.9321"
845 id="text3781"><tspan
846 sodipodi:role="line"
847 id="tspan3779"
848 x="313.46567"
849 y="412.9321" /></text>
850 <text
851 xml:space="preserve"
852 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
853 x="1199.6055"
854 y="250.21216"
855 id="text1185-9-7-1-1"><tspan
856 sodipodi:role="line"
857 x="1199.6055"
858 y="250.21216"
859 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
860 id="tspan31345">Oct.</tspan><tspan
861 sodipodi:role="line"
862 x="1199.6055"
863 y="268.20883"
864 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
865 id="tspan49906">2023</tspan></text>
866 <text
867 xml:space="preserve"
868 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
869 x="1439.3904"
870 y="249.86044"
871 id="text1185-9-7-1-1-89"><tspan
872 sodipodi:role="line"
873 x="1439.3904"
874 y="249.86044"
875 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
876 id="tspan31345-7">Oct.</tspan><tspan
877 sodipodi:role="line"
878 x="1439.3904"
879 y="267.85712"
880 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
881 id="tspan49906-76">2024</tspan></text>
882 <text
883 xml:space="preserve"
884 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
885 x="1679.3094"
886 y="250.58356"
887 id="text1185-9-7-1-1-89-6"><tspan
888 sodipodi:role="line"
889 x="1679.3094"
890 y="250.58356"
891 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
892 id="tspan31345-7-8">Oct.</tspan><tspan
893 sodipodi:role="line"
894 x="1679.3094"
895 y="268.58023"
896 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
897 id="tspan49906-76-0">2025</tspan></text>
898 <text
899 xml:space="preserve"
900 style="font-weight:bold;font-size:6.66667px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
901 x="849.49744"
902 y="61.106953"
903 id="text1185-9-7-1-1-0"><tspan
904 sodipodi:role="line"
905 x="849.49744"
906 y="61.106953"
907 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.66667px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;text-anchor:end;fill:#fffefe;fill-opacity:1;stroke:none"
908 id="tspan46212">Support for this version was extended to leave</tspan><tspan
909 sodipodi:role="line"
910 x="849.49744"
911 y="70.105324"
912 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.66667px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;text-anchor:end;fill:#fffefe;fill-opacity:1;stroke:none"
913 id="tspan120364">users more time to adapt to override syntax</tspan><tspan
914 sodipodi:role="line"
915 x="849.49744"
916 y="79.103691"
917 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.66667px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;text-anchor:end;fill:#fffefe;fill-opacity:1;stroke:none"
918 id="tspan123280">changes in the 3.4 release.</tspan></text>
919 <text
920 xml:space="preserve"
921 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
922 x="959.52008"
923 y="250.67822"
924 id="text1185-9-7-1-1-0-7"><tspan
925 sodipodi:role="line"
926 x="959.52008"
927 y="250.67822"
928 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
929 id="tspan31345-42-7">Oct.</tspan><tspan
930 sodipodi:role="line"
931 x="959.52008"
932 y="268.6749"
933 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
934 id="tspan49906-9-6">2022</tspan></text>
935 <text
936 xml:space="preserve"
937 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
938 x="719.13617"
939 y="250.21216"
940 id="text1185-9-7-1-1-2"><tspan
941 sodipodi:role="line"
942 x="719.13617"
943 y="250.21216"
944 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
945 id="tspan31345-1">Oct.</tspan><tspan
946 sodipodi:role="line"
947 x="719.13617"
948 y="268.20883"
949 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
950 id="tspan49906-5">2021</tspan></text>
951 <text
952 xml:space="preserve"
953 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
954 x="478.82367"
955 y="250.21216"
956 id="text1185-9-7-1-1-80"><tspan
957 sodipodi:role="line"
958 x="478.82367"
959 y="250.21216"
960 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
961 id="tspan31345-5">Oct.</tspan><tspan
962 sodipodi:role="line"
963 x="478.82367"
964 y="268.20883"
965 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
966 id="tspan49906-6">2020</tspan></text>
967 <text
968 xml:space="preserve"
969 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
970 x="361.81961"
971 y="250.07544"
972 id="text1185-9-7-1-1-8"><tspan
973 sodipodi:role="line"
974 x="361.81961"
975 y="250.07544"
976 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
977 id="tspan31345-4">Apr.</tspan><tspan
978 sodipodi:role="line"
979 x="361.81961"
980 y="268.07211"
981 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
982 id="tspan49906-7">2020</tspan></text>
983 <text
984 xml:space="preserve"
985 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
986 x="840.9248"
987 y="250.07544"
988 id="text1185-9-7-1-1-8-1"><tspan
989 sodipodi:role="line"
990 x="840.9248"
991 y="250.07544"
992 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
993 id="tspan31345-4-0">Apr</tspan><tspan
994 sodipodi:role="line"
995 x="840.9248"
996 y="268.07211"
997 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
998 id="tspan49906-7-3">2022</tspan></text>
999 <text
1000 xml:space="preserve"
1001 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1002 x="1321.8608"
1003 y="250.07544"
1004 id="text1185-9-7-1-1-8-1-0"><tspan
1005 sodipodi:role="line"
1006 x="1321.8608"
1007 y="250.07544"
1008 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1009 id="tspan31345-4-0-4">Apr.</tspan><tspan
1010 sodipodi:role="line"
1011 x="1321.8608"
1012 y="268.07211"
1013 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1014 id="tspan49906-7-3-8">2024</tspan></text>
1015 <text
1016 xml:space="preserve"
1017 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1018 x="1561.8163"
1019 y="249.66977"
1020 id="text1185-9-7-1-1-8-1-0-4"><tspan
1021 sodipodi:role="line"
1022 x="1561.8163"
1023 y="249.66977"
1024 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1025 id="tspan31345-4-0-4-81">Apr.</tspan><tspan
1026 sodipodi:role="line"
1027 x="1561.8163"
1028 y="267.66644"
1029 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1030 id="tspan49906-7-3-8-2">2025</tspan></text>
1031 <text
1032 xml:space="preserve"
1033 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1034 x="1802.1477"
1035 y="250.26334"
1036 id="text1185-9-7-1-1-8-1-0-4-2"><tspan
1037 sodipodi:role="line"
1038 x="1802.1477"
1039 y="250.26334"
1040 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1041 id="tspan31345-4-0-4-81-5">Apr.</tspan><tspan
1042 sodipodi:role="line"
1043 x="1802.1477"
1044 y="268.26001"
1045 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1046 id="tspan49906-7-3-8-2-8">2026</tspan></text>
1047 <text
1048 xml:space="preserve"
1049 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1050 x="1081.4458"
1051 y="250.07544"
1052 id="text1185-9-7-1-1-8-1-0-2"><tspan
1053 sodipodi:role="line"
1054 x="1081.4458"
1055 y="250.07544"
1056 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1057 id="tspan31345-4-0-4-8">Apr.</tspan><tspan
1058 sodipodi:role="line"
1059 x="1081.4458"
1060 y="268.07211"
1061 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1062 id="tspan49906-7-3-8-3">2023</tspan></text>
1063 <text
1064 xml:space="preserve"
1065 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1066 x="602.51526"
1067 y="250.07544"
1068 id="text1185-9-7-1-1-8-1-7"><tspan
1069 sodipodi:role="line"
1070 x="602.51526"
1071 y="250.07544"
1072 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1073 id="tspan31345-4-0-5">Apr.</tspan><tspan
1074 sodipodi:role="line"
1075 x="602.51526"
1076 y="268.07211"
1077 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1078 id="tspan49906-7-3-6">2021</tspan></text>
1079 <text
1080 xml:space="preserve"
1081 style="font-weight:bold;font-size:42.5884px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1082 x="-16.290483"
1083 y="345.7359"
1084 id="text3116"><tspan
1085 sodipodi:role="line"
1086 id="tspan3114"
1087 x="-16.290483"
1088 y="345.7359" /></text>
1089 <path
1090 id="path29430"
1091 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1092 d="M 319.99936,219.99912 H 2300 Z" />
1093 <path
1094 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1095 d="m 360,219.99997 v 10.00004 0"
1096 id="path29548" />
1097 <path
1098 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1099 d="m 480,219.99996 v 10 0"
1100 id="path29548-5" />
1101 <path
1102 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1103 d="m 600,219.99992 v 10.00005 0"
1104 id="path29548-5-1" />
1105 <path
1106 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1107 d="m 720,220.00002 v 9.99999 0"
1108 id="path29548-5-1-3" />
1109 <path
1110 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1111 d="m 840,220.00002 v 9.99995 0"
1112 id="path29548-5-1-3-6" />
1113 <path
1114 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1115 d="m 960,220.00002 v 9.99999 0"
1116 id="path29548-5-1-3-6-3" />
1117 <path
1118 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1119 d="m 1080,220.00002 v 9.99999 0"
1120 id="path29548-5-1-3-6-3-1" />
1121 <path
1122 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1123 d="m 380,219.99997 v 5.00004 0"
1124 id="path29548-8"
1125 inkscape:transform-center-x="14.782001"
1126 inkscape:transform-center-y="-0.085282837" />
1127 <path
1128 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1129 d="m 400,219.99997 v 5.00004 0"
1130 id="path29548-8-5"
1131 inkscape:transform-center-x="14.782001"
1132 inkscape:transform-center-y="-0.085282837" />
1133 <path
1134 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.999997;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1135 d="m 420,219.99997 v 5 0"
1136 id="path29548-8-5-0"
1137 inkscape:transform-center-x="14.782001"
1138 inkscape:transform-center-y="-0.085282155" />
1139 <path
1140 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.999997;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1141 d="m 440,219.99997 v 5 0"
1142 id="path29548-8-5-0-6"
1143 inkscape:transform-center-x="14.782001"
1144 inkscape:transform-center-y="-0.085282155" />
1145 <path
1146 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1147 d="m 460,219.99997 v 5.00004 0"
1148 id="path29548-8-5-0-6-4-6"
1149 inkscape:transform-center-x="14.782001"
1150 inkscape:transform-center-y="-0.085282837" />
1151 <path
1152 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1153 d="m 500,219.99997 v 5.00004 0"
1154 id="path29548-8-5-0-6-4-6-2"
1155 inkscape:transform-center-x="14.782001"
1156 inkscape:transform-center-y="-0.085282837" />
1157 <path
1158 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.999997;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1159 d="m 520,219.99997 v 5 0"
1160 id="path29548-8-5-0-6-4-6-2-9"
1161 inkscape:transform-center-x="14.782001"
1162 inkscape:transform-center-y="-0.085282155" />
1163 <path
1164 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1165 d="m 540,219.99997 v 5.00004 0"
1166 id="path29548-8-5-0-6-4-6-2-9-0"
1167 inkscape:transform-center-x="14.782001"
1168 inkscape:transform-center-y="-0.085282837" />
1169 <path
1170 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1171 d="m 560,219.99997 v 5.00004 0"
1172 id="path29548-8-5-0-6-4-6-2-9-0-8"
1173 inkscape:transform-center-x="14.782001"
1174 inkscape:transform-center-y="-0.085282837" />
1175 <path
1176 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1177 d="m 580,219.99997 v 5.00004 0"
1178 id="path29548-8-5-0-6-4-6-2-9-0-8-1"
1179 inkscape:transform-center-x="14.782001"
1180 inkscape:transform-center-y="-0.085282837" />
1181 <path
1182 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1183 d="m 620.266,219.99997 v 5.00004 0"
1184 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3"
1185 inkscape:transform-center-x="14.782001"
1186 inkscape:transform-center-y="-0.085282837" />
1187 <path
1188 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1189 d="m 640,219.99997 v 5.00004 0"
1190 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1"
1191 inkscape:transform-center-x="14.782001"
1192 inkscape:transform-center-y="-0.085282837" />
1193 <path
1194 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1195 d="m 660,219.99997 v 5.00004 0"
1196 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9"
1197 inkscape:transform-center-x="14.782001"
1198 inkscape:transform-center-y="-0.085282837" />
1199 <path
1200 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1201 d="m 679.61073,219.99997 v 5.00004 0"
1202 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6"
1203 inkscape:transform-center-x="14.782001"
1204 inkscape:transform-center-y="-0.085282837" />
1205 <path
1206 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1207 d="m 700,219.99997 v 5.00004 0"
1208 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9"
1209 inkscape:transform-center-x="14.782001"
1210 inkscape:transform-center-y="-0.085282837" />
1211 <path
1212 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1213 d="m 740,219.99997 v 5.00004 0"
1214 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3"
1215 inkscape:transform-center-x="14.782001"
1216 inkscape:transform-center-y="-0.085282837" />
1217 <path
1218 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1219 d="m 760,219.99997 v 5.00004 0"
1220 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4"
1221 inkscape:transform-center-x="14.782001"
1222 inkscape:transform-center-y="-0.085282837" />
1223 <path
1224 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1225 d="m 780.36587,219.99997 v 5.00004 0"
1226 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0"
1227 inkscape:transform-center-x="14.782001"
1228 inkscape:transform-center-y="-0.085282837" />
1229 <path
1230 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1231 d="m 800,219.99997 v 5.00004 0"
1232 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4"
1233 inkscape:transform-center-x="14.782001"
1234 inkscape:transform-center-y="-0.085282837" />
1235 <path
1236 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1237 d="m 820,219.99997 v 5.00004 0"
1238 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6"
1239 inkscape:transform-center-x="14.782001"
1240 inkscape:transform-center-y="-0.085282837" />
1241 <path
1242 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1243 d="m 860,219.99997 v 5.00004 0"
1244 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2"
1245 inkscape:transform-center-x="14.782001"
1246 inkscape:transform-center-y="-0.085282837" />
1247 <path
1248 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1249 d="m 880,219.99997 v 5.00004 0"
1250 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2"
1251 inkscape:transform-center-x="14.782001"
1252 inkscape:transform-center-y="-0.085282837" />
1253 <path
1254 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1255 d="m 899.72384,219.99997 v 5.00004 0"
1256 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7"
1257 inkscape:transform-center-x="14.782001"
1258 inkscape:transform-center-y="-0.085282837" />
1259 <path
1260 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1261 d="m 920,219.99997 v 5.00004 0"
1262 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6"
1263 inkscape:transform-center-x="14.782001"
1264 inkscape:transform-center-y="-0.085282837" />
1265 <path
1266 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1267 d="m 940,219.99997 v 5.00004 0"
1268 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1"
1269 inkscape:transform-center-x="14.782001"
1270 inkscape:transform-center-y="-0.085282837" />
1271 <path
1272 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1273 d="m 980,219.99997 v 5.00004 0"
1274 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9"
1275 inkscape:transform-center-x="14.782001"
1276 inkscape:transform-center-y="-0.085282837" />
1277 <path
1278 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1279 d="m 1000,219.99997 v 5.00004 0"
1280 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9"
1281 inkscape:transform-center-x="14.782001"
1282 inkscape:transform-center-y="-0.085282837" />
1283 <path
1284 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1285 d="m 1020,219.99997 v 5.00004 0"
1286 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1"
1287 inkscape:transform-center-x="14.782001"
1288 inkscape:transform-center-y="-0.085282837" />
1289 <path
1290 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1291 d="m 1040,219.99997 v 5.00004 0"
1292 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4"
1293 inkscape:transform-center-x="14.782001"
1294 inkscape:transform-center-y="-0.085282837" />
1295 <path
1296 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1297 d="m 1059.7216,219.99997 v 5.00004 0"
1298 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9"
1299 inkscape:transform-center-x="-14.78205"
1300 inkscape:transform-center-y="-0.085282837" />
1301 <path
1302 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1303 d="m 1100,219.99997 v 5.00004 0"
1304 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0"
1305 inkscape:transform-center-x="14.782001"
1306 inkscape:transform-center-y="-0.085282837" />
1307 <path
1308 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1309 d="m 1120,219.99997 v 5.00004 0"
1310 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7"
1311 inkscape:transform-center-x="14.782001"
1312 inkscape:transform-center-y="-0.085282837" />
1313 <path
1314 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1315 d="m 1140,219.99997 v 5.00004 0"
1316 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5"
1317 inkscape:transform-center-x="14.782001"
1318 inkscape:transform-center-y="-0.085282837" />
1319 <path
1320 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1321 d="m 1160,219.99997 v 5.00004 0"
1322 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8"
1323 inkscape:transform-center-x="14.782001"
1324 inkscape:transform-center-y="-0.085282837" />
1325 <path
1326 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1327 d="m 1179.7216,219.99997 v 5.00004 0"
1328 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7"
1329 inkscape:transform-center-x="-14.78205"
1330 inkscape:transform-center-y="-0.085282837" />
1331 <path
1332 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1333 d="m 1320,219.99996 v 10 0"
1334 id="path29548-5-1-3-6-3-1-0-8" />
1335 <g
1336 id="g1267">
1337 <path
1338 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1339 d="m 1200,220.00002 v 9.99999 0"
1340 id="path29548-5-1-3-6-3-1-0" />
1341 <path
1342 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1343 d="m 1220,219.99997 v 5.00004 0"
1344 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5"
1345 inkscape:transform-center-x="14.782001"
1346 inkscape:transform-center-y="-0.085282837" />
1347 <path
1348 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1349 d="m 1240,219.99997 v 5.00004 0"
1350 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5"
1351 inkscape:transform-center-x="14.782001"
1352 inkscape:transform-center-y="-0.085282837" />
1353 <path
1354 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1355 d="m 1260,219.99997 v 5.00004 0"
1356 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2"
1357 inkscape:transform-center-x="14.782001"
1358 inkscape:transform-center-y="-0.085282837" />
1359 <path
1360 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1361 d="m 1280,219.99997 v 5.00004 0"
1362 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9"
1363 inkscape:transform-center-x="14.782001"
1364 inkscape:transform-center-y="-0.085282837" />
1365 <path
1366 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1367 d="m 1299.7216,219.99997 v 5.00004 0"
1368 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0"
1369 inkscape:transform-center-x="-14.78205"
1370 inkscape:transform-center-y="-0.085282837" />
1371 </g>
1372 <g
1373 id="g1267-4"
1374 transform="translate(240,-4e-5)">
1375 <path
1376 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1377 d="m 1200,220.00002 v 9.99999 0"
1378 id="path29548-5-1-3-6-3-1-0-3" />
1379 <path
1380 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1381 d="m 1220,219.99997 v 5.00004 0"
1382 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0"
1383 inkscape:transform-center-x="14.782001"
1384 inkscape:transform-center-y="-0.085282837" />
1385 <path
1386 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1387 d="m 1240,219.99997 v 5.00004 0"
1388 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3"
1389 inkscape:transform-center-x="14.782001"
1390 inkscape:transform-center-y="-0.085282837" />
1391 <path
1392 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1393 d="m 1260,219.99997 v 5.00004 0"
1394 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0"
1395 inkscape:transform-center-x="14.782001"
1396 inkscape:transform-center-y="-0.085282837" />
1397 <path
1398 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1399 d="m 1280,219.99997 v 5.00004 0"
1400 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9"
1401 inkscape:transform-center-x="14.782001"
1402 inkscape:transform-center-y="-0.085282837" />
1403 <path
1404 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1405 d="m 1299.7216,219.99997 v 5.00004 0"
1406 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2"
1407 inkscape:transform-center-x="-14.78205"
1408 inkscape:transform-center-y="-0.085282837" />
1409 </g>
1410 <g
1411 id="g1267-4-5"
1412 transform="translate(480,-5e-5)">
1413 <path
1414 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1415 d="m 1200,220.00002 v 9.99999 0"
1416 id="path29548-5-1-3-6-3-1-0-3-4" />
1417 <path
1418 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1419 d="m 1220,219.99997 v 5.00004 0"
1420 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-0"
1421 inkscape:transform-center-x="14.782001"
1422 inkscape:transform-center-y="-0.085282837" />
1423 <path
1424 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1425 d="m 1240,219.99997 v 5.00004 0"
1426 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-5"
1427 inkscape:transform-center-x="14.782001"
1428 inkscape:transform-center-y="-0.085282837" />
1429 <path
1430 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1431 d="m 1260,219.99997 v 5.00004 0"
1432 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-9"
1433 inkscape:transform-center-x="14.782001"
1434 inkscape:transform-center-y="-0.085282837" />
1435 <path
1436 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1437 d="m 1280,219.99997 v 5.00004 0"
1438 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-4"
1439 inkscape:transform-center-x="14.782001"
1440 inkscape:transform-center-y="-0.085282837" />
1441 <path
1442 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1443 d="m 1299.7216,219.99997 v 5.00004 0"
1444 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-6"
1445 inkscape:transform-center-x="-14.78205"
1446 inkscape:transform-center-y="-0.085282837" />
1447 </g>
1448 <g
1449 id="g1267-4-5-22"
1450 transform="translate(600,-4e-5)">
1451 <path
1452 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1453 d="m 1200,220.00002 v 9.99999 0"
1454 id="path29548-5-1-3-6-3-1-0-3-4-0" />
1455 <path
1456 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1457 d="m 1220,219.99997 v 5.00004 0"
1458 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-0-55"
1459 inkscape:transform-center-x="14.782001"
1460 inkscape:transform-center-y="-0.085282837" />
1461 <path
1462 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1463 d="m 1240,219.99997 v 5.00004 0"
1464 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-5-2"
1465 inkscape:transform-center-x="14.782001"
1466 inkscape:transform-center-y="-0.085282837" />
1467 <path
1468 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1469 d="m 1260,219.99997 v 5.00004 0"
1470 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-9-90"
1471 inkscape:transform-center-x="14.782001"
1472 inkscape:transform-center-y="-0.085282837" />
1473 <path
1474 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1475 d="m 1280,219.99997 v 5.00004 0"
1476 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-4-2"
1477 inkscape:transform-center-x="14.782001"
1478 inkscape:transform-center-y="-0.085282837" />
1479 <path
1480 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1481 d="m 1299.7216,219.99997 v 5.00004 0"
1482 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-6-8"
1483 inkscape:transform-center-x="-14.78205"
1484 inkscape:transform-center-y="-0.085282837" />
1485 </g>
1486 <g
1487 id="g1267-4-5-9"
1488 transform="translate(360,-4e-5)">
1489 <path
1490 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1491 d="m 1200,220.00002 v 9.99999 0"
1492 id="path29548-5-1-3-6-3-1-0-3-4-2" />
1493 <path
1494 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1495 d="m 1220,219.99997 v 5.00004 0"
1496 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-0-2"
1497 inkscape:transform-center-x="14.782001"
1498 inkscape:transform-center-y="-0.085282837" />
1499 <path
1500 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1501 d="m 1240,219.99997 v 5.00004 0"
1502 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-5-4"
1503 inkscape:transform-center-x="14.782001"
1504 inkscape:transform-center-y="-0.085282837" />
1505 <path
1506 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1507 d="m 1260,219.99997 v 5.00004 0"
1508 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-9-7"
1509 inkscape:transform-center-x="14.782001"
1510 inkscape:transform-center-y="-0.085282837" />
1511 <path
1512 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1513 d="m 1280,219.99997 v 5.00004 0"
1514 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-4-7"
1515 inkscape:transform-center-x="14.782001"
1516 inkscape:transform-center-y="-0.085282837" />
1517 <path
1518 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1519 d="m 1299.7216,219.99997 v 5.00004 0"
1520 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-6-5"
1521 inkscape:transform-center-x="-14.78205"
1522 inkscape:transform-center-y="-0.085282837" />
1523 </g>
1524 <path
1525 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1526 d="m 1800,219.99997 v 9.99999 0"
1527 id="path29548-5-1-3-6-3-1-0-3-4-2-0" />
1528 <path
1529 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1530 d="m 1340,219.99997 v 5.00004 0"
1531 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-3"
1532 inkscape:transform-center-x="14.782001"
1533 inkscape:transform-center-y="-0.085282837" />
1534 <path
1535 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1536 d="m 1360,219.99997 v 5.00004 0"
1537 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-0"
1538 inkscape:transform-center-x="14.782001"
1539 inkscape:transform-center-y="-0.085282837" />
1540 <path
1541 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1542 d="m 1380,219.99997 v 5.00004 0"
1543 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-3"
1544 inkscape:transform-center-x="14.782001"
1545 inkscape:transform-center-y="-0.085282837" />
1546 <path
1547 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1548 d="m 1400,219.99997 v 5.00004 0"
1549 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-0"
1550 inkscape:transform-center-x="14.782001"
1551 inkscape:transform-center-y="-0.085282837" />
1552 <path
1553 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1554 d="m 1419.7216,219.99997 v 5.00004 0"
1555 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-9"
1556 inkscape:transform-center-x="-14.78205"
1557 inkscape:transform-center-y="-0.085282837" />
1558 <text
1559 xml:space="preserve"
1560 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1561 x="1919.3904"
1562 y="249.86044"
1563 id="text1185-9-7-1-1-89-62"><tspan
1564 sodipodi:role="line"
1565 x="1919.3904"
1566 y="249.86044"
1567 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1568 id="tspan31345-7-6">Oct.</tspan><tspan
1569 sodipodi:role="line"
1570 x="1919.3904"
1571 y="267.85712"
1572 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1573 id="tspan49906-76-7">2026</tspan></text>
1574 <text
1575 xml:space="preserve"
1576 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1577 x="2159.3093"
1578 y="250.58356"
1579 id="text1185-9-7-1-1-89-6-5"><tspan
1580 sodipodi:role="line"
1581 x="2159.3093"
1582 y="250.58356"
1583 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1584 id="tspan31345-7-8-6">Oct.</tspan><tspan
1585 sodipodi:role="line"
1586 x="2159.3093"
1587 y="268.58023"
1588 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1589 id="tspan49906-76-0-9">2027</tspan></text>
1590 <text
1591 xml:space="preserve"
1592 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1593 x="2041.8163"
1594 y="249.66977"
1595 id="text1185-9-7-1-1-8-1-0-4-8"><tspan
1596 sodipodi:role="line"
1597 x="2041.8163"
1598 y="249.66977"
1599 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1600 id="tspan31345-4-0-4-81-7">Apr.</tspan><tspan
1601 sodipodi:role="line"
1602 x="2041.8163"
1603 y="267.66644"
1604 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1605 id="tspan49906-7-3-8-2-2">2027</tspan></text>
1606 <text
1607 xml:space="preserve"
1608 style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
1609 x="2282.1477"
1610 y="250.26334"
1611 id="text1185-9-7-1-1-8-1-0-4-2-8"><tspan
1612 sodipodi:role="line"
1613 x="2282.1477"
1614 y="250.26334"
1615 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1616 id="tspan31345-4-0-4-81-5-2">Apr.</tspan><tspan
1617 sodipodi:role="line"
1618 x="2282.1477"
1619 y="268.26001"
1620 style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;stroke:none"
1621 id="tspan49906-7-3-8-2-8-9">2028</tspan></text>
1622 <g
1623 id="g1267-4-9"
1624 transform="translate(720,-3e-5)">
1625 <path
1626 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1627 d="m 1200,220.00002 v 9.99999 0"
1628 id="path29548-5-1-3-6-3-1-0-3-6" />
1629 <path
1630 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1631 d="m 1220,219.99997 v 5.00004 0"
1632 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-02"
1633 inkscape:transform-center-x="14.782001"
1634 inkscape:transform-center-y="-0.085282837" />
1635 <path
1636 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1637 d="m 1240,219.99997 v 5.00004 0"
1638 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-7"
1639 inkscape:transform-center-x="14.782001"
1640 inkscape:transform-center-y="-0.085282837" />
1641 <path
1642 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1643 d="m 1260,219.99997 v 5.00004 0"
1644 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-6"
1645 inkscape:transform-center-x="14.782001"
1646 inkscape:transform-center-y="-0.085282837" />
1647 <path
1648 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1649 d="m 1280,219.99997 v 5.00004 0"
1650 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-1"
1651 inkscape:transform-center-x="14.782001"
1652 inkscape:transform-center-y="-0.085282837" />
1653 <path
1654 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1655 d="m 1299.7216,219.99997 v 5.00004 0"
1656 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-3"
1657 inkscape:transform-center-x="-14.78205"
1658 inkscape:transform-center-y="-0.085282837" />
1659 </g>
1660 <g
1661 id="g1267-4-5-2"
1662 transform="translate(960,-4e-5)">
1663 <path
1664 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1665 d="m 1200,220.00002 v 9.99999 0"
1666 id="path29548-5-1-3-6-3-1-0-3-4-1" />
1667 <path
1668 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1669 d="m 1220,219.99997 v 5.00004 0"
1670 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-0-5"
1671 inkscape:transform-center-x="14.782001"
1672 inkscape:transform-center-y="-0.085282837" />
1673 <path
1674 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1675 d="m 1240,219.99997 v 5.00004 0"
1676 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-5-9"
1677 inkscape:transform-center-x="14.782001"
1678 inkscape:transform-center-y="-0.085282837" />
1679 <path
1680 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1681 d="m 1260,219.99997 v 5.00004 0"
1682 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-9-9"
1683 inkscape:transform-center-x="14.782001"
1684 inkscape:transform-center-y="-0.085282837" />
1685 <path
1686 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1687 d="m 1280,219.99997 v 5.00004 0"
1688 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-4-1"
1689 inkscape:transform-center-x="14.782001"
1690 inkscape:transform-center-y="-0.085282837" />
1691 <path
1692 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1693 d="m 1299.7216,219.99997 v 5.00004 0"
1694 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-6-4"
1695 inkscape:transform-center-x="-14.78205"
1696 inkscape:transform-center-y="-0.085282837" />
1697 </g>
1698 <g
1699 id="g1267-4-5-9-9"
1700 transform="translate(840,-3e-5)">
1701 <path
1702 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1703 d="m 1200,220.00002 v 9.99999 0"
1704 id="path29548-5-1-3-6-3-1-0-3-4-2-1" />
1705 <path
1706 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1707 d="m 1220,219.99997 v 5.00004 0"
1708 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-0-5-0-0-2-0"
1709 inkscape:transform-center-x="14.782001"
1710 inkscape:transform-center-y="-0.085282837" />
1711 <path
1712 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1713 d="m 1240,219.99997 v 5.00004 0"
1714 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-7-5-3-5-4-7"
1715 inkscape:transform-center-x="14.782001"
1716 inkscape:transform-center-y="-0.085282837" />
1717 <path
1718 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1719 d="m 1260,219.99997 v 5.00004 0"
1720 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-5-2-0-9-7-5"
1721 inkscape:transform-center-x="14.782001"
1722 inkscape:transform-center-y="-0.085282837" />
1723 <path
1724 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1725 d="m 1280,219.99997 v 5.00004 0"
1726 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-8-9-9-4-7-8"
1727 inkscape:transform-center-x="14.782001"
1728 inkscape:transform-center-y="-0.085282837" />
1729 <path
1730 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1731 d="m 1299.7216,219.99997 v 5.00004 0"
1732 id="path29548-8-5-0-6-4-6-2-9-0-8-1-3-1-9-6-9-3-4-0-4-6-2-2-7-6-1-9-9-1-4-9-7-0-2-6-5-7"
1733 inkscape:transform-center-x="-14.78205"
1734 inkscape:transform-center-y="-0.085282837" />
1735 </g>
1736 <path
1737 style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
1738 d="m 2280,219.99998 v 9.99999 0"
1739 id="path29548-5-1-3-6-3-1-0-3-4-2-0-0" />
1740 </g>
1741 <style
1742 type="text/css"
1743 id="style1021"> .st0{fill:#4A97D2;} .st1{fill:#333333;} </style>
1744</svg>
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index c8c1381cb9..0fc92550a5 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -4,7 +4,7 @@
4System Requirements 4System Requirements
5******************* 5*******************
6 6
7Welcome to the Yocto Project Reference Manual! This manual provides 7Welcome to the Yocto Project Reference Manual. This manual provides
8reference information for the current release of the Yocto Project, and 8reference information for the current release of the Yocto Project, and
9is most effectively used after you have an understanding of the basics 9is most effectively used after you have an understanding of the basics
10of the Yocto Project. The manual is neither meant to be read as a 10of the Yocto Project. The manual is neither meant to be read as a
@@ -29,46 +29,77 @@ and conceptual information in the :doc:`/overview-manual/index`.
29 For more information about the Yocto Project Documentation set, see 29 For more information about the Yocto Project Documentation set, see
30 the :ref:`ref-manual/resources:links and related documentation` section. 30 the :ref:`ref-manual/resources:links and related documentation` section.
31 31
32.. _detailed-supported-distros: 32Minimum Free Disk Space
33=======================
34
35To build an image such as ``core-image-sato`` for the ``qemux86-64`` machine,
36you need a system with at least &MIN_DISK_SPACE; Gbytes of free disk space.
37However, much more disk space will be necessary to build more complex images,
38to run multiple builds and to cache build artifacts, improving build efficiency.
39
40If you have a shortage of disk space, see the ":doc:`/dev-manual/disk-space`"
41section of the Development Tasks Manual.
42
43.. _system-requirements-minimum-ram:
44
45Minimum System RAM
46==================
47
48You will manage to build an image such as ``core-image-sato`` for the
49``qemux86-64`` machine with as little as &MIN_RAM; Gbytes of RAM on an old
50system with 4 CPU cores, but your builds will be much faster on a system with
51as much RAM and as many CPU cores as possible.
52
53.. _system-requirements-supported-distros:
33 54
34Supported Linux Distributions 55Supported Linux Distributions
35============================= 56=============================
36 57
37Currently, the Yocto Project is supported on the following 58Currently, the &DISTRO; release ("&DISTRO_NAME;") of the Yocto Project is
38distributions: 59supported on the following distributions:
39 60
40- Ubuntu 16.04 (LTS) 61- Ubuntu 20.04 (LTS)
41 62
42- Ubuntu 18.04 (LTS) 63- Ubuntu 22.04 (LTS)
43 64
44- Ubuntu 20.04 65- Fedora 38
45 66
46- Fedora 30 67- CentOS Stream 8
47 68
48- Fedora 31 69- Debian GNU/Linux 11 (Bullseye)
49 70
50- Fedora 32 71- Debian GNU/Linux 12 (Bookworm)
51 72
52- CentOS 7.x 73- OpenSUSE Leap 15.4
53 74
54- CentOS 8.x 75- AlmaLinux 8
55 76
56- Debian GNU/Linux 8.x (Jessie) 77- AlmaLinux 9
57 78
58- Debian GNU/Linux 9.x (Stretch) 79- Rocky 9
59 80
60- Debian GNU/Linux 10.x (Buster) 81The following distribution versions are still tested, even though the
82organizations publishing them no longer make updates publicly available:
61 83
62- OpenSUSE Leap 15.1 84- Ubuntu 18.04 (LTS)
85
86- Ubuntu 23.04
87
88Note that the Yocto Project doesn't have access to private updates
89that some of these versions may have. Therefore, our testing has
90limited value if you have access to such updates.
63 91
92Finally, here are the distribution versions which were previously
93tested on former revisions of "&DISTRO_NAME;", but no longer are:
94
95*This list is currently empty*
64 96
65.. note:: 97.. note::
66 98
67 - While the Yocto Project Team attempts to ensure all Yocto Project 99 - While the Yocto Project Team attempts to ensure all Yocto Project
68 releases are one hundred percent compatible with each officially 100 releases are one hundred percent compatible with each officially
69 supported Linux distribution, instances might exist where you 101 supported Linux distribution, you may still encounter problems
70 encounter a problem while using the Yocto Project on a specific 102 that happen only with a specific distribution.
71 distribution.
72 103
73 - Yocto Project releases are tested against the stable Linux 104 - Yocto Project releases are tested against the stable Linux
74 distributions in the above list. The Yocto Project should work 105 distributions in the above list. The Yocto Project should work
@@ -79,24 +110,29 @@ distributions:
79 has no plans to support rolling-releases or development 110 has no plans to support rolling-releases or development
80 distributions due to their constantly changing nature. We welcome 111 distributions due to their constantly changing nature. We welcome
81 patches and bug reports, but keep in mind that our priority is on 112 patches and bug reports, but keep in mind that our priority is on
82 the supported platforms listed below. 113 the supported platforms listed above.
114
115 - If your Linux distribution is not in the above list, we recommend to
116 get the :term:`buildtools` or :term:`buildtools-extended` tarballs
117 containing the host tools required by your Yocto Project release,
118 typically by running ``scripts/install-buildtools`` as explained in
119 the ":ref:`system-requirements-buildtools`" section.
83 120
84 - You may use Windows Subsystem For Linux v2 to set up a build host 121 - You may use Windows Subsystem For Linux v2 to set up a build host
85 using Windows 10, but validation is not performed against build 122 using Windows 10 or later, or Windows Server 2019 or later, but validation
86 hosts using WSLv2. 123 is not performed against build hosts using WSL 2.
87 124
88 - The Yocto Project is not compatible with WSLv1, it is 125 See the
89 compatible but not officially supported nor validated with 126 :ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`
90 WSLv2, if you still decide to use WSL please upgrade to WSLv2. 127 section in the Yocto Project Development Tasks Manual for more information.
91 128
92 - If you encounter problems, please go to :yocto_bugs:`Yocto Project 129 - If you encounter problems, please go to :yocto_bugs:`Yocto Project
93 Bugzilla <>` and submit a bug. We are 130 Bugzilla <>` and submit a bug. We are
94 interested in hearing about your experience. For information on 131 interested in hearing about your experience. For information on
95 how to submit a bug, see the Yocto Project 132 how to submit a bug, see the Yocto Project
96 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>` 133 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
97 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`" 134 and the ":doc:`../contributor-guide/report-defect`"
98 section in the Yocto Project Development Tasks Manual. 135 section in the Yocto Project and OpenEmbedded Contributor Guide.
99
100 136
101Required Packages for the Build Host 137Required Packages for the Build Host
102==================================== 138====================================
@@ -111,290 +147,240 @@ function.
111Ubuntu and Debian 147Ubuntu and Debian
112----------------- 148-----------------
113 149
114The following list shows the required packages by function given a 150Here are the packages needed to build an image on a headless system
115supported Ubuntu or Debian Linux distribution: 151with a supported Ubuntu or Debian Linux distribution::
152
153 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
116 154
117.. note:: 155.. note::
118 156
119 - If your build system has the ``oss4-dev`` package installed, you 157 - If your build system has the ``oss4-dev`` package installed, you
120 might experience QEMU build failures due to the package installing 158 might experience QEMU build failures due to the package installing
121 its own custom ``/usr/include/linux/soundcard.h`` on the Debian 159 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
122 system. If you run into this situation, either of the following 160 system. If you run into this situation, try either of these solutions::
123 solutions exist:
124 ::
125
126 $ sudo apt-get build-dep qemu
127 $ sudo apt-get remove oss4-dev
128
129 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
130 available via ``apt-get``.
131 ::
132
133 $ sudo pip3 install GitPython pylint==1.9.5
134 161
135- *Essentials:* Packages needed to build an image on a headless system: 162 $ sudo apt build-dep qemu
136 :: 163 $ sudo apt remove oss4-dev
137 164
138 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 165Here are the packages needed to build Project documentation manuals::
139 166
140- *Documentation:* Packages needed if you are going to build out the 167 $ sudo apt install git make inkscape texlive-latex-extra
141 Yocto Project documentation manuals: 168 $ sudo apt install sphinx python3-saneyaml python3-sphinx-rtd-theme
142 ::
143
144 $ sudo apt-get install make python3-pip
145 &PIP3_HOST_PACKAGES_DOC;
146
147 .. note::
148
149 It is currently not possible to build out documentation from Debian 8
150 (Jessie) because of outdated ``pip3`` and ``python3``. ``python3-sphinx``
151 is too outdated.
152 169
153Fedora Packages 170Fedora Packages
154--------------- 171---------------
155 172
156The following list shows the required packages by function given a 173Here are the packages needed to build an image on a headless system
157supported Fedora Linux distribution: 174with a supported Fedora Linux distribution::
158
159- *Essentials:* Packages needed to build an image for a headless
160 system:
161 ::
162 175
163 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; 176 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
164 177
165- *Documentation:* Packages needed if you are going to build out the 178Here are the packages needed to build Project documentation manuals::
166 Yocto Project documentation manuals:
167 ::
168 179
169 $ sudo dnf install make python3-pip which 180 $ sudo dnf install git make python3-pip which inkscape texlive-fncychap
170 &PIP3_HOST_PACKAGES_DOC; 181 &PIP3_HOST_PACKAGES_DOC;
171 182
172openSUSE Packages 183openSUSE Packages
173----------------- 184-----------------
174 185
175The following list shows the required packages by function given a 186Here are the packages needed to build an image on a headless system
176supported openSUSE Linux distribution: 187with a supported openSUSE distribution::
177
178- *Essentials:* Packages needed to build an image for a headless
179 system:
180 ::
181
182 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
183
184- *Documentation:* Packages needed if you are going to build out the
185 Yocto Project documentation manuals:
186 ::
187
188 $ sudo zypper install make python3-pip which
189 &PIP3_HOST_PACKAGES_DOC;
190
191
192CentOS-7 Packages
193-----------------
194
195The following list shows the required packages by function given a
196supported CentOS-7 Linux distribution:
197 188
198- *Essentials:* Packages needed to build an image for a headless 189 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
199 system:
200 ::
201 190
202 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; 191Here are the packages needed to build Project documentation manuals::
203 192
204 .. note:: 193 $ sudo zypper install git make python3-pip which inkscape texlive-fncychap
205 194 &PIP3_HOST_PACKAGES_DOC;
206 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
207 a collection of packages from Fedora built on RHEL/CentOS for
208 easy installation of packages not included in enterprise Linux
209 by default. You need to install these packages separately.
210 195
211 - The ``makecache`` command consumes additional Metadata from
212 ``epel-release``.
213 196
214- *Documentation:* Packages needed if you are going to build out the 197AlmaLinux Packages
215 Yocto Project documentation manuals: 198------------------
216 ::
217 199
218 $ sudo yum install make python3-pip which 200Here are the packages needed to build an image on a headless system
219 &PIP3_HOST_PACKAGES_DOC; 201with a supported AlmaLinux distribution::
220 202
221CentOS-8 Packages 203 $ sudo dnf install &ALMALINUX_HOST_PACKAGES_ESSENTIAL;
222-----------------
223 204
224The following list shows the required packages by function given a 205.. note::
225supported CentOS-8 Linux distribution:
226
227- *Essentials:* Packages needed to build an image for a headless
228 system:
229 ::
230
231 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
232 206
233 .. note:: 207 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
208 a collection of packages from Fedora built on RHEL/CentOS for
209 easy installation of packages not included in enterprise Linux
210 by default. You need to install these packages separately.
234 211
235 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is 212 - The ``PowerTools/CRB`` repo provides additional packages such as
236 a collection of packages from Fedora built on RHEL/CentOS for 213 ``rpcgen`` and ``texinfo``.
237 easy installation of packages not included in enterprise Linux
238 by default. You need to install these packages separately.
239 214
240 - The ``PowerTools`` repo provides additional packages such as 215 - The ``makecache`` command consumes additional Metadata from
241 ``rpcgen`` and ``texinfo``. 216 ``epel-release``.
242 217
243 - The ``makecache`` command consumes additional Metadata from 218Here are the packages needed to build Project documentation manuals::
244 ``epel-release``.
245 219
246- *Documentation:* Packages needed if you are going to build out the 220 $ sudo dnf install git make python3-pip which inkscape texlive-fncychap
247 Yocto Project documentation manuals: 221 &PIP3_HOST_PACKAGES_DOC;
248 ::
249 222
250 $ sudo dnf install make python3-pip which 223.. _system-requirements-buildtools:
251 &PIP3_HOST_PACKAGES_DOC;
252 224
253Required Git, tar, Python and gcc Versions 225Required Git, tar, Python, make and gcc Versions
254========================================== 226================================================
255 227
256In order to use the build system, your host development system must meet 228In order to use the build system, your host development system must meet
257the following version requirements for Git, tar, and Python: 229the following version requirements for Git, tar, and Python:
258 230
259- Git 1.8.3.1 or greater 231- Git &MIN_GIT_VERSION; or greater
232
233- tar &MIN_TAR_VERSION; or greater
260 234
261- tar 1.28 or greater 235- Python &MIN_PYTHON_VERSION; or greater
262 236
263- Python 3.5.0 or greater 237- GNU make &MIN_MAKE_VERSION; or greater
264 238
265If your host development system does not meet all these requirements, 239If your host development system does not meet all these requirements,
266you can resolve this by installing a ``buildtools`` tarball that 240you can resolve this by installing a :term:`buildtools` tarball that
267contains these tools. You can get the tarball one of two ways: download 241contains these tools. You can either download a pre-built tarball or
268a pre-built tarball or use BitBake to build the tarball. 242use BitBake to build one.
269 243
270In addition, your host development system must meet the following 244In addition, your host development system must meet the following
271version requirement for gcc: 245version requirement for gcc:
272 246
273- gcc 5.0 or greater 247- gcc &MIN_GCC_VERSION; or greater
274 248
275If your host development system does not meet this requirement, you can 249If your host development system does not meet this requirement, you can
276resolve this by installing a ``buildtools-extended`` tarball that 250resolve this by installing a :term:`buildtools-extended` tarball that
277contains additional tools, the equivalent of ``buildtools-essential``. 251contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
252package.
253
254For systems with a broken make version (e.g. make 4.2.1 without patches) but
255where the rest of the host tools are usable, you can use the :term:`buildtools-make`
256tarball instead.
257
258In the sections that follow, three different methods will be described for
259installing the :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make`
260toolset.
278 261
279Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script 262Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
280-------------------------------------------------------------------------------- 263--------------------------------------------------------------------------------
281 264
282The ``install-buildtools`` script is the easiest of the three methods by 265The ``install-buildtools`` script is the easiest of the three methods by
283which you can get these tools. It downloads a pre-built buildtools 266which you can get these tools. It downloads a pre-built :term:`buildtools`
284installer and automatically installs the tools for you: 267installer and automatically installs the tools for you:
285 268
2861. Execute the ``install-buildtools`` script. Here is an example: 269#. Execute the ``install-buildtools`` script. Here is an example::
287 ::
288 270
289 $ cd poky 271 $ cd poky
290 $ scripts/install-buildtools --without-extended-buildtools \ 272 $ scripts/install-buildtools \
273 --without-extended-buildtools \
291 --base-url &YOCTO_DL_URL;/releases/yocto \ 274 --base-url &YOCTO_DL_URL;/releases/yocto \
292 --release yocto-&DISTRO; \ 275 --release yocto-&DISTRO; \
293 --installer-version &DISTRO; 276 --installer-version &DISTRO;
294 277
295 During execution, the buildtools tarball will be downloaded, the 278 During execution, the :term:`buildtools` tarball will be downloaded, the
296 checksum of the download will be verified, the installer will be run 279 checksum of the download will be verified, the installer will be run
297 for you, and some basic checks will be run to to make sure the 280 for you, and some basic checks will be run to make sure the
298 installation is functional. 281 installation is functional.
299 282
300 To avoid the need of ``sudo`` privileges, the ``install-buildtools`` 283 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
301 script will by default tell the installer to install in: 284 script will by default tell the installer to install in::
302 ::
303 285
304 /path/to/poky/buildtools 286 /path/to/poky/buildtools
305 287
306 If your host development system needs the additional tools provided 288 If your host development system needs the additional tools provided
307 in the ``buildtools-extended`` tarball, you can instead execute the 289 in the :term:`buildtools-extended` tarball, you can instead execute the
308 ``install-buildtools`` script with the default parameters: 290 ``install-buildtools`` script with the default parameters::
309 ::
310 291
311 $ cd poky 292 $ cd poky
312 $ scripts/install-buildtools 293 $ scripts/install-buildtools
313 294
3142. Source the tools environment setup script by using a command like the 295 Alternatively if your host development system has a broken ``make``
315 following: 296 version such that you only need a known good version of ``make``,
316 :: 297 you can use the ``--make-only`` option::
317 298
318 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux 299 $ cd poky
300 $ scripts/install-buildtools --make-only
319 301
320 Of course, you need to supply your installation directory and be sure to 302#. Source the tools environment setup script by using a command like the
321 use the right file (i.e. i586 or x86_64). 303 following::
304
305 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
322 306
323 After you have sourced the setup script, the tools are added to 307 After you have sourced the setup script, the tools are added to
324 ``PATH`` and any other environment variables required to run the 308 ``PATH`` and any other environment variables required to run the
325 tools are initialized. The results are working versions versions of 309 tools are initialized. The results are working versions versions of
326 Git, tar, Python and ``chrpath``. And in the case of the 310 Git, tar, Python and ``chrpath``. And in the case of the
327 ``buildtools-extended`` tarball, additional working versions of tools 311 :term:`buildtools-extended` tarball, additional working versions of tools
328 including ``gcc``, ``make`` and the other tools included in 312 including ``gcc``, ``make`` and the other tools included in
329 ``packagegroup-core-buildessential``. 313 ``packagegroup-core-buildessential``.
330 314
331Downloading a Pre-Built ``buildtools`` Tarball 315Downloading a Pre-Built ``buildtools`` Tarball
332---------------------------------------------- 316----------------------------------------------
333 317
334Downloading and running a pre-built buildtools installer is the easiest 318If you would prefer not to use the ``install-buildtools`` script, you can instead
335of the two methods by which you can get these tools: 319download and run a pre-built :term:`buildtools` installer yourself with the following
320steps:
336 321
3371. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ 322#. Go to :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/`, locate and
323 download the ``.sh`` file corresponding to your host architecture
324 and to :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make`.
338 325
3392. Execute the installation script. Here is an example for the 326#. Execute the installation script. Here is an example for the
340 traditional installer: 327 traditional installer::
341 ::
342 328
343 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 329 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
344 330
345 Here is an example for the extended installer: 331 Here is an example for the extended installer::
346 ::
347 332
348 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 333 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
349 334
335 An example for the make-only installer::
336
337 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh
338
350 During execution, a prompt appears that allows you to choose the 339 During execution, a prompt appears that allows you to choose the
351 installation directory. For example, you could choose the following: 340 installation directory. For example, you could choose the following:
352 ``/home/your-username/buildtools`` 341 ``/home/your-username/buildtools``
353 342
3543. Source the tools environment setup script by using a command like the 343#. As instructed by the installer script, you will have to source the tools
355 following: 344 environment setup script::
356 ::
357 345
358 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux 346 $ source /home/your_username/buildtools/environment-setup-x86_64-pokysdk-linux
359
360 Of
361 course, you need to supply your installation directory and be sure to
362 use the right file (i.e. i585 or x86-64).
363 347
364 After you have sourced the setup script, the tools are added to 348 After you have sourced the setup script, the tools are added to
365 ``PATH`` and any other environment variables required to run the 349 ``PATH`` and any other environment variables required to run the
366 tools are initialized. The results are working versions versions of 350 tools are initialized. The results are working versions versions of
367 Git, tar, Python and ``chrpath``. And in the case of the 351 Git, tar, Python and ``chrpath``. And in the case of the
368 ``buildtools-extended`` tarball, additional working versions of tools 352 :term:`buildtools-extended` tarball, additional working versions of tools
369 including ``gcc``, ``make`` and the other tools included in 353 including ``gcc``, ``make`` and the other tools included in
370 ``packagegroup-core-buildessential``. 354 ``packagegroup-core-buildessential``.
371 355
372Building Your Own ``buildtools`` Tarball 356Building Your Own ``buildtools`` Tarball
373---------------------------------------- 357----------------------------------------
374 358
375Building and running your own buildtools installer applies only when you 359Building and running your own :term:`buildtools` installer applies only when you
376have a build host that can already run BitBake. In this case, you use 360have a build host that can already run BitBake. In this case, you use
377that machine to build the ``.sh`` file and then take steps to transfer 361that machine to build the ``.sh`` file and then take steps to transfer
378and run it on a machine that does not meet the minimal Git, tar, and 362and run it on a machine that does not meet the minimal Git, tar, and
379Python (or gcc) requirements. 363Python (or gcc) requirements.
380 364
381Here are the steps to take to build and run your own buildtools 365Here are the steps to take to build and run your own :term:`buildtools`
382installer: 366installer:
383 367
3841. On the machine that is able to run BitBake, be sure you have set up 368#. On the machine that is able to run BitBake, be sure you have set up
385 your build environment with the setup script 369 your build environment with the setup script
386 (:ref:`structure-core-script`). 370 (:ref:`structure-core-script`).
387 371
3882. Run the BitBake command to build the tarball: 372#. Run the BitBake command to build the tarball::
389 ::
390 373
391 $ bitbake buildtools-tarball 374 $ bitbake buildtools-tarball
392 375
393 or run the BitBake command to build the extended tarball: 376 or to build the extended tarball::
394 ::
395 377
396 $ bitbake buildtools-extended-tarball 378 $ bitbake buildtools-extended-tarball
397 379
380 or to build the make-only tarball::
381
382 $ bitbake buildtools-make-tarball
383
398 .. note:: 384 .. note::
399 385
400 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines 386 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
@@ -403,40 +389,37 @@ installer:
403 Once the build completes, you can find the ``.sh`` file that installs 389 Once the build completes, you can find the ``.sh`` file that installs
404 the tools in the ``tmp/deploy/sdk`` subdirectory of the 390 the tools in the ``tmp/deploy/sdk`` subdirectory of the
405 :term:`Build Directory`. The installer file has the string 391 :term:`Build Directory`. The installer file has the string
406 "buildtools" (or "buildtools-extended") in the name. 392 "buildtools" or "buildtools-extended" in the name.
407 393
4083. Transfer the ``.sh`` file from the build host to the machine that 394#. Transfer the ``.sh`` file from the build host to the machine that
409 does not meet the Git, tar, or Python (or gcc) requirements. 395 does not meet the Git, tar, or Python (or gcc) requirements.
410 396
4114. On the machine that does not meet the requirements, run the ``.sh`` 397#. On this machine, run the ``.sh`` file to install the tools. Here is an
412 file to install the tools. Here is an example for the traditional 398 example for the traditional installer::
413 installer:
414 ::
415 399
416 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 400 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
417 401
418 Here is an example for the extended installer: 402 For the extended installer::
419 ::
420 403
421 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 404 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
422 405
406 And for the make-only installer::
407
408 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh
409
423 During execution, a prompt appears that allows you to choose the 410 During execution, a prompt appears that allows you to choose the
424 installation directory. For example, you could choose the following: 411 installation directory. For example, you could choose the following:
425 ``/home/your_username/buildtools`` 412 ``/home/your_username/buildtools``
426 413
4275. Source the tools environment setup script by using a command like the 414#. Source the tools environment setup script by using a command like the
428 following: 415 following::
429 ::
430 416
431 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux 417 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
432 418
433 Of course, you need to supply your installation directory and be sure to
434 use the right file (i.e. i586 or x86_64).
435
436 After you have sourced the setup script, the tools are added to 419 After you have sourced the setup script, the tools are added to
437 ``PATH`` and any other environment variables required to run the 420 ``PATH`` and any other environment variables required to run the
438 tools are initialized. The results are working versions versions of 421 tools are initialized. The results are working versions versions of
439 Git, tar, Python and ``chrpath``. And in the case of the 422 Git, tar, Python and ``chrpath``. And in the case of the
440 ``buildtools-extended`` tarball, additional working versions of tools 423 :term:`buildtools-extended` tarball, additional working versions of tools
441 including ``gcc``, ``make`` and the other tools included in 424 including ``gcc``, ``make`` and the other tools included in
442 ``packagegroup-core-buildessential``. 425 ``packagegroup-core-buildessential``.
diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index 9fe1c296aa..c28cd7a94a 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -14,8 +14,8 @@ Normal Recipe Build Tasks
14 14
15The following sections describe normal tasks associated with building a 15The following sections describe normal tasks associated with building a
16recipe. For more information on tasks and dependencies, see the 16recipe. For more information on tasks and dependencies, see the
17":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and 17":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
18":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the 18":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
19BitBake User Manual. 19BitBake User Manual.
20 20
21.. _ref-tasks-build: 21.. _ref-tasks-build:
@@ -36,7 +36,7 @@ directory set to ``${``\ :term:`B`\ ``}``.
36 36
37The default behavior of this task is to run the ``oe_runmake`` function 37The default behavior of this task is to run the ``oe_runmake`` function
38if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. 38if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found.
39If no such file is found, the ``do_compile`` task does nothing. 39If no such file is found, the :ref:`ref-tasks-compile` task does nothing.
40 40
41.. _ref-tasks-compile_ptest_base: 41.. _ref-tasks-compile_ptest_base:
42 42
@@ -57,8 +57,8 @@ the current working directory set to ``${``\ :term:`B`\ ``}``.
57The default behavior of this task is to run ``oe_runmake clean`` if a 57The default behavior of this task is to run ``oe_runmake clean`` if a
58makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and 58makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and
59:term:`CLEANBROKEN` is not set to "1". If no such 59:term:`CLEANBROKEN` is not set to "1". If no such
60file is found or the ``CLEANBROKEN`` variable is set to "1", the 60file is found or the :term:`CLEANBROKEN` variable is set to "1", the
61``do_configure`` task does nothing. 61:ref:`ref-tasks-configure` task does nothing.
62 62
63.. _ref-tasks-configure_ptest_base: 63.. _ref-tasks-configure_ptest_base:
64 64
@@ -78,10 +78,10 @@ task runs with the current working directory set to
78``${``\ :term:`B`\ ``}``. 78``${``\ :term:`B`\ ``}``.
79 79
80Recipes implementing this task should inherit the 80Recipes implementing this task should inherit the
81:ref:`deploy <ref-classes-deploy>` class and should write the output 81:ref:`ref-classes-deploy` class and should write the output
82to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be 82to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be
83confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up 83confused with ``${DEPLOY_DIR}``. The :ref:`ref-classes-deploy` class sets up
84``do_deploy`` as a shared state (sstate) task that can be accelerated 84:ref:`ref-tasks-deploy` as a shared state (sstate) task that can be accelerated
85through sstate use. The sstate mechanism takes care of copying the 85through sstate use. The sstate mechanism takes care of copying the
86output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. 86output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
87 87
@@ -90,21 +90,19 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
90 Do not write the output directly to ``${DEPLOY_DIR_IMAGE}``, as this causes 90 Do not write the output directly to ``${DEPLOY_DIR_IMAGE}``, as this causes
91 the sstate mechanism to malfunction. 91 the sstate mechanism to malfunction.
92 92
93The ``do_deploy`` task is not added as a task by default and 93The :ref:`ref-tasks-deploy` task is not added as a task by default and
94consequently needs to be added manually. If you want the task to run 94consequently needs to be added manually. If you want the task to run
95after :ref:`ref-tasks-compile`, you can add it by doing 95after :ref:`ref-tasks-compile`, you can add it by doing
96the following: 96the following::
97::
98 97
99 addtask deploy after do_compile 98 addtask deploy after do_compile
100 99
101Adding ``do_deploy`` after other tasks works the same way. 100Adding :ref:`ref-tasks-deploy` after other tasks works the same way.
102 101
103.. note:: 102.. note::
104 103
105 You do not need to add ``before do_build`` to the ``addtask`` command 104 You do not need to add ``before do_build`` to the ``addtask`` command
106 (though it is harmless), because the ``base`` class contains the following: 105 (though it is harmless), because the :ref:`ref-classes-base` class contains the following::
107 ::
108 106
109 do_build[recrdeptask] += "do_deploy" 107 do_build[recrdeptask] += "do_deploy"
110 108
@@ -112,7 +110,7 @@ Adding ``do_deploy`` after other tasks works the same way.
112 See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" 110 See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
113 section in the BitBake User Manual for more information. 111 section in the BitBake User Manual for more information.
114 112
115If the ``do_deploy`` task re-executes, any previous output is removed 113If the :ref:`ref-tasks-deploy` task re-executes, any previous output is removed
116(i.e. "cleaned"). 114(i.e. "cleaned").
117 115
118.. _ref-tasks-fetch: 116.. _ref-tasks-fetch:
@@ -120,9 +118,9 @@ If the ``do_deploy`` task re-executes, any previous output is removed
120``do_fetch`` 118``do_fetch``
121------------ 119------------
122 120
123Fetches the source code. This task uses the 121Fetches the source code. This task uses the :term:`SRC_URI` variable and the
124:term:`SRC_URI` variable and the argument's prefix to 122argument's prefix to determine the correct
125determine the correct :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 123:ref:`fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
126module. 124module.
127 125
128.. _ref-tasks-image: 126.. _ref-tasks-image:
@@ -130,15 +128,15 @@ module.
130``do_image`` 128``do_image``
131------------ 129------------
132 130
133Starts the image generation process. The ``do_image`` task runs after 131Starts the image generation process. The :ref:`ref-tasks-image` task runs after
134the OpenEmbedded build system has run the 132the OpenEmbedded build system has run the
135:ref:`ref-tasks-rootfs` task during which packages are 133:ref:`ref-tasks-rootfs` task during which packages are
136identified for installation into the image and the root filesystem is 134identified for installation into the image and the root filesystem is
137created, complete with post-processing. 135created, complete with post-processing.
138 136
139The ``do_image`` task performs pre-processing on the image through the 137The :ref:`ref-tasks-image` task performs pre-processing on the image through the
140:term:`IMAGE_PREPROCESS_COMMAND` and 138:term:`IMAGE_PREPROCESS_COMMAND` and
141dynamically generates supporting ``do_image_*`` tasks as needed. 139dynamically generates supporting :ref:`do_image_* <ref-tasks-image>` tasks as needed.
142 140
143For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`" 141For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`"
144section in the Yocto Project Overview and Concepts Manual. 142section in the Yocto Project Overview and Concepts Manual.
@@ -148,13 +146,13 @@ section in the Yocto Project Overview and Concepts Manual.
148``do_image_complete`` 146``do_image_complete``
149--------------------- 147---------------------
150 148
151Completes the image generation process. The ``do_image_complete`` task 149Completes the image generation process. The :ref:`do_image_complete <ref-tasks-image-complete>` task
152runs after the OpenEmbedded build system has run the 150runs after the OpenEmbedded build system has run the
153:ref:`ref-tasks-image` task during which image 151:ref:`ref-tasks-image` task during which image
154pre-processing occurs and through dynamically generated ``do_image_*`` 152pre-processing occurs and through dynamically generated :ref:`do_image_* <ref-tasks-image>`
155tasks the image is constructed. 153tasks the image is constructed.
156 154
157The ``do_image_complete`` task performs post-processing on the image 155The :ref:`do_image_complete <ref-tasks-image-complete>` task performs post-processing on the image
158through the 156through the
159:term:`IMAGE_POSTPROCESS_COMMAND`. 157:term:`IMAGE_POSTPROCESS_COMMAND`.
160 158
@@ -170,9 +168,9 @@ section in the Yocto Project Overview and Concepts Manual.
170Copies files that are to be packaged into the holding area 168Copies files that are to be packaged into the holding area
171``${``\ :term:`D`\ ``}``. This task runs with the current 169``${``\ :term:`D`\ ``}``. This task runs with the current
172working directory set to ``${``\ :term:`B`\ ``}``, which is the 170working directory set to ``${``\ :term:`B`\ ``}``, which is the
173compilation directory. The ``do_install`` task, as well as other tasks 171compilation directory. The :ref:`ref-tasks-install` task, as well as other tasks
174that either directly or indirectly depend on the installed files (e.g. 172that either directly or indirectly depend on the installed files (e.g.
175:ref:`ref-tasks-package`, ``do_package_write_*``, and 173:ref:`ref-tasks-package`, :ref:`do_package_write_* <ref-tasks-package_write_deb>`, and
176:ref:`ref-tasks-rootfs`), run under 174:ref:`ref-tasks-rootfs`), run under
177:ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. 175:ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
178 176
@@ -189,11 +187,11 @@ that either directly or indirectly depend on the installed files (e.g.
189 187
190 - The ``install`` utility. This utility is the preferred method. 188 - The ``install`` utility. This utility is the preferred method.
191 189
192 - The ``cp`` command with the "--no-preserve=ownership" option. 190 - The ``cp`` command with the ``--no-preserve=ownership`` option.
193 191
194 - The ``tar`` command with the "--no-same-owner" option. See the 192 - The ``tar`` command with the ``--no-same-owner`` option. See the
195 ``bin_package.bbclass`` file in the ``meta/classes`` directory of 193 ``bin_package.bbclass`` file in the ``meta/classes-recipe``
196 the :term:`Source Directory` for an example. 194 subdirectory of the :term:`Source Directory` for an example.
197 195
198.. _ref-tasks-install_ptest_base: 196.. _ref-tasks-install_ptest_base:
199 197
@@ -214,7 +212,7 @@ based on available packages and files. This task makes use of the
214:term:`PACKAGES` and :term:`FILES` 212:term:`PACKAGES` and :term:`FILES`
215variables. 213variables.
216 214
217The ``do_package`` task, in conjunction with the 215The :ref:`ref-tasks-package` task, in conjunction with the
218:ref:`ref-tasks-packagedata` task, also saves some 216:ref:`ref-tasks-packagedata` task, also saves some
219important package metadata. For additional information, see the 217important package metadata. For additional information, see the
220:term:`PKGDESTWORK` variable and the 218:term:`PKGDESTWORK` variable and the
@@ -227,7 +225,7 @@ section in the Yocto Project Overview and Concepts Manual.
227----------------- 225-----------------
228 226
229Runs QA checks on packaged files. For more information on these checks, 227Runs QA checks on packaged files. For more information on these checks,
230see the :ref:`insane <ref-classes-insane>` class. 228see the :ref:`ref-classes-insane` class.
231 229
232.. _ref-tasks-package_write_deb: 230.. _ref-tasks-package_write_deb:
233 231
@@ -262,17 +260,6 @@ the package feeds area. For more information, see the
262":ref:`overview-manual/concepts:package feeds`" section in 260":ref:`overview-manual/concepts:package feeds`" section in
263the Yocto Project Overview and Concepts Manual. 261the Yocto Project Overview and Concepts Manual.
264 262
265.. _ref-tasks-package_write_tar:
266
267``do_package_write_tar``
268------------------------
269
270Creates tarballs and places them in the
271``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in
272the package feeds area. For more information, see the
273":ref:`overview-manual/concepts:package feeds`" section in
274the Yocto Project Overview and Concepts Manual.
275
276.. _ref-tasks-packagedata: 263.. _ref-tasks-packagedata:
277 264
278``do_packagedata`` 265``do_packagedata``
@@ -302,56 +289,50 @@ Patch files, by default, are ``*.patch`` and ``*.diff`` files created
302and kept in a subdirectory of the directory holding the recipe file. For 289and kept in a subdirectory of the directory holding the recipe file. For
303example, consider the 290example, consider the
304:yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>` 291:yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>`
305recipe from the OE-Core layer (i.e. ``poky/meta``): 292recipe from the OE-Core layer (i.e. ``poky/meta``)::
306::
307 293
308 poky/meta/recipes-connectivity/bluez5 294 poky/meta/recipes-connectivity/bluez5
309 295
310This recipe has two patch files located here: 296This recipe has two patch files located here::
311::
312 297
313 poky/meta/recipes-connectivity/bluez5/bluez5 298 poky/meta/recipes-connectivity/bluez5/bluez5
314 299
315In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source 300In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source
316and patch files needed to build the package. 301and patch files needed to build the package.
317 302
318.. note:: 303.. note::
319 304
320 In the case for the ``bluez5_5.48.bb`` recipe, the ``SRC_URI`` statements 305 In the case for the ``bluez5_5.48.bb`` recipe, the :term:`SRC_URI` statements
321 are from an include file ``bluez5.inc``. 306 are from an include file ``bluez5.inc``.
322 307
323As mentioned earlier, the build system treats files whose file types are 308As mentioned earlier, the build system treats files whose file types are
324``.patch`` and ``.diff`` as patch files. However, you can use the 309``.patch`` and ``.diff`` as patch files. However, you can use the
325"apply=yes" parameter with the ``SRC_URI`` statement to indicate any 310"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any
326file as a patch file: 311file as a patch file::
327::
328 312
329 SRC_URI = " \ 313 SRC_URI = " \
330 git://path_to_repo/some_package \ 314 git://path_to_repo/some_package \
331 file://file;apply=yes \ 315 file://file;apply=yes \
332 " 316 "
333 317
334Conversely, if you have a directory full of patch files and you want to 318Conversely, if you have a file whose file type is ``.patch`` or ``.diff``
335exclude some so that the ``do_patch`` task does not apply them during 319and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply
336the patch phase, you can use the "apply=no" parameter with the 320it during the patch phase, you can use the "apply=no" parameter with the
337``SRC_URI`` statement: 321:term:`SRC_URI` statement::
338::
339 322
340 SRC_URI = " \ 323 SRC_URI = " \
341 git://path_to_repo/some_package \ 324 git://path_to_repo/some_package \
342 file://path_to_lots_of_patch_files \ 325 file://file1.patch \
343 file://path_to_lots_of_patch_files/patch_file5;apply=no \ 326 file://file2.patch;apply=no \
344 " 327 "
345 328
346In the 329In the previous example ``file1.patch`` would be applied as a patch by default
347previous example, assuming all the files in the directory holding the 330while ``file2.patch`` would not be applied.
348patch files end with either ``.patch`` or ``.diff``, every file would be
349applied as a patch by default except for the ``patch_file5`` patch.
350 331
351You can find out more about the patching process in the 332You can find out more about the patching process in the
352":ref:`overview-manual/concepts:patching`" section in 333":ref:`overview-manual/concepts:patching`" section in
353the Yocto Project Overview and Concepts Manual and the 334the Yocto Project Overview and Concepts Manual and the
354":ref:`dev-manual/common-tasks:patching code`" section in the 335":ref:`dev-manual/new-recipe:patching code`" section in the
355Yocto Project Development Tasks Manual. 336Yocto Project Development Tasks Manual.
356 337
357.. _ref-tasks-populate_lic: 338.. _ref-tasks-populate_lic:
@@ -400,7 +381,7 @@ For information on what directories are copied by default, see the
400these variables inside your recipe if you need to make additional (or 381these variables inside your recipe if you need to make additional (or
401fewer) directories available to other recipes at build time. 382fewer) directories available to other recipes at build time.
402 383
403The ``do_populate_sysroot`` task is a shared state (sstate) task, which 384The :ref:`ref-tasks-populate_sysroot` task is a shared state (sstate) task, which
404means that the task can be accelerated through sstate use. Realize also 385means that the task can be accelerated through sstate use. Realize also
405that if the task is re-executed, any previous output is removed (i.e. 386that if the task is re-executed, any previous output is removed (i.e.
406"cleaned"). 387"cleaned").
@@ -414,7 +395,7 @@ Installs the files into the individual recipe specific sysroots (i.e.
414``recipe-sysroot`` and ``recipe-sysroot-native`` under 395``recipe-sysroot`` and ``recipe-sysroot-native`` under
415``${``\ :term:`WORKDIR`\ ``}`` based upon the 396``${``\ :term:`WORKDIR`\ ``}`` based upon the
416dependencies specified by :term:`DEPENDS`). See the 397dependencies specified by :term:`DEPENDS`). See the
417":ref:`staging <ref-classes-staging>`" class for more information. 398":ref:`ref-classes-staging`" class for more information.
418 399
419.. _ref-tasks-rm_work: 400.. _ref-tasks-rm_work:
420 401
@@ -423,7 +404,7 @@ dependencies specified by :term:`DEPENDS`). See the
423 404
424Removes work files after the OpenEmbedded build system has finished with 405Removes work files after the OpenEmbedded build system has finished with
425them. You can learn more by looking at the 406them. You can learn more by looking at the
426":ref:`rm_work.bbclass <ref-classes-rm-work>`" section. 407":ref:`ref-classes-rm-work`" section.
427 408
428.. _ref-tasks-unpack: 409.. _ref-tasks-unpack:
429 410
@@ -436,7 +417,7 @@ variable also plays a role in where unpacked source files ultimately
436reside. For more information on how source files are unpacked, see the 417reside. For more information on how source files are unpacked, see the
437":ref:`overview-manual/concepts:source fetching`" 418":ref:`overview-manual/concepts:source fetching`"
438section in the Yocto Project Overview and Concepts Manual and also see 419section in the Yocto Project Overview and Concepts Manual and also see
439the ``WORKDIR`` and ``S`` variable descriptions. 420the :term:`WORKDIR` and :term:`S` variable descriptions.
440 421
441Manually Called Tasks 422Manually Called Tasks
442===================== 423=====================
@@ -444,39 +425,6 @@ Manually Called Tasks
444These tasks are typically manually triggered (e.g. by using the 425These tasks are typically manually triggered (e.g. by using the
445``bitbake -c`` command-line option): 426``bitbake -c`` command-line option):
446 427
447.. _ref-tasks-checkpkg:
448
449``do_checkpkg``
450---------------
451
452Provides information about the recipe including its upstream version and
453status. The upstream version and status reveals whether or not a version
454of the recipe exists upstream and a status of not updated, updated, or
455unknown.
456
457To check the upstream version and status of a recipe, use the following
458devtool commands:
459::
460
461 $ devtool latest-version
462 $ devtool check-upgrade-status
463
464See the ":ref:`ref-manual/devtool-reference:\`\`devtool\`\` quick reference`"
465chapter for more information on
466``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
467section for information on checking the upgrade status of a recipe.
468
469To build the ``checkpkg`` task, use the ``bitbake`` command with the
470"-c" option and task name:
471::
472
473 $ bitbake core-image-minimal -c checkpkg
474
475By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
476``$BUILD_DIR/tmp/log``).
477
478.. _ref-tasks-checkuri:
479
480``do_checkuri`` 428``do_checkuri``
481--------------- 429---------------
482 430
@@ -488,14 +436,13 @@ Validates the :term:`SRC_URI` value.
488------------ 436------------
489 437
490Removes all output files for a target from the 438Removes all output files for a target from the
491:ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``, 439:ref:`ref-tasks-unpack` task forward (i.e. :ref:`ref-tasks-unpack`,
492:ref:`ref-tasks-configure`, 440:ref:`ref-tasks-configure`,
493:ref:`ref-tasks-compile`, 441:ref:`ref-tasks-compile`,
494:ref:`ref-tasks-install`, and 442:ref:`ref-tasks-install`, and
495:ref:`ref-tasks-package`). 443:ref:`ref-tasks-package`).
496 444
497You can run this task using BitBake as follows: 445You can run this task using BitBake as follows::
498::
499 446
500 $ bitbake -c clean recipe 447 $ bitbake -c clean recipe
501 448
@@ -515,18 +462,37 @@ use the :ref:`ref-tasks-cleansstate` task instead
515Removes all output files, shared state 462Removes all output files, shared state
516(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache, and 463(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache, and
517downloaded source files for a target (i.e. the contents of 464downloaded source files for a target (i.e. the contents of
518:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is 465:term:`DL_DIR`). Essentially, the :ref:`ref-tasks-cleanall` task is
519identical to the :ref:`ref-tasks-cleansstate` task 466identical to the :ref:`ref-tasks-cleansstate` task
520with the added removal of downloaded source files. 467with the added removal of downloaded source files.
521 468
522You can run this task using BitBake as follows: 469You can run this task using BitBake as follows::
523::
524 470
525 $ bitbake -c cleanall recipe 471 $ bitbake -c cleanall recipe
526 472
527Typically, you would not normally use the ``cleanall`` task. Do so only 473You should never use the :ref:`ref-tasks-cleanall` task in a normal
528if you want to start fresh with the :ref:`ref-tasks-fetch` 474scenario. If you want to start fresh with the :ref:`ref-tasks-fetch` task,
529task. 475use instead::
476
477 $ bitbake -f -c fetch recipe
478
479.. note::
480
481 The reason to prefer ``bitbake -f -c fetch`` is that the
482 :ref:`ref-tasks-cleanall` task would break in some cases, such as::
483
484 $ bitbake -c fetch recipe
485 $ bitbake -c cleanall recipe-native
486 $ bitbake -c unpack recipe
487
488 because after step 1 there is a stamp file for the
489 :ref:`ref-tasks-fetch` task of ``recipe``, and it won't be removed at
490 step 2 because step 2 uses a different work directory. So the unpack task
491 at step 3 will try to extract the downloaded archive and fail as it has
492 been deleted in step 2.
493
494 Note that this also applies to BitBake from concurrent processes when a
495 shared download directory (:term:`DL_DIR`) is setup.
530 496
531.. _ref-tasks-cleansstate: 497.. _ref-tasks-cleansstate:
532 498
@@ -535,41 +501,51 @@ task.
535 501
536Removes all output files and shared state 502Removes all output files and shared state
537(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache for a 503(:ref:`sstate <overview-manual/concepts:shared state cache>`) cache for a
538target. Essentially, the ``do_cleansstate`` task is identical to the 504target. Essentially, the :ref:`ref-tasks-cleansstate` task is identical to the
539:ref:`ref-tasks-clean` task with the added removal of 505:ref:`ref-tasks-clean` task with the added removal of
540shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) 506shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`)
541cache. 507cache.
542 508
543You can run this task using BitBake as follows: 509You can run this task using BitBake as follows::
544::
545 510
546 $ bitbake -c cleansstate recipe 511 $ bitbake -c cleansstate recipe
547 512
548When you run the ``do_cleansstate`` task, the OpenEmbedded build system 513When you run the :ref:`ref-tasks-cleansstate` task, the OpenEmbedded build system
549no longer uses any sstate. Consequently, building the recipe from 514no longer uses any sstate. Consequently, building the recipe from
550scratch is guaranteed. 515scratch is guaranteed.
551 516
552.. note:: 517.. note::
553 518
554 The ``do_cleansstate`` task cannot remove sstate from a remote sstate 519 Using :ref:`ref-tasks-cleansstate` with a shared :term:`SSTATE_DIR` is
520 not recommended because it could trigger an error during the build of a
521 separate BitBake instance. This is because the builds check sstate "up
522 front" but download the files later, so it if is deleted in the
523 meantime, it will cause an error but not a total failure as it will
524 rebuild it.
525
526 The reliable and preferred way to force a new build is to use ``bitbake
527 -f`` instead.
528
529.. note::
530
531 The :ref:`ref-tasks-cleansstate` task cannot remove sstate from a remote sstate
555 mirror. If you need to build a target from scratch using remote mirrors, use 532 mirror. If you need to build a target from scratch using remote mirrors, use
556 the "-f" option as follows: 533 the "-f" option as follows::
557 ::
558 534
559 $ bitbake -f -c do_cleansstate target 535 $ bitbake -f -c do_cleansstate target
560 536
561 537
562.. _ref-tasks-devpyshell: 538.. _ref-tasks-pydevshell:
563 539
564``do_devpyshell`` 540``do_pydevshell``
565----------------- 541-----------------
566 542
567Starts a shell in which an interactive Python interpreter allows you to 543Starts a shell in which an interactive Python interpreter allows you to
568interact with the BitBake build environment. From within this shell, you 544interact with the BitBake build environment. From within this shell, you
569can directly examine and set bits from the data store and execute 545can directly examine and set bits from the data store and execute
570functions as if within the BitBake environment. See the ":ref:`dev-manual/common-tasks:using a development python shell`" section in 546functions as if within the BitBake environment. See the ":ref:`dev-manual/python-development-shell:using a Python development shell`" section in
571the Yocto Project Development Tasks Manual for more information about 547the Yocto Project Development Tasks Manual for more information about
572using ``devpyshell``. 548using ``pydevshell``.
573 549
574.. _ref-tasks-devshell: 550.. _ref-tasks-devshell:
575 551
@@ -577,7 +553,7 @@ using ``devpyshell``.
577--------------- 553---------------
578 554
579Starts a shell whose environment is set up for development, debugging, 555Starts a shell whose environment is set up for development, debugging,
580or both. See the ":ref:`dev-manual/common-tasks:using a development shell`" section in the 556or both. See the ":ref:`dev-manual/development-shell:using a development shell`" section in the
581Yocto Project Development Tasks Manual for more information about using 557Yocto Project Development Tasks Manual for more information about using
582``devshell``. 558``devshell``.
583 559
@@ -620,10 +596,8 @@ information on live image types.
620``do_bundle_initramfs`` 596``do_bundle_initramfs``
621----------------------- 597-----------------------
622 598
623Combines an initial RAM disk (initramfs) image and kernel together to 599Combines an :term:`Initramfs` image and kernel together to
624form a single image. The 600form a single image.
625:term:`CONFIG_INITRAMFS_SOURCE` variable
626has some more information about these types of images.
627 601
628.. _ref-tasks-rootfs: 602.. _ref-tasks-rootfs:
629 603
@@ -642,7 +616,7 @@ information on how the root filesystem is created.
642 616
643Boots an image and performs runtime tests within the image. For 617Boots an image and performs runtime tests within the image. For
644information on automatically testing images, see the 618information on automatically testing images, see the
645":ref:`dev-manual/common-tasks:performing automated runtime testing`" 619":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
646section in the Yocto Project Development Tasks Manual. 620section in the Yocto Project Development Tasks Manual.
647 621
648.. _ref-tasks-testimage_auto: 622.. _ref-tasks-testimage_auto:
@@ -655,7 +629,7 @@ after it has been built. This task is enabled when you set
655:term:`TESTIMAGE_AUTO` equal to "1". 629:term:`TESTIMAGE_AUTO` equal to "1".
656 630
657For information on automatically testing images, see the 631For information on automatically testing images, see the
658":ref:`dev-manual/common-tasks:performing automated runtime testing`" 632":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
659section in the Yocto Project Development Tasks Manual. 633section in the Yocto Project Development Tasks Manual.
660 634
661Kernel-Related Tasks 635Kernel-Related Tasks
@@ -687,8 +661,7 @@ changes made by the user with other methods (i.e. using
687(:ref:`ref-tasks-kernel_menuconfig`). Once the 661(:ref:`ref-tasks-kernel_menuconfig`). Once the
688file of differences is created, it can be used to create a config 662file of differences is created, it can be used to create a config
689fragment that only contains the differences. You can invoke this task 663fragment that only contains the differences. You can invoke this task
690from the command line as follows: 664from the command line as follows::
691::
692 665
693 $ bitbake linux-yocto -c diffconfig 666 $ bitbake linux-yocto -c diffconfig
694 667
@@ -703,7 +676,7 @@ section in the Yocto Project Linux Kernel Development Manual.
703 676
704Converts the newly unpacked kernel source into a form with which the 677Converts the newly unpacked kernel source into a form with which the
705OpenEmbedded build system can work. Because the kernel source can be 678OpenEmbedded build system can work. Because the kernel source can be
706fetched in several different ways, the ``do_kernel_checkout`` task makes 679fetched in several different ways, the :ref:`ref-tasks-kernel_checkout` task makes
707sure that subsequent tasks are given a clean working tree copy of the 680sure that subsequent tasks are given a clean working tree copy of the
708kernel with the correct branches checked out. 681kernel with the correct branches checked out.
709 682
@@ -714,12 +687,11 @@ kernel with the correct branches checked out.
714 687
715Validates the configuration produced by the 688Validates the configuration produced by the
716:ref:`ref-tasks-kernel_menuconfig` task. The 689:ref:`ref-tasks-kernel_menuconfig` task. The
717``do_kernel_configcheck`` task produces warnings when a requested 690:ref:`ref-tasks-kernel_configcheck` task produces warnings when a requested
718configuration does not appear in the final ``.config`` file or when you 691configuration does not appear in the final ``.config`` file or when you
719override a policy configuration in a hardware configuration fragment. 692override a policy configuration in a hardware configuration fragment.
720You can run this task explicitly and view the output by using the 693You can run this task explicitly and view the output by using the
721following command: 694following command::
722::
723 695
724 $ bitbake linux-yocto -c kernel_configcheck -f 696 $ bitbake linux-yocto -c kernel_configcheck -f
725 697
@@ -733,7 +705,7 @@ section in the Yocto Project Linux Kernel Development Manual.
733---------------------- 705----------------------
734 706
735After the kernel is patched by the :ref:`ref-tasks-patch` 707After the kernel is patched by the :ref:`ref-tasks-patch`
736task, the ``do_kernel_configme`` task assembles and merges all the 708task, the :ref:`ref-tasks-kernel_configme` task assembles and merges all the
737kernel config fragments into a merged configuration that can then be 709kernel config fragments into a merged configuration that can then be
738passed to the kernel configuration phase proper. This is also the time 710passed to the kernel configuration phase proper. This is also the time
739during which user-specified defconfigs are applied if present, and where 711during which user-specified defconfigs are applied if present, and where
@@ -750,8 +722,7 @@ tool, which you then use to modify the kernel configuration.
750 722
751.. note:: 723.. note::
752 724
753 You can also invoke this tool from the command line as follows: 725 You can also invoke this tool from the command line as follows::
754 ::
755 726
756 $ bitbake linux-yocto -c menuconfig 727 $ bitbake linux-yocto -c menuconfig
757 728
@@ -767,7 +738,7 @@ information on this configuration tool.
767 738
768Collects all the features required for a given kernel build, whether the 739Collects all the features required for a given kernel build, whether the
769features come from :term:`SRC_URI` or from Git 740features come from :term:`SRC_URI` or from Git
770repositories. After collection, the ``do_kernel_metadata`` task 741repositories. After collection, the :ref:`ref-tasks-kernel_metadata` task
771processes the features into a series of config fragments and patches, 742processes the features into a series of config fragments and patches,
772which can then be applied by subsequent tasks such as 743which can then be applied by subsequent tasks such as
773:ref:`ref-tasks-patch` and 744:ref:`ref-tasks-patch` and
@@ -793,8 +764,7 @@ instead of the default defconfig. The saved defconfig contains the
793differences between the default defconfig and the changes made by the 764differences between the default defconfig and the changes made by the
794user using other methods (i.e. the 765user using other methods (i.e. the
795:ref:`ref-tasks-kernel_menuconfig` task. You 766:ref:`ref-tasks-kernel_menuconfig` task. You
796can invoke the task using the following command: 767can invoke the task using the following command::
797::
798 768
799 $ bitbake linux-yocto -c savedefconfig 769 $ bitbake linux-yocto -c savedefconfig
800 770
@@ -839,6 +809,5 @@ sections from a size-sensitive configuration.
839After the kernel is unpacked but before it is patched, this task makes 809After the kernel is unpacked but before it is patched, this task makes
840sure that the machine and metadata branches as specified by the 810sure that the machine and metadata branches as specified by the
841:term:`SRCREV` variables actually exist on the specified 811:term:`SRCREV` variables actually exist on the specified
842branches. If these branches do not exist and 812branches. Otherwise, if :term:`AUTOREV` is not being used, the
843:term:`AUTOREV` is not being used, the 813:ref:`ref-tasks-validate_branches` task fails during the build.
844``do_validate_branches`` task fails during the build.
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index bf46148876..ad9c46c339 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -4,7 +4,7 @@
4Yocto Project Terms 4Yocto Project Terms
5******************* 5*******************
6 6
7Following is a list of terms and definitions users new to the Yocto Project 7Here is a list of terms and definitions users new to the Yocto Project
8development environment might find helpful. While some of these terms are 8development environment might find helpful. While some of these terms are
9universal, the list includes them just in case: 9universal, the list includes them just in case:
10 10
@@ -21,18 +21,17 @@ universal, the list includes them just in case:
21 21
22 Information in append files extends or overrides the information in the 22 Information in append files extends or overrides the information in the
23 similarly-named recipe file. For an example of an append file in use, see 23 similarly-named recipe file. For an example of an append file in use, see
24 the ":ref:`dev-manual/common-tasks:Using .bbappend Files in 24 the ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
25 Your Layer`" section in the Yocto Project Development Tasks Manual. 25 section in the Yocto Project Development Tasks Manual.
26 26
27 When you name an append file, you can use the "``%``" wildcard character 27 When you name an append file, you can use the "``%``" wildcard character
28 to allow for matching recipe names. For example, suppose you have an 28 to allow for matching recipe names. For example, suppose you have an
29 append file named as follows: 29 append file named as follows::
30 :: 30
31
32 busybox_1.21.%.bbappend 31 busybox_1.21.%.bbappend
33 32
34 That append file 33 That append file
35 would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, 34 would match any ``busybox_1.21.x.bb`` version of the recipe. So,
36 the append file would match any of the following recipe names: 35 the append file would match any of the following recipe names:
37 36
38 .. code-block:: shell 37 .. code-block:: shell
@@ -65,54 +64,73 @@ universal, the list includes them just in case:
65 builds. The area is created when you ``source`` the setup environment 64 builds. The area is created when you ``source`` the setup environment
66 script that is found in the Source Directory 65 script that is found in the Source Directory
67 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The 66 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
68 :term:`TOPDIR` variable points to the Build Directory. 67 :term:`TOPDIR` variable points to the :term:`Build Directory`.
69 68
70 You have a lot of flexibility when creating the Build Directory. 69 You have a lot of flexibility when creating the :term:`Build Directory`.
71 Following are some examples that show how to create the directory. The 70 Here are some examples that show how to create the directory. The
72 examples assume your :term:`Source Directory` is named ``poky``: 71 examples assume your :term:`Source Directory` is named ``poky``:
73 72
74 - Create the Build Directory inside your Source Directory and let 73 - Create the :term:`Build Directory` inside your Source Directory and let
75 the name of the Build Directory default to ``build``: 74 the name of the :term:`Build Directory` default to ``build``:
76 75
77 .. code-block:: shell 76 .. code-block:: shell
78 77
79 $ cd $HOME/poky 78 $ cd poky
80 $ source oe-init-build-env 79 $ source oe-init-build-env
81 80
82 - Create the Build Directory inside your home directory and 81 - Create the :term:`Build Directory` inside your home directory and
83 specifically name it ``test-builds``: 82 specifically name it ``test-builds``:
84 83
85 .. code-block:: shell 84 .. code-block:: shell
86 85
87 $ cd $HOME
88 $ source poky/oe-init-build-env test-builds 86 $ source poky/oe-init-build-env test-builds
89 87
90 - Provide a directory path and specifically name the Build 88 - Provide a directory path and specifically name the
91 Directory. Any intermediate folders in the pathname must exist. 89 :term:`Build Directory`. Any intermediate folders in the pathname
92 This next example creates a Build Directory named 90 must exist. This next example creates a :term:`Build Directory`
93 ``YP-&POKYVERSION;`` in your home directory within the existing 91 named ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
94 directory ``mybuilds``:
95 92
96 .. code-block:: shell 93 .. code-block:: shell
97 94
98 $ cd $HOME 95 $ source poky/oe-init-build-env mybuilds/YP-&DISTRO;
99 $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-&POKYVERSION;
100 96
101 .. note:: 97 .. note::
102 98
103 By default, the Build Directory contains :term:`TMPDIR`, which is a 99 By default, the :term:`Build Directory` contains :term:`TMPDIR`, which is a
104 temporary directory the build system uses for its work. ``TMPDIR`` cannot 100 temporary directory the build system uses for its work. :term:`TMPDIR` cannot
105 be under NFS. Thus, by default, the Build Directory cannot be under 101 be under NFS. Thus, by default, the :term:`Build Directory` cannot be under
106 NFS. However, if you need the Build Directory to be under NFS, you can 102 NFS. However, if you need the :term:`Build Directory` to be under NFS, you can
107 set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local 103 set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local
108 drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the 104 drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the
109 Build Directory. 105 :term:`Build Directory`.
110 106
111 :term:`Build Host` 107 :term:`Build Host`
112 The system used to build images in a Yocto Project Development 108 The system used to build images in a Yocto Project Development
113 environment. The build system is sometimes referred to as the development 109 environment. The build system is sometimes referred to as the development
114 host. 110 host.
115 111
112 :term:`buildtools`
113 Build tools in binary form, providing required versions of development
114 tools (such as Git, GCC, Python and make), to run the OpenEmbedded build
115 system on a development host without such minimum versions.
116
117 See the ":ref:`system-requirements-buildtools`" paragraph in the
118 Reference Manual for details about downloading or building an archive
119 of such tools.
120
121 :term:`buildtools-extended`
122 A set of :term:`buildtools` binaries extended with additional development
123 tools, such as a required version of the GCC compiler to run the
124 OpenEmbedded build system.
125
126 See the ":ref:`system-requirements-buildtools`" paragraph in the
127 Reference Manual for details about downloading or building an archive
128 of such tools.
129
130 :term:`buildtools-make`
131 A variant of :term:`buildtools`, just providing the required
132 version of ``make`` to run the OpenEmbedded build system.
133
116 :term:`Classes` 134 :term:`Classes`
117 Files that provide for logic encapsulation and inheritance so that 135 Files that provide for logic encapsulation and inheritance so that
118 commonly used patterns can be defined once and then easily used in 136 commonly used patterns can be defined once and then easily used in
@@ -138,10 +156,25 @@ universal, the list includes them just in case:
138 the Texas Instruments ARM Cortex-A8 development board). 156 the Texas Instruments ARM Cortex-A8 development board).
139 157
140 :term:`Container Layer` 158 :term:`Container Layer`
141 Layers that hold other layers. An example of a container layer is 159 A flexible definition that typically refers to a single Git checkout
142 OpenEmbedded's `meta-openembedded 160 which contains multiple (and typically related) sub-layers which can
143 <https://github.com/openembedded/meta-openembedded>`_ layer. The 161 be included independently in your project's ``bblayers.conf`` file.
144 ``meta-openembedded`` layer contains many ``meta-*`` layers. 162
163 In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
164 layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
165 so you would never explicitly include it in a ``bblayers.conf`` file;
166 rather, you would include any number of its layer subdirectories, such as
167 :oe_git:`meta-oe </meta-openembedded/tree/meta-oe>`, :oe_git:`meta-python
168 </meta-openembedded/tree/meta-python>` and so on.
169
170 On the other hand, some container layers (such as
171 :yocto_git:`meta-security </meta-security>`)
172 have a top-level directory that is itself an actual layer, as well as
173 a variety of sub-layers, both of which could be included in your
174 ``bblayers.conf`` file.
175
176 In either case, the phrase "container layer" is simply used to describe
177 a directory structure which contains multiple valid OpenEmbedded layers.
145 178
146 :term:`Cross-Development Toolchain` 179 :term:`Cross-Development Toolchain`
147 In general, a cross-development toolchain is a collection of software 180 In general, a cross-development toolchain is a collection of software
@@ -179,6 +212,48 @@ universal, the list includes them just in case:
179 of the supported image types that the Yocto Project provides, see the 212 of the supported image types that the Yocto Project provides, see the
180 ":ref:`ref-manual/images:Images`" chapter. 213 ":ref:`ref-manual/images:Images`" chapter.
181 214
215 :term:`Initramfs`
216 An Initial RAM Filesystem (:term:`Initramfs`) is an optionally compressed
217 :wikipedia:`cpio <Cpio>` archive which is extracted
218 by the Linux kernel into RAM in a special :wikipedia:`tmpfs <Tmpfs>`
219 instance, used as the initial root filesystem.
220
221 This is a replacement for the legacy init RAM disk ("initrd")
222 technique, booting on an emulated block device in RAM, but being less
223 efficient because of the overhead of going through a filesystem and
224 having to duplicate accessed file contents in the file cache in RAM,
225 as for any block device.
226
227 .. note::
228
229 As far as bootloaders are concerned, :term:`Initramfs` and "initrd"
230 images are still copied to RAM in the same way. That's why most
231 most bootloaders refer to :term:`Initramfs` images as "initrd"
232 or "init RAM disk".
233
234 This kind of mechanism is typically used for two reasons:
235
236 - For booting the same kernel binary on multiple systems requiring
237 different device drivers. The :term:`Initramfs` image is then customized
238 for each type of system, to include the specific kernel modules
239 necessary to access the final root filesystem. This technique
240 is used on all GNU / Linux distributions for desktops and servers.
241
242 - For booting faster. As the root filesystem is extracted into RAM,
243 accessing the first user-space applications is very fast, compared
244 to having to initialize a block device, to access multiple blocks
245 from it, and to go through a filesystem having its own overhead.
246 For example, this allows to display a splashscreen very early,
247 and to later take care of mounting the final root filesystem and
248 loading less time-critical kernel drivers.
249
250 This cpio archive can either be loaded to RAM by the bootloader,
251 or be included in the kernel binary.
252
253 For information on creating and using an :term:`Initramfs`, see the
254 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
255 section in the Yocto Project Development Tasks Manual.
256
182 :term:`Layer` 257 :term:`Layer`
183 A collection of related recipes. Layers allow you to consolidate related 258 A collection of related recipes. Layers allow you to consolidate related
184 metadata to customize your build. Layers also isolate information used 259 metadata to customize your build. Layers also isolate information used
@@ -192,12 +267,18 @@ universal, the list includes them just in case:
192 ":ref:`overview-manual/yp-intro:The Yocto Project Layer 267 ":ref:`overview-manual/yp-intro:The Yocto Project Layer
193 Model`" section in the Yocto Project Overview and Concepts Manual. For 268 Model`" section in the Yocto Project Overview and Concepts Manual. For
194 more detailed information on layers, see the 269 more detailed information on layers, see the
195 ":ref:`dev-manual/common-tasks:Understanding and Creating 270 ":ref:`dev-manual/layers:Understanding and Creating
196 Layers`" section in the Yocto Project Development Tasks Manual. For a 271 Layers`" section in the Yocto Project Development Tasks Manual. For a
197 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP 272 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
198 Layers`" section in the Yocto Project Board Support Packages (BSP) 273 Layers`" section in the Yocto Project Board Support Packages (BSP)
199 Developer's Guide. 274 Developer's Guide.
200 275
276 :term:`LTS`
277 This term means "Long Term Support", and in the context of the Yocto
278 Project, it corresponds to selected stable releases for which bug and
279 security fixes are provided for at least four years. See
280 the :ref:`ref-long-term-support-releases` section for details.
281
201 :term:`Metadata` 282 :term:`Metadata`
202 A key element of the Yocto Project is the Metadata that 283 A key element of the Yocto Project is the Metadata that
203 is used to construct a Linux distribution and is contained in the 284 is used to construct a Linux distribution and is contained in the
@@ -217,6 +298,12 @@ universal, the list includes them just in case:
217 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>` 298 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
218 Git repository. 299 Git repository.
219 300
301 :term:`Mixin`
302 A :term:`Mixin` layer is a layer which can be created by the community to
303 add a specific feature or support a new version of some package for an
304 :term:`LTS` release. See the :ref:`ref-long-term-support-releases`
305 section for details.
306
220 :term:`OpenEmbedded-Core (OE-Core)` 307 :term:`OpenEmbedded-Core (OE-Core)`
221 OE-Core is metadata comprised of 308 OE-Core is metadata comprised of
222 foundational recipes, classes, and associated files that are meant to 309 foundational recipes, classes, and associated files that are meant to
@@ -257,7 +344,7 @@ universal, the list includes them just in case:
257 your Linux distribution. 344 your Linux distribution.
258 345
259 Another point worth noting is that historically within the Yocto 346 Another point worth noting is that historically within the Yocto
260 Project, recipes were referred to as packages - thus, the existence 347 Project, recipes were referred to as packages --- thus, the existence
261 of several BitBake variables that are seemingly mis-named, (e.g. 348 of several BitBake variables that are seemingly mis-named, (e.g.
262 :term:`PR`, :term:`PV`, and 349 :term:`PR`, :term:`PV`, and
263 :term:`PE`). 350 :term:`PE`).
@@ -310,6 +397,23 @@ universal, the list includes them just in case:
310 :term:`build host<Build Host>` and other components, that can 397 :term:`build host<Build Host>` and other components, that can
311 work on specific hardware. 398 work on specific hardware.
312 399
400 :term:`SBOM`
401 This term means *Software Bill of Materials*. When you distribute
402 software, it offers a description of all the components you used,
403 their corresponding licenses, their dependencies, the changes that were
404 applied and the known vulnerabilities that were fixed.
405
406 This can be used by the recipients of the software to assess
407 their exposure to license compliance and security vulnerability issues.
408
409 See the :wikipedia:`Software Supply Chain <Software_supply_chain>`
410 article on Wikipedia for more details.
411
412 The OpenEmbedded Build System can generate such documentation for your
413 project, in :term:`SPDX` format, based on all the metadata it used to
414 build the software images. See the ":ref:`dev-manual/sbom:creating
415 a software bill of materials`" section of the Development Tasks manual.
416
313 :term:`Source Directory` 417 :term:`Source Directory`
314 This term refers to the directory structure 418 This term refers to the directory structure
315 created as a result of creating a local copy of the ``poky`` Git 419 created as a result of creating a local copy of the ``poky`` Git
@@ -344,19 +448,19 @@ universal, the list includes them just in case:
344 repository results in a local Git repository whose top-level folder 448 repository results in a local Git repository whose top-level folder
345 is also named "poky". 449 is also named "poky".
346 450
347 While it is not recommended that you use tarball expansion to set up 451 While it is not recommended that you use tarball extraction to set up
348 the Source Directory, if you do, the top-level directory name of the 452 the Source Directory, if you do, the top-level directory name of the
349 Source Directory is derived from the Yocto Project release tarball. 453 Source Directory is derived from the Yocto Project release tarball.
350 For example, downloading and unpacking 454 For example, downloading and unpacking poky tarballs from
351 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` 455 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/`
352 results in a Source Directory whose root folder is named 456 results in a Source Directory whose root folder is named poky.
353 ``&YOCTO_POKY;``. 457
354 458
355 It is important to understand the differences between the Source 459 It is important to understand the differences between the Source
356 Directory created by unpacking a released tarball as compared to 460 Directory created by unpacking a released tarball as compared to
357 cloning ``git://git.yoctoproject.org/poky``. When you unpack a 461 cloning ``git://git.yoctoproject.org/poky``. When you unpack a
358 tarball, you have an exact copy of the files based on the time of 462 tarball, you have an exact copy of the files based on the time of
359 release - a fixed release point. Any changes you make to your local 463 release --- a fixed release point. Any changes you make to your local
360 files in the Source Directory are on top of the release and will 464 files in the Source Directory are on top of the release and will
361 remain local only. On the other hand, when you clone the ``poky`` Git 465 remain local only. On the other hand, when you clone the ``poky`` Git
362 repository, you have an active development repository with access to 466 repository, you have an active development repository with access to
@@ -370,11 +474,53 @@ universal, the list includes them just in case:
370 ":ref:`overview-manual/development-environment:repositories, tags, and branches`" 474 ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
371 section in the Yocto Project Overview and Concepts Manual. 475 section in the Yocto Project Overview and Concepts Manual.
372 476
477 :term:`SPDX`
478 This term means *Software Package Data Exchange*, and is used as an open
479 standard for providing a *Software Bill of Materials* (:term:`SBOM`).
480 This standard is developed through a `Linux Foundation project
481 <https://spdx.dev/>`__ and is used by the OpenEmbedded Build System to
482 provide an :term:`SBOM` associated to each software image.
483
484 For details, see Wikipedia's :wikipedia:`SPDX page <Software_Package_Data_Exchange>`
485 and the ":ref:`dev-manual/sbom:creating a software bill of materials`"
486 section of the Development Tasks manual.
487
488 :term:`Sysroot`
489 When cross-compiling, the target file system may be differently laid
490 out and contain different things compared to the host system. The concept
491 of a *sysroot* is directory which looks like the target filesystem and
492 can be used to cross-compile against.
493
494 In the context of cross-compiling toolchains, a *sysroot*
495 typically contains C library and kernel headers, plus the
496 compiled binaries for the C library. A *multilib toolchain*
497 can contain multiple variants of the C library binaries,
498 each compiled for a target instruction set (such as ``armv5``,
499 ``armv7`` and ``armv8``), and possibly optimized for a specific CPU core.
500
501 In the more specific context of the OpenEmbedded build System and
502 of the Yocto Project, each recipe has two sysroots:
503
504 - A *target sysroot* contains all the **target** libraries and headers
505 needed to build the recipe.
506
507 - A *native sysroot* contains all the **host** files and executables
508 needed to build the recipe.
509
510 See the :term:`SYSROOT_* <SYSROOT_DESTDIR>` variables controlling
511 how sysroots are created and stored.
512
373 :term:`Task` 513 :term:`Task`
374 A unit of execution for BitBake (e.g. 514 A per-recipe unit of execution for BitBake (e.g.
375 :ref:`ref-tasks-compile`, 515 :ref:`ref-tasks-compile`,
376 :ref:`ref-tasks-fetch`, 516 :ref:`ref-tasks-fetch`,
377 :ref:`ref-tasks-patch`, and so forth). 517 :ref:`ref-tasks-patch`, and so forth).
518 One of the major benefits of the build system is that, since each
519 recipe will typically spawn the execution of numerous tasks,
520 it is entirely possible that many tasks can execute in parallel,
521 either tasks from separate recipes or independent tasks within
522 the same recipe, potentially up to the parallelism of your
523 build system.
378 524
379 :term:`Toaster` 525 :term:`Toaster`
380 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. 526 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
@@ -385,7 +531,7 @@ universal, the list includes them just in case:
385 531
386 :term:`Upstream` 532 :term:`Upstream`
387 A reference to source code or repositories that are not 533 A reference to source code or repositories that are not
388 local to the development system but located in a master area that is 534 local to the development system but located in a remote area that is
389 controlled by the maintainer of the source code. For example, in 535 controlled by the maintainer of the source code. For example, in
390 order for a developer to work on a particular piece of code, they 536 order for a developer to work on a particular piece of code, they
391 need to first get a copy of it from an "upstream" source. 537 need to first get a copy of it from an "upstream" source.
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 2cb37b6a2b..435481c9aa 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -17,6 +17,7 @@ system and gives an overview of their function and contents.
17:term:`W <WARN_QA>` :term:`X <XSERVER>` 17:term:`W <WARN_QA>` :term:`X <XSERVER>`
18 18
19.. glossary:: 19.. glossary::
20 :sorted:
20 21
21 :term:`ABIEXTENSION` 22 :term:`ABIEXTENSION`
22 Extension to the Application Binary Interface (ABI) field of the GNU 23 Extension to the Application Binary Interface (ABI) field of the GNU
@@ -24,8 +25,7 @@ system and gives an overview of their function and contents.
24 25
25 ABI extensions are set in the machine include files. For example, the 26 ABI extensions are set in the machine include files. For example, the
26 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the 27 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
27 following extension: 28 following extension::
28 ::
29 29
30 ABIEXTENSION = "eabi" 30 ABIEXTENSION = "eabi"
31 31
@@ -37,12 +37,11 @@ system and gives an overview of their function and contents.
37 requirement on the existence of the package. 37 requirement on the existence of the package.
38 38
39 Like all package-controlling variables, you must always use them in 39 Like all package-controlling variables, you must always use them in
40 conjunction with a package name override, as in: 40 conjunction with a package name override, as in::
41 ::
42 41
43 ALLOW_EMPTY_${PN} = "1" 42 ALLOW_EMPTY:${PN} = "1"
44 ALLOW_EMPTY_${PN}-dev = "1" 43 ALLOW_EMPTY:${PN}-dev = "1"
45 ALLOW_EMPTY_${PN}-staticdev = "1" 44 ALLOW_EMPTY:${PN}-staticdev = "1"
46 45
47 :term:`ALTERNATIVE` 46 :term:`ALTERNATIVE`
48 Lists commands in a package that need an alternative binary naming 47 Lists commands in a package that need an alternative binary naming
@@ -51,25 +50,22 @@ system and gives an overview of their function and contents.
51 alternatives system to create a different binary naming scheme so the 50 alternatives system to create a different binary naming scheme so the
52 commands can co-exist. 51 commands can co-exist.
53 52
54 To use the variable, list out the package's commands that also exist 53 To use the variable, list out the package's commands that are also
55 as part of another package. For example, if the ``busybox`` package 54 provided by another package. For example, if the ``busybox`` package
56 has four commands that also exist as part of another package, you 55 has four such commands, you identify them as follows::
57 identify them as follows:
58 ::
59 56
60 ALTERNATIVE_busybox = "sh sed test bracket" 57 ALTERNATIVE:busybox = "sh sed test bracket"
61 58
62 For more information on the alternatives system, see the 59 For more information on the alternatives system, see the
63 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 60 ":ref:`ref-classes-update-alternatives`"
64 section. 61 section.
65 62
66 :term:`ALTERNATIVE_LINK_NAME` 63 :term:`ALTERNATIVE_LINK_NAME`
67 Used by the alternatives system to map duplicated commands to actual 64 Used by the alternatives system to map duplicated commands to actual
68 locations. For example, if the ``bracket`` command provided by the 65 locations. For example, if the ``bracket`` command provided by the
69 ``busybox`` package is duplicated through another package, you must 66 ``busybox`` package is duplicated through another package, you must
70 use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual 67 use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
71 location: 68 location::
72 ::
73 69
74 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" 70 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
75 71
@@ -78,10 +74,10 @@ system and gives an overview of their function and contents.
78 74
79 .. note:: 75 .. note::
80 76
81 If ``ALTERNATIVE_LINK_NAME`` is not defined, it defaults to ``${bindir}/name``. 77 If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``.
82 78
83 For more information on the alternatives system, see the 79 For more information on the alternatives system, see the
84 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 80 ":ref:`ref-classes-update-alternatives`"
85 section. 81 section.
86 82
87 :term:`ALTERNATIVE_PRIORITY` 83 :term:`ALTERNATIVE_PRIORITY`
@@ -90,15 +86,14 @@ system and gives an overview of their function and contents.
90 default regardless of the command name or package, a default for 86 default regardless of the command name or package, a default for
91 specific duplicated commands regardless of the package, or a default 87 specific duplicated commands regardless of the package, or a default
92 for specific commands tied to particular packages. Here are the 88 for specific commands tied to particular packages. Here are the
93 available syntax forms: 89 available syntax forms::
94 ::
95 90
96 ALTERNATIVE_PRIORITY = "priority" 91 ALTERNATIVE_PRIORITY = "priority"
97 ALTERNATIVE_PRIORITY[name] = "priority" 92 ALTERNATIVE_PRIORITY[name] = "priority"
98 ALTERNATIVE_PRIORITY_pkg[name] = "priority" 93 ALTERNATIVE_PRIORITY_pkg[name] = "priority"
99 94
100 For more information on the alternatives system, see the 95 For more information on the alternatives system, see the
101 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 96 ":ref:`ref-classes-update-alternatives`"
102 section. 97 section.
103 98
104 :term:`ALTERNATIVE_TARGET` 99 :term:`ALTERNATIVE_TARGET`
@@ -107,8 +102,7 @@ system and gives an overview of their function and contents.
107 default location for all duplicated commands regardless of the 102 default location for all duplicated commands regardless of the
108 command name or package, a default for specific duplicated commands 103 command name or package, a default for specific duplicated commands
109 regardless of the package, or a default for specific commands tied to 104 regardless of the package, or a default for specific commands tied to
110 particular packages. Here are the available syntax forms: 105 particular packages. Here are the available syntax forms::
111 ::
112 106
113 ALTERNATIVE_TARGET = "target" 107 ALTERNATIVE_TARGET = "target"
114 ALTERNATIVE_TARGET[name] = "target" 108 ALTERNATIVE_TARGET[name] = "target"
@@ -116,11 +110,11 @@ system and gives an overview of their function and contents.
116 110
117 .. note:: 111 .. note::
118 112
119 If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value 113 If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value
120 from the :term:`ALTERNATIVE_LINK_NAME` variable. 114 from the :term:`ALTERNATIVE_LINK_NAME` variable.
121 115
122 If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the 116 If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the
123 same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" 117 same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``"
124 appended to it. 118 appended to it.
125 119
126 Finally, if the file referenced has not been renamed, the 120 Finally, if the file referenced has not been renamed, the
@@ -129,38 +123,34 @@ system and gives an overview of their function and contents.
129 task while retaining support for the command if necessary. 123 task while retaining support for the command if necessary.
130 124
131 For more information on the alternatives system, see the 125 For more information on the alternatives system, see the
132 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 126 ":ref:`ref-classes-update-alternatives`" section.
133 section.
134 127
135 :term:`ANY_OF_DISTRO_FEATURES` 128 :term:`ANY_OF_DISTRO_FEATURES`
136 When inheriting the 129 When inheriting the :ref:`ref-classes-features_check`
137 :ref:`features_check <ref-classes-features_check>`
138 class, this variable identifies a list of distribution features where 130 class, this variable identifies a list of distribution features where
139 at least one must be enabled in the current configuration in order 131 at least one must be enabled in the current configuration in order
140 for the OpenEmbedded build system to build the recipe. In other words, 132 for the OpenEmbedded build system to build the recipe. In other words,
141 if none of the features listed in ``ANY_OF_DISTRO_FEATURES`` 133 if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES`
142 appear in ``DISTRO_FEATURES`` within the current configuration, then 134 appear in :term:`DISTRO_FEATURES` within the current configuration, then
143 the recipe will be skipped, and if the build system attempts to build 135 the recipe will be skipped, and if the build system attempts to build
144 the recipe then an error will be triggered. 136 the recipe then an error will be triggered.
145
146 137
147 :term:`APPEND` 138 :term:`APPEND`
148 An override list of append strings for each target specified with 139 An override list of append strings for each target specified with
149 :term:`LABELS`. 140 :term:`LABELS`.
150 141
151 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 142 See the :ref:`ref-classes-grub-efi` class for more
152 information on how this variable is used. 143 information on how this variable is used.
153 144
154 :term:`AR` 145 :term:`AR`
155 The minimal command and arguments used to run ``ar``. 146 The minimal command and arguments used to run ``ar``.
156 147
157 :term:`ARCHIVER_MODE` 148 :term:`ARCHIVER_MODE`
158 When used with the :ref:`archiver <ref-classes-archiver>` class, 149 When used with the :ref:`ref-classes-archiver` class,
159 determines the type of information used to create a released archive. 150 determines the type of information used to create a released archive.
160 You can use this variable to create archives of patched source, 151 You can use this variable to create archives of patched source,
161 original source, configured source, and so forth by employing the 152 original source, configured source, and so forth by employing the
162 following variable flags (varflags): 153 following variable flags (varflags)::
163 ::
164 154
165 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. 155 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
166 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. 156 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
@@ -182,7 +172,7 @@ system and gives an overview of their function and contents.
182 attempt to build. Instead, BitBake assumes these recipes have already 172 attempt to build. Instead, BitBake assumes these recipes have already
183 been built. 173 been built.
184 174
185 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native 175 In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
186 tools that should not be built. An example is ``git-native``, which 176 tools that should not be built. An example is ``git-native``, which
187 when specified, allows for the Git binary from the host to be used 177 when specified, allows for the Git binary from the host to be used
188 rather than building ``git-native``. 178 rather than building ``git-native``.
@@ -193,65 +183,47 @@ system and gives an overview of their function and contents.
193 system. Separate multiple entries using spaces. 183 system. Separate multiple entries using spaces.
194 184
195 As an example, use the following form to add an ``shlib`` provider of 185 As an example, use the following form to add an ``shlib`` provider of
196 shlibname in packagename with the optional version: 186 shlibname in packagename with the optional version::
197 ::
198 187
199 shlibname:packagename[_version] 188 shlibname:packagename[_version]
200 189
201 Here is an example that adds a shared library named ``libEGL.so.1`` 190 Here is an example that adds a shared library named ``libEGL.so.1``
202 as being provided by the ``libegl-implementation`` package: 191 as being provided by the ``libegl-implementation`` package::
203 ::
204 192
205 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" 193 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
206 194
207 :term:`AUTHOR`
208 The email address used to contact the original author or authors in
209 order to send patches and forward bugs.
210
211 :term:`AUTO_LIBNAME_PKGS` 195 :term:`AUTO_LIBNAME_PKGS`
212 When the :ref:`debian <ref-classes-debian>` class is inherited, 196 When the :ref:`ref-classes-debian` class is inherited,
213 which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which 197 which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which
214 packages should be checked for libraries and renamed according to 198 packages should be checked for libraries and renamed according to
215 Debian library package naming. 199 Debian library package naming.
216 200
217 The default value is "${PACKAGES}", which causes the debian class to 201 The default value is "${PACKAGES}", which causes the
218 act on all packages that are explicitly generated by the recipe. 202 :ref:`ref-classes-debian` class to act on all packages that are
219 203 explicitly generated by the recipe.
220 :term:`AUTO_SYSLINUXMENU`
221 Enables creating an automatic menu for the syslinux bootloader. You
222 must set this variable in your recipe. The
223 :ref:`syslinux <ref-classes-syslinux>` class checks this variable.
224 204
225 :term:`AUTOREV` 205 :term:`AUTOREV`
226 When ``SRCREV`` is set to the value of this variable, it specifies to 206 When :term:`SRCREV` is set to the value of this variable, it specifies to
227 use the latest source revision in the repository. Here is an example: 207 use the latest source revision in the repository. Here is an example::
228 ::
229 208
230 SRCREV = "${AUTOREV}" 209 SRCREV = "${AUTOREV}"
231 210
232 If you use the previous statement to retrieve the latest version of 211 If you use the previous statement to retrieve the latest version of
233 software, you need to be sure :term:`PV` contains 212 software, you need to be sure :term:`PV` contains
234 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you 213 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel
235 have a kernel recipe that inherits the 214 recipe that inherits the :ref:`ref-classes-kernel` class and you
236 :ref:`kernel <ref-classes-kernel>` class and you use the previous 215 use the previous statement. In this example, ``${SRCPV}`` does not
237 statement. In this example, ``${SRCPV}`` does not automatically get 216 automatically get into :term:`PV`. Consequently, you need to change
238 into ``PV``. Consequently, you need to change ``PV`` in your recipe 217 :term:`PV` in your recipe so that it does contain ``${SRCPV}``.
239 so that it does contain ``${SRCPV}``.
240 218
241 For more information see the 219 For more information see the
242 ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" 220 ":ref:`dev-manual/packages:automatically incrementing a package version number`"
243 section in the Yocto Project Development Tasks Manual. 221 section in the Yocto Project Development Tasks Manual.
244 222
245 :term:`AVAILABLE_LICENSES` 223 :term:`AUTO_SYSLINUXMENU`
246 List of licenses found in the directories specified by 224 Enables creating an automatic menu for the syslinux bootloader. You
247 :term:`COMMON_LICENSE_DIR` and 225 must set this variable in your recipe. The
248 :term:`LICENSE_PATH`. 226 :ref:`ref-classes-syslinux` class checks this variable.
249
250 .. note::
251
252 It is assumed that all changes to ``COMMON_LICENSE_DIR`` and
253 ``LICENSE_PATH`` have been done before ``AVAILABLE_LICENSES``
254 is defined (in :ref:`ref-classes-license`).
255 227
256 :term:`AVAILTUNES` 228 :term:`AVAILTUNES`
257 The list of defined CPU and Application Binary Interface (ABI) 229 The list of defined CPU and Application Binary Interface (ABI)
@@ -261,26 +233,36 @@ system and gives an overview of their function and contents.
261 The list simply presents the tunes that are available. Not all tunes 233 The list simply presents the tunes that are available. Not all tunes
262 may be compatible with a particular machine configuration, or with 234 may be compatible with a particular machine configuration, or with
263 each other in a 235 each other in a
264 :ref:`Multilib <dev-manual/common-tasks:combining multiple versions of library files into one image>` 236 :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>`
265 configuration. 237 configuration.
266 238
267 To add a tune to the list, be sure to append it with spaces using the 239 To add a tune to the list, be sure to append it with spaces using the
268 "+=" BitBake operator. Do not simply replace the list by using the 240 "+=" BitBake operator. Do not simply replace the list by using the
269 "=" operator. See the 241 "=" operator. See the
270 ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake 242 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake
271 User Manual for more information. 243 User Manual for more information.
272 244
245 :term:`AZ_SAS`
246 Azure Storage Shared Access Signature, when using the
247 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
248 This variable can be defined to be used by the fetcher to authenticate
249 and gain access to non-public artifacts::
250
251 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
252
253 For more information see Microsoft's Azure Storage documentation at
254 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
255
273 :term:`B` 256 :term:`B`
274 The directory within the :term:`Build Directory` in 257 The directory within the :term:`Build Directory` in which the
275 which the OpenEmbedded build system places generated objects during a 258 OpenEmbedded build system places generated objects during a recipe's
276 recipe's build process. By default, this directory is the same as the 259 build process. By default, this directory is the same as the
277 :term:`S` directory, which is defined as: 260 :term:`S` directory, which is defined as::
278 ::
279 261
280 S = "${WORKDIR}/${BP}" 262 S = "${WORKDIR}/${BP}"
281 263
282 You can separate the (``S``) directory and the directory pointed to 264 You can separate the (:term:`S`) directory and the directory pointed to
283 by the ``B`` variable. Most Autotools-based recipes support 265 by the :term:`B` variable. Most Autotools-based recipes support
284 separating these directories. The build system defaults to using 266 separating these directories. The build system defaults to using
285 separate directories for ``gcc`` and some kernel recipes. 267 separate directories for ``gcc`` and some kernel recipes.
286 268
@@ -289,17 +271,15 @@ system and gives an overview of their function and contents.
289 packages are packages installed only through the 271 packages are packages installed only through the
290 :term:`RRECOMMENDS` variable. You can prevent any 272 :term:`RRECOMMENDS` variable. You can prevent any
291 of these "recommended" packages from being installed by listing them 273 of these "recommended" packages from being installed by listing them
292 with the ``BAD_RECOMMENDATIONS`` variable: 274 with the :term:`BAD_RECOMMENDATIONS` variable::
293 ::
294 275
295 BAD_RECOMMENDATIONS = "package_name package_name package_name ..." 276 BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
296 277
297 You can set this variable globally in your ``local.conf`` file or you 278 You can set this variable globally in your ``local.conf`` file or you
298 can attach it to a specific image recipe by using the recipe name 279 can attach it to a specific image recipe by using the recipe name
299 override: 280 override::
300 ::
301 281
302 BAD_RECOMMENDATIONS_pn-target_image = "package_name" 282 BAD_RECOMMENDATIONS:pn-target_image = "package_name"
303 283
304 It is important to realize that if you choose to not install packages 284 It is important to realize that if you choose to not install packages
305 using this variable and some other packages are dependent on them 285 using this variable and some other packages are dependent on them
@@ -307,8 +287,8 @@ system and gives an overview of their function and contents.
307 variable), the OpenEmbedded build system ignores your request and 287 variable), the OpenEmbedded build system ignores your request and
308 will install the packages to avoid dependency errors. 288 will install the packages to avoid dependency errors.
309 289
310 Support for this variable exists only when using the IPK and RPM 290 This variable is supported only when using the IPK and RPM
311 packaging backend. Support does not exist for DEB. 291 packaging backends. DEB is not supported.
312 292
313 See the :term:`NO_RECOMMENDATIONS` and the 293 See the :term:`NO_RECOMMENDATIONS` and the
314 :term:`PACKAGE_EXCLUDE` variables for related 294 :term:`PACKAGE_EXCLUDE` variables for related
@@ -316,12 +296,12 @@ system and gives an overview of their function and contents.
316 296
317 :term:`BASE_LIB` 297 :term:`BASE_LIB`
318 The library directory name for the CPU or Application Binary 298 The library directory name for the CPU or Application Binary
319 Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib 299 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib
320 context. See the ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`" 300 context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`"
321 section in the Yocto Project Development Tasks Manual for information 301 section in the Yocto Project Development Tasks Manual for information
322 on Multilib. 302 on Multilib.
323 303
324 The ``BASE_LIB`` variable is defined in the machine include files in 304 The :term:`BASE_LIB` variable is defined in the machine include files in
325 the :term:`Source Directory`. If Multilib is not 305 the :term:`Source Directory`. If Multilib is not
326 being used, the value defaults to "lib". 306 being used, the value defaults to "lib".
327 307
@@ -331,16 +311,15 @@ system and gives an overview of their function and contents.
331 311
332 :term:`BB_ALLOWED_NETWORKS` 312 :term:`BB_ALLOWED_NETWORKS`
333 Specifies a space-delimited list of hosts that the fetcher is allowed 313 Specifies a space-delimited list of hosts that the fetcher is allowed
334 to use to obtain the required source code. Following are 314 to use to obtain the required source code. Here are
335 considerations surrounding this variable: 315 considerations surrounding this variable:
336 316
337 - This host list is only used if ``BB_NO_NETWORK`` is either not set 317 - This host list is only used if :term:`BB_NO_NETWORK` is either not set
338 or set to "0". 318 or set to "0".
339 319
340 - Limited support for wildcard matching against the beginning of 320 - There is limited support for wildcard matching against the beginning of
341 host names exists. For example, the following setting matches 321 host names. For example, the following setting matches
342 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. 322 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``::
343 ::
344 323
345 BB_ALLOWED_NETWORKS = "*.gnu.org" 324 BB_ALLOWED_NETWORKS = "*.gnu.org"
346 325
@@ -359,14 +338,29 @@ system and gives an overview of their function and contents.
359 338
360 - Attempts to access networks not in the host list cause a failure. 339 - Attempts to access networks not in the host list cause a failure.
361 340
362 Using ``BB_ALLOWED_NETWORKS`` in conjunction with 341 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
363 :term:`PREMIRRORS` is very useful. Adding the host 342 :term:`PREMIRRORS` is very useful. Adding the host
364 you want to use to ``PREMIRRORS`` results in the source code being 343 you want to use to :term:`PREMIRRORS` results in the source code being
365 fetched from an allowed location and avoids raising an error when a 344 fetched from an allowed location and avoids raising an error when a
366 host that is not allowed is in a :term:`SRC_URI` 345 host that is not allowed is in a :term:`SRC_URI`
367 statement. This is because the fetcher does not attempt to use the 346 statement. This is because the fetcher does not attempt to use the
368 host listed in ``SRC_URI`` after a successful fetch from the 347 host listed in :term:`SRC_URI` after a successful fetch from the
369 ``PREMIRRORS`` occurs. 348 :term:`PREMIRRORS` occurs.
349
350 :term:`BB_BASEHASH_IGNORE_VARS`
351 See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual.
352
353 :term:`BB_CACHEDIR`
354 See :term:`bitbake:BB_CACHEDIR` in the BitBake manual.
355
356 :term:`BB_CHECK_SSL_CERTS`
357 See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual.
358
359 :term:`BB_CONSOLELOG`
360 See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual.
361
362 :term:`BB_CURRENTTASK`
363 See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual.
370 364
371 :term:`BB_DANGLINGAPPENDS_WARNONLY` 365 :term:`BB_DANGLINGAPPENDS_WARNONLY`
372 Defines how BitBake handles situations where an append file 366 Defines how BitBake handles situations where an append file
@@ -382,17 +376,22 @@ system and gives an overview of their function and contents.
382 376
383 You can change the default behavior by setting this variable to "1", 377 You can change the default behavior by setting this variable to "1",
384 "yes", or "true" in your ``local.conf`` file, which is located in the 378 "yes", or "true" in your ``local.conf`` file, which is located in the
385 :term:`Build Directory`: Here is an example: 379 :term:`Build Directory`: Here is an example::
386 ::
387 380
388 BB_DANGLINGAPPENDS_WARNONLY = "1" 381 BB_DANGLINGAPPENDS_WARNONLY = "1"
389 382
383 :term:`BB_DEFAULT_TASK`
384 See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual.
385
386 :term:`BB_DEFAULT_UMASK`
387 See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual.
388
390 :term:`BB_DISKMON_DIRS` 389 :term:`BB_DISKMON_DIRS`
391 Monitors disk space and available inodes during the build and allows 390 Monitors disk space and available inodes during the build and allows
392 you to control the build based on these parameters. 391 you to control the build based on these parameters.
393 392
394 Disk space monitoring is disabled by default. To enable monitoring, 393 Disk space monitoring is disabled by default. To enable monitoring,
395 add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file 394 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
396 found in the :term:`Build Directory`. Use the 395 found in the :term:`Build Directory`. Use the
397 following form: 396 following form:
398 397
@@ -403,7 +402,7 @@ system and gives an overview of their function and contents.
403 where: 402 where:
404 403
405 action is: 404 action is:
406 ABORT: Immediately abort the build when 405 ABORT: Immediately stop the build when
407 a threshold is broken. 406 a threshold is broken.
408 STOPTASKS: Stop the build after the currently 407 STOPTASKS: Stop the build after the currently
409 executing tasks have finished when 408 executing tasks have finished when
@@ -432,8 +431,7 @@ system and gives an overview of their function and contents.
432 not specify G, M, or K, Kbytes is assumed by 431 not specify G, M, or K, Kbytes is assumed by
433 default. Do not use GB, MB, or KB. 432 default. Do not use GB, MB, or KB.
434 433
435 Here are some examples: 434 Here are some examples::
436 ::
437 435
438 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" 436 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
439 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" 437 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
@@ -442,13 +440,13 @@ system and gives an overview of their function and contents.
442 The first example works only if you also provide the 440 The first example works only if you also provide the
443 :term:`BB_DISKMON_WARNINTERVAL` 441 :term:`BB_DISKMON_WARNINTERVAL`
444 variable in the ``conf/local.conf``. This example causes the build 442 variable in the ``conf/local.conf``. This example causes the build
445 system to immediately abort when either the disk space in 443 system to immediately stop when either the disk space in
446 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops 444 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
447 below 100 Kbytes. Because two directories are provided with the 445 below 100 Kbytes. Because two directories are provided with the
448 variable, the build system also issue a warning when the disk space 446 variable, the build system also issue a warning when the disk space
449 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number 447 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
450 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 448 of free inodes drops below 100 Kbytes. Subsequent warnings are issued
451 during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` 449 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL`
452 variable. 450 variable.
453 451
454 The second example stops the build after all currently executing 452 The second example stops the build after all currently executing
@@ -456,7 +454,7 @@ system and gives an overview of their function and contents.
456 directory drops below 1 Gbyte. No disk monitoring occurs for the free 454 directory drops below 1 Gbyte. No disk monitoring occurs for the free
457 inodes in this case. 455 inodes in this case.
458 456
459 The final example immediately aborts the build when the number of 457 The final example immediately stops the build when the number of
460 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 458 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
461 disk space monitoring for the directory itself occurs in this case. 459 disk space monitoring for the directory itself occurs in this case.
462 460
@@ -465,16 +463,15 @@ system and gives an overview of their function and contents.
465 intervals, define the variable in your ``conf/local.conf`` file in 463 intervals, define the variable in your ``conf/local.conf`` file in
466 the :term:`Build Directory`. 464 the :term:`Build Directory`.
467 465
468 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you 466 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
469 must also use the :term:`BB_DISKMON_DIRS` 467 must also use the :term:`BB_DISKMON_DIRS`
470 variable and define its action as "WARN". During the build, 468 variable and define its action as "WARN". During the build,
471 subsequent warnings are issued each time disk space or number of free 469 subsequent warnings are issued each time disk space or number of free
472 inodes further reduces by the respective interval. 470 inodes further reduces by the respective interval.
473 471
474 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you 472 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
475 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk 473 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
476 monitoring interval defaults to the following: 474 monitoring interval defaults to the following::
477 ::
478 475
479 BB_DISKMON_WARNINTERVAL = "50M,5K" 476 BB_DISKMON_WARNINTERVAL = "50M,5K"
480 477
@@ -497,8 +494,7 @@ system and gives an overview of their function and contents.
497 G, M, or K for Gbytes, Mbytes, or Kbytes, 494 G, M, or K for Gbytes, Mbytes, or Kbytes,
498 respectively. You cannot use GB, MB, or KB. 495 respectively. You cannot use GB, MB, or KB.
499 496
500 Here is an example: 497 Here is an example::
501 ::
502 498
503 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 499 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
504 BB_DISKMON_WARNINTERVAL = "50M,5K" 500 BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -511,6 +507,18 @@ system and gives an overview of their function and contents.
511 a respective interval is reached beyond the initial warning (i.e. 1 507 a respective interval is reached beyond the initial warning (i.e. 1
512 Gbytes and 100 Kbytes). 508 Gbytes and 100 Kbytes).
513 509
510 :term:`BB_ENV_PASSTHROUGH`
511 See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual.
512
513 :term:`BB_ENV_PASSTHROUGH_ADDITIONS`
514 See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual.
515
516 :term:`BB_FETCH_PREMIRRORONLY`
517 See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual.
518
519 :term:`BB_FILENAME`
520 See :term:`bitbake:BB_FILENAME` in the BitBake manual.
521
514 :term:`BB_GENERATE_MIRROR_TARBALLS` 522 :term:`BB_GENERATE_MIRROR_TARBALLS`
515 Causes tarballs of the source control repositories (e.g. Git 523 Causes tarballs of the source control repositories (e.g. Git
516 repositories), including metadata, to be placed in the 524 repositories), including metadata, to be placed in the
@@ -518,8 +526,7 @@ system and gives an overview of their function and contents.
518 526
519 For performance reasons, creating and placing tarballs of these 527 For performance reasons, creating and placing tarballs of these
520 repositories is not the default action by the OpenEmbedded build 528 repositories is not the default action by the OpenEmbedded build
521 system. 529 system::
522 ::
523 530
524 BB_GENERATE_MIRROR_TARBALLS = "1" 531 BB_GENERATE_MIRROR_TARBALLS = "1"
525 532
@@ -527,72 +534,199 @@ system and gives an overview of their function and contents.
527 ``local.conf`` file in the :term:`Build Directory`. 534 ``local.conf`` file in the :term:`Build Directory`.
528 535
529 Once you have the tarballs containing your source files, you can 536 Once you have the tarballs containing your source files, you can
530 clean up your ``DL_DIR`` directory by deleting any Git or other 537 clean up your :term:`DL_DIR` directory by deleting any Git or other
531 source control work directories. 538 source control work directories.
532 539
540 :term:`BB_GENERATE_SHALLOW_TARBALLS`
541 See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
542
543 :term:`BB_GIT_SHALLOW`
544 See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual.
545
546 :term:`BB_GIT_SHALLOW_DEPTH`
547 See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual.
548
549 :term:`BB_HASHCHECK_FUNCTION`
550 See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual.
551
552 :term:`BB_HASHCONFIG_IGNORE_VARS`
553 See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual.
554
555 :term:`BB_HASHSERVE`
556 See :term:`bitbake:BB_HASHSERVE` in the BitBake manual.
557
558 :term:`BB_HASHSERVE_UPSTREAM`
559 See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual.
560
561 :term:`BB_INVALIDCONF`
562 See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual.
563
564 :term:`BB_LOGCONFIG`
565 See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual.
566
567 :term:`BB_LOGFMT`
568 See :term:`bitbake:BB_LOGFMT` in the BitBake manual.
569
570 :term:`BB_MULTI_PROVIDER_ALLOWED`
571 See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual.
572
573 :term:`BB_NICE_LEVEL`
574 See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual.
575
576 :term:`BB_NO_NETWORK`
577 See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual.
578
579 :term:`BB_NUMBER_PARSE_THREADS`
580 See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual.
581
533 :term:`BB_NUMBER_THREADS` 582 :term:`BB_NUMBER_THREADS`
534 The maximum number of tasks BitBake should run in parallel at any one 583 The maximum number of tasks BitBake should run in parallel at any one
535 time. The OpenEmbedded build system automatically configures this 584 time. The OpenEmbedded build system automatically configures this
536 variable to be equal to the number of cores on the build system. For 585 variable to be equal to the number of cores on the build system. For
537 example, a system with a dual core processor that also uses 586 example, a system with a dual core processor that also uses
538 hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default 587 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default
539 to "4". 588 to "4".
540 589
541 For single socket systems (i.e. one CPU), you should not have to 590 For single socket systems (i.e. one CPU), you should not have to
542 override this variable to gain optimal parallelism during builds. 591 override this variable to gain optimal parallelism during builds.
543 However, if you have very large systems that employ multiple physical 592 However, if you have very large systems that employ multiple physical
544 CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable 593 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable
545 is not set higher than "20". 594 is not set higher than "20".
546 595
547 For more information on speeding up builds, see the 596 For more information on speeding up builds, see the
548 ":ref:`dev-manual/common-tasks:speeding up a build`" 597 ":ref:`dev-manual/speeding-up-build:speeding up a build`"
549 section in the Yocto Project Development Tasks Manual. 598 section in the Yocto Project Development Tasks Manual.
550 599
600 On the other hand, if your goal is to limit the amount of system
601 resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS`
602 to a number lower than the number of CPU threads in your machine
603 won't be sufficient. That's because each package will still be built
604 and installed through a number of parallel jobs specified by the
605 :term:`PARALLEL_MAKE` variable, which is by default the number of CPU
606 threads in your system, and is not impacted by the
607 :term:`BB_NUMBER_THREADS` value.
608
609 So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set
610 :term:`PARALLEL_MAKE`, most of your system resources will be consumed
611 anyway.
612
613 Therefore, if you intend to reduce the load of your build system by
614 setting :term:`BB_NUMBER_THREADS` to a relatively low value compared
615 to the number of CPU threads on your system, you should also set
616 :term:`PARALLEL_MAKE` to a similarly low value.
617
618 An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage
619 of build system resources under control is to use the smarter
620 :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or
621 :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake
622 from starting new tasks as long as thresholds are exceeded. Anyway,
623 as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the
624 tasks already being run from using all CPU threads on the system
625 if :term:`PARALLEL_MAKE` is not set to a low value.
626
627 :term:`BB_ORIGENV`
628 See :term:`bitbake:BB_ORIGENV` in the BitBake manual.
629
630 :term:`BB_PRESERVE_ENV`
631 See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual.
632
633 :term:`BB_PRESSURE_MAX_CPU`
634 See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual.
635
636 :term:`BB_PRESSURE_MAX_IO`
637 See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual.
638
639 :term:`BB_PRESSURE_MAX_MEMORY`
640 See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual.
641
642 :term:`BB_RUNFMT`
643 See :term:`bitbake:BB_RUNFMT` in the BitBake manual.
644
645 :term:`BB_RUNTASK`
646 See :term:`bitbake:BB_RUNTASK` in the BitBake manual.
647
648 :term:`BB_SCHEDULER`
649 See :term:`bitbake:BB_SCHEDULER` in the BitBake manual.
650
651 :term:`BB_SCHEDULERS`
652 See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual.
653
551 :term:`BB_SERVER_TIMEOUT` 654 :term:`BB_SERVER_TIMEOUT`
552 Specifies the time (in seconds) after which to unload the BitBake 655 Specifies the time (in seconds) after which to unload the BitBake
553 server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how 656 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
554 long the BitBake server stays resident between invocations. 657 long the BitBake server stays resident between invocations.
555 658
556 For example, the following statement in your ``local.conf`` file 659 For example, the following statement in your ``local.conf`` file
557 instructs the server to be unloaded after 20 seconds of inactivity: 660 instructs the server to be unloaded after 20 seconds of inactivity::
558 ::
559 661
560 BB_SERVER_TIMEOUT = "20" 662 BB_SERVER_TIMEOUT = "20"
561 663
562 If you want the server to never be unloaded, 664 If you want the server to never be unloaded,
563 set ``BB_SERVER_TIMEOUT`` to "-1". 665 set :term:`BB_SERVER_TIMEOUT` to "-1".
666
667 :term:`BB_SETSCENE_DEPVALID`
668 See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual.
669
670 :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
671 See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual.
672
673 :term:`BB_SIGNATURE_HANDLER`
674 See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual.
675
676 :term:`BB_SRCREV_POLICY`
677 See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual.
678
679 :term:`BB_STRICT_CHECKSUM`
680 See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual.
681
682 :term:`BB_TASK_IONICE_LEVEL`
683 See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual.
684
685 :term:`BB_TASK_NICE_LEVEL`
686 See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual.
687
688 :term:`BB_TASKHASH`
689 See :term:`bitbake:BB_TASKHASH` in the BitBake manual.
690
691 :term:`BB_VERBOSE_LOGS`
692 See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual.
693
694 :term:`BB_WORKERCONTEXT`
695 See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual.
564 696
565 :term:`BBCLASSEXTEND` 697 :term:`BBCLASSEXTEND`
566 Allows you to extend a recipe so that it builds variants of the 698 Allows you to extend a recipe so that it builds variants of the
567 software. Common variants for recipes exist such as "natives" like 699 software. There are common variants for recipes as "natives" like
568 ``quilt-native``, which is a copy of Quilt built to run on the build 700 ``quilt-native``, which is a copy of Quilt built to run on the build
569 system; "crosses" such as ``gcc-cross``, which is a compiler built to 701 system; "crosses" such as ``gcc-cross``, which is a compiler built to
570 run on the build machine but produces binaries that run on the target 702 run on the build machine but produces binaries that run on the target
571 :term:`MACHINE`; "nativesdk", which targets the SDK 703 :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which
572 machine instead of ``MACHINE``; and "mulitlibs" in the form 704 targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in
573 "``multilib:``\ multilib_name". 705 the form "``multilib:``\ multilib_name".
574 706
575 To build a different variant of the recipe with a minimal amount of 707 To build a different variant of the recipe with a minimal amount of
576 code, it usually is as simple as adding the following to your recipe: 708 code, it usually is as simple as adding the following to your recipe::
577 ::
578 709
579 BBCLASSEXTEND =+ "native nativesdk" 710 BBCLASSEXTEND =+ "native nativesdk"
580 BBCLASSEXTEND =+ "multilib:multilib_name" 711 BBCLASSEXTEND =+ "multilib:multilib_name"
581 712
582 .. note:: 713 .. note::
583 714
584 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe 715 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
585 variants by rewriting variable values and applying overrides such 716 variants by rewriting variable values and applying overrides such
586 as ``_class-native``. For example, to generate a native version of 717 as ``:class-native``. For example, to generate a native version of
587 a recipe, a :term:`DEPENDS` on "foo" is rewritten 718 a recipe, a :term:`DEPENDS` on "foo" is rewritten
588 to a ``DEPENDS`` on "foo-native". 719 to a :term:`DEPENDS` on "foo-native".
589 720
590 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. 721 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
591 Parsing once adds some limitations. For example, it is not 722 Parsing once adds some limitations. For example, it is not
592 possible to include a different file depending on the variant, 723 possible to include a different file depending on the variant,
593 since ``include`` statements are processed when the recipe is 724 since ``include`` statements are processed when the recipe is
594 parsed. 725 parsed.
595 726
727 :term:`BBDEBUG`
728 See :term:`bitbake:BBDEBUG` in the BitBake manual.
729
596 :term:`BBFILE_COLLECTIONS` 730 :term:`BBFILE_COLLECTIONS`
597 Lists the names of configured layers. These names are used to find 731 Lists the names of configured layers. These names are used to find
598 the other ``BBFILE_*`` variables. Typically, each layer will append 732 the other ``BBFILE_*`` variables. Typically, each layer will append
@@ -610,17 +744,17 @@ system and gives an overview of their function and contents.
610 This variable is useful in situations where the same recipe appears 744 This variable is useful in situations where the same recipe appears
611 in more than one layer. Setting this variable allows you to 745 in more than one layer. Setting this variable allows you to
612 prioritize a layer against other layers that contain the same recipe 746 prioritize a layer against other layers that contain the same recipe
613 - effectively letting you control the precedence for the multiple 747 --- effectively letting you control the precedence for the multiple
614 layers. The precedence established through this variable stands 748 layers. The precedence established through this variable stands
615 regardless of a recipe's version (:term:`PV` variable). For 749 regardless of a recipe's version (:term:`PV` variable). For
616 example, a layer that has a recipe with a higher ``PV`` value but for 750 example, a layer that has a recipe with a higher :term:`PV` value but for
617 which the ``BBFILE_PRIORITY`` is set to have a lower precedence still 751 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still
618 has a lower precedence. 752 has a lower precedence.
619 753
620 A larger value for the ``BBFILE_PRIORITY`` variable results in a 754 A larger value for the :term:`BBFILE_PRIORITY` variable results in a
621 higher precedence. For example, the value 6 has a higher precedence 755 higher precedence. For example, the value 6 has a higher precedence
622 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable 756 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
623 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable 757 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
624 for more information. The default priority, if unspecified for a 758 for more information. The default priority, if unspecified for a
625 layer with no dependencies, is the lowest defined priority + 1 (or 1 759 layer with no dependencies, is the lowest defined priority + 1 (or 1
626 if no priorities are defined). 760 if no priorities are defined).
@@ -635,7 +769,7 @@ system and gives an overview of their function and contents.
635 software. 769 software.
636 770
637 When specifying recipe files, you can pattern match using Python's 771 When specifying recipe files, you can pattern match using Python's
638 `glob <https://docs.python.org/3/library/glob.html>`_ syntax. 772 `glob <https://docs.python.org/3/library/glob.html>`__ syntax.
639 For details on the syntax, see the documentation by following the 773 For details on the syntax, see the documentation by following the
640 previous link. 774 previous link.
641 775
@@ -643,15 +777,16 @@ system and gives an overview of their function and contents.
643 Activates content when identified layers are present. You identify 777 Activates content when identified layers are present. You identify
644 the layers by the collections that the layers define. 778 the layers by the collections that the layers define.
645 779
646 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files 780 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files
647 whose corresponding ``.bb`` file is in a layer that attempts to 781 whose corresponding ``.bb`` file is in a layer that attempts to
648 modify other layers through ``.bbappend`` but does not want to 782 modify other layers through ``.bbappend`` but does not want to
649 introduce a hard dependency on those other layers. 783 introduce a hard dependency on those other layers.
650 784
651 Use the following form for ``BBFILES_DYNAMIC``: 785 Use the following form for :term:`BBFILES_DYNAMIC`:
652 collection_name:filename_pattern The following example identifies two 786 ``collection_name:filename_pattern``.
653 collection names and two filename patterns: 787
654 :: 788 The following example identifies two collection names and two
789 filename patterns::
655 790
656 BBFILES_DYNAMIC += " \ 791 BBFILES_DYNAMIC += " \
657 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ 792 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
@@ -659,7 +794,7 @@ system and gives an overview of their function and contents.
659 " 794 "
660 795
661 This next example shows an error message that occurs because invalid 796 This next example shows an error message that occurs because invalid
662 entries are found, which cause parsing to abort: 797 entries are found, which cause parsing to fail:
663 798
664 .. code-block:: none 799 .. code-block:: none
665 800
@@ -667,20 +802,22 @@ system and gives an overview of their function and contents.
667 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 802 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
668 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 803 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
669 804
805 :term:`BBINCLUDED`
806 See :term:`bitbake:BBINCLUDED` in the BitBake manual.
807
670 :term:`BBINCLUDELOGS` 808 :term:`BBINCLUDELOGS`
671 Variable that controls how BitBake displays logs on build failure. 809 Variable that controls how BitBake displays logs on build failure.
672 810
673 :term:`BBINCLUDELOGS_LINES` 811 :term:`BBINCLUDELOGS_LINES`
674 If :term:`BBINCLUDELOGS` is set, specifies the 812 If :term:`BBINCLUDELOGS` is set, specifies the
675 maximum number of lines from the task log file to print when 813 maximum number of lines from the task log file to print when
676 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, 814 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
677 the entire log is printed. 815 the entire log is printed.
678 816
679 :term:`BBLAYERS` 817 :term:`BBLAYERS`
680 Lists the layers to enable during the build. This variable is defined 818 Lists the layers to enable during the build. This variable is defined
681 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. 819 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
682 Here is an example: 820 Here is an example::
683 ::
684 821
685 BBLAYERS = " \ 822 BBLAYERS = " \
686 /home/scottrif/poky/meta \ 823 /home/scottrif/poky/meta \
@@ -692,10 +829,13 @@ system and gives an overview of their function and contents.
692 This example enables four layers, one of which is a custom, 829 This example enables four layers, one of which is a custom,
693 user-defined layer named ``meta-mykernel``. 830 user-defined layer named ``meta-mykernel``.
694 831
832 :term:`BBLAYERS_FETCH_DIR`
833 See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual.
834
695 :term:`BBMASK` 835 :term:`BBMASK`
696 Prevents BitBake from processing recipes and recipe append files. 836 Prevents BitBake from processing recipes and recipe append files.
697 837
698 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and 838 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
699 ``.bbappend`` files. BitBake ignores any recipe or recipe append 839 ``.bbappend`` files. BitBake ignores any recipe or recipe append
700 files that match any of the expressions. It is as if BitBake does not 840 files that match any of the expressions. It is as if BitBake does not
701 see them at all. Consequently, matching files are not parsed or 841 see them at all. Consequently, matching files are not parsed or
@@ -709,14 +849,13 @@ system and gives an overview of their function and contents.
709 849
710 The following example uses a complete regular expression to tell 850 The following example uses a complete regular expression to tell
711 BitBake to ignore all recipe and recipe append files in the 851 BitBake to ignore all recipe and recipe append files in the
712 ``meta-ti/recipes-misc/`` directory: 852 ``meta-ti/recipes-misc/`` directory::
713 ::
714 853
715 BBMASK = "meta-ti/recipes-misc/" 854 BBMASK = "meta-ti/recipes-misc/"
716 855
717 If you want to mask out multiple directories or recipes, you can 856 If you want to mask out multiple directories or recipes, you can
718 specify multiple regular expression fragments. This next example 857 specify multiple regular expression fragments. This next example
719 masks out multiple directories and individual recipes: :: 858 masks out multiple directories and individual recipes::
720 859
721 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" 860 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
722 BBMASK += "/meta-oe/recipes-support/" 861 BBMASK += "/meta-oe/recipes-support/"
@@ -734,72 +873,55 @@ system and gives an overview of their function and contents.
734 building targets with multiple configurations. Use this variable in 873 building targets with multiple configurations. Use this variable in
735 your ``conf/local.conf`` configuration file. Specify a 874 your ``conf/local.conf`` configuration file. Specify a
736 multiconfigname for each configuration file you are using. For 875 multiconfigname for each configuration file you are using. For
737 example, the following line specifies three configuration files: 876 example, the following line specifies three configuration files::
738 ::
739 877
740 BBMULTICONFIG = "configA configB configC" 878 BBMULTICONFIG = "configA configB configC"
741 879
742 Each configuration file you 880 Each configuration file you use must reside in a ``multiconfig``
743 use must reside in the :term:`Build Directory` 881 subdirectory of a configuration directory within a layer, or
744 ``conf/multiconfig`` directory (e.g. 882 within the :term:`Build Directory` (e.g.
745 build_directory\ ``/conf/multiconfig/configA.conf``). 883 ``build_directory/conf/multiconfig/configA.conf`` or
884 ``mylayer/conf/multiconfig/configB.conf``).
746 885
747 For information on how to use ``BBMULTICONFIG`` in an environment 886 For information on how to use :term:`BBMULTICONFIG` in an environment
748 that supports building targets with multiple configurations, see the 887 that supports building targets with multiple configurations, see the
749 ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" 888 ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`"
750 section in the Yocto Project Development Tasks Manual. 889 section in the Yocto Project Development Tasks Manual.
751 890
752 :term:`BBPATH` 891 :term:`BBPATH`
753 Used by BitBake to locate ``.bbclass`` and configuration files. This 892 See :term:`bitbake:BBPATH` in the BitBake manual.
754 variable is analogous to the ``PATH`` variable.
755
756 .. note::
757
758 If you run BitBake from a directory outside of the
759 Build Directory
760 , you must be sure to set
761 BBPATH
762 to point to the Build Directory. Set the variable as you would any
763 environment variable and then run BitBake:
764 ::
765
766 $ BBPATH = "build_directory"
767 $ export BBPATH
768 $ bitbake target
769
770 893
771 :term:`BBSERVER` 894 :term:`BBSERVER`
772 If defined in the BitBake environment, ``BBSERVER`` points to the 895 If defined in the BitBake environment, :term:`BBSERVER` points to the
773 BitBake remote server. 896 BitBake remote server.
774 897
775 Use the following format to export the variable to the BitBake 898 Use the following format to export the variable to the BitBake
776 environment: 899 environment::
777 ::
778 900
779 export BBSERVER=localhost:$port 901 export BBSERVER=localhost:$port
780 902
781 By default, ``BBSERVER`` also appears in 903 By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`.
782 :term:`bitbake:BB_HASHBASE_WHITELIST`. 904 Consequently, :term:`BBSERVER` is excluded from checksum and dependency
783 Consequently, ``BBSERVER`` is excluded from checksum and dependency
784 data. 905 data.
785 906
907 :term:`BBTARGETS`
908 See :term:`bitbake:BBTARGETS` in the BitBake manual.
909
786 :term:`BINCONFIG` 910 :term:`BINCONFIG`
787 When inheriting the 911 When inheriting the :ref:`ref-classes-binconfig-disabled` class, this
788 :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, 912 variable specifies binary configuration scripts to disable in favor of
789 this variable specifies binary configuration scripts to disable in 913 using ``pkg-config`` to query the information. The
790 favor of using ``pkg-config`` to query the information. The 914 :ref:`ref-classes-binconfig-disabled` class will modify the specified
791 ``binconfig-disabled`` class will modify the specified scripts to 915 scripts to return an error so that calls to them can be easily found
792 return an error so that calls to them can be easily found and 916 and replaced.
793 replaced.
794 917
795 To add multiple scripts, separate them by spaces. Here is an example 918 To add multiple scripts, separate them by spaces. Here is an example
796 from the ``libpng`` recipe: 919 from the ``libpng`` recipe::
797 ::
798 920
799 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" 921 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
800 922
801 :term:`BINCONFIG_GLOB` 923 :term:`BINCONFIG_GLOB`
802 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, 924 When inheriting the :ref:`ref-classes-binconfig` class,
803 this variable specifies a wildcard for configuration scripts that 925 this variable specifies a wildcard for configuration scripts that
804 need editing. The scripts are edited to correct any paths that have 926 need editing. The scripts are edited to correct any paths that have
805 been set up during compilation so that they are correct for use when 927 been set up during compilation so that they are correct for use when
@@ -808,7 +930,7 @@ system and gives an overview of their function and contents.
808 930
809 .. note:: 931 .. note::
810 932
811 The ``BINCONFIG_GLOB`` variable uses 933 The :term:`BINCONFIG_GLOB` variable uses
812 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, 934 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__,
813 which is recognition and expansion of wildcards during pattern 935 which is recognition and expansion of wildcards during pattern
814 matching. Shell globbing is very similar to 936 matching. Shell globbing is very similar to
@@ -816,16 +938,18 @@ system and gives an overview of their function and contents.
816 and `glob <https://docs.python.org/3/library/glob.html>`__. 938 and `glob <https://docs.python.org/3/library/glob.html>`__.
817 939
818 For more information on how this variable works, see 940 For more information on how this variable works, see
819 ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. 941 ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`.
820 You can also find general 942 You can also find general
821 information on the class in the 943 information on the class in the
822 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. 944 ":ref:`ref-classes-binconfig`" section.
945
946 :term:`BITBAKE_UI`
947 See :term:`bitbake:BITBAKE_UI` in the BitBake manual.
823 948
824 :term:`BP` 949 :term:`BP`
825 The base recipe name and version but without any special recipe name 950 The base recipe name and version but without any special recipe name
826 suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is 951 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is
827 comprised of the following: 952 comprised of the following::
828 ::
829 953
830 ${BPN}-${PV} 954 ${BPN}-${PV}
831 955
@@ -846,23 +970,23 @@ system and gives an overview of their function and contents.
846 970
847 :term:`BUILD_ARCH` 971 :term:`BUILD_ARCH`
848 Specifies the architecture of the build host (e.g. ``i686``). The 972 Specifies the architecture of the build host (e.g. ``i686``). The
849 OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the 973 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
850 machine name reported by the ``uname`` command. 974 machine name reported by the ``uname`` command.
851 975
852 :term:`BUILD_AS_ARCH` 976 :term:`BUILD_AS_ARCH`
853 Specifies the architecture-specific assembler flags for the build 977 Specifies the architecture-specific assembler flags for the build
854 host. By default, the value of ``BUILD_AS_ARCH`` is empty. 978 host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
855 979
856 :term:`BUILD_CC_ARCH` 980 :term:`BUILD_CC_ARCH`
857 Specifies the architecture-specific C compiler flags for the build 981 Specifies the architecture-specific C compiler flags for the build
858 host. By default, the value of ``BUILD_CC_ARCH`` is empty. 982 host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
859 983
860 :term:`BUILD_CCLD` 984 :term:`BUILD_CCLD`
861 Specifies the linker command to be used for the build host when the C 985 Specifies the linker command to be used for the build host when the C
862 compiler is being used as the linker. By default, ``BUILD_CCLD`` 986 compiler is being used as the linker. By default, :term:`BUILD_CCLD`
863 points to GCC and passes as arguments the value of 987 points to GCC and passes as arguments the value of
864 :term:`BUILD_CC_ARCH`, assuming 988 :term:`BUILD_CC_ARCH`, assuming
865 ``BUILD_CC_ARCH`` is set. 989 :term:`BUILD_CC_ARCH` is set.
866 990
867 :term:`BUILD_CFLAGS` 991 :term:`BUILD_CFLAGS`
868 Specifies the flags to pass to the C compiler when building for the 992 Specifies the flags to pass to the C compiler when building for the
@@ -884,19 +1008,19 @@ system and gives an overview of their function and contents.
884 1008
885 :term:`BUILD_FC` 1009 :term:`BUILD_FC`
886 Specifies the Fortran compiler command for the build host. By 1010 Specifies the Fortran compiler command for the build host. By
887 default, ``BUILD_FC`` points to Gfortran and passes as arguments the 1011 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
888 value of :term:`BUILD_CC_ARCH`, assuming 1012 value of :term:`BUILD_CC_ARCH`, assuming
889 ``BUILD_CC_ARCH`` is set. 1013 :term:`BUILD_CC_ARCH` is set.
890 1014
891 :term:`BUILD_LD` 1015 :term:`BUILD_LD`
892 Specifies the linker command for the build host. By default, 1016 Specifies the linker command for the build host. By default,
893 ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments 1017 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
894 the value of :term:`BUILD_LD_ARCH`, assuming 1018 the value of :term:`BUILD_LD_ARCH`, assuming
895 ``BUILD_LD_ARCH`` is set. 1019 :term:`BUILD_LD_ARCH` is set.
896 1020
897 :term:`BUILD_LD_ARCH` 1021 :term:`BUILD_LD_ARCH`
898 Specifies architecture-specific linker flags for the build host. By 1022 Specifies architecture-specific linker flags for the build host. By
899 default, the value of ``BUILD_LD_ARCH`` is empty. 1023 default, the value of :term:`BUILD_LD_ARCH` is empty.
900 1024
901 :term:`BUILD_LDFLAGS` 1025 :term:`BUILD_LDFLAGS`
902 Specifies the flags to pass to the linker when building for the build 1026 Specifies the flags to pass to the linker when building for the build
@@ -910,99 +1034,96 @@ system and gives an overview of their function and contents.
910 the :term:`BUILD_CFLAGS` and 1034 the :term:`BUILD_CFLAGS` and
911 :term:`BUILDSDK_CFLAGS` default values. 1035 :term:`BUILDSDK_CFLAGS` default values.
912 1036
913 The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 1037 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2
914 -pipe". 1038 -pipe".
915 1039
916 :term:`BUILD_OS` 1040 :term:`BUILD_OS`
917 Specifies the operating system in use on the build host (e.g. 1041 Specifies the operating system in use on the build host (e.g.
918 "linux"). The OpenEmbedded build system sets the value of 1042 "linux"). The OpenEmbedded build system sets the value of
919 ``BUILD_OS`` from the OS reported by the ``uname`` command - the 1043 :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the
920 first word, converted to lower-case characters. 1044 first word, converted to lower-case characters.
921 1045
922 :term:`BUILD_PREFIX` 1046 :term:`BUILD_PREFIX`
923 The toolchain binary prefix used for native recipes. The OpenEmbedded 1047 The toolchain binary prefix used for native recipes. The OpenEmbedded
924 build system uses the ``BUILD_PREFIX`` value to set the 1048 build system uses the :term:`BUILD_PREFIX` value to set the
925 :term:`TARGET_PREFIX` when building for 1049 :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes.
926 ``native`` recipes.
927 1050
928 :term:`BUILD_STRIP` 1051 :term:`BUILD_STRIP`
929 Specifies the command to be used to strip debugging symbols from 1052 Specifies the command to be used to strip debugging symbols from
930 binaries produced for the build host. By default, ``BUILD_STRIP`` 1053 binaries produced for the build host. By default, :term:`BUILD_STRIP`
931 points to 1054 points to
932 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. 1055 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
933 1056
934 :term:`BUILD_SYS` 1057 :term:`BUILD_SYS`
935 Specifies the system, including the architecture and the operating 1058 Specifies the system, including the architecture and the operating
936 system, to use when building for the build host (i.e. when building 1059 system, to use when building for the build host (i.e. when building
937 ``native`` recipes). 1060 :ref:`ref-classes-native` recipes).
938 1061
939 The OpenEmbedded build system automatically sets this variable based 1062 The OpenEmbedded build system automatically sets this variable based
940 on :term:`BUILD_ARCH`, 1063 on :term:`BUILD_ARCH`,
941 :term:`BUILD_VENDOR`, and 1064 :term:`BUILD_VENDOR`, and
942 :term:`BUILD_OS`. You do not need to set the 1065 :term:`BUILD_OS`. You do not need to set the
943 ``BUILD_SYS`` variable yourself. 1066 :term:`BUILD_SYS` variable yourself.
944 1067
945 :term:`BUILD_VENDOR` 1068 :term:`BUILD_VENDOR`
946 Specifies the vendor name to use when building for the build host. 1069 Specifies the vendor name to use when building for the build host.
947 The default value is an empty string (""). 1070 The default value is an empty string ("").
948 1071
949 :term:`BUILDDIR` 1072 :term:`BUILDDIR`
950 Points to the location of the :term:`Build Directory`. 1073 Points to the location of the :term:`Build Directory`. You can define
951 You can define this directory indirectly through the 1074 this directory indirectly through the :ref:`structure-core-script` script
952 :ref:`structure-core-script` script by passing in a Build 1075 by passing in a :term:`Build Directory` path when you run the script. If
953 Directory path when you run the script. If you run the script and do 1076 you run the script and do not provide a :term:`Build Directory` path, the
954 not provide a Build Directory path, the ``BUILDDIR`` defaults to 1077 :term:`BUILDDIR` defaults to ``build`` in the current directory.
955 ``build`` in the current directory.
956 1078
957 :term:`BUILDHISTORY_COMMIT` 1079 :term:`BUILDHISTORY_COMMIT`
958 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1080 When inheriting the :ref:`ref-classes-buildhistory` class, this variable
959 class, this variable specifies whether or not to commit the build 1081 specifies whether or not to commit the build history output in a local
960 history output in a local Git repository. If set to "1", this local 1082 Git repository. If set to "1", this local repository will be maintained
961 repository will be maintained automatically by the ``buildhistory`` 1083 automatically by the :ref:`ref-classes-buildhistory` class and a commit
962 class and a commit will be created on every build for changes to each 1084 will be created on every build for changes to each top-level subdirectory
963 top-level subdirectory of the build history output (images, packages, 1085 of the build history output (images, packages, and sdk). If you want to
964 and sdk). If you want to track changes to build history over time, 1086 track changes to build history over time, you should set this value to
965 you should set this value to "1". 1087 "1".
966 1088
967 By default, the ``buildhistory`` class does not commit the build 1089 By default, the :ref:`ref-classes-buildhistory` class
968 history output in a local Git repository: 1090 enables committing the buildhistory output in a local Git repository::
969 ::
970 1091
971 BUILDHISTORY_COMMIT ?= "0" 1092 BUILDHISTORY_COMMIT ?= "1"
972 1093
973 :term:`BUILDHISTORY_COMMIT_AUTHOR` 1094 :term:`BUILDHISTORY_COMMIT_AUTHOR`
974 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1095 When inheriting the :ref:`ref-classes-buildhistory`
975 class, this variable specifies the author to use for each Git commit. 1096 class, this variable specifies the author to use for each Git commit.
976 In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the 1097 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the
977 :term:`BUILDHISTORY_COMMIT` variable must 1098 :term:`BUILDHISTORY_COMMIT` variable must
978 be set to "1". 1099 be set to "1".
979 1100
980 Git requires that the value you provide for the 1101 Git requires that the value you provide for the
981 ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name 1102 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name
982 email@host". Providing an email address or host that is not valid 1103 email@host". Providing an email address or host that is not valid
983 does not produce an error. 1104 does not produce an error.
984 1105
985 By default, the ``buildhistory`` class sets the variable as follows: 1106 By default, the :ref:`ref-classes-buildhistory` class sets the variable
986 :: 1107 as follows::
987 1108
988 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 1109 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
989 1110
990 :term:`BUILDHISTORY_DIR` 1111 :term:`BUILDHISTORY_DIR`
991 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1112 When inheriting the :ref:`ref-classes-buildhistory`
992 class, this variable specifies the directory in which build history 1113 class, this variable specifies the directory in which build history
993 information is kept. For more information on how the variable works, 1114 information is kept. For more information on how the variable works,
994 see the ``buildhistory.class``. 1115 see the :ref:`ref-classes-buildhistory` class.
995 1116
996 By default, the ``buildhistory`` class sets the directory as follows: 1117 By default, the :ref:`ref-classes-buildhistory` class sets the directory
997 :: 1118 as follows::
998 1119
999 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 1120 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1000 1121
1001 :term:`BUILDHISTORY_FEATURES` 1122 :term:`BUILDHISTORY_FEATURES`
1002 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1123 When inheriting the :ref:`ref-classes-buildhistory`
1003 class, this variable specifies the build history features to be 1124 class, this variable specifies the build history features to be
1004 enabled. For more information on how build history works, see the 1125 enabled. For more information on how build history works, see the
1005 ":ref:`dev-manual/common-tasks:maintaining build output quality`" 1126 ":ref:`dev-manual/build-quality:maintaining build output quality`"
1006 section in the Yocto Project Development Tasks Manual. 1127 section in the Yocto Project Development Tasks Manual.
1007 1128
1008 You can specify these features in the form of a space-separated list: 1129 You can specify these features in the form of a space-separated list:
@@ -1021,14 +1142,13 @@ system and gives an overview of their function and contents.
1021 This saves one file per task and lists the SHA-256 checksums for 1142 This saves one file per task and lists the SHA-256 checksums for
1022 each file staged (i.e. the output of the task). 1143 each file staged (i.e. the output of the task).
1023 1144
1024 By default, the ``buildhistory`` class enables the following 1145 By default, the :ref:`ref-classes-buildhistory` class enables the
1025 features: 1146 following features::
1026 ::
1027 1147
1028 BUILDHISTORY_FEATURES ?= "image package sdk" 1148 BUILDHISTORY_FEATURES ?= "image package sdk"
1029 1149
1030 :term:`BUILDHISTORY_IMAGE_FILES` 1150 :term:`BUILDHISTORY_IMAGE_FILES`
1031 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1151 When inheriting the :ref:`ref-classes-buildhistory`
1032 class, this variable specifies a list of paths to files copied from 1152 class, this variable specifies a list of paths to files copied from
1033 the image contents into the build history directory under an 1153 the image contents into the build history directory under an
1034 "image-files" directory in the directory for the image, so that you 1154 "image-files" directory in the directory for the image, so that you
@@ -1038,30 +1158,45 @@ system and gives an overview of their function and contents.
1038 any file. Specifying an invalid path does not produce an error. 1158 any file. Specifying an invalid path does not produce an error.
1039 Consequently, you can include files that might not always be present. 1159 Consequently, you can include files that might not always be present.
1040 1160
1041 By default, the ``buildhistory`` class provides paths to the 1161 By default, the :ref:`ref-classes-buildhistory` class provides paths to
1042 following files: 1162 the following files::
1043 ::
1044 1163
1045 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1164 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1046 1165
1166 :term:`BUILDHISTORY_PATH_PREFIX_STRIP`
1167 When inheriting the :ref:`ref-classes-buildhistory`
1168 class, this variable specifies a common path prefix that should be
1169 stripped off the beginning of paths in the task signature list when the
1170 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be
1171 useful when build history is populated from multiple sources that may not
1172 all use the same top level directory.
1173
1174 By default, the :ref:`ref-classes-buildhistory` class sets the variable
1175 as follows::
1176
1177 BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
1178
1179 In this case, no prefixes will be stripped.
1180
1047 :term:`BUILDHISTORY_PUSH_REPO` 1181 :term:`BUILDHISTORY_PUSH_REPO`
1048 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1182 When inheriting the :ref:`ref-classes-buildhistory` class, this variable
1049 class, this variable optionally specifies a remote repository to 1183 optionally specifies a remote repository to which build history pushes
1050 which build history pushes Git changes. In order for 1184 Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work,
1051 ``BUILDHISTORY_PUSH_REPO`` to work, 1185 :term:`BUILDHISTORY_COMMIT` must be set to "1".
1052 :term:`BUILDHISTORY_COMMIT` must be set to
1053 "1".
1054 1186
1055 The repository should correspond to a remote address that specifies a 1187 The repository should correspond to a remote address that specifies a
1056 repository as understood by Git, or alternatively to a remote name 1188 repository as understood by Git, or alternatively to a remote name
1057 that you have set up manually using ``git remote`` within the local 1189 that you have set up manually using ``git remote`` within the local
1058 repository. 1190 repository.
1059 1191
1060 By default, the ``buildhistory`` class sets the variable as follows: 1192 By default, the :ref:`ref-classes-buildhistory` class sets the variable
1061 :: 1193 as follows::
1062 1194
1063 BUILDHISTORY_PUSH_REPO ?= "" 1195 BUILDHISTORY_PUSH_REPO ?= ""
1064 1196
1197 :term:`BUILDNAME`
1198 See :term:`bitbake:BUILDNAME` in the BitBake manual.
1199
1065 :term:`BUILDSDK_CFLAGS` 1200 :term:`BUILDSDK_CFLAGS`
1066 Specifies the flags to pass to the C compiler when building for the 1201 Specifies the flags to pass to the C compiler when building for the
1067 SDK. When building in the ``nativesdk-`` context, 1202 SDK. When building in the ``nativesdk-`` context,
@@ -1088,9 +1223,8 @@ system and gives an overview of their function and contents.
1088 1223
1089 :term:`BUILDSTATS_BASE` 1224 :term:`BUILDSTATS_BASE`
1090 Points to the location of the directory that holds build statistics 1225 Points to the location of the directory that holds build statistics
1091 when you use and enable the 1226 when you use and enable the :ref:`ref-classes-buildstats` class. The
1092 :ref:`buildstats <ref-classes-buildstats>` class. The 1227 :term:`BUILDSTATS_BASE` directory defaults to
1093 ``BUILDSTATS_BASE`` directory defaults to
1094 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. 1228 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
1095 1229
1096 :term:`BUSYBOX_SPLIT_SUID` 1230 :term:`BUSYBOX_SPLIT_SUID`
@@ -1099,10 +1233,13 @@ system and gives an overview of their function and contents.
1099 ``setuid root``, and one for the remaining features (i.e. those that 1233 ``setuid root``, and one for the remaining features (i.e. those that
1100 do not require ``setuid root``). 1234 do not require ``setuid root``).
1101 1235
1102 The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in 1236 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in
1103 splitting the output executable file. Set the variable to "0" to get 1237 splitting the output executable file. Set the variable to "0" to get
1104 a single output executable file. 1238 a single output executable file.
1105 1239
1240 :term:`BZRDIR`
1241 See :term:`bitbake:BZRDIR` in the BitBake manual.
1242
1106 :term:`CACHE` 1243 :term:`CACHE`
1107 Specifies the directory BitBake uses to store a cache of the 1244 Specifies the directory BitBake uses to store a cache of the
1108 :term:`Metadata` so it does not need to be parsed every time 1245 :term:`Metadata` so it does not need to be parsed every time
@@ -1116,7 +1253,7 @@ system and gives an overview of their function and contents.
1116 exported to an environment variable and thus made visible to the 1253 exported to an environment variable and thus made visible to the
1117 software being built during the compilation step. 1254 software being built during the compilation step.
1118 1255
1119 Default initialization for ``CFLAGS`` varies depending on what is 1256 Default initialization for :term:`CFLAGS` varies depending on what is
1120 being built: 1257 being built:
1121 1258
1122 - :term:`TARGET_CFLAGS` when building for the 1259 - :term:`TARGET_CFLAGS` when building for the
@@ -1132,37 +1269,34 @@ system and gives an overview of their function and contents.
1132 An internal variable specifying the special class override that 1269 An internal variable specifying the special class override that
1133 should currently apply (e.g. "class-target", "class-native", and so 1270 should currently apply (e.g. "class-target", "class-native", and so
1134 forth). The classes that use this variable (e.g. 1271 forth). The classes that use this variable (e.g.
1135 :ref:`native <ref-classes-native>`, 1272 :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth)
1136 :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the 1273 set the variable to appropriate values.
1137 variable to appropriate values.
1138 1274
1139 .. note:: 1275 .. note::
1140 1276
1141 ``CLASSOVERRIDE`` gets its default "class-target" value from the 1277 :term:`CLASSOVERRIDE` gets its default "class-target" value from the
1142 ``bitbake.conf`` file. 1278 ``bitbake.conf`` file.
1143 1279
1144 As an example, the following override allows you to install extra 1280 As an example, the following override allows you to install extra
1145 files, but only when building for the target: 1281 files, but only when building for the target::
1146 ::
1147 1282
1148 do_install_append_class-target() { 1283 do_install:append:class-target() {
1149 install my-extra-file ${D}${sysconfdir} 1284 install my-extra-file ${D}${sysconfdir}
1150 } 1285 }
1151 1286
1152 Here is an example where ``FOO`` is set to 1287 Here is an example where ``FOO`` is set to
1153 "native" when building for the build host, and to "other" when not 1288 "native" when building for the build host, and to "other" when not
1154 building for the build host: 1289 building for the build host::
1155 ::
1156 1290
1157 FOO_class-native = "native" 1291 FOO:class-native = "native"
1158 FOO = "other" 1292 FOO = "other"
1159 1293
1160 The underlying mechanism behind ``CLASSOVERRIDE`` is simply 1294 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply
1161 that it is included in the default value of 1295 that it is included in the default value of
1162 :term:`OVERRIDES`. 1296 :term:`OVERRIDES`.
1163 1297
1164 :term:`CLEANBROKEN` 1298 :term:`CLEANBROKEN`
1165 If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the 1299 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the
1166 ``make clean`` command does not work for the software being built. 1300 ``make clean`` command does not work for the software being built.
1167 Consequently, the OpenEmbedded build system will not try to run 1301 Consequently, the OpenEmbedded build system will not try to run
1168 ``make clean`` during the :ref:`ref-tasks-configure` 1302 ``make clean`` during the :ref:`ref-tasks-configure`
@@ -1178,6 +1312,26 @@ system and gives an overview of their function and contents.
1178 optional at the distribution level, in case the hardware supports 1312 optional at the distribution level, in case the hardware supports
1179 Bluetooth but you do not ever intend to use it. 1313 Bluetooth but you do not ever intend to use it.
1180 1314
1315 :term:`COMMERCIAL_AUDIO_PLUGINS`
1316 This variable is specific to the :yocto_git:`GStreamer recipes
1317 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1318 It allows to build the GStreamer `"ugly"
1319 <https://github.com/GStreamer/gst-plugins-ugly>`__ and
1320 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins.
1321
1322 See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1323 section for usage details.
1324
1325 :term:`COMMERCIAL_VIDEO_PLUGINS`
1326 This variable is specific to the :yocto_git:`GStreamer recipes
1327 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1328 It allows to build the GStreamer `"ugly"
1329 <https://github.com/GStreamer/gst-plugins-ugly>`__ and
1330 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins.
1331
1332 See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1333 section for usage details.
1334
1181 :term:`COMMON_LICENSE_DIR` 1335 :term:`COMMON_LICENSE_DIR`
1182 Points to ``meta/files/common-licenses`` in the 1336 Points to ``meta/files/common-licenses`` in the
1183 :term:`Source Directory`, which is where generic license 1337 :term:`Source Directory`, which is where generic license
@@ -1204,35 +1358,63 @@ system and gives an overview of their function and contents.
1204 speed since the build system skips parsing recipes not compatible 1358 speed since the build system skips parsing recipes not compatible
1205 with the current machine. 1359 with the current machine.
1206 1360
1361 If one wants to have a recipe only available for some architectures
1362 (here ``aarch64`` and ``mips64``), the following can be used::
1363
1364 COMPATIBLE_MACHINE = "^$"
1365 COMPATIBLE_MACHINE:arch64 = "^(aarch64)$"
1366 COMPATIBLE_MACHINE:mips64 = "^(mips64)$"
1367
1368 The first line means "match all machines whose :term:`MACHINEOVERRIDES`
1369 contains the empty string", which will always be none.
1370
1371 The second is for matching all machines whose :term:`MACHINEOVERRIDES`
1372 contains one override which is exactly ``aarch64``.
1373
1374 The third is for matching all machines whose :term:`MACHINEOVERRIDES`
1375 contains one override which is exactly ``mips64``.
1376
1377 The same could be achieved with::
1378
1379 COMPATIBLE_MACHINE = "^(aarch64|mips64)$"
1380
1381 .. note::
1382
1383 When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from
1384 native, the recipe is always skipped. All native recipes must be
1385 entirely target independent and should not rely on :term:`MACHINE`.
1386
1207 :term:`COMPLEMENTARY_GLOB` 1387 :term:`COMPLEMENTARY_GLOB`
1208 Defines wildcards to match when installing a list of complementary 1388 Defines wildcards to match when installing a list of complementary
1209 packages for all the packages explicitly (or implicitly) installed in 1389 packages for all the packages explicitly (or implicitly) installed in
1210 an image. 1390 an image.
1211 1391
1212 .. note:: 1392 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching
1213 1393 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__),
1214 The ``COMPLEMENTARY_GLOB`` variable uses Unix filename pattern matching 1394 which is similar to the Unix style pathname pattern expansion
1215 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), 1395 (`glob <https://docs.python.org/3/library/glob.html>`__).
1216 which is similar to the Unix style pathname pattern expansion
1217 (`glob <https://docs.python.org/3/library/glob.html>`__).
1218 1396
1219 The resulting list of complementary packages is associated with an 1397 The resulting list of complementary packages is associated with an
1220 item that can be added to 1398 item that can be added to
1221 :term:`IMAGE_FEATURES`. An example usage of 1399 :term:`IMAGE_FEATURES`. An example usage of
1222 this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` 1400 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES`
1223 will install -dev packages (containing headers and other development 1401 will install -dev packages (containing headers and other development
1224 files) for every package in the image. 1402 files) for every package in the image.
1225 1403
1226 To add a new feature item pointing to a wildcard, use a variable flag 1404 To add a new feature item pointing to a wildcard, use a variable flag
1227 to specify the feature item name and use the value to specify the 1405 to specify the feature item name and use the value to specify the
1228 wildcard. Here is an example: 1406 wildcard. Here is an example::
1229 ::
1230 1407
1231 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' 1408 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1232 1409
1410 .. note::
1411
1412 When installing complementary packages, recommends relationships
1413 (set via :term:`RRECOMMENDS`) are always ignored.
1414
1233 :term:`COMPONENTS_DIR` 1415 :term:`COMPONENTS_DIR`
1234 Stores sysroot components for each recipe. The OpenEmbedded build 1416 Stores sysroot components for each recipe. The OpenEmbedded build
1235 system uses ``COMPONENTS_DIR`` when constructing recipe-specific 1417 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
1236 sysroots for other recipes. 1418 sysroots for other recipes.
1237 1419
1238 The default is 1420 The default is
@@ -1242,7 +1424,7 @@ system and gives an overview of their function and contents.
1242 1424
1243 :term:`CONF_VERSION` 1425 :term:`CONF_VERSION`
1244 Tracks the version of the local configuration file (i.e. 1426 Tracks the version of the local configuration file (i.e.
1245 ``local.conf``). The value for ``CONF_VERSION`` increments each time 1427 ``local.conf``). The value for :term:`CONF_VERSION` increments each time
1246 ``build/conf/`` compatibility changes. 1428 ``build/conf/`` compatibility changes.
1247 1429
1248 :term:`CONFFILES` 1430 :term:`CONFFILES`
@@ -1252,29 +1434,28 @@ system and gives an overview of their function and contents.
1252 files you have changed after the original installation and that you 1434 files you have changed after the original installation and that you
1253 now want to remain unchanged are overwritten. In other words, 1435 now want to remain unchanged are overwritten. In other words,
1254 editable files might exist in the package that you do not want reset 1436 editable files might exist in the package that you do not want reset
1255 as part of the package update process. You can use the ``CONFFILES`` 1437 as part of the package update process. You can use the :term:`CONFFILES`
1256 variable to list the files in the package that you wish to prevent 1438 variable to list the files in the package that you wish to prevent
1257 the PMS from overwriting during this update process. 1439 the PMS from overwriting during this update process.
1258 1440
1259 To use the ``CONFFILES`` variable, provide a package name override 1441 To use the :term:`CONFFILES` variable, provide a package name override
1260 that identifies the resulting package. Then, provide a 1442 that identifies the resulting package. Then, provide a
1261 space-separated list of files. Here is an example: 1443 space-separated list of files. Here is an example::
1262 ::
1263 1444
1264 CONFFILES_${PN} += "${sysconfdir}/file1 \ 1445 CONFFILES:${PN} += "${sysconfdir}/file1 \
1265 ${sysconfdir}/file2 ${sysconfdir}/file3" 1446 ${sysconfdir}/file2 ${sysconfdir}/file3"
1266 1447
1267 A relationship exists between the ``CONFFILES`` and ``FILES`` 1448 There is a relationship between the :term:`CONFFILES` and :term:`FILES`
1268 variables. The files listed within ``CONFFILES`` must be a subset of 1449 variables. The files listed within :term:`CONFFILES` must be a subset of
1269 the files listed within ``FILES``. Because the configuration files 1450 the files listed within :term:`FILES`. Because the configuration files
1270 you provide with ``CONFFILES`` are simply being identified so that 1451 you provide with :term:`CONFFILES` are simply being identified so that
1271 the PMS will not overwrite them, it makes sense that the files must 1452 the PMS will not overwrite them, it makes sense that the files must
1272 already be included as part of the package through the ``FILES`` 1453 already be included as part of the package through the :term:`FILES`
1273 variable. 1454 variable.
1274 1455
1275 .. note:: 1456 .. note::
1276 1457
1277 When specifying paths as part of the ``CONFFILES`` variable, it is 1458 When specifying paths as part of the :term:`CONFFILES` variable, it is
1278 good practice to use appropriate path variables. 1459 good practice to use appropriate path variables.
1279 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` 1460 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}``
1280 rather than ``/usr/bin``. You can find a list of these variables at 1461 rather than ``/usr/bin``. You can find a list of these variables at
@@ -1282,24 +1463,24 @@ system and gives an overview of their function and contents.
1282 :term:`Source Directory`. 1463 :term:`Source Directory`.
1283 1464
1284 :term:`CONFIG_INITRAMFS_SOURCE` 1465 :term:`CONFIG_INITRAMFS_SOURCE`
1285 Identifies the initial RAM filesystem (initramfs) source files. The 1466 Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The
1286 OpenEmbedded build system receives and uses this kernel Kconfig 1467 OpenEmbedded build system receives and uses this kernel Kconfig
1287 variable as an environment variable. By default, the variable is set 1468 variable as an environment variable. By default, the variable is set
1288 to null (""). 1469 to null ("").
1289 1470
1290 The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive 1471 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
1291 with a ``.cpio`` suffix or a space-separated list of directories and 1472 with a ``.cpio`` suffix or a space-separated list of directories and
1292 files for building the initramfs image. A cpio archive should contain 1473 files for building the :term:`Initramfs` image. A cpio archive should contain
1293 a filesystem archive to be used as an initramfs image. Directories 1474 a filesystem archive to be used as an :term:`Initramfs` image. Directories
1294 should contain a filesystem layout to be included in the initramfs 1475 should contain a filesystem layout to be included in the :term:`Initramfs`
1295 image. Files should contain entries according to the format described 1476 image. Files should contain entries according to the format described
1296 by the ``usr/gen_init_cpio`` program in the kernel tree. 1477 by the ``usr/gen_init_cpio`` program in the kernel tree.
1297 1478
1298 If you specify multiple directories and files, the initramfs image 1479 If you specify multiple directories and files, the :term:`Initramfs` image
1299 will be the aggregate of all of them. 1480 will be the aggregate of all of them.
1300 1481
1301 For information on creating an initramfs, see the 1482 For information on creating an :term:`Initramfs`, see the
1302 ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section 1483 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
1303 in the Yocto Project Development Tasks Manual. 1484 in the Yocto Project Development Tasks Manual.
1304 1485
1305 :term:`CONFIG_SITE` 1486 :term:`CONFIG_SITE`
@@ -1311,82 +1492,26 @@ system and gives an overview of their function and contents.
1311 The minimal arguments for GNU configure. 1492 The minimal arguments for GNU configure.
1312 1493
1313 :term:`CONFLICT_DISTRO_FEATURES` 1494 :term:`CONFLICT_DISTRO_FEATURES`
1314 When inheriting the 1495 When inheriting the :ref:`ref-classes-features_check`
1315 :ref:`features_check <ref-classes-features_check>`
1316 class, this variable identifies distribution features that would be 1496 class, this variable identifies distribution features that would be
1317 in conflict should the recipe be built. In other words, if the 1497 in conflict should the recipe be built. In other words, if the
1318 ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also 1498 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also
1319 appears in ``DISTRO_FEATURES`` within the current configuration, then 1499 appears in :term:`DISTRO_FEATURES` within the current configuration, then
1320 the recipe will be skipped, and if the build system attempts to build 1500 the recipe will be skipped, and if the build system attempts to build
1321 the recipe then an error will be triggered. 1501 the recipe then an error will be triggered.
1322 1502
1323 :term:`COPYLEFT_LICENSE_EXCLUDE` 1503 :term:`CONVERSION_CMD`
1324 A space-separated list of licenses to exclude from the source 1504 This variable is used for storing image conversion commands.
1325 archived by the :ref:`archiver <ref-classes-archiver>` class. In 1505 Image conversion can convert an image into different objects like:
1326 other words, if a license in a recipe's
1327 :term:`LICENSE` value is in the value of
1328 ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the
1329 class.
1330
1331 .. note::
1332
1333 The ``COPYLEFT_LICENSE_EXCLUDE`` variable takes precedence over the
1334 :term:`COPYLEFT_LICENSE_INCLUDE` variable.
1335
1336 The default value, which is "CLOSED Proprietary", for
1337 ``COPYLEFT_LICENSE_EXCLUDE`` is set by the
1338 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1339 is inherited by the ``archiver`` class.
1340
1341 :term:`COPYLEFT_LICENSE_INCLUDE`
1342 A space-separated list of licenses to include in the source archived
1343 by the :ref:`archiver <ref-classes-archiver>` class. In other
1344 words, if a license in a recipe's :term:`LICENSE`
1345 value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its
1346 source is archived by the class.
1347
1348 The default value is set by the
1349 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1350 is inherited by the ``archiver`` class. The default value includes
1351 "GPL*", "LGPL*", and "AGPL*".
1352 1506
1353 :term:`COPYLEFT_PN_EXCLUDE` 1507 - Compressed version of the image
1354 A list of recipes to exclude in the source archived by the
1355 :ref:`archiver <ref-classes-archiver>` class. The
1356 ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and
1357 exclusion caused through the
1358 :term:`COPYLEFT_LICENSE_INCLUDE` and
1359 :term:`COPYLEFT_LICENSE_EXCLUDE`
1360 variables, respectively.
1361 1508
1362 The default value, which is "" indicating to not explicitly exclude 1509 - Checksums for the image
1363 any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the
1364 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1365 is inherited by the ``archiver`` class.
1366 1510
1367 :term:`COPYLEFT_PN_INCLUDE` 1511 An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types`
1368 A list of recipes to include in the source archived by the 1512 class is::
1369 :ref:`archiver <ref-classes-archiver>` class. The
1370 ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and
1371 exclusion caused through the
1372 :term:`COPYLEFT_LICENSE_INCLUDE` and
1373 :term:`COPYLEFT_LICENSE_EXCLUDE`
1374 variables, respectively.
1375
1376 The default value, which is "" indicating to not explicitly include
1377 any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the
1378 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1379 is inherited by the ``archiver`` class.
1380
1381 :term:`COPYLEFT_RECIPE_TYPES`
1382 A space-separated list of recipe types to include in the source
1383 archived by the :ref:`archiver <ref-classes-archiver>` class.
1384 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``,
1385 ``crosssdk``, and ``cross-canadian``.
1386 1513
1387 The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` 1514 CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}"
1388 is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>`
1389 class, which is inherited by the ``archiver`` class.
1390 1515
1391 :term:`COPY_LIC_DIRS` 1516 :term:`COPY_LIC_DIRS`
1392 If set to "1" along with the 1517 If set to "1" along with the
@@ -1398,11 +1523,11 @@ system and gives an overview of their function and contents.
1398 1523
1399 .. note:: 1524 .. note::
1400 1525
1401 The ``COPY_LIC_DIRS`` does not offer a path for adding licenses for 1526 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for
1402 newly installed packages to an image, which might be most suitable for 1527 newly installed packages to an image, which might be most suitable for
1403 read-only filesystems that cannot be upgraded. See the 1528 read-only filesystems that cannot be upgraded. See the
1404 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1529 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
1405 You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" 1530 You can also reference the ":ref:`dev-manual/licenses:providing license text`"
1406 section in the Yocto Project Development Tasks Manual for 1531 section in the Yocto Project Development Tasks Manual for
1407 information on providing license text. 1532 information on providing license text.
1408 1533
@@ -1414,14 +1539,77 @@ system and gives an overview of their function and contents.
1414 1539
1415 .. note:: 1540 .. note::
1416 1541
1417 The ``COPY_LIC_MANIFEST`` does not offer a path for adding licenses for 1542 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for
1418 newly installed packages to an image, which might be most suitable for 1543 newly installed packages to an image, which might be most suitable for
1419 read-only filesystems that cannot be upgraded. See the 1544 read-only filesystems that cannot be upgraded. See the
1420 :term:`LICENSE_CREATE_PACKAGE` variable for additional information. 1545 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
1421 You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" 1546 You can also reference the ":ref:`dev-manual/licenses:providing license text`"
1422 section in the Yocto Project Development Tasks Manual for 1547 section in the Yocto Project Development Tasks Manual for
1423 information on providing license text. 1548 information on providing license text.
1424 1549
1550 :term:`COPYLEFT_LICENSE_EXCLUDE`
1551 A space-separated list of licenses to exclude from the source archived by
1552 the :ref:`ref-classes-archiver` class. In other words, if a license in a
1553 recipe's :term:`LICENSE` value is in the value of
1554 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the
1555 class.
1556
1557 .. note::
1558
1559 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the
1560 :term:`COPYLEFT_LICENSE_INCLUDE` variable.
1561
1562 The default value, which is "CLOSED Proprietary", for
1563 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the
1564 :ref:`ref-classes-copyleft_filter` class, which
1565 is inherited by the :ref:`ref-classes-archiver` class.
1566
1567 :term:`COPYLEFT_LICENSE_INCLUDE`
1568 A space-separated list of licenses to include in the source archived
1569 by the :ref:`ref-classes-archiver` class. In other
1570 words, if a license in a recipe's :term:`LICENSE`
1571 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its
1572 source is archived by the class.
1573
1574 The default value is set by the :ref:`ref-classes-copyleft_filter` class,
1575 which is inherited by the :ref:`ref-classes-archiver` class. The default
1576 value includes "GPL*", "LGPL*", and "AGPL*".
1577
1578 :term:`COPYLEFT_PN_EXCLUDE`
1579 A list of recipes to exclude in the source archived by the
1580 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE`
1581 variable overrides the license inclusion and exclusion caused through the
1582 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
1583 variables, respectively.
1584
1585 The default value, which is "" indicating to not explicitly exclude
1586 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the
1587 :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1588 :ref:`ref-classes-archiver` class.
1589
1590 :term:`COPYLEFT_PN_INCLUDE`
1591 A list of recipes to include in the source archived by the
1592 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE`
1593 variable overrides the license inclusion and exclusion caused through the
1594 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
1595 variables, respectively.
1596
1597 The default value, which is "" indicating to not explicitly include
1598 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the
1599 :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1600 :ref:`ref-classes-archiver` class.
1601
1602 :term:`COPYLEFT_RECIPE_TYPES`
1603 A space-separated list of recipe types to include in the source
1604 archived by the :ref:`archiver <ref-classes-archiver>` class.
1605 Recipe types are ``target``, :ref:`ref-classes-native`,
1606 :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`,
1607 :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`.
1608
1609 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES`
1610 is set by the :ref:`ref-classes-copyleft_filter` class, which is
1611 inherited by the :ref:`ref-classes-archiver` class.
1612
1425 :term:`CORE_IMAGE_EXTRA_INSTALL` 1613 :term:`CORE_IMAGE_EXTRA_INSTALL`
1426 Specifies the list of packages to be added to the image. You should 1614 Specifies the list of packages to be added to the image. You should
1427 only set this variable in the ``local.conf`` configuration file found 1615 only set this variable in the ``local.conf`` configuration file found
@@ -1434,24 +1622,24 @@ system and gives an overview of their function and contents.
1434 Specifies the parent directory of the OpenEmbedded-Core Metadata 1622 Specifies the parent directory of the OpenEmbedded-Core Metadata
1435 layer (i.e. ``meta``). 1623 layer (i.e. ``meta``).
1436 1624
1437 It is an important distinction that ``COREBASE`` points to the parent 1625 It is an important distinction that :term:`COREBASE` points to the parent
1438 of this layer and not the layer itself. Consider an example where you 1626 of this layer and not the layer itself. Consider an example where you
1439 have cloned the Poky Git repository and retained the ``poky`` name 1627 have cloned the Poky Git repository and retained the ``poky`` name
1440 for your local copy of the repository. In this case, ``COREBASE`` 1628 for your local copy of the repository. In this case, :term:`COREBASE`
1441 points to the ``poky`` folder because it is the parent directory of 1629 points to the ``poky`` folder because it is the parent directory of
1442 the ``poky/meta`` layer. 1630 the ``poky/meta`` layer.
1443 1631
1444 :term:`COREBASE_FILES` 1632 :term:`COREBASE_FILES`
1445 Lists files from the :term:`COREBASE` directory that 1633 Lists files from the :term:`COREBASE` directory that
1446 should be copied other than the layers listed in the 1634 should be copied other than the layers listed in the
1447 ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for 1635 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
1448 the purpose of copying metadata from the OpenEmbedded build system 1636 to copy metadata from the OpenEmbedded build system
1449 into the extensible SDK. 1637 into the extensible SDK.
1450 1638
1451 Explicitly listing files in ``COREBASE`` is needed because it 1639 Explicitly listing files in :term:`COREBASE` is needed because it
1452 typically contains build directories and other files that should not 1640 typically contains build directories and other files that should not
1453 normally be copied into the extensible SDK. Consequently, the value 1641 normally be copied into the extensible SDK. Consequently, the value
1454 of ``COREBASE_FILES`` is used in order to only copy the files that 1642 of :term:`COREBASE_FILES` is used in order to only copy the files that
1455 are actually needed. 1643 are actually needed.
1456 1644
1457 :term:`CPP` 1645 :term:`CPP`
@@ -1463,7 +1651,7 @@ system and gives an overview of their function and contents.
1463 variable and thus made visible to the software being built during the 1651 variable and thus made visible to the software being built during the
1464 compilation step. 1652 compilation step.
1465 1653
1466 Default initialization for ``CPPFLAGS`` varies depending on what is 1654 Default initialization for :term:`CPPFLAGS` varies depending on what is
1467 being built: 1655 being built:
1468 1656
1469 - :term:`TARGET_CPPFLAGS` when building for 1657 - :term:`TARGET_CPPFLAGS` when building for
@@ -1477,15 +1665,98 @@ system and gives an overview of their function and contents.
1477 1665
1478 :term:`CROSS_COMPILE` 1666 :term:`CROSS_COMPILE`
1479 The toolchain binary prefix for the target tools. The 1667 The toolchain binary prefix for the target tools. The
1480 ``CROSS_COMPILE`` variable is the same as the 1668 :term:`CROSS_COMPILE` variable is the same as the
1481 :term:`TARGET_PREFIX` variable. 1669 :term:`TARGET_PREFIX` variable.
1482 1670
1483 .. note:: 1671 .. note::
1484 1672
1485 The OpenEmbedded build system sets the ``CROSS_COMPILE`` 1673 The OpenEmbedded build system sets the :term:`CROSS_COMPILE`
1486 variable only in certain contexts (e.g. when building for kernel 1674 variable only in certain contexts (e.g. when building for kernel
1487 and kernel module recipes). 1675 and kernel module recipes).
1488 1676
1677 :term:`CVE_CHECK_IGNORE`
1678 This variable is deprecated and should be replaced by :term:`CVE_STATUS`.
1679
1680 :term:`CVE_CHECK_SHOW_WARNINGS`
1681 Specifies whether or not the :ref:`ref-classes-cve-check`
1682 class should generate warning messages on the console when unpatched
1683 CVEs are found. The default is "1", but you may wish to set it to "0" if
1684 you are already examining/processing the logs after the build has
1685 completed and thus do not need the warning messages.
1686
1687 :term:`CVE_CHECK_SKIP_RECIPE`
1688 The list of package names (:term:`PN`) for which
1689 CVEs (Common Vulnerabilities and Exposures) are ignored.
1690
1691 :term:`CVE_DB_UPDATE_INTERVAL`
1692 Specifies the CVE database update interval in seconds, as used by
1693 ``cve-update-db-native``. The default value is "86400" i.e. once a day
1694 (24*60*60). If the value is set to "0" then the update will be forced
1695 every time. Alternatively, a negative value e.g. "-1" will disable
1696 updates entirely.
1697
1698 :term:`CVE_PRODUCT`
1699 In a recipe, defines the name used to match the recipe name
1700 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
1701
1702 The default is ${:term:`BPN`} (except for recipes that inherit the
1703 :ref:`ref-classes-pypi` class where it is set based upon
1704 :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE
1705 database or matches with multiple entries in the database, the default
1706 value needs to be changed.
1707
1708 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
1709
1710 CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
1711
1712 Sometimes the product name is not specific enough, for example
1713 "tar" has been matching CVEs for the GNU ``tar`` package and also
1714 the ``node-tar`` node.js extension. To avoid this problem, use the
1715 vendor name as a prefix. The syntax for this is::
1716
1717 CVE_PRODUCT = "vendor:package"
1718
1719 :term:`CVE_STATUS`
1720 The CVE ID which is patched or should be ignored. Here is
1721 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
1722
1723 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
1724
1725 It has the format "reason: description" and the description is optional.
1726 The Reason is mapped to the final CVE state by mapping via
1727 :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes`
1728 for details.
1729
1730 :term:`CVE_STATUS_GROUPS`
1731 If there are many CVEs with the same status and reason, they can by simplified by using this
1732 variable instead of many similar lines with :term:`CVE_STATUS`::
1733
1734 CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"
1735
1736 CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002"
1737 CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows"
1738 CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004"
1739 CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally"
1740
1741 :term:`CVE_CHECK_STATUSMAP`
1742 Mapping variable for all possible reasons of :term:`CVE_STATUS`:
1743 ``Patched``, ``Unpatched`` and ``Ignored``.
1744 See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details::
1745
1746 CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"
1747
1748 :term:`CVE_VERSION`
1749 In a recipe, defines the version used to match the recipe version
1750 against the version in the `NIST CVE database <https://nvd.nist.gov/>`__
1751 when usign :ref:`ref-classes-cve-check`.
1752
1753 The default is ${:term:`PV`} but if recipes use custom version numbers
1754 which do not map to upstream software component release versions and the versions
1755 used in the CVE database, then this variable can be used to set the
1756 version number for :ref:`ref-classes-cve-check`. Example::
1757
1758 CVE_VERSION = "2.39"
1759
1489 :term:`CVSDIR` 1760 :term:`CVSDIR`
1490 The directory in which files checked out under the CVS system are 1761 The directory in which files checked out under the CVS system are
1491 stored. 1762 stored.
@@ -1498,7 +1769,7 @@ system and gives an overview of their function and contents.
1498 exported to an environment variable and thus made visible to the 1769 exported to an environment variable and thus made visible to the
1499 software being built during the compilation step. 1770 software being built during the compilation step.
1500 1771
1501 Default initialization for ``CXXFLAGS`` varies depending on what is 1772 Default initialization for :term:`CXXFLAGS` varies depending on what is
1502 being built: 1773 being built:
1503 1774
1504 - :term:`TARGET_CXXFLAGS` when building for 1775 - :term:`TARGET_CXXFLAGS` when building for
@@ -1514,8 +1785,7 @@ system and gives an overview of their function and contents.
1514 The destination directory. The location in the :term:`Build Directory` 1785 The destination directory. The location in the :term:`Build Directory`
1515 where components are installed by the 1786 where components are installed by the
1516 :ref:`ref-tasks-install` task. This location defaults 1787 :ref:`ref-tasks-install` task. This location defaults
1517 to: 1788 to::
1518 ::
1519 1789
1520 ${WORKDIR}/image 1790 ${WORKDIR}/image
1521 1791
@@ -1533,54 +1803,69 @@ system and gives an overview of their function and contents.
1533 suitable for timestamps. 1803 suitable for timestamps.
1534 1804
1535 :term:`DEBIAN_NOAUTONAME` 1805 :term:`DEBIAN_NOAUTONAME`
1536 When the :ref:`debian <ref-classes-debian>` class is inherited, 1806 When the :ref:`ref-classes-debian` class is inherited,
1537 which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a 1807 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
1538 particular package should not be renamed according to Debian library 1808 particular package should not be renamed according to Debian library
1539 package naming. You must use the package name as an override when you 1809 package naming. You must use the package name as an override when you
1540 set this variable. Here is an example from the ``fontconfig`` recipe: 1810 set this variable. Here is an example from the ``fontconfig`` recipe::
1541 ::
1542 1811
1543 DEBIAN_NOAUTONAME_fontconfig-utils = "1" 1812 DEBIAN_NOAUTONAME:fontconfig-utils = "1"
1544 1813
1545 :term:`DEBIANNAME` 1814 :term:`DEBIANNAME`
1546 When the :ref:`debian <ref-classes-debian>` class is inherited, 1815 When the :ref:`ref-classes-debian` class is inherited,
1547 which is the default behavior, ``DEBIANNAME`` allows you to override 1816 which is the default behavior, :term:`DEBIANNAME` allows you to override
1548 the library name for an individual package. Overriding the library 1817 the library name for an individual package. Overriding the library
1549 name in these cases is rare. You must use the package name as an 1818 name in these cases is rare. You must use the package name as an
1550 override when you set this variable. Here is an example from the 1819 override when you set this variable. Here is an example from the
1551 ``dbus`` recipe: 1820 ``dbus`` recipe::
1552 ::
1553 1821
1554 DEBIANNAME_${PN} = "dbus-1" 1822 DEBIANNAME:${PN} = "dbus-1"
1555 1823
1556 :term:`DEBUG_BUILD` 1824 :term:`DEBUG_BUILD`
1557 Specifies to build packages with debugging information. This 1825 Specifies to build packages with debugging information. This
1558 influences the value of the ``SELECTED_OPTIMIZATION`` variable. 1826 influences the value of the :term:`SELECTED_OPTIMIZATION` variable.
1559 1827
1560 :term:`DEBUG_OPTIMIZATION` 1828 :term:`DEBUG_OPTIMIZATION`
1561 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when 1829 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
1562 compiling a system for debugging. This variable defaults to "-O 1830 compiling a system for debugging. This variable defaults to "-O
1563 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1831 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1564 1832
1833 :term:`DEBUG_PREFIX_MAP`
1834 Allows to set C compiler options, such as ``-fdebug-prefix-map``,
1835 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to
1836 replace build-time paths by install-time ones in the debugging sections
1837 of binaries. This makes compiler output files location independent,
1838 at the cost of having to pass an extra command to tell the debugger
1839 where source files are.
1840
1841 This is used by the Yocto Project to guarantee
1842 :doc:`/test-manual/reproducible-builds` even when the source code of
1843 a package uses the ``__FILE__`` or ``assert()`` macros. See the
1844 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__
1845 website for details.
1846
1847 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1848 not intended to be user-configurable.
1849
1565 :term:`DEFAULT_PREFERENCE` 1850 :term:`DEFAULT_PREFERENCE`
1566 Specifies a weak bias for recipe selection priority. 1851 Specifies a weak bias for recipe selection priority.
1567 1852
1568 The most common usage of this is variable is to set it to "-1" within 1853 The most common usage of this is variable is to set it to "-1" within
1569 a recipe for a development version of a piece of software. Using the 1854 a recipe for a development version of a piece of software. Using the
1570 variable in this way causes the stable version of the recipe to build 1855 variable in this way causes the stable version of the recipe to build
1571 by default in the absence of ``PREFERRED_VERSION`` being used to 1856 by default in the absence of :term:`PREFERRED_VERSION` being used to
1572 build the development version. 1857 build the development version.
1573 1858
1574 .. note:: 1859 .. note::
1575 1860
1576 The bias provided by ``DEFAULT_PREFERENCE`` is weak and is overridden 1861 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden
1577 by :term:`BBFILE_PRIORITY` if that variable is different between two 1862 by :term:`BBFILE_PRIORITY` if that variable is different between two
1578 layers that contain different versions of the same recipe. 1863 layers that contain different versions of the same recipe.
1579 1864
1580 :term:`DEFAULTTUNE` 1865 :term:`DEFAULTTUNE`
1581 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1866 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1582 the "tune") used by the OpenEmbedded build system. The 1867 the "tune") used by the OpenEmbedded build system. The
1583 ``DEFAULTTUNE`` helps define 1868 :term:`DEFAULTTUNE` helps define
1584 :term:`TUNE_FEATURES`. 1869 :term:`TUNE_FEATURES`.
1585 1870
1586 The default tune is either implicitly or explicitly set by the 1871 The default tune is either implicitly or explicitly set by the
@@ -1594,83 +1879,79 @@ system and gives an overview of their function and contents.
1594 needed by the recipe at build time. 1879 needed by the recipe at build time.
1595 1880
1596 As an example, consider a recipe ``foo`` that contains the following 1881 As an example, consider a recipe ``foo`` that contains the following
1597 assignment: 1882 assignment::
1598 ::
1599 1883
1600 DEPENDS = "bar" 1884 DEPENDS = "bar"
1601 1885
1602 The practical effect of the previous 1886 The practical effect of the previous assignment is that all files
1603 assignment is that all files installed by bar will be available in 1887 installed by bar will be available in the appropriate staging sysroot,
1604 the appropriate staging sysroot, given by the 1888 given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time
1605 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the 1889 the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is
1606 :ref:`ref-tasks-configure` task for ``foo`` runs. 1890 implemented by having :ref:`ref-tasks-configure` depend on the
1607 This mechanism is implemented by having ``do_configure`` depend on 1891 :ref:`ref-tasks-populate_sysroot` task of each recipe listed in
1608 the :ref:`ref-tasks-populate_sysroot` task of 1892 :term:`DEPENDS`, through a
1609 each recipe listed in ``DEPENDS``, through a 1893 ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1610 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1894 declaration in the :ref:`ref-classes-base` class.
1611 declaration in the :ref:`base <ref-classes-base>` class.
1612 1895
1613 .. note:: 1896 .. note::
1614 1897
1615 It seldom is necessary to reference, for example, ``STAGING_DIR_HOST`` 1898 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
1616 explicitly. The standard classes and build-related variables are 1899 explicitly. The standard classes and build-related variables are
1617 configured to automatically use the appropriate staging sysroots. 1900 configured to automatically use the appropriate staging sysroots.
1618 1901
1619 As another example, ``DEPENDS`` can also be used to add utilities 1902 As another example, :term:`DEPENDS` can also be used to add utilities
1620 that run on the build machine during the build. For example, a recipe 1903 that run on the build machine during the build. For example, a recipe
1621 that makes use of a code generator built by the recipe ``codegen`` 1904 that makes use of a code generator built by the recipe ``codegen``
1622 might have the following: 1905 might have the following::
1623 ::
1624 1906
1625 DEPENDS = "codegen-native" 1907 DEPENDS = "codegen-native"
1626 1908
1627 For more 1909 For more
1628 information, see the :ref:`native <ref-classes-native>` class and 1910 information, see the :ref:`ref-classes-native` class and
1629 the :term:`EXTRANATIVEPATH` variable. 1911 the :term:`EXTRANATIVEPATH` variable.
1630 1912
1631 .. note:: 1913 .. note::
1632 1914
1633 - ``DEPENDS`` is a list of recipe names. Or, to be more precise, 1915 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
1634 it is a list of :term:`PROVIDES` names, which 1916 it is a list of :term:`PROVIDES` names, which
1635 usually match recipe names. Putting a package name such as 1917 usually match recipe names. Putting a package name such as
1636 "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" 1918 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
1637 instead, as this will put files from all the packages that make 1919 instead, as this will put files from all the packages that make
1638 up ``foo``, which includes those from ``foo-dev``, into the 1920 up ``foo``, which includes those from ``foo-dev``, into the
1639 sysroot. 1921 sysroot.
1640 1922
1641 - One recipe having another recipe in ``DEPENDS`` does not by 1923 - One recipe having another recipe in :term:`DEPENDS` does not by
1642 itself add any runtime dependencies between the packages 1924 itself add any runtime dependencies between the packages
1643 produced by the two recipes. However, as explained in the 1925 produced by the two recipes. However, as explained in the
1644 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 1926 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
1645 section in the Yocto Project Overview and Concepts Manual, 1927 section in the Yocto Project Overview and Concepts Manual,
1646 runtime dependencies will often be added automatically, meaning 1928 runtime dependencies will often be added automatically, meaning
1647 ``DEPENDS`` alone is sufficient for most recipes. 1929 :term:`DEPENDS` alone is sufficient for most recipes.
1648 1930
1649 - Counterintuitively, ``DEPENDS`` is often necessary even for 1931 - Counterintuitively, :term:`DEPENDS` is often necessary even for
1650 recipes that install precompiled components. For example, if 1932 recipes that install precompiled components. For example, if
1651 ``libfoo`` is a precompiled library that links against 1933 ``libfoo`` is a precompiled library that links against
1652 ``libbar``, then linking against ``libfoo`` requires both 1934 ``libbar``, then linking against ``libfoo`` requires both
1653 ``libfoo`` and ``libbar`` to be available in the sysroot. 1935 ``libfoo`` and ``libbar`` to be available in the sysroot.
1654 Without a ``DEPENDS`` from the recipe that installs ``libfoo`` 1936 Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
1655 to the recipe that installs ``libbar``, other recipes might 1937 to the recipe that installs ``libbar``, other recipes might
1656 fail to link against ``libfoo``. 1938 fail to link against ``libfoo``.
1657 1939
1658 For information on runtime dependencies, see the 1940 For information on runtime dependencies, see the :term:`RDEPENDS`
1659 :term:`RDEPENDS` variable. You can also see the 1941 variable. You can also see the
1660 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and 1942 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
1661 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the 1943 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
1662 BitBake User Manual for additional information on tasks and 1944 sections in the BitBake User Manual for additional information on tasks
1663 dependencies. 1945 and dependencies.
1664 1946
1665 :term:`DEPLOY_DIR` 1947 :term:`DEPLOY_DIR`
1666 Points to the general area that the OpenEmbedded build system uses to 1948 Points to the general area that the OpenEmbedded build system uses to
1667 place images, packages, SDKs, and other output files that are ready 1949 place images, packages, SDKs, and other output files that are ready
1668 to be used outside of the build system. By default, this directory 1950 to be used outside of the build system. By default, this directory
1669 resides within the :term:`Build Directory` as 1951 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``.
1670 ``${TMPDIR}/deploy``.
1671 1952
1672 For more information on the structure of the Build Directory, see 1953 For more information on the structure of the Build Directory, see
1673 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. 1954 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
1674 For more detail on the contents of the ``deploy`` directory, see the 1955 For more detail on the contents of the ``deploy`` directory, see the
1675 ":ref:`overview-manual/concepts:images`", 1956 ":ref:`overview-manual/concepts:images`",
1676 ":ref:`overview-manual/concepts:package feeds`", and 1957 ":ref:`overview-manual/concepts:package feeds`", and
@@ -1680,19 +1961,17 @@ system and gives an overview of their function and contents.
1680 :term:`DEPLOY_DIR_DEB` 1961 :term:`DEPLOY_DIR_DEB`
1681 Points to the area that the OpenEmbedded build system uses to place 1962 Points to the area that the OpenEmbedded build system uses to place
1682 Debian packages that are ready to be used outside of the build 1963 Debian packages that are ready to be used outside of the build
1683 system. This variable applies only when 1964 system. This variable applies only when :term:`PACKAGE_CLASSES` contains
1684 :term:`PACKAGE_CLASSES` contains 1965 ":ref:`ref-classes-package_deb`".
1685 "package_deb".
1686 1966
1687 The BitBake configuration file initially defines the 1967 The BitBake configuration file initially defines the
1688 ``DEPLOY_DIR_DEB`` variable as a sub-folder of 1968 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of
1689 :term:`DEPLOY_DIR`: 1969 :term:`DEPLOY_DIR`::
1690 ::
1691 1970
1692 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" 1971 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
1693 1972
1694 The :ref:`package_deb <ref-classes-package_deb>` class uses the 1973 The :ref:`ref-classes-package_deb` class uses the
1695 ``DEPLOY_DIR_DEB`` variable to make sure the 1974 :term:`DEPLOY_DIR_DEB` variable to make sure the
1696 :ref:`ref-tasks-package_write_deb` task 1975 :ref:`ref-tasks-package_write_deb` task
1697 writes Debian packages into the appropriate folder. For more 1976 writes Debian packages into the appropriate folder. For more
1698 information on how packaging works, see the 1977 information on how packaging works, see the
@@ -1707,8 +1986,14 @@ system and gives an overview of their function and contents.
1707 resides within the :term:`Build Directory` as 1986 resides within the :term:`Build Directory` as
1708 ``${DEPLOY_DIR}/images/${MACHINE}/``. 1987 ``${DEPLOY_DIR}/images/${MACHINE}/``.
1709 1988
1710 For more information on the structure of the Build Directory, see 1989 It must not be used directly in recipes when deploying files. Instead,
1711 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. 1990 it's only useful when a recipe needs to "read" a file already deployed
1991 by a dependency. So, it should be filled with the contents of
1992 :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the
1993 contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class.
1994
1995 For more information on the structure of the :term:`Build Directory`, see
1996 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
1712 For more detail on the contents of the ``deploy`` directory, see the 1997 For more detail on the contents of the ``deploy`` directory, see the
1713 ":ref:`overview-manual/concepts:images`" and 1998 ":ref:`overview-manual/concepts:images`" and
1714 ":ref:`overview-manual/concepts:application development sdk`" sections both in 1999 ":ref:`overview-manual/concepts:application development sdk`" sections both in
@@ -1717,19 +2002,16 @@ system and gives an overview of their function and contents.
1717 :term:`DEPLOY_DIR_IPK` 2002 :term:`DEPLOY_DIR_IPK`
1718 Points to the area that the OpenEmbedded build system uses to place 2003 Points to the area that the OpenEmbedded build system uses to place
1719 IPK packages that are ready to be used outside of the build system. 2004 IPK packages that are ready to be used outside of the build system.
1720 This variable applies only when 2005 This variable applies only when :term:`PACKAGE_CLASSES` contains
1721 :term:`PACKAGE_CLASSES` contains 2006 ":ref:`ref-classes-package_ipk`".
1722 "package_ipk".
1723 2007
1724 The BitBake configuration file initially defines this variable as a 2008 The BitBake configuration file initially defines this variable as a
1725 sub-folder of :term:`DEPLOY_DIR`: 2009 sub-folder of :term:`DEPLOY_DIR`::
1726 ::
1727 2010
1728 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" 2011 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
1729 2012
1730 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the 2013 The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK`
1731 ``DEPLOY_DIR_IPK`` variable to make sure the 2014 variable to make sure the :ref:`ref-tasks-package_write_ipk` task
1732 :ref:`ref-tasks-package_write_ipk` task
1733 writes IPK packages into the appropriate folder. For more information 2015 writes IPK packages into the appropriate folder. For more information
1734 on how packaging works, see the 2016 on how packaging works, see the
1735 ":ref:`overview-manual/concepts:package feeds`" section 2017 ":ref:`overview-manual/concepts:package feeds`" section
@@ -1738,89 +2020,81 @@ system and gives an overview of their function and contents.
1738 :term:`DEPLOY_DIR_RPM` 2020 :term:`DEPLOY_DIR_RPM`
1739 Points to the area that the OpenEmbedded build system uses to place 2021 Points to the area that the OpenEmbedded build system uses to place
1740 RPM packages that are ready to be used outside of the build system. 2022 RPM packages that are ready to be used outside of the build system.
1741 This variable applies only when 2023 This variable applies only when :term:`PACKAGE_CLASSES` contains
1742 :term:`PACKAGE_CLASSES` contains 2024 ":ref:`ref-classes-package_rpm`".
1743 "package_rpm".
1744 2025
1745 The BitBake configuration file initially defines this variable as a 2026 The BitBake configuration file initially defines this variable as a
1746 sub-folder of :term:`DEPLOY_DIR`: 2027 sub-folder of :term:`DEPLOY_DIR`::
1747 ::
1748 2028
1749 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" 2029 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
1750 2030
1751 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the 2031 The :ref:`ref-classes-package_rpm` class uses the
1752 ``DEPLOY_DIR_RPM`` variable to make sure the 2032 :term:`DEPLOY_DIR_RPM` variable to make sure the
1753 :ref:`ref-tasks-package_write_rpm` task 2033 :ref:`ref-tasks-package_write_rpm` task
1754 writes RPM packages into the appropriate folder. For more information 2034 writes RPM packages into the appropriate folder. For more information
1755 on how packaging works, see the 2035 on how packaging works, see the
1756 ":ref:`overview-manual/concepts:package feeds`" section 2036 ":ref:`overview-manual/concepts:package feeds`" section
1757 in the Yocto Project Overview and Concepts Manual. 2037 in the Yocto Project Overview and Concepts Manual.
1758 2038
1759 :term:`DEPLOY_DIR_TAR`
1760 Points to the area that the OpenEmbedded build system uses to place
1761 tarballs that are ready to be used outside of the build system. This
1762 variable applies only when
1763 :term:`PACKAGE_CLASSES` contains
1764 "package_tar".
1765
1766 The BitBake configuration file initially defines this variable as a
1767 sub-folder of :term:`DEPLOY_DIR`:
1768 ::
1769
1770 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
1771
1772 The :ref:`package_tar <ref-classes-package_tar>` class uses the
1773 ``DEPLOY_DIR_TAR`` variable to make sure the
1774 :ref:`ref-tasks-package_write_tar` task
1775 writes TAR packages into the appropriate folder. For more information
1776 on how packaging works, see the
1777 ":ref:`overview-manual/concepts:package feeds`" section
1778 in the Yocto Project Overview and Concepts Manual.
1779
1780 :term:`DEPLOYDIR` 2039 :term:`DEPLOYDIR`
1781 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the 2040 When inheriting the :ref:`ref-classes-deploy` class, the
1782 ``DEPLOYDIR`` points to a temporary work area for deployed files that 2041 :term:`DEPLOYDIR` points to a temporary work area for deployed files that
1783 is set in the ``deploy`` class as follows: 2042 is set in the :ref:`ref-classes-deploy` class as follows::
1784 ::
1785 2043
1786 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 2044 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
1787 2045
1788 Recipes inheriting the ``deploy`` class should copy files to be 2046 Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be
1789 deployed into ``DEPLOYDIR``, and the class will take care of copying 2047 deployed into :term:`DEPLOYDIR`, and the class will take care of copying
1790 them into :term:`DEPLOY_DIR_IMAGE` 2048 them into :term:`DEPLOY_DIR_IMAGE`
1791 afterwards. 2049 afterwards.
1792 2050
1793 :term:`DESCRIPTION` 2051 :term:`DESCRIPTION`
1794 The package description used by package managers. If not set, 2052 The package description used by package managers. If not set,
1795 ``DESCRIPTION`` takes the value of the :term:`SUMMARY` 2053 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
1796 variable. 2054 variable.
1797 2055
2056 :term:`DEV_PKG_DEPENDENCY`
2057 Provides an easy way for recipes to disable or adjust the runtime recommendation
2058 (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main
2059 (``${PN}``) package.
2060
2061 :term:`DISABLE_STATIC`
2062 Used in order to disable static linking by default (in order to save
2063 space, since static libraries are often unused in embedded systems.)
2064 The default value is " --disable-static", however it can be set to ""
2065 in order to enable static linking if desired. Certain recipes do this
2066 individually, and also there is a
2067 ``meta/conf/distro/include/no-static-libs.inc`` include file that
2068 disables static linking for a number of recipes. Some software
2069 packages or build tools (such as CMake) have explicit support for
2070 enabling / disabling static linking, and in those cases
2071 :term:`DISABLE_STATIC` is not used.
2072
1798 :term:`DISTRO` 2073 :term:`DISTRO`
1799 The short name of the distribution. For information on the long name 2074 The short name of the distribution. For information on the long name
1800 of the distribution, see the :term:`DISTRO_NAME` 2075 of the distribution, see the :term:`DISTRO_NAME`
1801 variable. 2076 variable.
1802 2077
1803 The ``DISTRO`` variable corresponds to a distribution configuration 2078 The :term:`DISTRO` variable corresponds to a distribution configuration
1804 file whose root name is the same as the variable's argument and whose 2079 file whose root name is the same as the variable's argument and whose
1805 filename extension is ``.conf``. For example, the distribution 2080 filename extension is ``.conf``. For example, the distribution
1806 configuration file for the Poky distribution is named ``poky.conf`` 2081 configuration file for the Poky distribution is named ``poky.conf``
1807 and resides in the ``meta-poky/conf/distro`` directory of the 2082 and resides in the ``meta-poky/conf/distro`` directory of the
1808 :term:`Source Directory`. 2083 :term:`Source Directory`.
1809 2084
1810 Within that ``poky.conf`` file, the ``DISTRO`` variable is set as 2085 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
1811 follows: 2086 follows::
1812 ::
1813 2087
1814 DISTRO = "poky" 2088 DISTRO = "poky"
1815 2089
1816 Distribution configuration files are located in a ``conf/distro`` 2090 Distribution configuration files are located in a ``conf/distro``
1817 directory within the :term:`Metadata` that contains the 2091 directory within the :term:`Metadata` that contains the
1818 distribution configuration. The value for ``DISTRO`` must not contain 2092 distribution configuration. The value for :term:`DISTRO` must not contain
1819 spaces, and is typically all lower-case. 2093 spaces, and is typically all lower-case.
1820 2094
1821 .. note:: 2095 .. note::
1822 2096
1823 If the ``DISTRO`` variable is blank, a set of default configurations 2097 If the :term:`DISTRO` variable is blank, a set of default configurations
1824 are used, which are specified within 2098 are used, which are specified within
1825 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2099 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
1826 2100
@@ -1829,7 +2103,7 @@ system and gives an overview of their function and contents.
1829 2103
1830 :term:`DISTRO_EXTRA_RDEPENDS` 2104 :term:`DISTRO_EXTRA_RDEPENDS`
1831 Specifies a list of distro-specific packages to add to all images. 2105 Specifies a list of distro-specific packages to add to all images.
1832 This variable takes affect through ``packagegroup-base`` so the 2106 This variable takes effect through ``packagegroup-base`` so the
1833 variable only really applies to the more full-featured images that 2107 variable only really applies to the more full-featured images that
1834 include ``packagegroup-base``. You can use this variable to keep 2108 include ``packagegroup-base``. You can use this variable to keep
1835 distro policy out of generic images. As with all other distro 2109 distro policy out of generic images. As with all other distro
@@ -1847,32 +2121,47 @@ system and gives an overview of their function and contents.
1847 configuration file. 2121 configuration file.
1848 2122
1849 In most cases, the presence or absence of a feature in 2123 In most cases, the presence or absence of a feature in
1850 ``DISTRO_FEATURES`` is translated to the appropriate option supplied 2124 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied
1851 to the configure script during the 2125 to the configure script during the
1852 :ref:`ref-tasks-configure` task for recipes that 2126 :ref:`ref-tasks-configure` task for recipes that
1853 optionally support the feature. For example, specifying "x11" in 2127 optionally support the feature. For example, specifying "x11" in
1854 ``DISTRO_FEATURES``, causes every piece of software built for the 2128 :term:`DISTRO_FEATURES`, causes every piece of software built for the
1855 target that can optionally support X11 to have its X11 support 2129 target that can optionally support X11 to have its X11 support
1856 enabled. 2130 enabled.
1857 2131
2132 .. note::
2133
2134 Just enabling :term:`DISTRO_FEATURES` alone doesn't
2135 enable feature support for packages. Mechanisms such as making
2136 :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used
2137 to enable/disable package features.
2138
1858 Two more examples are Bluetooth and NFS support. For a more complete 2139 Two more examples are Bluetooth and NFS support. For a more complete
1859 list of features that ships with the Yocto Project and that you can 2140 list of features that ships with the Yocto Project and that you can
1860 provide with this variable, see the ":ref:`ref-features-distro`" section. 2141 provide with this variable, see the ":ref:`ref-features-distro`" section.
1861 2142
1862 :term:`DISTRO_FEATURES_BACKFILL` 2143 :term:`DISTRO_FEATURES_BACKFILL`
1863 Features to be added to ``DISTRO_FEATURES`` if not also present in 2144 A space-separated list of features to be added to :term:`DISTRO_FEATURES`
1864 ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. 2145 if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
1865 2146
1866 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 2147 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1867 not intended to be user-configurable. It is best to just reference 2148 not intended to be user-configurable. It is best to just reference
1868 the variable to see which distro features are being backfilled for 2149 the variable to see which distro features are being
1869 all distro configurations. See the ":ref:`ref-features-backfill`" section 2150 :ref:`backfilled <ref-features-backfill>` for all distro configurations.
1870 for more information.
1871 2151
1872 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 2152 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
1873 Features from ``DISTRO_FEATURES_BACKFILL`` that should not be 2153 A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL`
1874 backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See 2154 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
1875 the ":ref:`ref-features-backfill`" section for more information. 2155 to :term:`DISTRO_FEATURES`) during the build.
2156
2157 This corresponds to an opt-out mechanism. When new default distro
2158 features are introduced, distribution maintainers can review (`consider`)
2159 them and decide to exclude them from the
2160 :ref:`backfilled <ref-features-backfill>` features. Therefore, the
2161 combination of :term:`DISTRO_FEATURES_BACKFILL` and
2162 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to
2163 add new default features without breaking existing distributions.
2164
1876 2165
1877 :term:`DISTRO_FEATURES_DEFAULT` 2166 :term:`DISTRO_FEATURES_DEFAULT`
1878 A convenience variable that gives you the default list of distro 2167 A convenience variable that gives you the default list of distro
@@ -1883,26 +2172,24 @@ system and gives an overview of their function and contents.
1883 able to reuse the default 2172 able to reuse the default
1884 :term:`DISTRO_FEATURES` options without the 2173 :term:`DISTRO_FEATURES` options without the
1885 need to write out the full set. Here is an example that uses 2174 need to write out the full set. Here is an example that uses
1886 ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: 2175 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
1887 ::
1888 2176
1889 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" 2177 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
1890 2178
1891 :term:`DISTRO_FEATURES_FILTER_NATIVE` 2179 :term:`DISTRO_FEATURES_FILTER_NATIVE`
1892 Specifies a list of features that if present in the target 2180 Specifies a list of features that if present in the target
1893 :term:`DISTRO_FEATURES` value should be 2181 :term:`DISTRO_FEATURES` value should be
1894 included in ``DISTRO_FEATURES`` when building native recipes. This 2182 included in :term:`DISTRO_FEATURES` when building native recipes. This
1895 variable is used in addition to the features filtered using the 2183 variable is used in addition to the features filtered using the
1896 :term:`DISTRO_FEATURES_NATIVE` 2184 :term:`DISTRO_FEATURES_NATIVE`
1897 variable. 2185 variable.
1898 2186
1899 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 2187 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
1900 Specifies a list of features that if present in the target 2188 Specifies a list of features that if present in the target
1901 :term:`DISTRO_FEATURES` value should be 2189 :term:`DISTRO_FEATURES` value should be included in
1902 included in ``DISTRO_FEATURES`` when building nativesdk recipes. This 2190 :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk`
1903 variable is used in addition to the features filtered using the 2191 recipes. This variable is used in addition to the features filtered using
1904 :term:`DISTRO_FEATURES_NATIVESDK` 2192 the :term:`DISTRO_FEATURES_NATIVESDK` variable.
1905 variable.
1906 2193
1907 :term:`DISTRO_FEATURES_NATIVE` 2194 :term:`DISTRO_FEATURES_NATIVE`
1908 Specifies a list of features that should be included in 2195 Specifies a list of features that should be included in
@@ -1915,25 +2202,23 @@ system and gives an overview of their function and contents.
1915 :term:`DISTRO_FEATURES_NATIVESDK` 2202 :term:`DISTRO_FEATURES_NATIVESDK`
1916 Specifies a list of features that should be included in 2203 Specifies a list of features that should be included in
1917 :term:`DISTRO_FEATURES` when building 2204 :term:`DISTRO_FEATURES` when building
1918 nativesdk recipes. This variable is used in addition to the features 2205 :ref:`ref-classes-nativesdk` recipes. This variable is used
1919 filtered using the 2206 in addition to the features filtered using the
1920 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 2207 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable.
1921 variable.
1922 2208
1923 :term:`DISTRO_NAME` 2209 :term:`DISTRO_NAME`
1924 The long name of the distribution. For information on the short name 2210 The long name of the distribution. For information on the short name
1925 of the distribution, see the :term:`DISTRO` variable. 2211 of the distribution, see the :term:`DISTRO` variable.
1926 2212
1927 The ``DISTRO_NAME`` variable corresponds to a distribution 2213 The :term:`DISTRO_NAME` variable corresponds to a distribution
1928 configuration file whose root name is the same as the variable's 2214 configuration file whose root name is the same as the variable's
1929 argument and whose filename extension is ``.conf``. For example, the 2215 argument and whose filename extension is ``.conf``. For example, the
1930 distribution configuration file for the Poky distribution is named 2216 distribution configuration file for the Poky distribution is named
1931 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory 2217 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
1932 of the :term:`Source Directory`. 2218 of the :term:`Source Directory`.
1933 2219
1934 Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set 2220 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
1935 as follows: 2221 as follows::
1936 ::
1937 2222
1938 DISTRO_NAME = "Poky (Yocto Project Reference Distro)" 2223 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
1939 2224
@@ -1943,7 +2228,7 @@ system and gives an overview of their function and contents.
1943 2228
1944 .. note:: 2229 .. note::
1945 2230
1946 If the ``DISTRO_NAME`` variable is blank, a set of default 2231 If the :term:`DISTRO_NAME` variable is blank, a set of default
1947 configurations are used, which are specified within 2232 configurations are used, which are specified within
1948 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. 2233 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
1949 2234
@@ -1955,26 +2240,30 @@ system and gives an overview of their function and contents.
1955 distribution. By default, this list includes the value of 2240 distribution. By default, this list includes the value of
1956 :term:`DISTRO`. 2241 :term:`DISTRO`.
1957 2242
1958 You can extend ``DISTROOVERRIDES`` to add extra overrides that should 2243 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
1959 apply to the distribution. 2244 apply to the distribution.
1960 2245
1961 The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it 2246 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
1962 is included in the default value of 2247 is included in the default value of
1963 :term:`OVERRIDES`. 2248 :term:`OVERRIDES`.
1964 2249
2250 Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf
2251 </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`::
2252
2253 DISTROOVERRIDES = "poky:poky-tiny"
2254
1965 :term:`DL_DIR` 2255 :term:`DL_DIR`
1966 The central download directory used by the build process to store 2256 The central download directory used by the build process to store
1967 downloads. By default, ``DL_DIR`` gets files suitable for mirroring 2257 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
1968 for everything except Git repositories. If you want tarballs of Git 2258 for everything except Git repositories. If you want tarballs of Git
1969 repositories, use the 2259 repositories, use the
1970 :term:`BB_GENERATE_MIRROR_TARBALLS` 2260 :term:`BB_GENERATE_MIRROR_TARBALLS`
1971 variable. 2261 variable.
1972 2262
1973 You can set this directory by defining the ``DL_DIR`` variable in the 2263 You can set this directory by defining the :term:`DL_DIR` variable in the
1974 ``conf/local.conf`` file. This directory is self-maintaining and you 2264 ``conf/local.conf`` file. This directory is self-maintaining and you
1975 should not have to touch it. By default, the directory is 2265 should not have to touch it. By default, the directory is
1976 ``downloads`` in the :term:`Build Directory`. 2266 ``downloads`` in the :term:`Build Directory`::
1977 ::
1978 2267
1979 #DL_DIR ?= "${TOPDIR}/downloads" 2268 #DL_DIR ?= "${TOPDIR}/downloads"
1980 2269
@@ -1984,7 +2273,7 @@ system and gives an overview of their function and contents.
1984 During a first build, the system downloads many different source code 2273 During a first build, the system downloads many different source code
1985 tarballs from various upstream projects. Downloading can take a 2274 tarballs from various upstream projects. Downloading can take a
1986 while, particularly if your network connection is slow. Tarballs are 2275 while, particularly if your network connection is slow. Tarballs are
1987 all stored in the directory defined by ``DL_DIR`` and the build 2276 all stored in the directory defined by :term:`DL_DIR` and the build
1988 system looks there first to find source tarballs. 2277 system looks there first to find source tarballs.
1989 2278
1990 .. note:: 2279 .. note::
@@ -2001,24 +2290,45 @@ system and gives an overview of their function and contents.
2001 Wiki page. 2290 Wiki page.
2002 2291
2003 :term:`DOC_COMPRESS` 2292 :term:`DOC_COMPRESS`
2004 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` 2293 When inheriting the :ref:`ref-classes-compress_doc`
2005 class, this variable sets the compression policy used when the 2294 class, this variable sets the compression policy used when the
2006 OpenEmbedded build system compresses man pages and info pages. By 2295 OpenEmbedded build system compresses manual and info pages. By
2007 default, the compression method used is gz (gzip). Other policies 2296 default, the compression method used is gz (gzip). Other policies
2008 available are xz and bz2. 2297 available are xz and bz2.
2009 2298
2010 For information on policies and on how to use this variable, see the 2299 For information on policies and on how to use this variable, see the
2011 comments in the ``meta/classes/compress_doc.bbclass`` file. 2300 comments in the ``meta/classes-recipe/compress_doc.bbclass`` file.
2301
2302 :term:`DT_FILES`
2303 Space-separated list of device tree source files to compile using
2304 a recipe that inherits the :ref:`ref-classes-devicetree` class. These
2305 are relative to the :term:`DT_FILES_PATH`.
2306
2307 For convenience, both ``.dts`` and ``.dtb`` extensions can be used.
2308
2309 Use an empty string (default) to build all device tree sources within
2310 the :term:`DT_FILES_PATH` directory.
2311
2312 :term:`DT_FILES_PATH`
2313 When compiling out-of-tree device tree sources using a recipe that
2314 inherits the :ref:`ref-classes-devicetree` class, this variable specifies
2315 the path to the directory containing dts files to build.
2316
2317 Defaults to the :term:`S` directory.
2318
2319 :term:`DT_PADDING_SIZE`
2320 When inheriting the :ref:`ref-classes-devicetree` class, this variable
2321 specifies the size of padding appended to the device tree blob, used as
2322 extra space typically for additional properties during boot.
2012 2323
2013 :term:`EFI_PROVIDER` 2324 :term:`EFI_PROVIDER`
2014 When building bootable images (i.e. where ``hddimg``, ``iso``, or 2325 When building bootable images (i.e. where ``hddimg``, ``iso``, or
2015 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the 2326 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
2016 ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The 2327 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
2017 default is "grub-efi", but "systemd-boot" can be used instead. 2328 default is "grub-efi", but "systemd-boot" can be used instead.
2018 2329
2019 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and 2330 See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live`
2020 :ref:`image-live <ref-classes-image-live>` classes for more 2331 classes for more information.
2021 information.
2022 2332
2023 :term:`ENABLE_BINARY_LOCALE_GENERATION` 2333 :term:`ENABLE_BINARY_LOCALE_GENERATION`
2024 Variable that controls which locales for ``glibc`` are generated 2334 Variable that controls which locales for ``glibc`` are generated
@@ -2026,18 +2336,16 @@ system and gives an overview of their function and contents.
2026 less). 2336 less).
2027 2337
2028 :term:`ERR_REPORT_DIR` 2338 :term:`ERR_REPORT_DIR`
2029 When used with the :ref:`report-error <ref-classes-report-error>` 2339 When used with the :ref:`ref-classes-report-error` class, specifies the
2030 class, specifies the path used for storing the debug files created by 2340 path used for storing the debug files created by the :ref:`error reporting
2031 the :ref:`error reporting 2341 tool <dev-manual/error-reporting-tool:using the error reporting tool>`,
2032 tool <dev-manual/common-tasks:using the error reporting tool>`, which 2342 which allows you to submit build errors you encounter to a central
2033 allows you to submit build errors you encounter to a central
2034 database. By default, the value of this variable is 2343 database. By default, the value of this variable is
2035 ``${``\ :term:`LOG_DIR`\ ``}/error-report``. 2344 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2036 2345
2037 You can set ``ERR_REPORT_DIR`` to the path you want the error 2346 You can set :term:`ERR_REPORT_DIR` to the path you want the error
2038 reporting tool to store the debug files as follows in your 2347 reporting tool to store the debug files as follows in your
2039 ``local.conf`` file: 2348 ``local.conf`` file::
2040 ::
2041 2349
2042 ERR_REPORT_DIR = "path" 2350 ERR_REPORT_DIR = "path"
2043 2351
@@ -2046,7 +2354,69 @@ system and gives an overview of their function and contents.
2046 errors by the OpenEmbedded build system. You set this variable in 2354 errors by the OpenEmbedded build system. You set this variable in
2047 your distribution configuration file. For a list of the checks you 2355 your distribution configuration file. For a list of the checks you
2048 can control with this variable, see the 2356 can control with this variable, see the
2049 ":ref:`insane.bbclass <ref-classes-insane>`" section. 2357 ":ref:`ref-classes-insane`" section.
2358
2359 :term:`ESDK_CLASS_INHERIT_DISABLE`
2360 A list of classes to remove from the :term:`INHERIT`
2361 value globally within the extensible SDK configuration. The
2362 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
2363 default value::
2364
2365 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc"
2366
2367 Some classes are not generally applicable within the extensible SDK
2368 context. You can use this variable to disable those classes.
2369
2370 For additional information on how to customize the extensible SDK's
2371 configuration, see the
2372 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2373 section in the Yocto Project Application Development and the
2374 Extensible Software Development Kit (eSDK) manual.
2375
2376 :term:`ESDK_LOCALCONF_ALLOW`
2377 A list of variables allowed through from the OpenEmbedded build
2378 system configuration into the extensible SDK configuration. By
2379 default, the list of variables is empty and is set in the
2380 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
2381
2382 This list overrides the variables specified using the
2383 :term:`ESDK_LOCALCONF_REMOVE` variable as well as
2384 other variables automatically added due to the "/" character
2385 being found at the start of the
2386 value, which is usually indicative of being a path and thus might not
2387 be valid on the system where the SDK is installed.
2388
2389 For additional information on how to customize the extensible SDK's
2390 configuration, see the
2391 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2392 section in the Yocto Project Application Development and the
2393 Extensible Software Development Kit (eSDK) manual.
2394
2395 :term:`ESDK_LOCALCONF_REMOVE`
2396 A list of variables not allowed through from the OpenEmbedded build
2397 system configuration into the extensible SDK configuration. Usually,
2398 these are variables that are specific to the machine on which the
2399 build system is running and thus would be potentially problematic
2400 within the extensible SDK.
2401
2402 By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the
2403 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
2404 excludes the following variables:
2405
2406 - :term:`CONF_VERSION`
2407 - :term:`BB_NUMBER_THREADS`
2408 - :term:`BB_NUMBER_PARSE_THREADS`
2409 - :term:`PARALLEL_MAKE`
2410 - :term:`PRSERV_HOST`
2411 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
2412 - :term:`SSTATE_DIR` :term:`TMPDIR`
2413 - :term:`BB_SERVER_TIMEOUT`
2414
2415 For additional information on how to customize the extensible SDK's
2416 configuration, see the
2417 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2418 section in the Yocto Project Application Development and the
2419 Extensible Software Development Kit (eSDK) manual.
2050 2420
2051 :term:`EXCLUDE_FROM_SHLIBS` 2421 :term:`EXCLUDE_FROM_SHLIBS`
2052 Triggers the OpenEmbedded build system's shared libraries resolver to 2422 Triggers the OpenEmbedded build system's shared libraries resolver to
@@ -2060,13 +2430,12 @@ system and gives an overview of their function and contents.
2060 libraries resolver might implicitly define some dependencies between 2430 libraries resolver might implicitly define some dependencies between
2061 packages. 2431 packages.
2062 2432
2063 The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the 2433 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
2064 :term:`PRIVATE_LIBS` variable, which excludes a 2434 :term:`PRIVATE_LIBS` variable, which excludes a
2065 package's particular libraries only and not the whole package. 2435 package's particular libraries only and not the whole package.
2066 2436
2067 Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a 2437 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
2068 particular package: 2438 particular package::
2069 ::
2070 2439
2071 EXCLUDE_FROM_SHLIBS = "1" 2440 EXCLUDE_FROM_SHLIBS = "1"
2072 2441
@@ -2081,18 +2450,18 @@ system and gives an overview of their function and contents.
2081 2450
2082 .. note:: 2451 .. note::
2083 2452
2084 Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a 2453 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
2085 world build in order to satisfy dependencies of other recipes. Adding 2454 world build in order to satisfy dependencies of other recipes. Adding
2086 a recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not 2455 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
2087 explicitly added to the list of build targets in a world build. 2456 explicitly added to the list of build targets in a world build.
2088 2457
2089 :term:`EXTENDPE` 2458 :term:`EXTENDPE`
2090 Used with file and pathnames to create a prefix for a recipe's 2459 Used with file and pathnames to create a prefix for a recipe's
2091 version based on the recipe's :term:`PE` value. If ``PE`` 2460 version based on the recipe's :term:`PE` value. If :term:`PE`
2092 is set and greater than zero for a recipe, ``EXTENDPE`` becomes that 2461 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
2093 value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). 2462 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
2094 If a recipe's ``PE`` is not set (the default) or is equal to zero, 2463 If a recipe's :term:`PE` is not set (the default) or is equal to zero,
2095 ``EXTENDPE`` becomes "". 2464 :term:`EXTENDPE` becomes "".
2096 2465
2097 See the :term:`STAMP` variable for an example. 2466 See the :term:`STAMP` variable for an example.
2098 2467
@@ -2100,55 +2469,67 @@ system and gives an overview of their function and contents.
2100 The full package version specification as it appears on the final 2469 The full package version specification as it appears on the final
2101 packages produced by a recipe. The variable's value is normally used 2470 packages produced by a recipe. The variable's value is normally used
2102 to fix a runtime dependency to the exact same version of another 2471 to fix a runtime dependency to the exact same version of another
2103 package in the same recipe: 2472 package in the same recipe::
2104 ::
2105 2473
2106 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" 2474 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2107 2475
2108 The dependency relationships are intended to force the package 2476 The dependency relationships are intended to force the package
2109 manager to upgrade these types of packages in lock-step. 2477 manager to upgrade these types of packages in lock-step.
2110 2478
2111 :term:`EXTERNAL_KERNEL_TOOLS` 2479 :term:`EXTERNAL_KERNEL_TOOLS`
2112 When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these 2480 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
2113 tools are not in the source tree. 2481 tools are not in the source tree.
2114 2482
2115 When kernel tools are available in the tree, they are preferred over 2483 When kernel tools are available in the tree, they are preferred over
2116 any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` 2484 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
2117 variable tells the OpenEmbedded build system to prefer the installed 2485 variable tells the OpenEmbedded build system to prefer the installed
2118 external tools. See the 2486 external tools. See the :ref:`ref-classes-kernel-yocto` class in
2119 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in 2487 ``meta/classes-recipe`` to see how the variable is used.
2120 ``meta/classes`` to see how the variable is used. 2488
2489 :term:`KERNEL_LOCALVERSION`
2490 This variable allows to append a string to the version
2491 of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION``
2492 kernel configuration parameter.
2493
2494 Using this variable is only useful when you are using a kernel recipe
2495 inheriting the :ref:`ref-classes-kernel` class, and which doesn't
2496 already set a local version. Therefore, setting this variable has no
2497 impact on ``linux-yocto`` kernels.
2498
2499 :term:`EXTERNAL_TOOLCHAIN`
2500 When you intend to use an
2501 :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`,
2502 this variable allows to specify the directory where this toolchain was
2503 installed.
2121 2504
2122 :term:`EXTERNALSRC` 2505 :term:`EXTERNALSRC`
2123 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` 2506 When inheriting the :ref:`ref-classes-externalsrc`
2124 class, this variable points to the source tree, which is outside of 2507 class, this variable points to the source tree, which is outside of
2125 the OpenEmbedded build system. When set, this variable sets the 2508 the OpenEmbedded build system. When set, this variable sets the
2126 :term:`S` variable, which is what the OpenEmbedded build 2509 :term:`S` variable, which is what the OpenEmbedded build
2127 system uses to locate unpacked recipe source code. 2510 system uses to locate unpacked recipe source code.
2128 2511
2129 For more information on ``externalsrc.bbclass``, see the 2512 See the ":ref:`ref-classes-externalsrc`" section for details. You
2130 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2131 can also find information on how to use this variable in the 2513 can also find information on how to use this variable in the
2132 ":ref:`dev-manual/common-tasks:building software from an external source`" 2514 ":ref:`dev-manual/building:building software from an external source`"
2133 section in the Yocto Project Development Tasks Manual. 2515 section in the Yocto Project Development Tasks Manual.
2134 2516
2135 :term:`EXTERNALSRC_BUILD` 2517 :term:`EXTERNALSRC_BUILD`
2136 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` 2518 When inheriting the :ref:`ref-classes-externalsrc`
2137 class, this variable points to the directory in which the recipe's 2519 class, this variable points to the directory in which the recipe's
2138 source code is built, which is outside of the OpenEmbedded build 2520 source code is built, which is outside of the OpenEmbedded build
2139 system. When set, this variable sets the :term:`B` variable, 2521 system. When set, this variable sets the :term:`B` variable,
2140 which is what the OpenEmbedded build system uses to locate the Build 2522 which is what the OpenEmbedded build system uses to locate the
2141 Directory. 2523 :term:`Build Directory`.
2142 2524
2143 For more information on ``externalsrc.bbclass``, see the 2525 See the ":ref:`ref-classes-externalsrc`" section for details. You
2144 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2145 can also find information on how to use this variable in the 2526 can also find information on how to use this variable in the
2146 ":ref:`dev-manual/common-tasks:building software from an external source`" 2527 ":ref:`dev-manual/building:building software from an external source`"
2147 section in the Yocto Project Development Tasks Manual. 2528 section in the Yocto Project Development Tasks Manual.
2148 2529
2149 :term:`EXTRA_AUTORECONF` 2530 :term:`EXTRA_AUTORECONF`
2150 For recipes inheriting the :ref:`autotools <ref-classes-autotools>` 2531 For recipes inheriting the :ref:`ref-classes-autotools`
2151 class, you can use ``EXTRA_AUTORECONF`` to specify extra options to 2532 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
2152 pass to the ``autoreconf`` command that is executed during the 2533 pass to the ``autoreconf`` command that is executed during the
2153 :ref:`ref-tasks-configure` task. 2534 :ref:`ref-tasks-configure` task.
2154 2535
@@ -2159,9 +2540,8 @@ system and gives an overview of their function and contents.
2159 more than one feature, separate them with a space. 2540 more than one feature, separate them with a space.
2160 2541
2161 Typically, you configure this variable in your ``local.conf`` file, 2542 Typically, you configure this variable in your ``local.conf`` file,
2162 which is found in the :term:`Build Directory`. 2543 which is found in the :term:`Build Directory`. Although you can use this
2163 Although you can use this variable from within a recipe, best 2544 variable from within a recipe, best practices dictate that you do not.
2164 practices dictate that you do not.
2165 2545
2166 .. note:: 2546 .. note::
2167 2547
@@ -2170,70 +2550,58 @@ system and gives an overview of their function and contents.
2170 2550
2171 Here are some examples of features you can add: 2551 Here are some examples of features you can add:
2172 2552
2173 - "dbg-pkgs" - Adds -dbg packages for all installed packages including 2553 - "dbg-pkgs" --- adds -dbg packages for all installed packages including
2174 symbol information for debugging and profiling. 2554 symbol information for debugging and profiling.
2175 2555
2176 - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and 2556 - "debug-tweaks" --- makes an image suitable for debugging. For example, allows root logins without passwords and
2177 enables post-installation logging. See the 'allow-empty-password' and 2557 enables post-installation logging. See the 'allow-empty-password' and
2178 'post-install-logging' features in the ":ref:`ref-features-image`" 2558 'post-install-logging' features in the ":ref:`ref-features-image`"
2179 section for more information. 2559 section for more information.
2180 - "dev-pkgs" - Adds -dev packages for all installed packages. This is 2560 - "dev-pkgs" --- adds -dev packages for all installed packages. This is
2181 useful if you want to develop against the libraries in the image. 2561 useful if you want to develop against the libraries in the image.
2182 - "read-only-rootfs" - Creates an image whose root filesystem is 2562 - "read-only-rootfs" --- creates an image whose root filesystem is
2183 read-only. See the 2563 read-only. See the
2184 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" 2564 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`"
2185 section in the Yocto Project Development Tasks Manual for more 2565 section in the Yocto Project Development Tasks Manual for more
2186 information 2566 information
2187 - "tools-debug" - Adds debugging tools such as gdb and strace. 2567 - "tools-debug" --- adds debugging tools such as gdb and strace.
2188 - "tools-sdk" - Adds development tools such as gcc, make, 2568 - "tools-sdk" --- adds development tools such as gcc, make,
2189 pkgconfig and so forth. 2569 pkgconfig and so forth.
2190 - "tools-testapps" - Adds useful testing tools 2570 - "tools-testapps" --- adds useful testing tools
2191 such as ts_print, aplay, arecord and so forth. 2571 such as ts_print, aplay, arecord and so forth.
2192 2572
2193 For a complete list of image features that ships with the Yocto 2573 For a complete list of image features that ships with the Yocto
2194 Project, see the ":ref:`ref-features-image`" section. 2574 Project, see the ":ref:`ref-features-image`" section.
2195 2575
2196 For an example that shows how to customize your image by using this 2576 For an example that shows how to customize your image by using this
2197 variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 2577 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
2198 section in the Yocto Project Development Tasks Manual. 2578 section in the Yocto Project Development Tasks Manual.
2199 2579
2200 :term:`EXTRA_IMAGECMD` 2580 :term:`EXTRA_IMAGECMD`
2201 Specifies additional options for the image creation command that has 2581 Specifies additional options for the image creation command that has
2202 been specified in :term:`IMAGE_CMD`. When setting 2582 been specified in :term:`IMAGE_CMD`. When setting
2203 this variable, use an override for the associated image type. Here is 2583 this variable, use an override for the associated image type. Here is
2204 an example: 2584 an example::
2205 ::
2206 2585
2207 EXTRA_IMAGECMD_ext3 ?= "-i 4096" 2586 EXTRA_IMAGECMD:ext3 ?= "-i 4096"
2208 2587
2209 :term:`EXTRA_IMAGEDEPENDS` 2588 :term:`EXTRA_IMAGEDEPENDS`
2210 A list of recipes to build that do not provide packages for 2589 A list of recipes to build that do not provide packages for
2211 installing into the root filesystem. 2590 installing into the root filesystem.
2212 2591
2213 Sometimes a recipe is required to build the final image but is not 2592 Sometimes a recipe is required to build the final image but is not
2214 needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` 2593 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
2215 variable to list these recipes and thus specify the dependencies. A 2594 variable to list these recipes and thus specify the dependencies. A
2216 typical example is a required bootloader in a machine configuration. 2595 typical example is a required bootloader in a machine configuration.
2217 2596
2218 .. note:: 2597 .. note::
2219 2598
2220 To add packages to the root filesystem, see the various 2599 To add packages to the root filesystem, see the various
2221 \*:term:`RDEPENDS` and \*:term:`RRECOMMENDS` variables. 2600 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
2222
2223 :term:`EXTRANATIVEPATH`
2224 A list of subdirectories of
2225 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2226 added to the beginning of the environment variable ``PATH``. As an
2227 example, the following prepends
2228 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2229 ``PATH``:
2230 ::
2231
2232 EXTRANATIVEPATH = "foo bar"
2233 2601
2234 :term:`EXTRA_OECMAKE` 2602 :term:`EXTRA_OECMAKE`
2235 Additional `CMake <https://cmake.org/overview/>`__ options. See the 2603 Additional `CMake <https://cmake.org/overview/>`__ options. See the
2236 :ref:`cmake <ref-classes-cmake>` class for additional information. 2604 :ref:`ref-classes-cmake` class for additional information.
2237 2605
2238 :term:`EXTRA_OECONF` 2606 :term:`EXTRA_OECONF`
2239 Additional ``configure`` script options. See 2607 Additional ``configure`` script options. See
@@ -2243,30 +2611,44 @@ system and gives an overview of their function and contents.
2243 :term:`EXTRA_OEMAKE` 2611 :term:`EXTRA_OEMAKE`
2244 Additional GNU ``make`` options. 2612 Additional GNU ``make`` options.
2245 2613
2246 Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the 2614 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
2247 variable to specify any required GNU options. 2615 variable to specify any required GNU options.
2248 2616
2249 :term:`PARALLEL_MAKE` and 2617 :term:`PARALLEL_MAKE` and
2250 :term:`PARALLEL_MAKEINST` also make use of 2618 :term:`PARALLEL_MAKEINST` also make use of
2251 ``EXTRA_OEMAKE`` to pass the required flags. 2619 :term:`EXTRA_OEMAKE` to pass the required flags.
2252 2620
2253 :term:`EXTRA_OESCONS` 2621 :term:`EXTRA_OESCONS`
2254 When inheriting the :ref:`scons <ref-classes-scons>` class, this 2622 When inheriting the :ref:`ref-classes-scons` class, this
2255 variable specifies additional configuration options you want to pass 2623 variable specifies additional configuration options you want to pass
2256 to the ``scons`` command line. 2624 to the ``scons`` command line.
2257 2625
2626 :term:`EXTRA_OEMESON`
2627 Additional `Meson <https://mesonbuild.com/>`__ options. See the
2628 :ref:`ref-classes-meson` class for additional information.
2629
2630 In addition to standard Meson options, such options correspond to
2631 `Meson build options <https://mesonbuild.com/Build-options.html>`__
2632 defined in the ``meson_options.txt`` file in the sources to build.
2633 Here is an example::
2634
2635 EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled"
2636
2637 Note that any custom value for the Meson ``--buildtype`` option
2638 should be set through the :term:`MESON_BUILDTYPE` variable.
2639
2258 :term:`EXTRA_USERS_PARAMS` 2640 :term:`EXTRA_USERS_PARAMS`
2259 When inheriting the :ref:`extrausers <ref-classes-extrausers>` 2641 When inheriting the :ref:`ref-classes-extrausers`
2260 class, this variable provides image level user and group operations. 2642 class, this variable provides image level user and group operations.
2261 This is a more global method of providing user and group 2643 This is a more global method of providing user and group
2262 configuration as compared to using the 2644 configuration as compared to using the
2263 :ref:`useradd <ref-classes-useradd>` class, which ties user and 2645 :ref:`ref-classes-useradd` class, which ties user and
2264 group configurations to a specific recipe. 2646 group configurations to a specific recipe.
2265 2647
2266 The set list of commands you can configure using the 2648 The set list of commands you can configure using the
2267 ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These 2649 :term:`EXTRA_USERS_PARAMS` is shown in the
2268 commands map to the normal Unix commands of the same names: 2650 :ref:`ref-classes-extrausers` class. These commands map to the normal
2269 :: 2651 Unix commands of the same names::
2270 2652
2271 # EXTRA_USERS_PARAMS = "\ 2653 # EXTRA_USERS_PARAMS = "\
2272 # useradd -p '' tester; \ 2654 # useradd -p '' tester; \
@@ -2277,23 +2659,92 @@ system and gives an overview of their function and contents.
2277 # usermod -s /bin/sh tester; \ 2659 # usermod -s /bin/sh tester; \
2278 # " 2660 # "
2279 2661
2662 Hardcoded passwords are supported via the ``-p`` parameters for
2663 ``useradd`` or ``usermod``, but only hashed.
2664
2665 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
2666 passwords. First on host, create the (escaped) password hash::
2667
2668 printf "%q" $(mkpasswd -m sha256crypt tester01)
2669
2670 The resulting hash is set to a variable and used in ``useradd`` command parameters::
2671
2672 inherit extrausers
2673 PASSWD = "\$X\$ABC123\$A-Long-Hash"
2674 EXTRA_USERS_PARAMS = "\
2675 useradd -p '${PASSWD}' tester-jim; \
2676 useradd -p '${PASSWD}' tester-sue; \
2677 "
2678
2679 Finally, here is an example that sets the root password::
2680
2681 inherit extrausers
2682 EXTRA_USERS_PARAMS = "\
2683 usermod -p '${PASSWD}' root; \
2684 "
2685
2686 .. note::
2687
2688 From a security perspective, hardcoding a default password is not
2689 generally a good idea or even legal in some jurisdictions. It is
2690 recommended that you do not do this if you are building a production
2691 image.
2692
2693 Additionally there is a special ``passwd-expire`` command that will
2694 cause the password for a user to be expired and thus force changing it
2695 on first login, for example::
2696
2697 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
2698
2699 .. note::
2700
2701 At present, ``passwd-expire`` may only work for remote logins when
2702 using OpenSSH and not dropbear as an SSH server.
2703
2704 :term:`EXTRANATIVEPATH`
2705 A list of subdirectories of
2706 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2707 added to the beginning of the environment variable ``PATH``. As an
2708 example, the following prepends
2709 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2710 ``PATH``::
2711
2712 EXTRANATIVEPATH = "foo bar"
2713
2714 :term:`FAKEROOT`
2715 See :term:`bitbake:FAKEROOT` in the BitBake manual.
2716
2717 :term:`FAKEROOTBASEENV`
2718 See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual.
2719
2720 :term:`FAKEROOTCMD`
2721 See :term:`bitbake:FAKEROOTCMD` in the BitBake manual.
2722
2723 :term:`FAKEROOTDIRS`
2724 See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual.
2725
2726 :term:`FAKEROOTENV`
2727 See :term:`bitbake:FAKEROOTENV` in the BitBake manual.
2728
2729 :term:`FAKEROOTNOENV`
2730 See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual.
2731
2280 :term:`FEATURE_PACKAGES` 2732 :term:`FEATURE_PACKAGES`
2281 Defines one or more packages to include in an image when a specific 2733 Defines one or more packages to include in an image when a specific
2282 item is included in :term:`IMAGE_FEATURES`. 2734 item is included in :term:`IMAGE_FEATURES`.
2283 When setting the value, ``FEATURE_PACKAGES`` should have the name of 2735 When setting the value, :term:`FEATURE_PACKAGES` should have the name of
2284 the feature item as an override. Here is an example: 2736 the feature item as an override. Here is an example::
2285 ::
2286 2737
2287 FEATURE_PACKAGES_widget = "package1 package2" 2738 FEATURE_PACKAGES_widget = "package1 package2"
2288 2739
2289 In this example, if "widget" were added to ``IMAGE_FEATURES``, 2740 In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
2290 package1 and package2 would be included in the image. 2741 package1 and package2 would be included in the image.
2291 2742
2292 .. note:: 2743 .. note::
2293 2744
2294 Packages installed by features defined through ``FEATURE_PACKAGES`` 2745 Packages installed by features defined through :term:`FEATURE_PACKAGES`
2295 are often package groups. While similarly named, you should not 2746 are often package groups. While similarly named, you should not
2296 confuse the ``FEATURE_PACKAGES`` variable with package groups, which 2747 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
2297 are discussed elsewhere in the documentation. 2748 are discussed elsewhere in the documentation.
2298 2749
2299 :term:`FEED_DEPLOYDIR_BASE_URI` 2750 :term:`FEED_DEPLOYDIR_BASE_URI`
@@ -2302,8 +2753,7 @@ system and gives an overview of their function and contents.
2302 OPKG to support runtime package management of IPK packages. You set 2753 OPKG to support runtime package management of IPK packages. You set
2303 this variable in your ``local.conf`` file. 2754 this variable in your ``local.conf`` file.
2304 2755
2305 Consider the following example: 2756 Consider the following example::
2306 ::
2307 2757
2308 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" 2758 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2309 2759
@@ -2314,37 +2764,42 @@ system and gives an overview of their function and contents.
2314 a set of configuration files for you in your target that work with 2764 a set of configuration files for you in your target that work with
2315 the feed. 2765 the feed.
2316 2766
2767 :term:`FETCHCMD`
2768 See :term:`bitbake:FETCHCMD` in the BitBake manual.
2769
2770 :term:`FILE`
2771 See :term:`bitbake:FILE` in the BitBake manual.
2772
2317 :term:`FILES` 2773 :term:`FILES`
2318 The list of files and directories that are placed in a package. The 2774 The list of files and directories that are placed in a package. The
2319 :term:`PACKAGES` variable lists the packages 2775 :term:`PACKAGES` variable lists the packages
2320 generated by a recipe. 2776 generated by a recipe.
2321 2777
2322 To use the ``FILES`` variable, provide a package name override that 2778 To use the :term:`FILES` variable, provide a package name override that
2323 identifies the resulting package. Then, provide a space-separated 2779 identifies the resulting package. Then, provide a space-separated
2324 list of files or paths that identify the files you want included as 2780 list of files or paths that identify the files you want included as
2325 part of the resulting package. Here is an example: 2781 part of the resulting package. Here is an example::
2326 ::
2327 2782
2328 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" 2783 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
2329 2784
2330 .. note:: 2785 .. note::
2331 2786
2332 - When specifying files or paths, you can pattern match using 2787 - When specifying files or paths, you can pattern match using
2333 Python's 2788 Python's
2334 `glob <https://docs.python.org/3/library/glob.html>`_ 2789 `glob <https://docs.python.org/3/library/glob.html>`__
2335 syntax. For details on the syntax, see the documentation by 2790 syntax. For details on the syntax, see the documentation by
2336 following the previous link. 2791 following the previous link.
2337 2792
2338 - When specifying paths as part of the ``FILES`` variable, it is 2793 - When specifying paths as part of the :term:`FILES` variable, it is
2339 good practice to use appropriate path variables. For example, 2794 good practice to use appropriate path variables. For example,
2340 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` 2795 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2341 rather than ``/usr/bin``. You can find a list of these 2796 rather than ``/usr/bin``. You can find a list of these
2342 variables at the top of the ``meta/conf/bitbake.conf`` file in 2797 variables at the top of the ``meta/conf/bitbake.conf`` file in
2343 the :term:`Source Directory`. You will also 2798 the :term:`Source Directory`. You will also
2344 find the default values of the various ``FILES_*`` variables in 2799 find the default values of the various ``FILES:*`` variables in
2345 this file. 2800 this file.
2346 2801
2347 If some of the files you provide with the ``FILES`` variable are 2802 If some of the files you provide with the :term:`FILES` variable are
2348 editable and you know they should not be overwritten during the 2803 editable and you know they should not be overwritten during the
2349 package update process by the Package Management System (PMS), you 2804 package update process by the Package Management System (PMS), you
2350 can identify these files so that the PMS will not overwrite them. See 2805 can identify these files so that the PMS will not overwrite them. See
@@ -2354,29 +2809,26 @@ system and gives an overview of their function and contents.
2354 :term:`FILES_SOLIBSDEV` 2809 :term:`FILES_SOLIBSDEV`
2355 Defines the file specification to match 2810 Defines the file specification to match
2356 :term:`SOLIBSDEV`. In other words, 2811 :term:`SOLIBSDEV`. In other words,
2357 ``FILES_SOLIBSDEV`` defines the full path name of the development 2812 :term:`FILES_SOLIBSDEV` defines the full path name of the development
2358 symbolic link (symlink) for shared libraries on the target platform. 2813 symbolic link (symlink) for shared libraries on the target platform.
2359 2814
2360 The following statement from the ``bitbake.conf`` shows how it is 2815 The following statement from the ``bitbake.conf`` shows how it is
2361 set: 2816 set::
2362 ::
2363 2817
2364 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" 2818 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2365 2819
2366 :term:`FILESEXTRAPATHS` 2820 :term:`FILESEXTRAPATHS`
2367 Extends the search path the OpenEmbedded build system uses when 2821 A colon-separated list to extend the search path the OpenEmbedded build
2368 looking for files and patches as it processes recipes and append 2822 system uses when looking for files and patches as it processes recipes
2369 files. The default directories BitBake uses when it processes recipes 2823 and append files. The default directories BitBake uses when it processes
2370 are initially defined by the :term:`FILESPATH` 2824 recipes are initially defined by the :term:`FILESPATH` variable. You can
2371 variable. You can extend ``FILESPATH`` variable by using 2825 extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`.
2372 ``FILESEXTRAPATHS``.
2373 2826
2374 Best practices dictate that you accomplish this by using 2827 Best practices dictate that you accomplish this by using
2375 ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you 2828 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
2376 prepend paths as follows: 2829 prepend paths as follows::
2377 ::
2378 2830
2379 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 2831 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
2380 2832
2381 In the above example, the build system first 2833 In the above example, the build system first
2382 looks for files in a directory that has the same name as the 2834 looks for files in a directory that has the same name as the
@@ -2384,7 +2836,7 @@ system and gives an overview of their function and contents.
2384 2836
2385 .. note:: 2837 .. note::
2386 2838
2387 When extending ``FILESEXTRAPATHS``, be sure to use the immediate 2839 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
2388 expansion (``:=``) operator. Immediate expansion makes sure that 2840 expansion (``:=``) operator. Immediate expansion makes sure that
2389 BitBake evaluates :term:`THISDIR` at the time the 2841 BitBake evaluates :term:`THISDIR` at the time the
2390 directive is encountered rather than at some later time when 2842 directive is encountered rather than at some later time when
@@ -2396,26 +2848,23 @@ system and gives an overview of their function and contents.
2396 are directing BitBake to extend the path by prepending directories 2848 are directing BitBake to extend the path by prepending directories
2397 to the search path. 2849 to the search path.
2398 2850
2399 Here is another common use: 2851 Here is another common use::
2400 ::
2401 2852
2402 FILESEXTRAPATHS_prepend := "${THISDIR}/files:" 2853 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
2403 2854
2404 In this example, the build system extends the 2855 In this example, the build system extends the
2405 ``FILESPATH`` variable to include a directory named ``files`` that is 2856 :term:`FILESPATH` variable to include a directory named ``files`` that is
2406 in the same directory as the corresponding append file. 2857 in the same directory as the corresponding append file.
2407 2858
2408 This next example specifically adds three paths: 2859 This next example specifically adds three paths::
2409 ::
2410 2860
2411 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" 2861 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
2412 2862
2413 A final example shows how you can extend the search path and include 2863 A final example shows how you can extend the search path and include
2414 a :term:`MACHINE`-specific override, which is useful 2864 a :term:`MACHINE`-specific override, which is useful
2415 in a BSP layer: 2865 in a BSP layer::
2416 ::
2417 2866
2418 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" 2867 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
2419 2868
2420 The previous statement appears in the 2869 The previous statement appears in the
2421 ``linux-yocto-dev.bbappend`` file, which is found in the 2870 ``linux-yocto-dev.bbappend`` file, which is found in the
@@ -2427,83 +2876,78 @@ system and gives an overview of their function and contents.
2427 .. note:: 2876 .. note::
2428 2877
2429 For a layer that supports a single BSP, the override could just be 2878 For a layer that supports a single BSP, the override could just be
2430 the value of ``MACHINE``. 2879 the value of :term:`MACHINE`.
2431 2880
2432 By prepending paths in ``.bbappend`` files, you allow multiple append 2881 By prepending paths in ``.bbappend`` files, you allow multiple append
2433 files that reside in different layers but are used for the same 2882 files that reside in different layers but are used for the same
2434 recipe to correctly extend the path. 2883 recipe to correctly extend the path.
2435 2884
2436 :term:`FILESOVERRIDES` 2885 :term:`FILESOVERRIDES`
2437 A subset of :term:`OVERRIDES` used by the 2886 A colon-separated list to specify a subset of :term:`OVERRIDES` used by
2438 OpenEmbedded build system for creating 2887 the OpenEmbedded build system for creating :term:`FILESPATH`. The
2439 :term:`FILESPATH`. The ``FILESOVERRIDES`` variable 2888 :term:`FILESOVERRIDES` variable uses overrides to automatically extend
2440 uses overrides to automatically extend the 2889 the :term:`FILESPATH` variable. For an example of how that works, see the
2441 :term:`FILESPATH` variable. For an example of how 2890 :term:`FILESPATH` variable description. Additionally, you find more
2442 that works, see the :term:`FILESPATH` variable 2891 information on how overrides are handled in the
2443 description. Additionally, you find more information on how overrides 2892 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2444 are handled in the
2445 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2446 section of the BitBake User Manual. 2893 section of the BitBake User Manual.
2447 2894
2448 By default, the ``FILESOVERRIDES`` variable is defined as: 2895 By default, the :term:`FILESOVERRIDES` variable is defined as::
2449 ::
2450 2896
2451 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" 2897 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2452 2898
2453 .. note:: 2899 .. note::
2454 2900
2455 Do not hand-edit the ``FILESOVERRIDES`` variable. The values match up 2901 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
2456 with expected overrides and are used in an expected manner by the 2902 with expected overrides and are used in an expected manner by the
2457 build system. 2903 build system.
2458 2904
2459 :term:`FILESPATH` 2905 :term:`FILESPATH`
2460 The default set of directories the OpenEmbedded build system uses 2906 A colon-separated list specifying the default set of directories the
2461 when searching for patches and files. 2907 OpenEmbedded build system uses when searching for patches and files.
2462 2908
2463 During the build process, BitBake searches each directory in 2909 During the build process, BitBake searches each directory in
2464 ``FILESPATH`` in the specified order when looking for files and 2910 :term:`FILESPATH` in the specified order when looking for files and
2465 patches specified by each ``file://`` URI in a recipe's 2911 patches specified by each ``file://`` URI in a recipe's
2466 :term:`SRC_URI` statements. 2912 :term:`SRC_URI` statements.
2467 2913
2468 The default value for the ``FILESPATH`` variable is defined in the 2914 The default value for the :term:`FILESPATH` variable is defined in the
2469 ``base.bbclass`` class found in ``meta/classes`` in the 2915 :ref:`ref-classes-base` class found in ``meta/classes-global`` in the
2470 :term:`Source Directory`: 2916 :term:`Source Directory`::
2471 ::
2472 2917
2473 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ 2918 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2474 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" 2919 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2475 2920
2476 The 2921 The
2477 ``FILESPATH`` variable is automatically extended using the overrides 2922 :term:`FILESPATH` variable is automatically extended using the overrides
2478 from the :term:`FILESOVERRIDES` variable. 2923 from the :term:`FILESOVERRIDES` variable.
2479 2924
2480 .. note:: 2925 .. note::
2481 2926
2482 - Do not hand-edit the ``FILESPATH`` variable. If you want the 2927 - Do not hand-edit the :term:`FILESPATH` variable. If you want the
2483 build system to look in directories other than the defaults, 2928 build system to look in directories other than the defaults,
2484 extend the ``FILESPATH`` variable by using the 2929 extend the :term:`FILESPATH` variable by using the
2485 :term:`FILESEXTRAPATHS` variable. 2930 :term:`FILESEXTRAPATHS` variable.
2486 2931
2487 - Be aware that the default ``FILESPATH`` directories do not map 2932 - Be aware that the default :term:`FILESPATH` directories do not map
2488 to directories in custom layers where append files 2933 to directories in custom layers where append files
2489 (``.bbappend``) are used. If you want the build system to find 2934 (``.bbappend``) are used. If you want the build system to find
2490 patches or files that reside with your append files, you need 2935 patches or files that reside with your append files, you need
2491 to extend the ``FILESPATH`` variable by using the 2936 to extend the :term:`FILESPATH` variable by using the
2492 ``FILESEXTRAPATHS`` variable. 2937 :term:`FILESEXTRAPATHS` variable.
2493 2938
2494 You can take advantage of this searching behavior in useful ways. For 2939 You can take advantage of this searching behavior in useful ways. For
2495 example, consider a case where the following directory structure 2940 example, consider a case where there is the following directory structure
2496 exists for general and machine-specific configurations: 2941 for general and machine-specific configurations::
2497 ::
2498 2942
2499 files/defconfig 2943 files/defconfig
2500 files/MACHINEA/defconfig 2944 files/MACHINEA/defconfig
2501 files/MACHINEB/defconfig 2945 files/MACHINEB/defconfig
2502 2946
2503 Also in the example, the ``SRC_URI`` statement contains 2947 Also in the example, the :term:`SRC_URI` statement contains
2504 "file://defconfig". Given this scenario, you can set 2948 "file://defconfig". Given this scenario, you can set
2505 :term:`MACHINE` to "MACHINEA" and cause the build 2949 :term:`MACHINE` to "MACHINEA" and cause the build
2506 system to use files from ``files/MACHINEA``. Set ``MACHINE`` to 2950 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
2507 "MACHINEB" and the build system uses files from ``files/MACHINEB``. 2951 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2508 Finally, for any machine other than "MACHINEA" and "MACHINEB", the 2952 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2509 build system uses files from ``files/defconfig``. 2953 build system uses files from ``files/defconfig``.
@@ -2511,7 +2955,7 @@ system and gives an overview of their function and contents.
2511 You can find out more about the patching process in the 2955 You can find out more about the patching process in the
2512 ":ref:`overview-manual/concepts:patching`" section 2956 ":ref:`overview-manual/concepts:patching`" section
2513 in the Yocto Project Overview and Concepts Manual and the 2957 in the Yocto Project Overview and Concepts Manual and the
2514 ":ref:`dev-manual/common-tasks:patching code`" section in 2958 ":ref:`dev-manual/new-recipe:patching code`" section in
2515 the Yocto Project Development Tasks Manual. See the 2959 the Yocto Project Development Tasks Manual. See the
2516 :ref:`ref-tasks-patch` task as well. 2960 :ref:`ref-tasks-patch` task as well.
2517 2961
@@ -2528,69 +2972,121 @@ system and gives an overview of their function and contents.
2528 permissions setting table, you should place it in your layer or the 2972 permissions setting table, you should place it in your layer or the
2529 distro's layer. 2973 distro's layer.
2530 2974
2531 You define the ``FILESYSTEM_PERMS_TABLES`` variable in the 2975 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
2532 ``conf/local.conf`` file, which is found in the :term:`Build Directory`, 2976 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2533 to point to your custom 2977 to point to your custom ``fs-perms.txt``. You can specify more than a
2534 ``fs-perms.txt``. You can specify more than a single file permissions 2978 single file permissions setting table. The paths you specify to these
2535 setting table. The paths you specify to these files must be defined 2979 files must be defined within the :term:`BBPATH` variable.
2536 within the :term:`BBPATH` variable.
2537 2980
2538 For guidance on how to create your own file permissions settings 2981 For guidance on how to create your own file permissions settings
2539 table file, examine the existing ``fs-perms.txt``. 2982 table file, examine the existing ``fs-perms.txt``.
2540 2983
2984 :term:`FIT_ADDRESS_CELLS`
2985 Specifies the value of the ``#address-cells`` value for the
2986 description of the FIT image.
2987
2988 The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage`
2989 class, which corresponds to 32 bit addresses.
2990
2991 For platforms that need to set 64 bit addresses, for example in
2992 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
2993 set this value to "2", as two 32 bit values (cells) will be needed
2994 to represent such addresses.
2995
2996 Here is an example setting "0x400000000" as a load address::
2997
2998 FIT_ADDRESS_CELLS = "2"
2999 UBOOT_LOADADDRESS= "0x04 0x00000000"
3000
3001 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
3002
3003 :term:`FIT_CONF_DEFAULT_DTB`
3004 Specifies the default device tree binary (dtb) file for a FIT image
3005 when multiple ones are provided.
3006
3007 This variable is used in the :ref:`ref-classes-kernel-fitimage` class.
3008
2541 :term:`FIT_DESC` 3009 :term:`FIT_DESC`
2542 Specifies the description string encoded into a fitImage. The default 3010 Specifies the description string encoded into a FIT image. The
2543 value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` 3011 default value is set by the :ref:`ref-classes-kernel-fitimage` class as
2544 class as follows:: 3012 follows::
2545 3013
2546 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" 3014 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
2547 3015
2548 :term:`FIT_GENERATE_KEYS` 3016 :term:`FIT_GENERATE_KEYS`
2549 Decides whether to generate the keys for signing fitImage if they 3017 Decides whether to generate the keys for signing the FIT image if
2550 don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``. 3018 they don't already exist. The keys are created in
2551 The default value is 0. 3019 :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0"
3020 by the :ref:`ref-classes-kernel-fitimage` class.
2552 3021
2553 :term:`FIT_HASH_ALG` 3022 :term:`FIT_HASH_ALG`
2554 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. 3023 Specifies the hash algorithm used in creating the FIT Image.
3024 This variable is set by default to "sha256" by the
3025 :ref:`ref-classes-kernel-fitimage` class.
3026
3027 :term:`FIT_KERNEL_COMP_ALG`
3028 The compression algorithm to use for the kernel image inside the FIT Image.
3029 At present, the only supported values are "gzip" (default), "lzo" or "none".
3030 If you set this variable to anything other than "none" you may also need
3031 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
3032
3033 This variable is used in the :ref:`ref-classes-kernel-uboot` class.
3034
3035 :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
3036 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
3037 value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you
3038 set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this
3039 variable to ".lzo".
2555 3040
2556 :term:`FIT_KEY_GENRSA_ARGS` 3041 :term:`FIT_KEY_GENRSA_ARGS`
2557 Arguments to openssl genrsa for generating RSA private key for signing 3042 Arguments to ``openssl genrsa`` for generating a RSA private key for
2558 fitImage. The default value is "-F4". i.e. the public exponent 65537 to 3043 signing the FIT image. The default value is set to "-F4" by the
2559 use. 3044 :ref:`ref-classes-kernel-fitimage` class.
2560 3045
2561 :term:`FIT_KEY_REQ_ARGS` 3046 :term:`FIT_KEY_REQ_ARGS`
2562 Arguments to openssl req for generating certificate for signing fitImage. 3047 Arguments to ``openssl req`` for generating a certificate for signing
2563 The default value is "-batch -new". batch for non interactive mode 3048 the FIT image. The default value is "-batch -new" by the
2564 and new for generating new keys. 3049 :ref:`ref-classes-kernel-fitimage` class, "batch" for
3050 non interactive mode and "new" for generating new keys.
2565 3051
2566 :term:`FIT_KEY_SIGN_PKCS` 3052 :term:`FIT_KEY_SIGN_PKCS`
2567 Format for public key ceritifcate used in signing fitImage. 3053 Format for the public key certificate used for signing the FIT image.
2568 The default value is "x509". 3054 The default value is set to "x509" by the
3055 :ref:`ref-classes-kernel-fitimage` class.
2569 3056
2570 :term:`FIT_SIGN_ALG` 3057 :term:`FIT_SIGN_ALG`
2571 Specifies the signature algorithm used in creating the FIT Image. 3058 Specifies the signature algorithm used in creating the FIT Image.
2572 For e.g. rsa2048. 3059 This variable is set by default to "rsa2048" by the
3060 :ref:`ref-classes-kernel-fitimage` class.
2573 3061
2574 :term:`FIT_SIGN_NUMBITS` 3062 :term:`FIT_PAD_ALG`
2575 Size of private key in number of bits used in fitImage. The default 3063 Specifies the padding algorithm used in creating the FIT Image.
2576 value is "2048". 3064 The default value is set to "pkcs-1.5" by the
3065 :ref:`ref-classes-kernel-fitimage` class.
2577 3066
2578 :term:`FIT_SIGN_INDIVIDUAL` 3067 :term:`FIT_SIGN_INDIVIDUAL`
2579 If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` 3068 If set to "1", then the :ref:`ref-classes-kernel-fitimage`
2580 class will sign the kernel, dtb and ramdisk images individually in addition 3069 class will sign the kernel, dtb and ramdisk images individually in addition
2581 to signing the fitImage itself. This could be useful if you are 3070 to signing the FIT image itself. This could be useful if you are
2582 intending to verify signatures in another context than booting via 3071 intending to verify signatures in another context than booting via
2583 U-Boot. 3072 U-Boot.
2584 3073
3074 This variable is set to "0" by default.
3075
3076 :term:`FIT_SIGN_NUMBITS`
3077 Size of the private key used in the FIT image, in number of bits.
3078 The default value for this variable is set to "2048"
3079 by the :ref:`ref-classes-kernel-fitimage` class.
3080
2585 :term:`FONT_EXTRA_RDEPENDS` 3081 :term:`FONT_EXTRA_RDEPENDS`
2586 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, 3082 When inheriting the :ref:`ref-classes-fontcache` class,
2587 this variable specifies the runtime dependencies for font packages. 3083 this variable specifies the runtime dependencies for font packages.
2588 By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". 3084 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
2589 3085
2590 :term:`FONT_PACKAGES` 3086 :term:`FONT_PACKAGES`
2591 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, 3087 When inheriting the :ref:`ref-classes-fontcache` class, this variable
2592 this variable identifies packages containing font files that need to 3088 identifies packages containing font files that need to be cached by
2593 be cached by Fontconfig. By default, the ``fontcache`` class assumes 3089 Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes
2594 that fonts are in the recipe's main package (i.e. 3090 that fonts are in the recipe's main package (i.e.
2595 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you 3091 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
2596 need are in a package other than that main package. 3092 need are in a package other than that main package.
@@ -2602,7 +3098,7 @@ system and gives an overview of their function and contents.
2602 Set the variable to "1" to force the removal of these packages. 3098 Set the variable to "1" to force the removal of these packages.
2603 3099
2604 :term:`FULL_OPTIMIZATION` 3100 :term:`FULL_OPTIMIZATION`
2605 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when 3101 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
2606 compiling an optimized system. This variable defaults to "-O2 -pipe 3102 compiling an optimized system. This variable defaults to "-O2 -pipe
2607 ${DEBUG_FLAGS}". 3103 ${DEBUG_FLAGS}".
2608 3104
@@ -2612,16 +3108,14 @@ system and gives an overview of their function and contents.
2612 Programming (ROP) attacks much more difficult to execute. 3108 Programming (ROP) attacks much more difficult to execute.
2613 3109
2614 By default the ``security_flags.inc`` file enables PIE by setting the 3110 By default the ``security_flags.inc`` file enables PIE by setting the
2615 variable as follows: 3111 variable as follows::
2616 ::
2617 3112
2618 GCCPIE ?= "--enable-default-pie" 3113 GCCPIE ?= "--enable-default-pie"
2619 3114
2620 :term:`GCCVERSION` 3115 :term:`GCCVERSION`
2621 Specifies the default version of the GNU C Compiler (GCC) used for 3116 Specifies the default version of the GNU C Compiler (GCC) used for
2622 compilation. By default, ``GCCVERSION`` is set to "8.x" in the 3117 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
2623 ``meta/conf/distro/include/tcmode-default.inc`` include file: 3118 ``meta/conf/distro/include/tcmode-default.inc`` include file::
2624 ::
2625 3119
2626 GCCVERSION ?= "8.%" 3120 GCCVERSION ?= "8.%"
2627 3121
@@ -2631,10 +3125,24 @@ system and gives an overview of their function and contents.
2631 :term:`GDB` 3125 :term:`GDB`
2632 The minimal command and arguments to run the GNU Debugger. 3126 The minimal command and arguments to run the GNU Debugger.
2633 3127
3128 :term:`GIR_EXTRA_LIBS_PATH`
3129 Allows to specify an extra search path for ``.so`` files
3130 in GLib related recipes using GObject introspection,
3131 and which do not compile without this setting.
3132 See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`"
3133 section for details.
3134
2634 :term:`GITDIR` 3135 :term:`GITDIR`
2635 The directory in which a local copy of a Git repository is stored 3136 The directory in which a local copy of a Git repository is stored
2636 when it is cloned. 3137 when it is cloned.
2637 3138
3139 :term:`GITHUB_BASE_URI`
3140 When inheriting the :ref:`ref-classes-github-releases`
3141 class, specifies the base URL for fetching releases for the github
3142 project you wish to fetch sources from. The default value is as follows::
3143
3144 GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/"
3145
2638 :term:`GLIBC_GENERATE_LOCALES` 3146 :term:`GLIBC_GENERATE_LOCALES`
2639 Specifies the list of GLIBC locales to generate should you not wish 3147 Specifies the list of GLIBC locales to generate should you not wish
2640 to generate all LIBC locals, which can be time consuming. 3148 to generate all LIBC locals, which can be time consuming.
@@ -2644,28 +3152,101 @@ system and gives an overview of their function and contents.
2644 If you specifically remove the locale ``en_US.UTF-8``, you must set 3152 If you specifically remove the locale ``en_US.UTF-8``, you must set
2645 :term:`IMAGE_LINGUAS` appropriately. 3153 :term:`IMAGE_LINGUAS` appropriately.
2646 3154
2647 You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. 3155 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
2648 By default, all locales are generated. 3156 By default, all locales are generated::
2649 ::
2650 3157
2651 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" 3158 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
2652 3159
3160 :term:`GO_IMPORT`
3161 When inheriting the :ref:`ref-classes-go` class, this mandatory variable
3162 sets the import path for the Go package that will be created for the code
3163 to build. If you have a ``go.mod`` file in the source directory, this
3164 typically matches the path in the ``module`` line in this file.
3165
3166 Other Go programs importing this package will use this path.
3167
3168 Here is an example setting from the
3169 :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
3170 recipe::
3171
3172 GO_IMPORT = "golang.org/x/example"
3173
3174 :term:`GO_INSTALL`
3175 When inheriting the :ref:`ref-classes-go` class, this optional variable
3176 specifies which packages in the sources should be compiled and
3177 installed in the Go build space by the
3178 `go install <https://go.dev/ref/mod#go-install>`__ command.
3179
3180 Here is an example setting from the
3181 :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>`
3182 recipe::
3183
3184 GO_INSTALL = "\
3185 ${GO_IMPORT}/cmd/crucible \
3186 ${GO_IMPORT}/cmd/habtool \
3187 "
3188
3189 By default, :term:`GO_INSTALL` is defined as::
3190
3191 GO_INSTALL ?= "${GO_IMPORT}/..."
3192
3193 The ``...`` wildcard means that it will catch all
3194 packages found in the sources.
3195
3196 See the :term:`GO_INSTALL_FILTEROUT` variable for
3197 filtering out unwanted packages from the ones
3198 found from the :term:`GO_INSTALL` value.
3199
3200 :term:`GO_INSTALL_FILTEROUT`
3201 When using the Go "vendor" mechanism to bring in dependencies for a Go
3202 package, the default :term:`GO_INSTALL` setting, which uses the ``...``
3203 wildcard, will include the vendored packages in the build, which produces
3204 incorrect results.
3205
3206 There are also some Go packages that are structured poorly, so that the
3207 ``...`` wildcard results in building example or test code that should not
3208 be included in the build, or could fail to build.
3209
3210 This optional variable allows for filtering out a subset of the sources.
3211 It defaults to excluding everything under the ``vendor`` subdirectory
3212 under package's main directory. This is the normal location for vendored
3213 packages, but it can be overridden by a recipe to filter out other
3214 subdirectories if needed.
3215
3216 :term:`GO_WORKDIR`
3217 When using Go Modules, the current working directory must be the directory
3218 containing the ``go.mod`` file, or one of its subdirectories. When the
3219 ``go`` tool is used, it will automatically look for the ``go.mod`` file
3220 in the Go working directory or in any parent directory, but not in
3221 subdirectories.
3222
3223 When using the :ref:`ref-classes-go-mod` class to use Go modules,
3224 the optional :term:`GO_WORKDIR` variable, defaulting to the value
3225 of :term:`GO_IMPORT`, allows to specify a different Go working directory.
3226
2653 :term:`GROUPADD_PARAM` 3227 :term:`GROUPADD_PARAM`
2654 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 3228 When inheriting the :ref:`ref-classes-useradd` class,
2655 this variable specifies for a package what parameters should be 3229 this variable specifies for a package what parameters should be
2656 passed to the ``groupadd`` command if you wish to add a group to the 3230 passed to the ``groupadd`` command if you wish to add a group to the
2657 system when the package is installed. 3231 system when the package is installed.
2658 3232
2659 Here is an example from the ``dbus`` recipe: 3233 Here is an example from the ``dbus`` recipe::
2660 :: 3234
3235 GROUPADD_PARAM:${PN} = "-r netdev"
3236
3237 More than one group can be added by separating each set of different
3238 groups' parameters with a semicolon.
2661 3239
2662 GROUPADD_PARAM_${PN} = "-r netdev" 3240 Here is an example adding multiple groups from the ``useradd-example.bb``
3241 file in the ``meta-skeleton`` layer::
3242
3243 GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2"
2663 3244
2664 For information on the standard Linux shell command 3245 For information on the standard Linux shell command
2665 ``groupadd``, see https://linux.die.net/man/8/groupadd. 3246 ``groupadd``, see https://linux.die.net/man/8/groupadd.
2666 3247
2667 :term:`GROUPMEMS_PARAM` 3248 :term:`GROUPMEMS_PARAM`
2668 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 3249 When inheriting the :ref:`ref-classes-useradd` class,
2669 this variable specifies for a package what parameters should be 3250 this variable specifies for a package what parameters should be
2670 passed to the ``groupmems`` command if you wish to modify the members 3251 passed to the ``groupmems`` command if you wish to modify the members
2671 of a group when the package is installed. 3252 of a group when the package is installed.
@@ -2679,7 +3260,7 @@ system and gives an overview of their function and contents.
2679 ``local.conf`` or distribution configuration file to enable graphics 3260 ``local.conf`` or distribution configuration file to enable graphics
2680 and serial in the menu. 3261 and serial in the menu.
2681 3262
2682 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 3263 See the :ref:`ref-classes-grub-efi` class for more
2683 information on how this variable is used. 3264 information on how this variable is used.
2684 3265
2685 :term:`GRUB_OPTS` 3266 :term:`GRUB_OPTS`
@@ -2687,25 +3268,27 @@ system and gives an overview of their function and contents.
2687 configuration. Use a semi-colon character (``;``) to separate 3268 configuration. Use a semi-colon character (``;``) to separate
2688 multiple options. 3269 multiple options.
2689 3270
2690 The ``GRUB_OPTS`` variable is optional. See the 3271 The :term:`GRUB_OPTS` variable is optional. See the
2691 :ref:`grub-efi <ref-classes-grub-efi>` class for more information 3272 :ref:`ref-classes-grub-efi` class for more information
2692 on how this variable is used. 3273 on how this variable is used.
2693 3274
2694 :term:`GRUB_TIMEOUT` 3275 :term:`GRUB_TIMEOUT`
2695 Specifies the timeout before executing the default ``LABEL`` in the 3276 Specifies the timeout before executing the default ``LABEL`` in the
2696 GNU GRand Unified Bootloader (GRUB). 3277 GNU GRand Unified Bootloader (GRUB).
2697 3278
2698 The ``GRUB_TIMEOUT`` variable is optional. See the 3279 The :term:`GRUB_TIMEOUT` variable is optional. See the
2699 :ref:`grub-efi <ref-classes-grub-efi>` class for more information 3280 :ref:`ref-classes-grub-efi` class for more information
2700 on how this variable is used. 3281 on how this variable is used.
2701 3282
2702 :term:`GTKIMMODULES_PACKAGES` 3283 :term:`GTKIMMODULES_PACKAGES`
2703 When inheriting the 3284 When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
2704 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
2705 this variable specifies the packages that contain the GTK+ input 3285 this variable specifies the packages that contain the GTK+ input
2706 method modules being installed when the modules are in packages other 3286 method modules being installed when the modules are in packages other
2707 than the main package. 3287 than the main package.
2708 3288
3289 :term:`HGDIR`
3290 See :term:`bitbake:HGDIR` in the BitBake manual.
3291
2709 :term:`HOMEPAGE` 3292 :term:`HOMEPAGE`
2710 Website where more information about the software the recipe is 3293 Website where more information about the software the recipe is
2711 building can be found. 3294 building can be found.
@@ -2729,7 +3312,7 @@ system and gives an overview of their function and contents.
2729 Specifies architecture-specific compiler flags that are passed to the 3312 Specifies architecture-specific compiler flags that are passed to the
2730 C compiler. 3313 C compiler.
2731 3314
2732 Default initialization for ``HOST_CC_ARCH`` varies depending on what 3315 Default initialization for :term:`HOST_CC_ARCH` varies depending on what
2733 is being built: 3316 is being built:
2734 3317
2735 - :term:`TARGET_CC_ARCH` when building for the 3318 - :term:`TARGET_CC_ARCH` when building for the
@@ -2749,7 +3332,7 @@ system and gives an overview of their function and contents.
2749 "linux-musleabi" values possible. 3332 "linux-musleabi" values possible.
2750 3333
2751 :term:`HOST_PREFIX` 3334 :term:`HOST_PREFIX`
2752 Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` 3335 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
2753 is normally the same as :term:`TARGET_PREFIX`. 3336 is normally the same as :term:`TARGET_PREFIX`.
2754 3337
2755 :term:`HOST_SYS` 3338 :term:`HOST_SYS`
@@ -2774,11 +3357,15 @@ system and gives an overview of their function and contents.
2774 - Given a recipe being built for a little-endian MIPS target running 3357 - Given a recipe being built for a little-endian MIPS target running
2775 Linux, the value might be "mipsel-linux". 3358 Linux, the value might be "mipsel-linux".
2776 3359
3360 :term:`HOST_VENDOR`
3361 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
3362 same as :term:`TARGET_VENDOR`.
3363
2777 :term:`HOSTTOOLS` 3364 :term:`HOSTTOOLS`
2778 A space-separated list (filter) of tools on the build host that 3365 A space-separated list (filter) of tools on the build host that
2779 should be allowed to be called from within build tasks. Using this 3366 should be allowed to be called from within build tasks. Using this
2780 filter helps reduce the possibility of host contamination. If a tool 3367 filter helps reduce the possibility of host contamination. If a tool
2781 specified in the value of ``HOSTTOOLS`` is not found on the build 3368 specified in the value of :term:`HOSTTOOLS` is not found on the build
2782 host, the OpenEmbedded build system produces an error and the build 3369 host, the OpenEmbedded build system produces an error and the build
2783 is not started. 3370 is not started.
2784 3371
@@ -2791,39 +3378,45 @@ system and gives an overview of their function and contents.
2791 filter helps reduce the possibility of host contamination. Unlike 3378 filter helps reduce the possibility of host contamination. Unlike
2792 :term:`HOSTTOOLS`, the OpenEmbedded build system 3379 :term:`HOSTTOOLS`, the OpenEmbedded build system
2793 does not produce an error if a tool specified in the value of 3380 does not produce an error if a tool specified in the value of
2794 ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can 3381 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
2795 use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. 3382 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
2796 3383
2797 :term:`HOST_VENDOR` 3384 :term:`ICECC_CLASS_DISABLE`
2798 Specifies the name of the vendor. ``HOST_VENDOR`` is normally the 3385 Identifies user classes that you do not want the Icecream distributed
2799 same as :term:`TARGET_VENDOR`. 3386 compile support to consider. This variable is used by the
3387 :ref:`ref-classes-icecc` class. You set this variable in
3388 your ``local.conf`` file.
3389
3390 When you list classes using this variable, the recipes inheriting
3391 those classes will not benefit from distributed compilation across
3392 remote hosts. Instead they will be built locally.
2800 3393
2801 :term:`ICECC_DISABLED` 3394 :term:`ICECC_DISABLED`
2802 Disables or enables the ``icecc`` (Icecream) function. For more 3395 Disables or enables the ``icecc`` (Icecream) function. For more
2803 information on this function and best practices for using this 3396 information on this function and best practices for using this
2804 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" 3397 variable, see the ":ref:`ref-classes-icecc`"
2805 section. 3398 section.
2806 3399
2807 Setting this variable to "1" in your ``local.conf`` disables the 3400 Setting this variable to "1" in your ``local.conf`` disables the
2808 function: 3401 function::
2809 ::
2810 3402
2811 ICECC_DISABLED ??= "1" 3403 ICECC_DISABLED ??= "1"
2812 3404
2813 To enable the function, set the variable as follows: 3405 To enable the function, set the variable as follows::
2814 ::
2815 3406
2816 ICECC_DISABLED = "" 3407 ICECC_DISABLED = ""
2817 3408
2818 :term:`ICECC_ENV_EXEC` 3409 :term:`ICECC_ENV_EXEC`
2819 Points to the ``icecc-create-env`` script that you provide. This 3410 Points to the ``icecc-create-env`` script that you provide. This
2820 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You 3411 variable is used by the :ref:`ref-classes-icecc` class. You
2821 set this variable in your ``local.conf`` file. 3412 set this variable in your ``local.conf`` file.
2822 3413
2823 If you do not point to a script that you provide, the OpenEmbedded 3414 If you do not point to a script that you provide, the OpenEmbedded
2824 build system uses the default script provided by the 3415 build system uses the default script provided by the
2825 ``icecc-create-env.bb`` recipe, which is a modified version and not 3416 :oe_git:`icecc-create-env_0.1.bb
2826 the one that comes with ``icecc``. 3417 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`
3418 recipe, which is a modified version and not the one that comes with
3419 ``icecream``.
2827 3420
2828 :term:`ICECC_PARALLEL_MAKE` 3421 :term:`ICECC_PARALLEL_MAKE`
2829 Extra options passed to the ``make`` command during the 3422 Extra options passed to the ``make`` command during the
@@ -2842,87 +3435,41 @@ system and gives an overview of their function and contents.
2842 network lag, available memory, and existing machine loads can all 3435 network lag, available memory, and existing machine loads can all
2843 affect build time. Consequently, unlike the 3436 affect build time. Consequently, unlike the
2844 :term:`PARALLEL_MAKE` variable, there is no 3437 :term:`PARALLEL_MAKE` variable, there is no
2845 rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal 3438 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
2846 performance. 3439 performance.
2847 3440
2848 If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not 3441 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
2849 use it (i.e. the system does not detect and assign the number of 3442 use it (i.e. the system does not detect and assign the number of
2850 cores as is done with ``PARALLEL_MAKE``). 3443 cores as is done with :term:`PARALLEL_MAKE`).
2851 3444
2852 :term:`ICECC_PATH` 3445 :term:`ICECC_PATH`
2853 The location of the ``icecc`` binary. You can set this variable in 3446 The location of the ``icecc`` binary. You can set this variable in
2854 your ``local.conf`` file. If your ``local.conf`` file does not define 3447 your ``local.conf`` file. If your ``local.conf`` file does not define
2855 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts 3448 this variable, the :ref:`ref-classes-icecc` class attempts
2856 to define it by locating ``icecc`` using ``which``. 3449 to define it by locating ``icecc`` using ``which``.
2857 3450
2858 :term:`ICECC_USER_CLASS_BL` 3451 :term:`ICECC_RECIPE_DISABLE`
2859 Identifies user classes that you do not want the Icecream distributed
2860 compile support to consider. This variable is used by the
2861 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2862 your ``local.conf`` file.
2863
2864 When you list classes using this variable, you are "blacklisting"
2865 them from distributed compilation across remote hosts. Any classes
2866 you list will be distributed and compiled locally.
2867
2868 :term:`ICECC_USER_PACKAGE_BL`
2869 Identifies user recipes that you do not want the Icecream distributed 3452 Identifies user recipes that you do not want the Icecream distributed
2870 compile support to consider. This variable is used by the 3453 compile support to consider. This variable is used by the
2871 :ref:`icecc <ref-classes-icecc>` class. You set this variable in 3454 :ref:`ref-classes-icecc` class. You set this variable in
2872 your ``local.conf`` file. 3455 your ``local.conf`` file.
2873 3456
2874 When you list packages using this variable, you are "blacklisting" 3457 When you list recipes using this variable, you are excluding them
2875 them from distributed compilation across remote hosts. Any packages 3458 from distributed compilation across remote hosts. Instead they will
2876 you list will be distributed and compiled locally. 3459 be built locally.
2877 3460
2878 :term:`ICECC_USER_PACKAGE_WL` 3461 :term:`ICECC_RECIPE_ENABLE`
2879 Identifies user recipes that use an empty 3462 Identifies user recipes that use an empty
2880 :term:`PARALLEL_MAKE` variable that you want to 3463 :term:`PARALLEL_MAKE` variable that you want to
2881 force remote distributed compilation on using the Icecream 3464 force remote distributed compilation on using the Icecream
2882 distributed compile support. This variable is used by the 3465 distributed compile support. This variable is used by the
2883 :ref:`icecc <ref-classes-icecc>` class. You set this variable in 3466 :ref:`ref-classes-icecc` class. You set this variable in
2884 your ``local.conf`` file. 3467 your ``local.conf`` file.
2885 3468
2886 :term:`IMAGE_BASENAME` 3469 :term:`IMAGE_BASENAME`
2887 The base name of image output files. This variable defaults to the 3470 The base name of image output files. This variable defaults to the
2888 recipe name (``${``\ :term:`PN`\ ``}``). 3471 recipe name (``${``\ :term:`PN`\ ``}``).
2889 3472
2890 :term:`IMAGE_EFI_BOOT_FILES`
2891 A space-separated list of files installed into the boot partition
2892 when preparing an image using the Wic tool with the
2893 ``bootimg-efi`` source plugin. By default,
2894 the files are
2895 installed under the same name as the source files. To change the
2896 installed name, separate it from the original name with a semi-colon
2897 (;). Source files need to be located in
2898 :term:`DEPLOY_DIR_IMAGE`. Here are two
2899 examples:
2900 ::
2901
2902 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
2903 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
2904
2905 Alternatively, source files can be picked up using a glob pattern. In
2906 this case, the destination file must have the same name as the base
2907 name of the source file path. To install files into a directory
2908 within the target location, pass its name after a semi-colon (;).
2909 Here are two examples:
2910 ::
2911
2912 IMAGE_EFI_BOOT_FILES = "boot/loader/*"
2913 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
2914
2915 The first example
2916 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
2917 into the root of the target partition. The second example installs
2918 the same files into a ``boot`` directory within the target partition.
2919
2920 You can find information on how to use the Wic tool in the
2921 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
2922 section of the Yocto Project Development Tasks Manual. Reference
2923 material for Wic is located in the
2924 ":doc:`/ref-manual/kickstart`" chapter.
2925
2926 :term:`IMAGE_BOOT_FILES` 3473 :term:`IMAGE_BOOT_FILES`
2927 A space-separated list of files installed into the boot partition 3474 A space-separated list of files installed into the boot partition
2928 when preparing an image using the Wic tool with the 3475 when preparing an image using the Wic tool with the
@@ -2932,8 +3479,7 @@ system and gives an overview of their function and contents.
2932 installed name, separate it from the original name with a semi-colon 3479 installed name, separate it from the original name with a semi-colon
2933 (;). Source files need to be located in 3480 (;). Source files need to be located in
2934 :term:`DEPLOY_DIR_IMAGE`. Here are two 3481 :term:`DEPLOY_DIR_IMAGE`. Here are two
2935 examples: 3482 examples::
2936 ::
2937 3483
2938 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" 3484 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2939 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" 3485 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
@@ -2942,8 +3488,7 @@ system and gives an overview of their function and contents.
2942 this case, the destination file must have the same name as the base 3488 this case, the destination file must have the same name as the base
2943 name of the source file path. To install files into a directory 3489 name of the source file path. To install files into a directory
2944 within the target location, pass its name after a semi-colon (;). 3490 within the target location, pass its name after a semi-colon (;).
2945 Here are two examples: 3491 Here are two examples::
2946 ::
2947 3492
2948 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" 3493 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2949 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" 3494 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
@@ -2954,50 +3499,89 @@ system and gives an overview of their function and contents.
2954 the same files into a ``boot`` directory within the target partition. 3499 the same files into a ``boot`` directory within the target partition.
2955 3500
2956 You can find information on how to use the Wic tool in the 3501 You can find information on how to use the Wic tool in the
2957 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" 3502 ":ref:`dev-manual/wic:creating partitioned images using wic`"
2958 section of the Yocto Project Development Tasks Manual. Reference 3503 section of the Yocto Project Development Tasks Manual. Reference
2959 material for Wic is located in the 3504 material for Wic is located in the
2960 ":doc:`/ref-manual/kickstart`" chapter. 3505 ":doc:`/ref-manual/kickstart`" chapter.
2961 3506
2962 :term:`IMAGE_CLASSES` 3507 :term:`IMAGE_BUILDINFO_FILE`
2963 A list of classes that all images should inherit. You typically use 3508 When using the :ref:`ref-classes-image-buildinfo` class,
2964 this variable to specify the list of classes that register the 3509 specifies the file in the image to write the build information into. The
2965 different types of images the OpenEmbedded build system creates. 3510 default value is "``${sysconfdir}/buildinfo``".
2966 3511
2967 The default value for ``IMAGE_CLASSES`` is ``image_types``. You can 3512 :term:`IMAGE_BUILDINFO_VARS`
2968 set this variable in your ``local.conf`` or in a distribution 3513 When using the :ref:`ref-classes-image-buildinfo` class,
2969 configuration file. 3514 specifies the list of variables to include in the `Build Configuration`
3515 section of the output file (as a space-separated list). Defaults to
3516 ":term:`DISTRO` :term:`DISTRO_VERSION`".
2970 3517
2971 For more information, see ``meta/classes/image_types.bbclass`` in the 3518 :term:`IMAGE_CLASSES`
2972 :term:`Source Directory`. 3519 A list of classes that all images should inherit. This is typically used
3520 to enable functionality across all image recipes.
3521
3522 Classes specified in :term:`IMAGE_CLASSES` must be located in the
3523 ``classes-recipe/`` or ``classes/`` subdirectories.
2973 3524
2974 :term:`IMAGE_CMD` 3525 :term:`IMAGE_CMD`
2975 Specifies the command to create the image file for a specific image 3526 Specifies the command to create the image file for a specific image
2976 type, which corresponds to the value set set in 3527 type, which corresponds to the value set in
2977 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, 3528 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
2978 ``btrfs``, and so forth). When setting this variable, you should use 3529 ``btrfs``, and so forth). When setting this variable, you should use
2979 an override for the associated type. Here is an example: 3530 an override for the associated type. Here is an example::
2980 ::
2981 3531
2982 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ 3532 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
2983 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ 3533 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
2984 ${EXTRA_IMAGECMD}" 3534 ${EXTRA_IMAGECMD}"
2985 3535
2986 You typically do not need to set this variable unless you are adding 3536 You typically do not need to set this variable unless you are adding
2987 support for a new image type. For more examples on how to set this 3537 support for a new image type. For more examples on how to set this
2988 variable, see the :ref:`image_types <ref-classes-image_types>` 3538 variable, see the :ref:`ref-classes-image_types`
2989 class file, which is ``meta/classes/image_types.bbclass``. 3539 class file, which is ``meta/classes-recipe/image_types.bbclass``.
2990 3540
2991 :term:`IMAGE_DEVICE_TABLES` 3541 :term:`IMAGE_DEVICE_TABLES`
2992 Specifies one or more files that contain custom device tables that 3542 Specifies one or more files that contain custom device tables that
2993 are passed to the ``makedevs`` command as part of creating an image. 3543 are passed to the ``makedevs`` command as part of creating an image.
2994 These files list basic device nodes that should be created under 3544 These files list basic device nodes that should be created under
2995 ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, 3545 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
2996 ``files/device_table-minimal.txt`` is used, which is located by 3546 ``files/device_table-minimal.txt`` is used, which is located by
2997 :term:`BBPATH`. For details on how you should write 3547 :term:`BBPATH`. For details on how you should write
2998 device table files, see ``meta/files/device_table-minimal.txt`` as an 3548 device table files, see ``meta/files/device_table-minimal.txt`` as an
2999 example. 3549 example.
3000 3550
3551 :term:`IMAGE_EFI_BOOT_FILES`
3552 A space-separated list of files installed into the boot partition
3553 when preparing an image using the Wic tool with the
3554 ``bootimg-efi`` source plugin. By default,
3555 the files are
3556 installed under the same name as the source files. To change the
3557 installed name, separate it from the original name with a semi-colon
3558 (;). Source files need to be located in
3559 :term:`DEPLOY_DIR_IMAGE`. Here are two
3560 examples::
3561
3562 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
3563 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
3564
3565 Alternatively, source files can be picked up using a glob pattern. In
3566 this case, the destination file must have the same name as the base
3567 name of the source file path. To install files into a directory
3568 within the target location, pass its name after a semi-colon (;).
3569 Here are two examples::
3570
3571 IMAGE_EFI_BOOT_FILES = "boot/loader/*"
3572 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
3573
3574 The first example
3575 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
3576 into the root of the target partition. The second example installs
3577 the same files into a ``boot`` directory within the target partition.
3578
3579 You can find information on how to use the Wic tool in the
3580 ":ref:`dev-manual/wic:creating partitioned images using wic`"
3581 section of the Yocto Project Development Tasks Manual. Reference
3582 material for Wic is located in the
3583 ":doc:`/ref-manual/kickstart`" chapter.
3584
3001 :term:`IMAGE_FEATURES` 3585 :term:`IMAGE_FEATURES`
3002 The primary list of features to include in an image. Typically, you 3586 The primary list of features to include in an image. Typically, you
3003 configure this variable in an image recipe. Although you can use this 3587 configure this variable in an image recipe. Although you can use this
@@ -3014,15 +3598,14 @@ system and gives an overview of their function and contents.
3014 the ":ref:`ref-features-image`" section. 3598 the ":ref:`ref-features-image`" section.
3015 3599
3016 For an example that shows how to customize your image by using this 3600 For an example that shows how to customize your image by using this
3017 variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" 3601 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
3018 section in the Yocto Project Development Tasks Manual. 3602 section in the Yocto Project Development Tasks Manual.
3019 3603
3020 :term:`IMAGE_FSTYPES` 3604 :term:`IMAGE_FSTYPES`
3021 Specifies the formats the OpenEmbedded build system uses during the 3605 Specifies the formats the OpenEmbedded build system uses during the
3022 build when creating the root filesystem. For example, setting 3606 build when creating the root filesystem. For example, setting
3023 ``IMAGE_FSTYPES`` as follows causes the build system to create root 3607 :term:`IMAGE_FSTYPES` as follows causes the build system to create root
3024 filesystems using two formats: ``.ext3`` and ``.tar.bz2``: 3608 filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
3025 ::
3026 3609
3027 IMAGE_FSTYPES = "ext3 tar.bz2" 3610 IMAGE_FSTYPES = "ext3 tar.bz2"
3028 3611
@@ -3032,31 +3615,29 @@ system and gives an overview of their function and contents.
3032 .. note:: 3615 .. note::
3033 3616
3034 - If an image recipe uses the "inherit image" line and you are 3617 - If an image recipe uses the "inherit image" line and you are
3035 setting ``IMAGE_FSTYPES`` inside the recipe, you must set 3618 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
3036 ``IMAGE_FSTYPES`` prior to using the "inherit image" line. 3619 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
3037 3620
3038 - Due to the way the OpenEmbedded build system processes this 3621 - Due to the way the OpenEmbedded build system processes this
3039 variable, you cannot update its contents by using ``_append`` 3622 variable, you cannot update its contents by using ``:append``
3040 or ``_prepend``. You must use the ``+=`` operator to add one or 3623 or ``:prepend``. You must use the ``+=`` operator to add one or
3041 more options to the ``IMAGE_FSTYPES`` variable. 3624 more options to the :term:`IMAGE_FSTYPES` variable.
3042 3625
3043 :term:`IMAGE_INSTALL` 3626 :term:`IMAGE_INSTALL`
3044 Used by recipes to specify the packages to install into an image 3627 Used by recipes to specify the packages to install into an image
3045 through the :ref:`image <ref-classes-image>` class. Use the 3628 through the :ref:`ref-classes-image` class. Use the
3046 ``IMAGE_INSTALL`` variable with care to avoid ordering issues. 3629 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
3047 3630
3048 Image recipes set ``IMAGE_INSTALL`` to specify the packages to 3631 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
3049 install into an image through ``image.bbclass``. Additionally, 3632 install into an image through :ref:`ref-classes-image`. Additionally,
3050 "helper" classes such as the 3633 there are "helper" classes such as the :ref:`ref-classes-core-image`
3051 :ref:`core-image <ref-classes-core-image>` class exist that can 3634 class which can take lists used with :term:`IMAGE_FEATURES` and turn
3052 take lists used with ``IMAGE_FEATURES`` and turn them into 3635 them into auto-generated entries in :term:`IMAGE_INSTALL` in addition
3053 auto-generated entries in ``IMAGE_INSTALL`` in addition to its 3636 to its default contents.
3054 default contents.
3055 3637
3056 When you use this variable, it is best to use it as follows: 3638 When you use this variable, it is best to use it as follows::
3057 ::
3058 3639
3059 IMAGE_INSTALL_append = " package-name" 3640 IMAGE_INSTALL:append = " package-name"
3060 3641
3061 Be sure to include the space 3642 Be sure to include the space
3062 between the quotation character and the start of the package name or 3643 between the quotation character and the start of the package name or
@@ -3066,39 +3647,38 @@ system and gives an overview of their function and contents.
3066 3647
3067 - When working with a 3648 - When working with a
3068 :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 3649 :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
3069 image, do not use the ``IMAGE_INSTALL`` variable to specify 3650 image, do not use the :term:`IMAGE_INSTALL` variable to specify
3070 packages for installation. Instead, use the 3651 packages for installation. Instead, use the
3071 :term:`PACKAGE_INSTALL` variable, which 3652 :term:`PACKAGE_INSTALL` variable, which
3072 allows the initial RAM filesystem (initramfs) recipe to use a 3653 allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a
3073 fixed set of packages and not be affected by ``IMAGE_INSTALL``. 3654 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
3074 For information on creating an initramfs, see the 3655 For information on creating an :term:`Initramfs`, see the
3075 ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" 3656 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
3076 section in the Yocto Project Development Tasks Manual. 3657 section in the Yocto Project Development Tasks Manual.
3077 3658
3078 - Using ``IMAGE_INSTALL`` with the 3659 - Using :term:`IMAGE_INSTALL` with the
3079 :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` 3660 :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
3080 BitBake operator within the ``/conf/local.conf`` file or from 3661 BitBake operator within the ``/conf/local.conf`` file or from
3081 within an image recipe is not recommended. Use of this operator 3662 within an image recipe is not recommended. Use of this operator in
3082 in these ways can cause ordering issues. Since 3663 these ways can cause ordering issues. Since
3083 ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default 3664 :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a
3084 value using the 3665 default value using the
3085 :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` 3666 :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
3086 operator, using a ``+=`` operation against ``IMAGE_INSTALL`` 3667 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
3087 results in unexpected behavior when used within 3668 results in unexpected behavior when used within
3088 ``conf/local.conf``. Furthermore, the same operation from 3669 ``conf/local.conf``. Furthermore, the same operation from within an
3089 within an image recipe may or may not succeed depending on the 3670 image recipe may or may not succeed depending on the specific
3090 specific situation. In both these cases, the behavior is 3671 situation. In both these cases, the behavior is contrary to how
3091 contrary to how most users expect the ``+=`` operator to work. 3672 most users expect the ``+=`` operator to work.
3092 3673
3093 :term:`IMAGE_LINGUAS` 3674 :term:`IMAGE_LINGUAS`
3094 Specifies the list of locales to install into the image during the 3675 Specifies the list of locales to install into the image during the
3095 root filesystem construction process. The OpenEmbedded build system 3676 root filesystem construction process. The OpenEmbedded build system
3096 automatically splits locale files, which are used for localization, 3677 automatically splits locale files, which are used for localization,
3097 into separate packages. Setting the ``IMAGE_LINGUAS`` variable 3678 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
3098 ensures that any locale packages that correspond to packages already 3679 ensures that any locale packages that correspond to packages already
3099 selected for installation into the image are also installed. Here is 3680 selected for installation into the image are also installed. Here is
3100 an example: 3681 an example::
3101 ::
3102 3682
3103 IMAGE_LINGUAS = "pt-br de-de" 3683 IMAGE_LINGUAS = "pt-br de-de"
3104 3684
@@ -3116,54 +3696,72 @@ system and gives an overview of their function and contents.
3116 :term:`IMAGE_LINK_NAME` 3696 :term:`IMAGE_LINK_NAME`
3117 The name of the output image symlink (which does not include 3697 The name of the output image symlink (which does not include
3118 the version part as :term:`IMAGE_NAME` does). The default value 3698 the version part as :term:`IMAGE_NAME` does). The default value
3119 is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE` 3699 is derived using the :term:`IMAGE_BASENAME` and
3120 variables: 3700 :term:`IMAGE_MACHINE_SUFFIX` variables::
3121 :: 3701
3702 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}"
3703
3704 .. note::
3705
3706 It is possible to set this to "" to disable symlink creation,
3707 however, you also need to set :term:`IMAGE_NAME` to still have
3708 a reasonable value e.g.::
3709
3710 IMAGE_LINK_NAME = ""
3711 IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
3712
3713 :term:`IMAGE_MACHINE_SUFFIX`
3714 Specifies the by default machine-specific suffix for image file names
3715 (before the extension). The default value is set as follows::
3122 3716
3123 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}" 3717 IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}"
3124 3718
3719 The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE`
3720 subdirectory, so you may find it unnecessary to also include this suffix
3721 in the name of every image file. If you prefer to remove the suffix you
3722 can set this variable to an empty string::
3723
3724 IMAGE_MACHINE_SUFFIX = ""
3725
3726 (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.)
3125 3727
3126 :term:`IMAGE_MANIFEST` 3728 :term:`IMAGE_MANIFEST`
3127 The manifest file for the image. This file lists all the installed 3729 The manifest file for the image. This file lists all the installed
3128 packages that make up the image. The file contains package 3730 packages that make up the image. The file contains package
3129 information on a line-per-package basis as follows: 3731 information on a line-per-package basis as follows::
3130 ::
3131 3732
3132 packagename packagearch version 3733 packagename packagearch version
3133 3734
3134 The :ref:`image <ref-classes-image>` class defines the manifest 3735 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
3135 file as follows: 3736 file as follows::
3136 ::
3137 3737
3138 IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" 3738 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
3139 3739
3140 The location is 3740 The location is
3141 derived using the :term:`DEPLOY_DIR_IMAGE` 3741 derived using the :term:`IMGDEPLOYDIR`
3142 and :term:`IMAGE_NAME` variables. You can find 3742 and :term:`IMAGE_NAME` variables. You can find
3143 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" 3743 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
3144 section in the Yocto Project Overview and Concepts Manual. 3744 section in the Yocto Project Overview and Concepts Manual.
3145 3745
3146 :term:`IMAGE_NAME` 3746 :term:`IMAGE_NAME`
3147 The name of the output image files minus the extension. This variable 3747 The name of the output image files minus the extension. By default
3148 is derived using the :term:`IMAGE_BASENAME`, 3748 this variable is set using the :term:`IMAGE_LINK_NAME`, and
3149 :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX` 3749 :term:`IMAGE_VERSION_SUFFIX` variables::
3150 variables:
3151 ::
3152 3750
3153 IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3751 IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}"
3154 3752
3155 :term:`IMAGE_NAME_SUFFIX` 3753 :term:`IMAGE_NAME_SUFFIX`
3156 Suffix used for the image output file name - defaults to ``".rootfs"`` 3754 Suffix used for the image output filename --- defaults to ``".rootfs"``
3157 to distinguish the image file from other files created during image 3755 to distinguish the image file from other files created during image
3158 building; however if this suffix is redundant or not desired you can 3756 building; however if this suffix is redundant or not desired you can
3159 clear the value of this variable (set the value to ""). For example, 3757 clear the value of this variable (set the value to ""). For example,
3160 this is typically cleared in initramfs image recipes. 3758 this is typically cleared in :term:`Initramfs` image recipes.
3161 3759
3162 :term:`IMAGE_OVERHEAD_FACTOR` 3760 :term:`IMAGE_OVERHEAD_FACTOR`
3163 Defines a multiplier that the build system applies to the initial 3761 Defines a multiplier that the build system applies to the initial
3164 image size for cases when the multiplier times the returned disk 3762 image size for cases when the multiplier times the returned disk
3165 usage value for the image is greater than the sum of 3763 usage value for the image is greater than the sum of
3166 ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of 3764 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
3167 the multiplier applied to the initial image size creates free disk 3765 the multiplier applied to the initial image size creates free disk
3168 space in the image as overhead. By default, the build process uses a 3766 space in the image as overhead. By default, the build process uses a
3169 multiplier of 1.3 for this variable. This default value results in 3767 multiplier of 1.3 for this variable. This default value results in
@@ -3172,40 +3770,31 @@ system and gives an overview of their function and contents.
3172 post install scripts and the package management system uses disk 3770 post install scripts and the package management system uses disk
3173 space inside this overhead area. Consequently, the multiplier does 3771 space inside this overhead area. Consequently, the multiplier does
3174 not produce an image with all the theoretical free disk space. See 3772 not produce an image with all the theoretical free disk space. See
3175 ``IMAGE_ROOTFS_SIZE`` for information on how the build system 3773 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system
3176 determines the overall image size. 3774 determines the overall image size.
3177 3775
3178 The default 30% free disk space typically gives the image enough room 3776 The default 30% free disk space typically gives the image enough room
3179 to boot and allows for basic post installs while still leaving a 3777 to boot and allows for basic post installs while still leaving a
3180 small amount of free disk space. If 30% free space is inadequate, you 3778 small amount of free disk space. If 30% free space is inadequate, you
3181 can increase the default value. For example, the following setting 3779 can increase the default value. For example, the following setting
3182 gives you 50% free space added to the image: 3780 gives you 50% free space added to the image::
3183 ::
3184 3781
3185 IMAGE_OVERHEAD_FACTOR = "1.5" 3782 IMAGE_OVERHEAD_FACTOR = "1.5"
3186 3783
3187 Alternatively, you can ensure a specific amount of free disk space is 3784 Alternatively, you can ensure a specific amount of free disk space is
3188 added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` 3785 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3189 variable. 3786 variable.
3190 3787
3191 :term:`IMAGE_PKGTYPE` 3788 :term:`IMAGE_PKGTYPE`
3192 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 3789 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
3193 OpenEmbedded build system. The variable is defined appropriately by 3790 OpenEmbedded build system. The variable is defined appropriately by
3194 the :ref:`package_deb <ref-classes-package_deb>`, 3791 the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`,
3195 :ref:`package_rpm <ref-classes-package_rpm>`, 3792 or :ref:`ref-classes-package_ipk` class.
3196 :ref:`package_ipk <ref-classes-package_ipk>`, or
3197 :ref:`package_tar <ref-classes-package_tar>` class.
3198 3793
3199 .. note:: 3794 The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image`
3795 classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs.
3200 3796
3201 The ``package_tar`` class is broken and is not supported. It is 3797 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
3202 recommended that you do not use it.
3203
3204 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
3205 :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE``
3206 for packaging up images and SDKs.
3207
3208 You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the
3209 variable is set indirectly through the appropriate 3798 variable is set indirectly through the appropriate
3210 :ref:`package_* <ref-classes-package>` class using the 3799 :ref:`package_* <ref-classes-package>` class using the
3211 :term:`PACKAGE_CLASSES` variable. The 3800 :term:`PACKAGE_CLASSES` variable. The
@@ -3221,10 +3810,9 @@ system and gives an overview of their function and contents.
3221 :term:`IMAGE_POSTPROCESS_COMMAND` 3810 :term:`IMAGE_POSTPROCESS_COMMAND`
3222 Specifies a list of functions to call once the OpenEmbedded build 3811 Specifies a list of functions to call once the OpenEmbedded build
3223 system creates the final image output files. You can specify 3812 system creates the final image output files. You can specify
3224 functions separated by semicolons: 3813 functions separated by spaces::
3225 ::
3226 3814
3227 IMAGE_POSTPROCESS_COMMAND += "function; ... " 3815 IMAGE_POSTPROCESS_COMMAND += "function"
3228 3816
3229 If you need to pass the root filesystem path to a command within the 3817 If you need to pass the root filesystem path to a command within the
3230 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3818 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -3235,10 +3823,9 @@ system and gives an overview of their function and contents.
3235 :term:`IMAGE_PREPROCESS_COMMAND` 3823 :term:`IMAGE_PREPROCESS_COMMAND`
3236 Specifies a list of functions to call before the OpenEmbedded build 3824 Specifies a list of functions to call before the OpenEmbedded build
3237 system creates the final image output files. You can specify 3825 system creates the final image output files. You can specify
3238 functions separated by semicolons: 3826 functions separated by spaces::
3239 ::
3240 3827
3241 IMAGE_PREPROCESS_COMMAND += "function; ... " 3828 IMAGE_PREPROCESS_COMMAND += "function"
3242 3829
3243 If you need to pass the root filesystem path to a command within the 3830 If you need to pass the root filesystem path to a command within the
3244 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3831 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -3262,19 +3849,17 @@ system and gives an overview of their function and contents.
3262 Defines additional free disk space created in the image in Kbytes. By 3849 Defines additional free disk space created in the image in Kbytes. By
3263 default, this variable is set to "0". This free disk space is added 3850 default, this variable is set to "0". This free disk space is added
3264 to the image after the build system determines the image size as 3851 to the image after the build system determines the image size as
3265 described in ``IMAGE_ROOTFS_SIZE``. 3852 described in :term:`IMAGE_ROOTFS_SIZE`.
3266 3853
3267 This variable is particularly useful when you want to ensure that a 3854 This variable is particularly useful when you want to ensure that a
3268 specific amount of free disk space is available on a device after an 3855 specific amount of free disk space is available on a device after an
3269 image is installed and running. For example, to be sure 5 Gbytes of 3856 image is installed and running. For example, to be sure 5 Gbytes of
3270 free disk space is available, set the variable as follows: 3857 free disk space is available, set the variable as follows::
3271 ::
3272 3858
3273 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 3859 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3274 3860
3275 For example, the Yocto Project Build Appliance specifically requests 3861 For example, the Yocto Project Build Appliance specifically requests
3276 40 Gbytes of extra space with the line: 3862 40 Gbytes of extra space with the line::
3277 ::
3278 3863
3279 IMAGE_ROOTFS_EXTRA_SPACE = "41943040" 3864 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3280 3865
@@ -3285,8 +3870,7 @@ system and gives an overview of their function and contents.
3285 the generated image, a requested size for the image, and requested 3870 the generated image, a requested size for the image, and requested
3286 additional free disk space to be added to the image. Programatically, 3871 additional free disk space to be added to the image. Programatically,
3287 the build system determines the final size of the generated image as 3872 the build system determines the final size of the generated image as
3288 follows: 3873 follows::
3289 ::
3290 3874
3291 if (image-du * overhead) < rootfs-size: 3875 if (image-du * overhead) < rootfs-size:
3292 internal-rootfs-size = rootfs-size + xspace 3876 internal-rootfs-size = rootfs-size + xspace
@@ -3305,10 +3889,9 @@ system and gives an overview of their function and contents.
3305 3889
3306 :term:`IMAGE_TYPEDEP` 3890 :term:`IMAGE_TYPEDEP`
3307 Specifies a dependency from one image type on another. Here is an 3891 Specifies a dependency from one image type on another. Here is an
3308 example from the :ref:`image-live <ref-classes-image-live>` class: 3892 example from the :ref:`ref-classes-image-live` class::
3309 ::
3310 3893
3311 IMAGE_TYPEDEP_live = "ext3" 3894 IMAGE_TYPEDEP:live = "ext3"
3312 3895
3313 In the previous example, the variable ensures that when "live" is 3896 In the previous example, the variable ensures that when "live" is
3314 listed with the :term:`IMAGE_FSTYPES` variable, 3897 listed with the :term:`IMAGE_FSTYPES` variable,
@@ -3327,6 +3910,9 @@ system and gives an overview of their function and contents.
3327 - cpio.lzma 3910 - cpio.lzma
3328 - cpio.xz 3911 - cpio.xz
3329 - cramfs 3912 - cramfs
3913 - erofs
3914 - erofs-lz4
3915 - erofs-lz4hc
3330 - ext2 3916 - ext2
3331 - ext2.bz2 3917 - ext2.bz2
3332 - ext2.gz 3918 - ext2.gz
@@ -3359,7 +3945,7 @@ system and gives an overview of their function and contents.
3359 - wic.lzma 3945 - wic.lzma
3360 3946
3361 For more information about these types of images, see 3947 For more information about these types of images, see
3362 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. 3948 ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`.
3363 3949
3364 :term:`IMAGE_VERSION_SUFFIX` 3950 :term:`IMAGE_VERSION_SUFFIX`
3365 Version suffix that is part of the default :term:`IMAGE_NAME` and 3951 Version suffix that is part of the default :term:`IMAGE_NAME` and
@@ -3369,97 +3955,83 @@ system and gives an overview of their function and contents.
3369 desired, and this suffix would then be used consistently across 3955 desired, and this suffix would then be used consistently across
3370 the build artifacts. 3956 the build artifacts.
3371 3957
3372 :term:`INC_PR` 3958 :term:`IMGDEPLOYDIR`
3373 Helps define the recipe revision for recipes that share a common 3959 When inheriting the :ref:`ref-classes-image` class directly or
3374 ``include`` file. You can think of this variable as part of the 3960 through the :ref:`ref-classes-core-image` class, the
3375 recipe revision as set from within an include file. 3961 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
3376 3962 that is set in the ``image`` class as follows::
3377 Suppose, for example, you have a set of recipes that are used across
3378 several projects. And, within each of those recipes the revision (its
3379 :term:`PR` value) is set accordingly. In this case, when
3380 the revision of those recipes changes, the burden is on you to find
3381 all those recipes and be sure that they get changed to reflect the
3382 updated version of the recipe. In this scenario, it can get
3383 complicated when recipes that are used in many places and provide
3384 common functionality are upgraded to a new revision.
3385
3386 A more efficient way of dealing with this situation is to set the
3387 ``INC_PR`` variable inside the ``include`` files that the recipes
3388 share and then expand the ``INC_PR`` variable within the recipes to
3389 help define the recipe revision.
3390
3391 The following provides an example that shows how to use the
3392 ``INC_PR`` variable given a common ``include`` file that defines the
3393 variable. Once the variable is defined in the ``include`` file, you
3394 can use the variable to set the ``PR`` values in each recipe. You
3395 will notice that when you set a recipe's ``PR`` you can provide more
3396 granular revisioning by appending values to the ``INC_PR`` variable:
3397 ::
3398
3399 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3400 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3401 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3402 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3403 3963
3404 The 3964 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
3405 first line of the example establishes the baseline revision to be 3965
3406 used for all recipes that use the ``include`` file. The remaining 3966 Recipes inheriting the :ref:`ref-classes-image` class should copy
3407 lines in the example are from individual recipes and show how the 3967 files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take
3408 ``PR`` value is set. 3968 care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
3409 3969
3410 :term:`INCOMPATIBLE_LICENSE` 3970 :term:`INCOMPATIBLE_LICENSE`
3411 Specifies a space-separated list of license names (as they would 3971 Specifies a space-separated list of license names (as they would
3412 appear in :term:`LICENSE`) that should be excluded 3972 appear in :term:`LICENSE`) that should be excluded
3413 from the build. Recipes that provide no alternatives to listed 3973 from the build (if set globally), or from an image (if set locally
3974 in an image recipe).
3975
3976 When the variable is set globally, recipes that provide no alternatives to listed
3414 incompatible licenses are not built. Packages that are individually 3977 incompatible licenses are not built. Packages that are individually
3415 licensed with the specified incompatible licenses will be deleted. 3978 licensed with the specified incompatible licenses will be deleted.
3979 Most of the time this does not allow a feasible build (because it becomes impossible
3980 to satisfy build time dependencies), so the recommended way to
3981 implement license restrictions is to set the variable in specific
3982 image recipes where the restrictions must apply. That way there
3983 are no build time restrictions, but the license check is still
3984 performed when the image's filesystem is assembled from packages.
3985
3986 There is some support for wildcards in this variable's value,
3987 however it is restricted to specific licenses. Currently only
3988 these wildcards are allowed and expand as follows:
3989
3990 - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later``
3991 - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later``
3992 - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later``
3416 3993
3417 .. note:: 3994 .. note::
3418 3995
3419 This functionality is only regularly tested using the following 3996 This functionality is only regularly tested using the following
3420 setting: 3997 setting::
3421 ::
3422 3998
3423 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" 3999 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"
3424 4000
3425 4001
3426 Although you can use other settings, you might be required to 4002 Although you can use other settings, you might be required to
3427 remove dependencies on or provide alternatives to components that 4003 remove dependencies on (or provide alternatives to) components that
3428 are required to produce a functional system image. 4004 are required to produce a functional system image.
3429 4005
3430 .. note:: 4006 :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`
3431 4007 Specifies a space-separated list of package and license pairs that
3432 It is possible to define a list of licenses that are allowed to be 4008 are allowed to be used even if the license is specified in
3433 used instead of the licenses that are excluded. To do this, define 4009 :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are
3434 a variable ``COMPATIBLE_LICENSES`` with the names of the licences 4010 separated using a colon. Example::
3435 that are allowed. Then define ``INCOMPATIBLE_LICENSE`` as:
3436 ::
3437
3438 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
3439 4011
3440 4012 INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only"
3441 This will result in ``INCOMPATIBLE_LICENSE`` containing the names of
3442 all licences from :term:`AVAILABLE_LICENSES` except the ones specified
3443 in ``COMPATIBLE_LICENSES`` , thus only allowing the latter licences to
3444 be used.
3445 4013
3446 :term:`INHERIT` 4014 :term:`INHERIT`
3447 Causes the named class or classes to be inherited globally. Anonymous 4015 Causes the named class or classes to be inherited globally. Anonymous
3448 functions in the class or classes are not executed for the base 4016 functions in the class or classes are not executed for the base
3449 configuration and in each individual recipe. The OpenEmbedded build 4017 configuration and in each individual recipe. The OpenEmbedded build
3450 system ignores changes to ``INHERIT`` in individual recipes. 4018 system ignores changes to :term:`INHERIT` in individual recipes.
4019 Classes inherited using :term:`INHERIT` must be located in the
4020 ``classes-global/`` or ``classes/`` subdirectories.
3451 4021
3452 For more information on ``INHERIT``, see the 4022 For more information on :term:`INHERIT`, see the
3453 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" 4023 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
3454 section in the Bitbake User Manual. 4024 section in the BitBake User Manual.
3455 4025
3456 :term:`INHERIT_DISTRO` 4026 :term:`INHERIT_DISTRO`
3457 Lists classes that will be inherited at the distribution level. It is 4027 Lists classes that will be inherited at the distribution level. It is
3458 unlikely that you want to edit this variable. 4028 unlikely that you want to edit this variable.
3459 4029
4030 Classes specified in :term:`INHERIT_DISTRO` must be located in the
4031 ``classes-global/`` or ``classes/`` subdirectories.
4032
3460 The default value of the variable is set as follows in the 4033 The default value of the variable is set as follows in the
3461 ``meta/conf/distro/defaultsetup.conf`` file: 4034 ``meta/conf/distro/defaultsetup.conf`` file::
3462 ::
3463 4035
3464 INHERIT_DISTRO ?= "debian devshell sstate license" 4036 INHERIT_DISTRO ?= "debian devshell sstate license"
3465 4037
@@ -3482,9 +4054,8 @@ system and gives an overview of their function and contents.
3482 variable. 4054 variable.
3483 4055
3484 To prevent the build system from splitting out debug information 4056 To prevent the build system from splitting out debug information
3485 during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as 4057 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
3486 follows: 4058 follows::
3487 ::
3488 4059
3489 INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 4060 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
3490 4061
@@ -3495,7 +4066,7 @@ system and gives an overview of their function and contents.
3495 4066
3496 By default, the OpenEmbedded build system strips binaries and puts 4067 By default, the OpenEmbedded build system strips binaries and puts
3497 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. 4068 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
3498 Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you 4069 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
3499 plan to debug in general. 4070 plan to debug in general.
3500 4071
3501 :term:`INHIBIT_SYSROOT_STRIP` 4072 :term:`INHIBIT_SYSROOT_STRIP`
@@ -3504,46 +4075,80 @@ system and gives an overview of their function and contents.
3504 4075
3505 By default, the OpenEmbedded build system strips binaries in the 4076 By default, the OpenEmbedded build system strips binaries in the
3506 resulting sysroot. When you specifically set the 4077 resulting sysroot. When you specifically set the
3507 ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit 4078 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
3508 this stripping. 4079 this stripping.
3509 4080
3510 If you want to use this variable, include the 4081 If you want to use this variable, include the :ref:`ref-classes-staging`
3511 :ref:`staging <ref-classes-staging>` class. This class uses a 4082 class. This class uses a ``sys_strip()`` function to test for the variable
3512 ``sys_strip()`` function to test for the variable and acts 4083 and acts accordingly.
3513 accordingly.
3514 4084
3515 .. note:: 4085 .. note::
3516 4086
3517 Use of the ``INHIBIT_SYSROOT_STRIP`` variable occurs in rare and 4087 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
3518 special circumstances. For example, suppose you are building 4088 special circumstances. For example, suppose you are building
3519 bare-metal firmware by using an external GCC toolchain. Furthermore, 4089 bare-metal firmware by using an external GCC toolchain. Furthermore,
3520 even if the toolchain's binaries are strippable, other files exist 4090 even if the toolchain's binaries are strippable, there are other files
3521 that are needed for the build that are not strippable. 4091 needed for the build that are not strippable.
4092
4093 :term:`INIT_MANAGER`
4094 Specifies the system init manager to use. Available options are:
4095
4096 - ``sysvinit``
4097 - ``systemd``
4098 - ``mdev-busybox``
4099
4100 With ``sysvinit``, the init manager is set to
4101 :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init
4102 system. This is the default choice in the Poky distribution, together with
4103 the Udev device manager (see the ":ref:`device-manager`" section).
4104
4105 With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`,
4106 which comes with the :wikipedia:`udev <Udev>` device manager.
4107
4108 With ``mdev-busybox``, the init manager becomes the much simpler BusyBox
4109 init, together with the BusyBox mdev device manager. This is the simplest
4110 and lightest solution, and probably the best choice for low-end systems
4111 with a rather slow CPU and a limited amount of RAM.
4112
4113 More concretely, this is used to include
4114 ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global
4115 configuration. You can have a look at the
4116 :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>`
4117 files for more information, and also the ":ref:`init-manager`"
4118 section in the Yocto Project Development Tasks Manual.
4119
4120 :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
4121 Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs`
4122 where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is
4123 set by default to ``${DEPLOY_DIR_IMAGE}`` in the
4124 :ref:`ref-classes-kernel` class and it's only meant to be changed when
4125 building an :term:`Initramfs` image from a separate multiconfig via
4126 :term:`INITRAMFS_MULTICONFIG`.
3522 4127
3523 :term:`INITRAMFS_FSTYPES` 4128 :term:`INITRAMFS_FSTYPES`
3524 Defines the format for the output image of an initial RAM filesystem 4129 Defines the format for the output image of an initial RAM filesystem
3525 (initramfs), which is used during boot. Supported formats are the 4130 (:term:`Initramfs`), which is used during boot. Supported formats are the
3526 same as those supported by the 4131 same as those supported by the
3527 :term:`IMAGE_FSTYPES` variable. 4132 :term:`IMAGE_FSTYPES` variable.
3528 4133
3529 The default value of this variable, which is set in the 4134 The default value of this variable, which is set in the
3530 ``meta/conf/bitbake.conf`` configuration file in the 4135 ``meta/conf/bitbake.conf`` configuration file in the
3531 :term:`Source Directory`, is "cpio.gz". The Linux kernel's 4136 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
3532 initramfs mechanism, as opposed to the initial RAM filesystem 4137 :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem
3533 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects 4138 :wikipedia:`initrd <Initrd>` mechanism, expects
3534 an optionally compressed cpio archive. 4139 an optionally compressed cpio archive.
3535 4140
3536 :term:`INITRAMFS_IMAGE` 4141 :term:`INITRAMFS_IMAGE`
3537 Specifies the :term:`PROVIDES` name of an image 4142 Specifies the :term:`PROVIDES` name of an image
3538 recipe that is used to build an initial RAM filesystem (initramfs) 4143 recipe that is used to build an initial RAM filesystem (:term:`Initramfs`)
3539 image. In other words, the ``INITRAMFS_IMAGE`` variable causes an 4144 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
3540 additional recipe to be built as a dependency to whatever root 4145 additional recipe to be built as a dependency to whatever root
3541 filesystem recipe you might be using (e.g. ``core-image-sato``). The 4146 filesystem recipe you might be using (e.g. ``core-image-sato``). The
3542 initramfs image recipe you provide should set 4147 :term:`Initramfs` image recipe you provide should set
3543 :term:`IMAGE_FSTYPES` to 4148 :term:`IMAGE_FSTYPES` to
3544 :term:`INITRAMFS_FSTYPES`. 4149 :term:`INITRAMFS_FSTYPES`.
3545 4150
3546 An initramfs image provides a temporary root filesystem used for 4151 An :term:`Initramfs` image provides a temporary root filesystem used for
3547 early system initialization (e.g. loading of modules needed to locate 4152 early system initialization (e.g. loading of modules needed to locate
3548 and mount the "real" root filesystem). 4153 and mount the "real" root filesystem).
3549 4154
@@ -3551,24 +4156,24 @@ system and gives an overview of their function and contents.
3551 4156
3552 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` 4157 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
3553 recipe in the :term:`Source Directory` 4158 recipe in the :term:`Source Directory`
3554 for an example initramfs recipe. To select this sample recipe as 4159 for an example :term:`Initramfs` recipe. To select this sample recipe as
3555 the one built to provide the initramfs image, set ``INITRAMFS_IMAGE`` 4160 the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE`
3556 to "core-image-minimal-initramfs". 4161 to "core-image-minimal-initramfs".
3557 4162
3558 You can also find more information by referencing the 4163 You can also find more information by referencing the
3559 ``meta-poky/conf/local.conf.sample.extended`` configuration file in 4164 ``meta-poky/conf/templates/default/local.conf.sample.extended``
3560 the Source Directory, the :ref:`image <ref-classes-image>` class, 4165 configuration file in the Source Directory, the :ref:`ref-classes-image`
3561 and the :ref:`kernel <ref-classes-kernel>` class to see how to use 4166 class, and the :ref:`ref-classes-kernel` class to see how to use the
3562 the ``INITRAMFS_IMAGE`` variable. 4167 :term:`INITRAMFS_IMAGE` variable.
3563 4168
3564 If ``INITRAMFS_IMAGE`` is empty, which is the default, then no 4169 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
3565 initramfs image is built. 4170 :term:`Initramfs` image is built.
3566 4171
3567 For more information, you can also see the 4172 For more information, you can also see the
3568 :term:`INITRAMFS_IMAGE_BUNDLE` 4173 :term:`INITRAMFS_IMAGE_BUNDLE`
3569 variable, which allows the generated image to be bundled inside the 4174 variable, which allows the generated image to be bundled inside the
3570 kernel image. Additionally, for information on creating an initramfs 4175 kernel image. Additionally, for information on creating an :term:`Initramfs`
3571 image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section 4176 image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
3572 in the Yocto Project Development Tasks Manual. 4177 in the Yocto Project Development Tasks Manual.
3573 4178
3574 :term:`INITRAMFS_IMAGE_BUNDLE` 4179 :term:`INITRAMFS_IMAGE_BUNDLE`
@@ -3577,102 +4182,121 @@ system and gives an overview of their function and contents.
3577 extra pass 4182 extra pass
3578 (:ref:`ref-tasks-bundle_initramfs`) during 4183 (:ref:`ref-tasks-bundle_initramfs`) during
3579 kernel compilation in order to build a single binary that contains 4184 kernel compilation in order to build a single binary that contains
3580 both the kernel image and the initial RAM filesystem (initramfs) 4185 both the kernel image and the initial RAM filesystem (:term:`Initramfs`)
3581 image. This makes use of the 4186 image. This makes use of the
3582 :term:`CONFIG_INITRAMFS_SOURCE` kernel 4187 :term:`CONFIG_INITRAMFS_SOURCE` kernel
3583 feature. 4188 feature.
3584 4189
3585 .. note:: 4190 .. note::
3586 4191
3587 Using an extra compilation pass to bundle the initramfs avoids a 4192 Bundling the :term:`Initramfs` with the kernel conflates the code in the
3588 circular dependency between the kernel recipe and the initramfs 4193 :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
3589 recipe should the initramfs include kernel modules. Should that be 4194 compatible software may be part of a bundled :term:`Initramfs`.
3590 the case, the initramfs recipe depends on the kernel for the 4195
3591 kernel modules, and the kernel depends on the initramfs recipe 4196 .. note::
3592 since the initramfs is bundled inside the kernel image. 4197
4198 Using an extra compilation pass to bundle the :term:`Initramfs` avoids a
4199 circular dependency between the kernel recipe and the :term:`Initramfs`
4200 recipe should the :term:`Initramfs` include kernel modules. Should that be
4201 the case, the :term:`Initramfs` recipe depends on the kernel for the
4202 kernel modules, and the kernel depends on the :term:`Initramfs` recipe
4203 since the :term:`Initramfs` is bundled inside the kernel image.
3593 4204
3594 The combined binary is deposited into the ``tmp/deploy`` directory, 4205 The combined binary is deposited into the ``tmp/deploy`` directory,
3595 which is part of the :term:`Build Directory`. 4206 which is part of the :term:`Build Directory`.
3596 4207
3597 Setting the variable to "1" in a configuration file causes the 4208 Setting the variable to "1" in a configuration file causes the
3598 OpenEmbedded build system to generate a kernel image with the 4209 OpenEmbedded build system to generate a kernel image with the
3599 initramfs specified in ``INITRAMFS_IMAGE`` bundled within: 4210 :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within::
3600 ::
3601 4211
3602 INITRAMFS_IMAGE_BUNDLE = "1" 4212 INITRAMFS_IMAGE_BUNDLE = "1"
3603 4213
3604 By default, the 4214 By default, the :ref:`ref-classes-kernel` class sets this variable to a
3605 :ref:`kernel <ref-classes-kernel>` class sets this variable to a 4215 null string as follows::
3606 null string as follows:
3607 ::
3608 4216
3609 INITRAMFS_IMAGE_BUNDLE ?= "" 4217 INITRAMFS_IMAGE_BUNDLE ?= ""
3610 4218
3611 .. note:: 4219 .. note::
3612 4220
3613 You must set the ``INITRAMFS_IMAGE_BUNDLE`` variable in a 4221 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a
3614 configuration file. You cannot set the variable in a recipe file. 4222 configuration file. You cannot set the variable in a recipe file.
3615 4223
3616 See the 4224 See the
3617 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>` 4225 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>`
3618 file for additional information. Also, for information on creating an 4226 file for additional information. Also, for information on creating an
3619 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section 4227 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
3620 in the Yocto Project Development Tasks Manual. 4228 in the Yocto Project Development Tasks Manual.
3621 4229
4230 :term:`INITRAMFS_IMAGE_NAME`
4231
4232 This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with
4233 :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value
4234 is set as follows:
4235
4236 INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}"
4237
4238 That is, if :term:`INITRAMFS_IMAGE` is set, the value of
4239 :term:`INITRAMFS_IMAGE_NAME` will be set based upon
4240 :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`.
4241
4242
3622 :term:`INITRAMFS_LINK_NAME` 4243 :term:`INITRAMFS_LINK_NAME`
3623 The link name of the initial RAM filesystem image. This variable is 4244 The link name of the initial RAM filesystem image. This variable is
3624 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 4245 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
3625 follows: 4246 follows::
3626 ::
3627 4247
3628 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" 4248 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
3629 4249
3630 The value of the 4250 The value of the
3631 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4251 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3632 file, has the following value: 4252 file, has the following value::
3633 ::
3634 4253
3635 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4254 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3636 4255
3637 See the :term:`MACHINE` variable for additional 4256 See the :term:`MACHINE` variable for additional
3638 information. 4257 information.
3639 4258
4259 :term:`INITRAMFS_MULTICONFIG`
4260 Defines the multiconfig to create a multiconfig dependency to be used by
4261 the :ref:`ref-classes-kernel` class.
4262
4263 This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from
4264 a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`.
4265
4266 For more information on how to bundle an :term:`Initramfs` image from a separate
4267 multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`"
4268 section in the Yocto Project Development Tasks Manual.
4269
3640 :term:`INITRAMFS_NAME` 4270 :term:`INITRAMFS_NAME`
3641 The base name of the initial RAM filesystem image. This variable is 4271 The base name of the initial RAM filesystem image. This variable is
3642 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 4272 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
3643 follows: 4273 follows::
3644 ::
3645 4274
3646 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" 4275 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
3647 4276
3648 The value of the :term:`KERNEL_ARTIFACT_NAME` 4277 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
3649 variable, which is set in the same file, has the following value:
3650 ::
3651
3652 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3653 4278
3654 :term:`INITRD` 4279 :term:`INITRD`
3655 Indicates list of filesystem images to concatenate and use as an 4280 Indicates list of filesystem images to concatenate and use as an
3656 initial RAM disk (``initrd``). 4281 initial RAM disk (``initrd``).
3657 4282
3658 The ``INITRD`` variable is an optional variable used with the 4283 The :term:`INITRD` variable is an optional variable used with the
3659 :ref:`image-live <ref-classes-image-live>` class. 4284 :ref:`ref-classes-image-live` class.
3660 4285
3661 :term:`INITRD_IMAGE` 4286 :term:`INITRD_IMAGE`
3662 When building a "live" bootable image (i.e. when 4287 When building a "live" bootable image (i.e. when
3663 :term:`IMAGE_FSTYPES` contains "live"), 4288 :term:`IMAGE_FSTYPES` contains "live"),
3664 ``INITRD_IMAGE`` specifies the image recipe that should be built to 4289 :term:`INITRD_IMAGE` specifies the image recipe that should be built to
3665 provide the initial RAM disk image. The default value is 4290 provide the initial RAM disk image. The default value is
3666 "core-image-minimal-initramfs". 4291 "core-image-minimal-initramfs".
3667 4292
3668 See the :ref:`image-live <ref-classes-image-live>` class for more 4293 See the :ref:`ref-classes-image-live` class for more information.
3669 information.
3670 4294
3671 :term:`INITSCRIPT_NAME` 4295 :term:`INITSCRIPT_NAME`
3672 The filename of the initialization script as installed to 4296 The filename of the initialization script as installed to
3673 ``${sysconfdir}/init.d``. 4297 ``${sysconfdir}/init.d``.
3674 4298
3675 This variable is used in recipes when using ``update-rc.d.bbclass``. 4299 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
3676 The variable is mandatory. 4300 The variable is mandatory.
3677 4301
3678 :term:`INITSCRIPT_PACKAGES` 4302 :term:`INITSCRIPT_PACKAGES`
@@ -3680,13 +4304,12 @@ system and gives an overview of their function and contents.
3680 are specified, you need to append the package name to the other 4304 are specified, you need to append the package name to the other
3681 ``INITSCRIPT_*`` as an override. 4305 ``INITSCRIPT_*`` as an override.
3682 4306
3683 This variable is used in recipes when using ``update-rc.d.bbclass``. 4307 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
3684 The variable is optional and defaults to the :term:`PN` 4308 The variable is optional and defaults to the :term:`PN`
3685 variable. 4309 variable.
3686 4310
3687 :term:`INITSCRIPT_PARAMS` 4311 :term:`INITSCRIPT_PARAMS`
3688 Specifies the options to pass to ``update-rc.d``. Here is an example: 4312 Specifies the options to pass to ``update-rc.d``. Here is an example::
3689 ::
3690 4313
3691 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." 4314 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3692 4315
@@ -3694,9 +4317,9 @@ system and gives an overview of their function and contents.
3694 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. 4317 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3695 4318
3696 The variable's default value is "defaults", which is set in the 4319 The variable's default value is "defaults", which is set in the
3697 :ref:`update-rc.d <ref-classes-update-rc.d>` class. 4320 :ref:`ref-classes-update-rc.d` class.
3698 4321
3699 The value in ``INITSCRIPT_PARAMS`` is passed through to the 4322 The value in :term:`INITSCRIPT_PARAMS` is passed through to the
3700 ``update-rc.d`` command. For more information on valid parameters, 4323 ``update-rc.d`` command. For more information on valid parameters,
3701 please see the ``update-rc.d`` manual page at 4324 please see the ``update-rc.d`` manual page at
3702 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html 4325 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
@@ -3706,17 +4329,16 @@ system and gives an overview of their function and contents.
3706 recipe. For example, to skip the check for symbolic link ``.so`` 4329 recipe. For example, to skip the check for symbolic link ``.so``
3707 files in the main package of a recipe, add the following to the 4330 files in the main package of a recipe, add the following to the
3708 recipe. The package name override must be used, which in this example 4331 recipe. The package name override must be used, which in this example
3709 is ``${PN}``: 4332 is ``${PN}``::
3710 ::
3711 4333
3712 INSANE_SKIP_${PN} += "dev-so" 4334 INSANE_SKIP:${PN} += "dev-so"
3713 4335
3714 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a 4336 See the ":ref:`ref-classes-insane`" section for a
3715 list of the valid QA checks you can specify using this variable. 4337 list of the valid QA checks you can specify using this variable.
3716 4338
3717 :term:`INSTALL_TIMEZONE_FILE` 4339 :term:`INSTALL_TIMEZONE_FILE`
3718 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. 4340 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
3719 Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the 4341 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the
3720 configuration level to disable this behavior. 4342 configuration level to disable this behavior.
3721 4343
3722 :term:`IPK_FEED_URIS` 4344 :term:`IPK_FEED_URIS`
@@ -3737,7 +4359,7 @@ system and gives an overview of their function and contents.
3737 - qemu 4359 - qemu
3738 - mips 4360 - mips
3739 4361
3740 You define the ``KARCH`` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. 4362 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`.
3741 4363
3742 :term:`KBRANCH` 4364 :term:`KBRANCH`
3743 A regular expression used by the build process to explicitly identify 4365 A regular expression used by the build process to explicitly identify
@@ -3748,34 +4370,31 @@ system and gives an overview of their function and contents.
3748 Values for this variable are set in the kernel's recipe file and the 4370 Values for this variable are set in the kernel's recipe file and the
3749 kernel's append file. For example, if you are using the 4371 kernel's append file. For example, if you are using the
3750 ``linux-yocto_4.12`` kernel, the kernel recipe file is the 4372 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
3751 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` 4373 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
3752 is set as follows in that kernel recipe file: 4374 is set as follows in that kernel recipe file::
3753 ::
3754 4375
3755 KBRANCH ?= "standard/base" 4376 KBRANCH ?= "standard/base"
3756 4377
3757 This variable is also used from the kernel's append file to identify 4378 This variable is also used from the kernel's append file to identify
3758 the kernel branch specific to a particular machine or target 4379 the kernel branch specific to a particular machine or target
3759 hardware. Continuing with the previous kernel example, the kernel's 4380 hardware. Continuing with the previous kernel example, the kernel's
3760 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the 4381 append file is located in the
3761 BSP layer for a given machine. For example, the append file for the 4382 BSP layer for a given machine. For example, the append file for the
3762 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA 4383 Beaglebone and generic versions of both 32 and 64-bit IA
3763 machines (``meta-yocto-bsp``) is named 4384 machines (``meta-yocto-bsp``) is named
3764 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. 4385 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``.
3765 Here are the related statements from that append file: 4386 Here are the related statements from that append file::
3766 ::
3767 4387
3768 KBRANCH_genericx86 = "standard/base" 4388 KBRANCH:genericx86 = "v6.1/standard/base"
3769 KBRANCH_genericx86-64 = "standard/base" 4389 KBRANCH:genericx86-64 = "v6.1/standard/base"
3770 KBRANCH_edgerouter = "standard/edgerouter" 4390 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone"
3771 KBRANCH_beaglebone = "standard/beaglebone"
3772 4391
3773 The ``KBRANCH`` statements 4392 The :term:`KBRANCH` statements
3774 identify the kernel branch to use when building for each supported 4393 identify the kernel branch to use when building for each supported
3775 BSP. 4394 BSP.
3776 4395
3777 :term:`KBUILD_DEFCONFIG` 4396 :term:`KBUILD_DEFCONFIG`
3778 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` 4397 When used with the :ref:`ref-classes-kernel-yocto`
3779 class, specifies an "in-tree" kernel configuration file for use 4398 class, specifies an "in-tree" kernel configuration file for use
3780 during a kernel build. 4399 during a kernel build.
3781 4400
@@ -3784,60 +4403,118 @@ system and gives an overview of their function and contents.
3784 would place patch files and configuration fragment files (i.e. 4403 would place patch files and configuration fragment files (i.e.
3785 "out-of-tree"). However, if you want to use a ``defconfig`` file that 4404 "out-of-tree"). However, if you want to use a ``defconfig`` file that
3786 is part of the kernel tree (i.e. "in-tree"), you can use the 4405 is part of the kernel tree (i.e. "in-tree"), you can use the
3787 ``KBUILD_DEFCONFIG`` variable and append the 4406 :term:`KBUILD_DEFCONFIG` variable and append the
3788 :term:`KMACHINE` variable to point to the 4407 :term:`KMACHINE` variable to point to the
3789 ``defconfig`` file. 4408 ``defconfig`` file.
3790 4409
3791 To use the variable, set it in the append file for your kernel recipe 4410 To use the variable, set it in the append file for your kernel recipe
3792 using the following form: 4411 using the following form::
3793 ::
3794 4412
3795 KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file 4413 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
3796 4414
3797 Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses 4415 Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses
3798 a ``defconfig`` file named "bcm2709_defconfig": 4416 a ``defconfig`` file named "bcm2709_defconfig"::
3799 ::
3800 4417
3801 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" 4418 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
3802 4419
3803 As an alternative, you can use the following within your append file: 4420 As an alternative, you can use the following within your append file::
3804 ::
3805 4421
3806 KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file 4422 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
3807 4423
3808 For more 4424 For more
3809 information on how to use the ``KBUILD_DEFCONFIG`` variable, see the 4425 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the
3810 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" 4426 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
3811 section in the Yocto Project Linux Kernel Development Manual. 4427 section in the Yocto Project Linux Kernel Development Manual.
3812 4428
4429 :term:`KCONFIG_MODE`
4430 When used with the :ref:`ref-classes-kernel-yocto`
4431 class, specifies the kernel configuration values to use for options
4432 not specified in the provided ``defconfig`` file. Valid options are::
4433
4434 KCONFIG_MODE = "alldefconfig"
4435 KCONFIG_MODE = "allnoconfig"
4436
4437 In ``alldefconfig`` mode the options not explicitly specified will be
4438 assigned their Kconfig default value. In ``allnoconfig`` mode the
4439 options not explicitly specified will be disabled in the kernel
4440 config.
4441
4442 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where
4443 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
4444 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
4445 in ``${WORKDIR}`` through a meta-layer will be handled in
4446 ``allnoconfig`` mode.
4447
4448 An "in-tree" ``defconfig`` file can be selected via the
4449 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to
4450 be explicitly set.
4451
4452 A ``defconfig`` file compatible with ``allnoconfig`` mode can be
4453 generated by copying the ``.config`` file from a working Linux kernel
4454 build, renaming it to ``defconfig`` and placing it into the Linux
4455 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does
4456 not need to be explicitly set.
4457
4458 A ``defconfig`` file compatible with ``alldefconfig`` mode can be
4459 generated using the
4460 :ref:`ref-tasks-savedefconfig`
4461 task and placed into the Linux kernel ``${WORKDIR}`` through your
4462 meta-layer. Explicitely set :term:`KCONFIG_MODE`::
4463
4464 KCONFIG_MODE = "alldefconfig"
4465
3813 :term:`KERNEL_ALT_IMAGETYPE` 4466 :term:`KERNEL_ALT_IMAGETYPE`
3814 Specifies an alternate kernel image type for creation in addition to 4467 Specifies an alternate kernel image type for creation in addition to
3815 the kernel image type specified using the 4468 the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and
3816 :term:`KERNEL_IMAGETYPE` variable. 4469 :term:`KERNEL_IMAGETYPES` variables.
3817 4470
3818 :term:`KERNEL_ARTIFACT_NAME` 4471 :term:`KERNEL_ARTIFACT_NAME`
3819 Specifies the name of all of the build artifacts. You can change the 4472 Specifies the name of all of the build artifacts. You can change the
3820 name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` 4473 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME`
3821 variable. 4474 variable.
3822 4475
3823 The value of ``KERNEL_ARTIFACT_NAME``, which is set in the 4476 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
3824 ``meta/classes/kernel-artifact-names.bbclass`` file, has the 4477 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the
3825 following default value: 4478 following default value::
3826 ::
3827 4479
3828 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 4480 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
3829 4481
3830 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`MACHINE` 4482 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX`
3831 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. 4483 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information.
3832 4484
3833 :term:`KERNEL_CLASSES` 4485 :term:`KERNEL_CLASSES`
3834 A list of classes defining kernel image types that the 4486 A list of classes defining kernel image types that the
3835 :ref:`kernel <ref-classes-kernel>` class should inherit. You 4487 :ref:`ref-classes-kernel` class should inherit. You typically
3836 typically append this variable to enable extended image types. An 4488 append this variable to enable extended image types. An example is
3837 example is the "kernel-fitimage", which enables fitImage support and 4489 ":ref:`ref-classes-kernel-fitimage`", which enables
3838 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register 4490 FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``.
3839 custom kernel image types with the ``kernel`` class using this 4491 You can register custom kernel image types with the
3840 variable. 4492 :ref:`ref-classes-kernel` class using this variable.
4493
4494 :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY`
4495 When kernel configuration fragments are missing for some
4496 :term:`KERNEL_FEATURES` specified by layers or BSPs,
4497 building and configuring the kernel stops with an error.
4498
4499 You can turn these errors into warnings by setting the
4500 following in ``conf/local.conf``::
4501
4502 KERNEL_DANGLING_FEATURES_WARN_ONLY = "1"
4503
4504 You will still be warned that runtime issues may occur,
4505 but at least the kernel configuration and build process will
4506 be allowed to continue.
4507
4508 :term:`KERNEL_DEBUG_TIMESTAMPS`
4509 If set to "1", enables timestamping functionality during building
4510 the kernel. The default is "0" to disable this for reproducibility
4511 reasons.
4512
4513 :term:`KERNEL_DEPLOY_DEPEND`
4514 Provides a means of controlling the dependency of an image recipe
4515 on the kernel. The default value is "virtual/kernel:do_deploy",
4516 however for a small initramfs image or other images that do not
4517 need the kernel, this can be set to "" in the image recipe.
3841 4518
3842 :term:`KERNEL_DEVICETREE` 4519 :term:`KERNEL_DEVICETREE`
3843 Specifies the name of the generated Linux kernel device tree (i.e. 4520 Specifies the name of the generated Linux kernel device tree (i.e.
@@ -3845,25 +4522,32 @@ system and gives an overview of their function and contents.
3845 4522
3846 .. note:: 4523 .. note::
3847 4524
3848 Legacy support exists for specifying the full path to the device 4525 There is legacy support for specifying the full path to the device
3849 tree. However, providing just the ``.dtb`` file is preferred. 4526 tree. However, providing just the ``.dtb`` file is preferred.
3850 4527
3851 In order to use this variable, the 4528 In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
3852 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must 4529 class must be inherited.
3853 be inherited. 4530
4531 :term:`KERNEL_DEVICETREE_BUNDLE`
4532 When set to "1", this variable allows to bundle the Linux kernel
4533 and the Device Tree Binary together in a single file.
4534
4535 This feature is currently only supported on the "arm" (32 bit)
4536 architecture.
4537
4538 This variable is set to "0" by default by the
4539 :ref:`ref-classes-kernel-devicetree` class.
3854 4540
3855 :term:`KERNEL_DTB_LINK_NAME` 4541 :term:`KERNEL_DTB_LINK_NAME`
3856 The link name of the kernel device tree binary (DTB). This variable 4542 The link name of the kernel device tree binary (DTB). This variable
3857 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 4543 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
3858 follows: 4544 follows::
3859 ::
3860 4545
3861 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4546 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3862 4547
3863 The 4548 The
3864 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in 4549 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
3865 the same file, has the following value: 4550 the same file, has the following value::
3866 ::
3867 4551
3868 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4552 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3869 4553
@@ -3872,26 +4556,37 @@ system and gives an overview of their function and contents.
3872 4556
3873 :term:`KERNEL_DTB_NAME` 4557 :term:`KERNEL_DTB_NAME`
3874 The base name of the kernel device tree binary (DTB). This variable 4558 The base name of the kernel device tree binary (DTB). This variable
3875 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 4559 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
3876 follows: 4560 follows::
3877 ::
3878 4561
3879 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4562 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3880 4563
3881 The value of the :term:`KERNEL_ARTIFACT_NAME` 4564 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
3882 variable, which is set in the same file, has the following value: 4565
3883 :: 4566 :term:`KERNEL_DTBDEST`
4567 This variable, used by the :ref:`ref-classes-kernel-devicetree`
4568 class, allows to change the installation directory of the DTB
4569 (Device Tree Binary) files.
3884 4570
3885 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 4571 It is set by default to "${KERNEL_IMAGEDEST}" by the
4572 :ref:`ref-classes-kernel` class.
4573
4574 :term:`KERNEL_DTBVENDORED`
4575 This variable, used by the :ref:`ref-classes-kernel-devicetree`,
4576 allows to ignore vendor subdirectories when installing DTB
4577 (Device Tree Binary) files, when it is set to "false".
4578
4579 To keep vendor subdirectories, set this variable to "true".
4580
4581 It is set by default to "false" by the :ref:`ref-classes-kernel` class.
3886 4582
3887 :term:`KERNEL_DTC_FLAGS` 4583 :term:`KERNEL_DTC_FLAGS`
3888 Specifies the ``dtc`` flags that are passed to the Linux kernel build 4584 Specifies the ``dtc`` flags that are passed to the Linux kernel build
3889 system when generating the device trees (via ``DTC_FLAGS`` environment 4585 system when generating the device trees (via ``DTC_FLAGS`` environment
3890 variable). 4586 variable).
3891 4587
3892 In order to use this variable, the 4588 In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
3893 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must 4589 class must be inherited.
3894 be inherited.
3895 4590
3896 :term:`KERNEL_EXTRA_ARGS` 4591 :term:`KERNEL_EXTRA_ARGS`
3897 Specifies additional ``make`` command-line arguments the OpenEmbedded 4592 Specifies additional ``make`` command-line arguments the OpenEmbedded
@@ -3902,40 +4597,37 @@ system and gives an overview of their function and contents.
3902 system, the default Board Support Packages (BSPs) 4597 system, the default Board Support Packages (BSPs)
3903 :term:`Metadata` is provided through the 4598 :term:`Metadata` is provided through the
3904 :term:`KMACHINE` and :term:`KBRANCH` 4599 :term:`KMACHINE` and :term:`KBRANCH`
3905 variables. You can use the ``KERNEL_FEATURES`` variable from within 4600 variables. You can use the :term:`KERNEL_FEATURES` variable from within
3906 the kernel recipe or kernel append file to further add metadata for 4601 the kernel recipe or kernel append file to further add metadata for
3907 all BSPs or specific BSPs. 4602 all BSPs or specific BSPs.
3908 4603
3909 The metadata you add through this variable includes config fragments 4604 The metadata you add through this variable includes config fragments
3910 and features descriptions, which usually includes patches as well as 4605 and features descriptions, which usually includes patches as well as
3911 config fragments. You typically override the ``KERNEL_FEATURES`` 4606 config fragments. You typically override the :term:`KERNEL_FEATURES`
3912 variable for a specific machine. In this way, you can provide 4607 variable for a specific machine. In this way, you can provide
3913 validated, but optional, sets of kernel configurations and features. 4608 validated, but optional, sets of kernel configurations and features.
3914 4609
3915 For example, the following example from the ``linux-yocto-rt_4.12`` 4610 For example, the following example from the ``linux-yocto-rt_4.12``
3916 kernel recipe adds "netfilter" and "taskstats" features to all BSPs 4611 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
3917 as well as "virtio" configurations to all QEMU machines. The last two 4612 as well as "virtio" configurations to all QEMU machines. The last two
3918 statements add specific configurations to targeted machine types: 4613 statements add specific configurations to targeted machine types::
3919 ::
3920 4614
3921 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" 4615 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
3922 KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" 4616 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
3923 KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc" 4617 KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
3924 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" 4618 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
3925 KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc" 4619 KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"
3926 4620
3927 :term:`KERNEL_FIT_LINK_NAME` 4621 :term:`KERNEL_FIT_LINK_NAME`
3928 The link name of the kernel flattened image tree (FIT) image. This 4622 The link name of the kernel flattened image tree (FIT) image. This
3929 variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` 4623 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
3930 file as follows: 4624 file as follows::
3931 ::
3932 4625
3933 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4626 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3934 4627
3935 The value of the 4628 The value of the
3936 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4629 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3937 file, has the following value: 4630 file, has the following value::
3938 ::
3939 4631
3940 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4632 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3941 4633
@@ -3944,29 +4636,22 @@ system and gives an overview of their function and contents.
3944 4636
3945 :term:`KERNEL_FIT_NAME` 4637 :term:`KERNEL_FIT_NAME`
3946 The base name of the kernel flattened image tree (FIT) image. This 4638 The base name of the kernel flattened image tree (FIT) image. This
3947 variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` 4639 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
3948 file as follows: 4640 file as follows::
3949 ::
3950 4641
3951 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4642 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3952 4643
3953 The value of the :term:`KERNEL_ARTIFACT_NAME` 4644 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
3954 variable, which is set in the same file, has the following value:
3955 ::
3956
3957 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3958 4645
3959 :term:`KERNEL_IMAGE_LINK_NAME` 4646 :term:`KERNEL_IMAGE_LINK_NAME`
3960 The link name for the kernel image. This variable is set in the 4647 The link name for the kernel image. This variable is set in the
3961 ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 4648 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
3962 ::
3963 4649
3964 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 4650 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3965 4651
3966 The value of 4652 The value of
3967 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 4653 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3968 file, has the following value: 4654 file, has the following value::
3969 ::
3970 4655
3971 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 4656 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3972 4657
@@ -3975,12 +4660,12 @@ system and gives an overview of their function and contents.
3975 4660
3976 :term:`KERNEL_IMAGE_MAXSIZE` 4661 :term:`KERNEL_IMAGE_MAXSIZE`
3977 Specifies the maximum size of the kernel image file in kilobytes. If 4662 Specifies the maximum size of the kernel image file in kilobytes. If
3978 ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is 4663 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is
3979 checked against the set value during the 4664 checked against the set value during the
3980 :ref:`ref-tasks-sizecheck` task. The task fails if 4665 :ref:`ref-tasks-sizecheck` task. The task fails if
3981 the kernel image file is larger than the setting. 4666 the kernel image file is larger than the setting.
3982 4667
3983 ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a 4668 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a
3984 limited amount of space in which the kernel image must be stored. 4669 limited amount of space in which the kernel image must be stored.
3985 4670
3986 By default, this variable is not set, which means the size of the 4671 By default, this variable is not set, which means the size of the
@@ -3988,17 +4673,11 @@ system and gives an overview of their function and contents.
3988 4673
3989 :term:`KERNEL_IMAGE_NAME` 4674 :term:`KERNEL_IMAGE_NAME`
3990 The base name of the kernel image. This variable is set in the 4675 The base name of the kernel image. This variable is set in the
3991 ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 4676 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
3992 ::
3993 4677
3994 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" 4678 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3995 4679
3996 The value of the 4680 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
3997 :term:`KERNEL_ARTIFACT_NAME` variable,
3998 which is set in the same file, has the following value:
3999 ::
4000
4001 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4002 4681
4003 :term:`KERNEL_IMAGETYPE` 4682 :term:`KERNEL_IMAGETYPE`
4004 The type of kernel to build for a device, usually set by the machine 4683 The type of kernel to build for a device, usually set by the machine
@@ -4006,9 +4685,12 @@ system and gives an overview of their function and contents.
4006 when building the kernel and is passed to ``make`` as the target to 4685 when building the kernel and is passed to ``make`` as the target to
4007 build. 4686 build.
4008 4687
4009 If you want to build an alternate kernel image type in addition to that 4688 To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`.
4010 specified by ``KERNEL_IMAGETYPE``, use the :term:`KERNEL_ALT_IMAGETYPE` 4689
4011 variable. 4690 :term:`KERNEL_IMAGETYPES`
4691 Lists additional types of kernel images to build for a device in addition
4692 to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the
4693 machine configuration files.
4012 4694
4013 :term:`KERNEL_MODULE_AUTOLOAD` 4695 :term:`KERNEL_MODULE_AUTOLOAD`
4014 Lists kernel modules that need to be auto-loaded during boot. 4696 Lists kernel modules that need to be auto-loaded during boot.
@@ -4018,23 +4700,21 @@ system and gives an overview of their function and contents.
4018 This variable replaces the deprecated :term:`module_autoload` 4700 This variable replaces the deprecated :term:`module_autoload`
4019 variable. 4701 variable.
4020 4702
4021 You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it 4703 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it
4022 can be recognized by the kernel recipe or by an out-of-tree kernel 4704 can be recognized by the kernel recipe or by an out-of-tree kernel
4023 module recipe (e.g. a machine configuration file, a distribution 4705 module recipe (e.g. a machine configuration file, a distribution
4024 configuration file, an append file for the recipe, or the recipe 4706 configuration file, an append file for the recipe, or the recipe
4025 itself). 4707 itself).
4026 4708
4027 Specify it as follows: 4709 Specify it as follows::
4028 ::
4029 4710
4030 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" 4711 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
4031 4712
4032 Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build 4713 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build
4033 system to populate the ``/etc/modules-load.d/modname.conf`` file with 4714 system to populate the ``/etc/modules-load.d/modname.conf`` file with
4034 the list of modules to be auto-loaded on boot. The modules appear 4715 the list of modules to be auto-loaded on boot. The modules appear
4035 one-per-line in the file. Here is an example of the most common use 4716 one-per-line in the file. Here is an example of the most common use
4036 case: 4717 case::
4037 ::
4038 4718
4039 KERNEL_MODULE_AUTOLOAD += "module_name" 4719 KERNEL_MODULE_AUTOLOAD += "module_name"
4040 4720
@@ -4048,56 +4728,65 @@ system and gives an overview of their function and contents.
4048 provide those module configurations, see the 4728 provide those module configurations, see the
4049 :term:`module_conf_* <module_conf>` variable. 4729 :term:`module_conf_* <module_conf>` variable.
4050 4730
4731 :term:`KERNEL_PACKAGE_NAME`
4732 Specifies the base name of the kernel packages, such as "kernel"
4733 in the kernel packages such as "kernel-modules", "kernel-image" and
4734 "kernel-dbg".
4735
4736 The default value for this variable is set to "kernel" by the
4737 :ref:`ref-classes-kernel` class.
4738
4051 :term:`KERNEL_PATH` 4739 :term:`KERNEL_PATH`
4052 The location of the kernel sources. This variable is set to the value 4740 The location of the kernel sources. This variable is set to the value
4053 of the :term:`STAGING_KERNEL_DIR` within 4741 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4054 the :ref:`module <ref-classes-module>` class. For information on 4742 class. For information on how this variable is used, see the
4055 how this variable is used, see the
4056 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4743 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
4057 section in the Yocto Project Linux Kernel Development Manual. 4744 section in the Yocto Project Linux Kernel Development Manual.
4058 4745
4059 To help maximize compatibility with out-of-tree drivers used to build 4746 To help maximize compatibility with out-of-tree drivers used to build
4060 modules, the OpenEmbedded build system also recognizes and uses the 4747 modules, the OpenEmbedded build system also recognizes and uses the
4061 :term:`KERNEL_SRC` variable, which is identical to 4748 :term:`KERNEL_SRC` variable, which is identical to
4062 the ``KERNEL_PATH`` variable. Both variables are common variables 4749 the :term:`KERNEL_PATH` variable. Both variables are common variables
4063 used by external Makefiles to point to the kernel source directory. 4750 used by external Makefiles to point to the kernel source directory.
4064 4751
4065 :term:`KERNEL_SRC` 4752 :term:`KERNEL_SRC`
4066 The location of the kernel sources. This variable is set to the value 4753 The location of the kernel sources. This variable is set to the value
4067 of the :term:`STAGING_KERNEL_DIR` within 4754 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4068 the :ref:`module <ref-classes-module>` class. For information on 4755 class. For information on how this variable is used, see the
4069 how this variable is used, see the
4070 ":ref:`kernel-dev/common:incorporating out-of-tree modules`" 4756 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
4071 section in the Yocto Project Linux Kernel Development Manual. 4757 section in the Yocto Project Linux Kernel Development Manual.
4072 4758
4073 To help maximize compatibility with out-of-tree drivers used to build 4759 To help maximize compatibility with out-of-tree drivers used to build
4074 modules, the OpenEmbedded build system also recognizes and uses the 4760 modules, the OpenEmbedded build system also recognizes and uses the
4075 :term:`KERNEL_PATH` variable, which is identical 4761 :term:`KERNEL_PATH` variable, which is identical
4076 to the ``KERNEL_SRC`` variable. Both variables are common variables 4762 to the :term:`KERNEL_SRC` variable. Both variables are common variables
4077 used by external Makefiles to point to the kernel source directory. 4763 used by external Makefiles to point to the kernel source directory.
4078 4764
4765 :term:`KERNEL_STRIP`
4766 Allows to specific which ``strip`` command to use to strip the kernel
4767 binary, typically either GNU binutils ``strip`` or ``llvm-strip``.
4768
4079 :term:`KERNEL_VERSION` 4769 :term:`KERNEL_VERSION`
4080 Specifies the version of the kernel as extracted from ``version.h`` 4770 Specifies the version of the kernel as extracted from ``version.h``
4081 or ``utsrelease.h`` within the kernel sources. Effects of setting 4771 or ``utsrelease.h`` within the kernel sources. Effects of setting
4082 this variable do not take affect until the kernel has been 4772 this variable do not take effect until the kernel has been
4083 configured. Consequently, attempting to refer to this variable in 4773 configured. Consequently, attempting to refer to this variable in
4084 contexts prior to configuration will not work. 4774 contexts prior to configuration will not work.
4085 4775
4086 :term:`KERNELDEPMODDEPEND` 4776 :term:`KERNELDEPMODDEPEND`
4087 Specifies whether the data referenced through 4777 Specifies whether the data referenced through
4088 :term:`PKGDATA_DIR` is needed or not. The 4778 :term:`PKGDATA_DIR` is needed or not.
4089 ``KERNELDEPMODDEPEND`` does not control whether or not that data 4779 :term:`KERNELDEPMODDEPEND` does not control whether or not that data
4090 exists, but simply whether or not it is used. If you do not need to 4780 exists, but simply whether or not it is used. If you do not need to
4091 use the data, set the ``KERNELDEPMODDEPEND`` variable in your 4781 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
4092 ``initramfs`` recipe. Setting the variable there when the data is not 4782 :term:`Initramfs` recipe. Setting the variable there when the data is not
4093 needed avoids a potential dependency loop. 4783 needed avoids a potential dependency loop.
4094 4784
4095 :term:`KFEATURE_DESCRIPTION` 4785 :term:`KFEATURE_DESCRIPTION`
4096 Provides a short description of a configuration fragment. You use 4786 Provides a short description of a configuration fragment. You use
4097 this variable in the ``.scc`` file that describes a configuration 4787 this variable in the ``.scc`` file that describes a configuration
4098 fragment file. Here is the variable used in a file named ``smp.scc`` 4788 fragment file. Here is the variable used in a file named ``smp.scc``
4099 to describe SMP being enabled: 4789 to describe SMP being enabled::
4100 ::
4101 4790
4102 define KFEATURE_DESCRIPTION "Enable SMP" 4791 define KFEATURE_DESCRIPTION "Enable SMP"
4103 4792
@@ -4108,23 +4797,22 @@ system and gives an overview of their function and contents.
4108 OpenEmbedded build system understands as ``core2-32-intel-common`` 4797 OpenEmbedded build system understands as ``core2-32-intel-common``
4109 goes by a different name in the Linux Yocto kernel. The kernel 4798 goes by a different name in the Linux Yocto kernel. The kernel
4110 understands that machine as ``intel-core2-32``. For cases like these, 4799 understands that machine as ``intel-core2-32``. For cases like these,
4111 the ``KMACHINE`` variable maps the kernel machine name to the 4800 the :term:`KMACHINE` variable maps the kernel machine name to the
4112 OpenEmbedded build system machine name. 4801 OpenEmbedded build system machine name.
4113 4802
4114 These mappings between different names occur in the Yocto Linux 4803 These mappings between different names occur in the Yocto Linux
4115 Kernel's ``meta`` branch. As an example take a look in the 4804 Kernel's ``meta`` branch. As an example take a look in the
4116 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: 4805 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
4117 :: 4806
4118 4807 LINUX_VERSION:core2-32-intel-common = "3.19.0"
4119 LINUX_VERSION_core2-32-intel-common = "3.19.0" 4808 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
4120 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" 4809 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
4121 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" 4810 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
4122 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" 4811 KMACHINE:core2-32-intel-common = "intel-core2-32"
4123 KMACHINE_core2-32-intel-common = "intel-core2-32" 4812 KBRANCH:core2-32-intel-common = "standard/base"
4124 KBRANCH_core2-32-intel-common = "standard/base" 4813 KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}"
4125 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" 4814
4126 4815 The :term:`KMACHINE` statement says
4127 The ``KMACHINE`` statement says
4128 that the kernel understands the machine name as "intel-core2-32". 4816 that the kernel understands the machine name as "intel-core2-32".
4129 However, the OpenEmbedded build system understands the machine as 4817 However, the OpenEmbedded build system understands the machine as
4130 "core2-32-intel-common". 4818 "core2-32-intel-common".
@@ -4137,7 +4825,7 @@ system and gives an overview of their function and contents.
4137 Yocto Project Linux Kernel Development Manual for more information on 4825 Yocto Project Linux Kernel Development Manual for more information on
4138 kernel types. 4826 kernel types.
4139 4827
4140 You define the ``KTYPE`` variable in the 4828 You define the :term:`KTYPE` variable in the
4141 :ref:`kernel-dev/advanced:bsp descriptions`. The 4829 :ref:`kernel-dev/advanced:bsp descriptions`. The
4142 value you use must match the value used for the 4830 value you use must match the value used for the
4143 :term:`LINUX_KERNEL_TYPE` value used by the 4831 :term:`LINUX_KERNEL_TYPE` value used by the
@@ -4146,14 +4834,13 @@ system and gives an overview of their function and contents.
4146 :term:`LABELS` 4834 :term:`LABELS`
4147 Provides a list of targets for automatic configuration. 4835 Provides a list of targets for automatic configuration.
4148 4836
4149 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 4837 See the :ref:`ref-classes-grub-efi` class for more
4150 information on how this variable is used. 4838 information on how this variable is used.
4151 4839
4152 :term:`LAYERDEPENDS` 4840 :term:`LAYERDEPENDS`
4153 Lists the layers, separated by spaces, on which this recipe depends. 4841 Lists the layers, separated by spaces, on which this recipe depends.
4154 Optionally, you can specify a specific layer version for a dependency 4842 Optionally, you can specify a specific layer version for a dependency
4155 by adding it to the end of the layer name. Here is an example: 4843 by adding it to the end of the layer name. Here is an example::
4156 ::
4157 4844
4158 LAYERDEPENDS_mylayer = "anotherlayer (=3)" 4845 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4159 4846
@@ -4172,14 +4859,16 @@ system and gives an overview of their function and contents.
4172 available outside of ``layer.conf`` and references are expanded 4859 available outside of ``layer.conf`` and references are expanded
4173 immediately when parsing of the file completes. 4860 immediately when parsing of the file completes.
4174 4861
4862 :term:`LAYERDIR_RE`
4863 See :term:`bitbake:LAYERDIR_RE` in the BitBake manual.
4864
4175 :term:`LAYERRECOMMENDS` 4865 :term:`LAYERRECOMMENDS`
4176 Lists the layers, separated by spaces, recommended for use with this 4866 Lists the layers, separated by spaces, recommended for use with this
4177 layer. 4867 layer.
4178 4868
4179 Optionally, you can specify a specific layer version for a 4869 Optionally, you can specify a specific layer version for a
4180 recommendation by adding the version to the end of the layer name. 4870 recommendation by adding the version to the end of the layer name.
4181 Here is an example: 4871 Here is an example::
4182 ::
4183 4872
4184 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" 4873 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
4185 4874
@@ -4191,32 +4880,7 @@ system and gives an overview of their function and contents.
4191 ``LAYERRECOMMENDS_mylayer``). 4880 ``LAYERRECOMMENDS_mylayer``).
4192 4881
4193 :term:`LAYERSERIES_COMPAT` 4882 :term:`LAYERSERIES_COMPAT`
4194 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which 4883 See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual.
4195 a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable
4196 allows the layer maintainer to indicate which combinations of the
4197 layer and OE-Core can be expected to work. The variable gives the
4198 system a way to detect when a layer has not been tested with new
4199 releases of OE-Core (e.g. the layer is not maintained).
4200
4201 To specify the OE-Core versions for which a layer is compatible, use
4202 this variable in your layer's ``conf/layer.conf`` configuration file.
4203 For the list, use the Yocto Project
4204 :yocto_wiki:`Release Name </Releases>` (e.g.
4205 &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the
4206 layer, use a space-separated list:
4207 ::
4208
4209 LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
4210
4211 .. note::
4212
4213 Setting ``LAYERSERIES_COMPAT`` is required by the Yocto Project
4214 Compatible version 2 standard.
4215 The OpenEmbedded build system produces a warning if the variable
4216 is not set for any given layer.
4217
4218 See the ":ref:`dev-manual/common-tasks:creating your own layer`"
4219 section in the Yocto Project Development Tasks Manual.
4220 4884
4221 :term:`LAYERVERSION` 4885 :term:`LAYERVERSION`
4222 Optionally specifies the version of a layer as a single number. You 4886 Optionally specifies the version of a layer as a single number. You
@@ -4234,7 +4898,7 @@ system and gives an overview of their function and contents.
4234 to an environment variable and thus made visible to the software 4898 to an environment variable and thus made visible to the software
4235 being built during the compilation step. 4899 being built during the compilation step.
4236 4900
4237 Default initialization for ``LDFLAGS`` varies depending on what is 4901 Default initialization for :term:`LDFLAGS` varies depending on what is
4238 being built: 4902 being built:
4239 4903
4240 - :term:`TARGET_LDFLAGS` when building for the 4904 - :term:`TARGET_LDFLAGS` when building for the
@@ -4248,10 +4912,11 @@ system and gives an overview of their function and contents.
4248 4912
4249 :term:`LEAD_SONAME` 4913 :term:`LEAD_SONAME`
4250 Specifies the lead (or primary) compiled library file (i.e. ``.so``) 4914 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
4251 that the :ref:`debian <ref-classes-debian>` class applies its 4915 that the :ref:`ref-classes-debian` class applies its
4252 naming policy to given a recipe that packages multiple libraries. 4916 naming policy to given a recipe that packages multiple libraries.
4253 4917
4254 This variable works in conjunction with the ``debian`` class. 4918 This variable works in conjunction with the :ref:`ref-classes-debian`
4919 class.
4255 4920
4256 :term:`LIC_FILES_CHKSUM` 4921 :term:`LIC_FILES_CHKSUM`
4257 Checksums of the license text in the recipe source code. 4922 Checksums of the license text in the recipe source code.
@@ -4264,7 +4929,7 @@ system and gives an overview of their function and contents.
4264 This variable must be defined for all recipes (unless 4929 This variable must be defined for all recipes (unless
4265 :term:`LICENSE` is set to "CLOSED"). 4930 :term:`LICENSE` is set to "CLOSED").
4266 4931
4267 For more information, see the ":ref:`dev-manual/common-tasks:tracking license changes`" 4932 For more information, see the ":ref:`dev-manual/licenses:tracking license changes`"
4268 section in the Yocto Project Development Tasks Manual. 4933 section in the Yocto Project Development Tasks Manual.
4269 4934
4270 :term:`LICENSE` 4935 :term:`LICENSE`
@@ -4275,8 +4940,8 @@ system and gives an overview of their function and contents.
4275 - Separate license names using \| (pipe) when there is a choice 4940 - Separate license names using \| (pipe) when there is a choice
4276 between licenses. 4941 between licenses.
4277 4942
4278 - Separate license names using & (ampersand) when multiple licenses 4943 - Separate license names using & (ampersand) when there are
4279 exist that cover different parts of the source. 4944 multiple licenses for different parts of the source.
4280 4945
4281 - You can use spaces between license names. 4946 - You can use spaces between license names.
4282 4947
@@ -4285,12 +4950,11 @@ system and gives an overview of their function and contents.
4285 :term:`SPDXLICENSEMAP` flag names defined in 4950 :term:`SPDXLICENSEMAP` flag names defined in
4286 ``meta/conf/licenses.conf``. 4951 ``meta/conf/licenses.conf``.
4287 4952
4288 Here are some examples: 4953 Here are some examples::
4289 ::
4290 4954
4291 LICENSE = "LGPLv2.1 | GPLv3" 4955 LICENSE = "LGPL-2.1-only | GPL-3.0-only"
4292 LICENSE = "MPL-1 & LGPLv2.1" 4956 LICENSE = "MPL-1.0 & LGPL-2.1-only"
4293 LICENSE = "GPLv2+" 4957 LICENSE = "GPL-2.0-or-later"
4294 4958
4295 The first example is from the 4959 The first example is from the
4296 recipes for Qt, which the user may choose to distribute under either 4960 recipes for Qt, which the user may choose to distribute under either
@@ -4303,19 +4967,18 @@ system and gives an overview of their function and contents.
4303 situations where components of the output have different licenses. 4967 situations where components of the output have different licenses.
4304 For example, a piece of software whose code is licensed under GPLv2 4968 For example, a piece of software whose code is licensed under GPLv2
4305 but has accompanying documentation licensed under the GNU Free 4969 but has accompanying documentation licensed under the GNU Free
4306 Documentation License 1.2 could be specified as follows: 4970 Documentation License 1.2 could be specified as follows::
4307 ::
4308 4971
4309 LICENSE = "GFDL-1.2 & GPLv2" 4972 LICENSE = "GFDL-1.2 & GPL-2.0-only"
4310 LICENSE_${PN} = "GPLv2" 4973 LICENSE:${PN} = "GPL-2.0.only"
4311 LICENSE_${PN}-doc = "GFDL-1.2" 4974 LICENSE:${PN}-doc = "GFDL-1.2"
4312 4975
4313 :term:`LICENSE_CREATE_PACKAGE` 4976 :term:`LICENSE_CREATE_PACKAGE`
4314 Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded 4977 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded
4315 build system to create an extra package (i.e. 4978 build system to create an extra package (i.e.
4316 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add 4979 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
4317 those packages to the 4980 those packages to the
4318 :term:`RRECOMMENDS`\ ``_${PN}``. 4981 :term:`RRECOMMENDS`\ ``:${PN}``.
4319 4982
4320 The ``${PN}-lic`` package installs a directory in 4983 The ``${PN}-lic`` package installs a directory in
4321 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base 4984 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
@@ -4330,37 +4993,52 @@ system and gives an overview of their function and contents.
4330 For related information on providing license text, see the 4993 For related information on providing license text, see the
4331 :term:`COPY_LIC_DIRS` variable, the 4994 :term:`COPY_LIC_DIRS` variable, the
4332 :term:`COPY_LIC_MANIFEST` variable, and the 4995 :term:`COPY_LIC_MANIFEST` variable, and the
4333 ":ref:`dev-manual/common-tasks:providing license text`" 4996 ":ref:`dev-manual/licenses:providing license text`"
4334 section in the Yocto Project Development Tasks Manual. 4997 section in the Yocto Project Development Tasks Manual.
4335 4998
4336 :term:`LICENSE_FLAGS` 4999 :term:`LICENSE_FLAGS`
4337 Specifies additional flags for a recipe you must whitelist through 5000 Specifies additional flags for a recipe you must allow through
4338 :term:`LICENSE_FLAGS_WHITELIST` in 5001 :term:`LICENSE_FLAGS_ACCEPTED` in
4339 order to allow the recipe to be built. When providing multiple flags, 5002 order for the recipe to be built. When providing multiple flags,
4340 separate them with spaces. 5003 separate them with spaces.
4341 5004
4342 This value is independent of :term:`LICENSE` and is 5005 This value is independent of :term:`LICENSE` and is
4343 typically used to mark recipes that might require additional licenses 5006 typically used to mark recipes that might require additional licenses
4344 in order to be used in a commercial product. For more information, 5007 in order to be used in a commercial product. For more information,
4345 see the 5008 see the
4346 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" 5009 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
4347 section in the Yocto Project Development Tasks Manual. 5010 section in the Yocto Project Development Tasks Manual.
4348 5011
4349 :term:`LICENSE_FLAGS_WHITELIST` 5012 :term:`LICENSE_FLAGS_ACCEPTED`
4350 Lists license flags that when specified in 5013 Lists license flags that when specified in
4351 :term:`LICENSE_FLAGS` within a recipe should not 5014 :term:`LICENSE_FLAGS` within a recipe should not
4352 prevent that recipe from being built. This practice is otherwise 5015 prevent that recipe from being built. For more information, see the
4353 known as "whitelisting" license flags. For more information, see the 5016 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
4354 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
4355 section in the Yocto Project Development Tasks Manual. 5017 section in the Yocto Project Development Tasks Manual.
4356 5018
5019 :term:`LICENSE_FLAGS_DETAILS`
5020 Adds details about a flag in :term:`LICENSE_FLAGS`. This way,
5021 if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`,
5022 the error message will be more informative, containing the specified
5023 extra details.
5024
5025 For example, a recipe with an EULA may set::
5026
5027 LICENSE_FLAGS = "FooBar-EULA"
5028 LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula."
5029
5030 If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the
5031 error message is more useful::
5032
5033 Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED.
5034 For further details, see https://example.com/eula.
5035
4357 :term:`LICENSE_PATH` 5036 :term:`LICENSE_PATH`
4358 Path to additional licenses used during the build. By default, the 5037 Path to additional licenses used during the build. By default, the
4359 OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the 5038 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
4360 directory that holds common license text used during the build. The 5039 directory that holds common license text used during the build. The
4361 ``LICENSE_PATH`` variable allows you to extend that location to other 5040 :term:`LICENSE_PATH` variable allows you to extend that location to other
4362 areas that have additional licenses: 5041 areas that have additional licenses::
4363 ::
4364 5042
4365 LICENSE_PATH += "path-to-additional-common-licenses" 5043 LICENSE_PATH += "path-to-additional-common-licenses"
4366 5044
@@ -4372,9 +5050,9 @@ system and gives an overview of their function and contents.
4372 Yocto Project Linux Kernel Development Manual for more information on 5050 Yocto Project Linux Kernel Development Manual for more information on
4373 kernel types. 5051 kernel types.
4374 5052
4375 If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to 5053 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to
4376 "standard". Together with :term:`KMACHINE`, the 5054 "standard". Together with :term:`KMACHINE`, the
4377 ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by 5055 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by
4378 the kernel tools to find the appropriate description within the 5056 the kernel tools to find the appropriate description within the
4379 kernel :term:`Metadata` with which to build out the sources 5057 kernel :term:`Metadata` with which to build out the sources
4380 and configuration. 5058 and configuration.
@@ -4384,14 +5062,12 @@ system and gives an overview of their function and contents.
4384 being built using the OpenEmbedded build system is based. You define 5062 being built using the OpenEmbedded build system is based. You define
4385 this variable in the kernel recipe. For example, the 5063 this variable in the kernel recipe. For example, the
4386 ``linux-yocto-3.4.bb`` kernel recipe found in 5064 ``linux-yocto-3.4.bb`` kernel recipe found in
4387 ``meta/recipes-kernel/linux`` defines the variables as follows: 5065 ``meta/recipes-kernel/linux`` defines the variables as follows::
4388 ::
4389 5066
4390 LINUX_VERSION ?= "3.4.24" 5067 LINUX_VERSION ?= "3.4.24"
4391 5068
4392 The ``LINUX_VERSION`` variable is used to define :term:`PV` 5069 The :term:`LINUX_VERSION` variable is used to define :term:`PV`
4393 for the recipe: 5070 for the recipe::
4394 ::
4395 5071
4396 PV = "${LINUX_VERSION}+git${SRCPV}" 5072 PV = "${LINUX_VERSION}+git${SRCPV}"
4397 5073
@@ -4399,16 +5075,14 @@ system and gives an overview of their function and contents.
4399 A string extension compiled into the version string of the Linux 5075 A string extension compiled into the version string of the Linux
4400 kernel built with the OpenEmbedded build system. You define this 5076 kernel built with the OpenEmbedded build system. You define this
4401 variable in the kernel recipe. For example, the linux-yocto kernel 5077 variable in the kernel recipe. For example, the linux-yocto kernel
4402 recipes all define the variable as follows: 5078 recipes all define the variable as follows::
4403 ::
4404 5079
4405 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" 5080 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
4406 5081
4407 Defining this variable essentially sets the Linux kernel 5082 Defining this variable essentially sets the Linux kernel
4408 configuration item ``CONFIG_LOCALVERSION``, which is visible through 5083 configuration item ``CONFIG_LOCALVERSION``, which is visible through
4409 the ``uname`` command. Here is an example that shows the extension 5084 the ``uname`` command. Here is an example that shows the extension
4410 assuming it was set as previously shown: 5085 assuming it was set as previously shown::
4411 ::
4412 5086
4413 $ uname -r 5087 $ uname -r
4414 3.7.0-rc8-custom 5088 3.7.0-rc8-custom
@@ -4422,24 +5096,22 @@ system and gives an overview of their function and contents.
4422 5096
4423 :term:`MACHINE` 5097 :term:`MACHINE`
4424 Specifies the target device for which the image is built. You define 5098 Specifies the target device for which the image is built. You define
4425 ``MACHINE`` in the ``local.conf`` file found in the 5099 :term:`MACHINE` in the ``local.conf`` file found in the
4426 :term:`Build Directory`. By default, ``MACHINE`` is set to 5100 :term:`Build Directory`. By default, :term:`MACHINE` is set to
4427 "qemux86", which is an x86-based architecture machine to be emulated 5101 "qemux86", which is an x86-based architecture machine to be emulated
4428 using QEMU: 5102 using QEMU::
4429 ::
4430 5103
4431 MACHINE ?= "qemux86" 5104 MACHINE ?= "qemux86"
4432 5105
4433 The variable corresponds to a machine configuration file of the same 5106 The variable corresponds to a machine configuration file of the same
4434 name, through which machine-specific configurations are set. Thus, 5107 name, through which machine-specific configurations are set. Thus,
4435 when ``MACHINE`` is set to "qemux86" there exists the corresponding 5108 when :term:`MACHINE` is set to "qemux86", the corresponding
4436 ``qemux86.conf`` machine configuration file, which can be found in 5109 ``qemux86.conf`` machine configuration file can be found in
4437 the :term:`Source Directory` in 5110 the :term:`Source Directory` in
4438 ``meta/conf/machine``. 5111 ``meta/conf/machine``.
4439 5112
4440 The list of machines supported by the Yocto Project as shipped 5113 The list of machines supported by the Yocto Project as shipped
4441 include the following: 5114 include the following::
4442 ::
4443 5115
4444 MACHINE ?= "qemuarm" 5116 MACHINE ?= "qemuarm"
4445 MACHINE ?= "qemuarm64" 5117 MACHINE ?= "qemuarm64"
@@ -4451,7 +5123,6 @@ system and gives an overview of their function and contents.
4451 MACHINE ?= "genericx86" 5123 MACHINE ?= "genericx86"
4452 MACHINE ?= "genericx86-64" 5124 MACHINE ?= "genericx86-64"
4453 MACHINE ?= "beaglebone" 5125 MACHINE ?= "beaglebone"
4454 MACHINE ?= "edgerouter"
4455 5126
4456 The last five are Yocto Project reference hardware 5127 The last five are Yocto Project reference hardware
4457 boards, which are provided in the ``meta-yocto-bsp`` layer. 5128 boards, which are provided in the ``meta-yocto-bsp`` layer.
@@ -4459,13 +5130,13 @@ system and gives an overview of their function and contents.
4459 .. note:: 5130 .. note::
4460 5131
4461 Adding additional Board Support Package (BSP) layers to your 5132 Adding additional Board Support Package (BSP) layers to your
4462 configuration adds new possible settings for ``MACHINE``. 5133 configuration adds new possible settings for :term:`MACHINE`.
4463 5134
4464 :term:`MACHINE_ARCH` 5135 :term:`MACHINE_ARCH`
4465 Specifies the name of the machine-specific architecture. This 5136 Specifies the name of the machine-specific architecture. This
4466 variable is set automatically from :term:`MACHINE` or 5137 variable is set automatically from :term:`MACHINE` or
4467 :term:`TUNE_PKGARCH`. You should not hand-edit 5138 :term:`TUNE_PKGARCH`. You should not hand-edit
4468 the ``MACHINE_ARCH`` variable. 5139 the :term:`MACHINE_ARCH` variable.
4469 5140
4470 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` 5141 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
4471 A list of required machine-specific packages to install as part of 5142 A list of required machine-specific packages to install as part of
@@ -4477,7 +5148,7 @@ system and gives an overview of their function and contents.
4477 image. 5148 image.
4478 5149
4479 This variable is similar to the 5150 This variable is similar to the
4480 ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception 5151 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception
4481 that the image being built has a build dependency on the variable's 5152 that the image being built has a build dependency on the variable's
4482 list of packages. In other words, the image will not build if a file 5153 list of packages. In other words, the image will not build if a file
4483 in this list is not found. 5154 in this list is not found.
@@ -4485,8 +5156,7 @@ system and gives an overview of their function and contents.
4485 As an example, suppose the machine for which you are building 5156 As an example, suppose the machine for which you are building
4486 requires ``example-init`` to be run during boot to initialize the 5157 requires ``example-init`` to be run during boot to initialize the
4487 hardware. In this case, you would use the following in the machine's 5158 hardware. In this case, you would use the following in the machine's
4488 ``.conf`` configuration file: 5159 ``.conf`` configuration file::
4489 ::
4490 5160
4491 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" 5161 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4492 5162
@@ -4499,7 +5169,7 @@ system and gives an overview of their function and contents.
4499 on ``packagegroup-core-boot``, including the ``core-image-minimal`` 5169 on ``packagegroup-core-boot``, including the ``core-image-minimal``
4500 image. 5170 image.
4501 5171
4502 This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` 5172 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
4503 variable with the exception that the image being built does not have 5173 variable with the exception that the image being built does not have
4504 a build dependency on the variable's list of packages. In other 5174 a build dependency on the variable's list of packages. In other
4505 words, the image will still build if a package in this list is not 5175 words, the image will still build if a package in this list is not
@@ -4517,8 +5187,7 @@ system and gives an overview of their function and contents.
4517 "recommends" relationship so that in the latter case, the build will 5187 "recommends" relationship so that in the latter case, the build will
4518 not fail due to the missing package. To accomplish this, assuming the 5188 not fail due to the missing package. To accomplish this, assuming the
4519 package for the module was called ``kernel-module-ab123``, you would 5189 package for the module was called ``kernel-module-ab123``, you would
4520 use the following in the machine's ``.conf`` configuration file: 5190 use the following in the machine's ``.conf`` configuration file::
4521 ::
4522 5191
4523 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 5192 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4524 5193
@@ -4542,7 +5211,7 @@ system and gives an overview of their function and contents.
4542 which does not include the ``core-image-minimal`` or 5211 which does not include the ``core-image-minimal`` or
4543 ``core-image-full-cmdline`` images. 5212 ``core-image-full-cmdline`` images.
4544 5213
4545 The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable 5214 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable
4546 with the exception that the image being built has a build dependency 5215 with the exception that the image being built has a build dependency
4547 on the variable's list of packages. In other words, the image will 5216 on the variable's list of packages. In other words, the image will
4548 not build if a file in this list is not found. 5217 not build if a file in this list is not found.
@@ -4554,8 +5223,7 @@ system and gives an overview of their function and contents.
4554 exist, so it is acceptable for the build process to depend upon 5223 exist, so it is acceptable for the build process to depend upon
4555 finding the package. In this case, assuming the package for the 5224 finding the package. In this case, assuming the package for the
4556 firmware was called ``wifidriver-firmware``, you would use the 5225 firmware was called ``wifidriver-firmware``, you would use the
4557 following in the ``.conf`` file for the machine: 5226 following in the ``.conf`` file for the machine::
4558 ::
4559 5227
4560 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" 5228 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4561 5229
@@ -4568,7 +5236,7 @@ system and gives an overview of their function and contents.
4568 which does not include the ``core-image-minimal`` or 5236 which does not include the ``core-image-minimal`` or
4569 ``core-image-full-cmdline`` images. 5237 ``core-image-full-cmdline`` images.
4570 5238
4571 This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable 5239 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable
4572 with the exception that the image being built does not have a build 5240 with the exception that the image being built does not have a build
4573 dependency on the variable's list of packages. In other words, the 5241 dependency on the variable's list of packages. In other words, the
4574 image will build if a file in this list is not found. 5242 image will build if a file in this list is not found.
@@ -4581,8 +5249,7 @@ system and gives an overview of their function and contents.
4581 the build to succeed instead of failing as a result of the package 5249 the build to succeed instead of failing as a result of the package
4582 not being found. To accomplish this, assuming the package for the 5250 not being found. To accomplish this, assuming the package for the
4583 module was called ``kernel-module-examplewifi``, you would use the 5251 module was called ``kernel-module-examplewifi``, you would use the
4584 following in the ``.conf`` file for the machine: 5252 following in the ``.conf`` file for the machine::
4585 ::
4586 5253
4587 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" 5254 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4588 5255
@@ -4598,112 +5265,144 @@ system and gives an overview of their function and contents.
4598 shipped, see the ":ref:`ref-features-machine`" section. 5265 shipped, see the ":ref:`ref-features-machine`" section.
4599 5266
4600 :term:`MACHINE_FEATURES_BACKFILL` 5267 :term:`MACHINE_FEATURES_BACKFILL`
4601 Features to be added to ``MACHINE_FEATURES`` if not also present in 5268 A list of space-separated features to be added to
4602 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. 5269 :term:`MACHINE_FEATURES` if not also present in
5270 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
4603 5271
4604 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 5272 This variable is set in the ``meta/conf/bitbake.conf`` file. It is not
4605 not intended to be user-configurable. It is best to just reference 5273 intended to be user-configurable. It is best to just reference the
4606 the variable to see which machine features are being backfilled for 5274 variable to see which machine features are being
4607 all machine configurations. See the ":ref:`ref-features-backfill`" 5275 :ref:`backfilled <ref-features-backfill>` for all machine configurations.
4608 section for more information.
4609 5276
4610 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` 5277 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
4611 Features from ``MACHINE_FEATURES_BACKFILL`` that should not be 5278 A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL`
4612 backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See 5279 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
4613 the ":ref:`ref-features-backfill`" section for more information. 5280 to :term:`MACHINE_FEATURES`) during the build.
5281
5282 This corresponds to an opt-out mechanism. When new default machine
5283 features are introduced, machine definition maintainers can review
5284 (`consider`) them and decide to exclude them from the
5285 :ref:`backfilled <ref-features-backfill>` features. Therefore, the
5286 combination of :term:`MACHINE_FEATURES_BACKFILL` and
5287 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to
5288 add new default features without breaking existing machine definitions.
4614 5289
4615 :term:`MACHINEOVERRIDES` 5290 :term:`MACHINEOVERRIDES`
4616 A colon-separated list of overrides that apply to the current 5291 A colon-separated list of overrides that apply to the current
4617 machine. By default, this list includes the value of 5292 machine. By default, this list includes the value of
4618 :term:`MACHINE`. 5293 :term:`MACHINE`.
4619 5294
4620 You can extend ``MACHINEOVERRIDES`` to add extra overrides that 5295 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that
4621 should apply to a machine. For example, all machines emulated in QEMU 5296 should apply to a machine. For example, all machines emulated in QEMU
4622 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named 5297 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
4623 ``meta/conf/machine/include/qemu.inc`` that prepends the following 5298 ``meta/conf/machine/include/qemu.inc`` that prepends the following
4624 override to ``MACHINEOVERRIDES``: 5299 override to :term:`MACHINEOVERRIDES`::
4625 ::
4626 5300
4627 MACHINEOVERRIDES =. "qemuall:" 5301 MACHINEOVERRIDES =. "qemuall:"
4628 5302
4629 This 5303 This
4630 override allows variables to be overridden for all machines emulated 5304 override allows variables to be overridden for all machines emulated
4631 in QEMU, like in the following example from the ``connman-conf`` 5305 in QEMU, like in the following example from the ``connman-conf``
4632 recipe: 5306 recipe::
4633 ::
4634 5307
4635 SRC_URI_append_qemuall = " file://wired.config \ 5308 SRC_URI:append:qemuall = " file://wired.config \
4636 file://wired-setup \ 5309 file://wired-setup \
4637 " 5310 "
4638 5311
4639 The underlying mechanism behind 5312 The underlying mechanism behind
4640 ``MACHINEOVERRIDES`` is simply that it is included in the default 5313 :term:`MACHINEOVERRIDES` is simply that it is included in the default
4641 value of :term:`OVERRIDES`. 5314 value of :term:`OVERRIDES`.
4642 5315
4643 :term:`MAINTAINER` 5316 :term:`MAINTAINER`
4644 The email address of the distribution maintainer. 5317 The email address of the distribution maintainer.
4645 5318
5319 :term:`MESON_BUILDTYPE`
5320 Value of the Meson ``--buildtype`` argument used by the
5321 :ref:`ref-classes-meson` class. It defaults to ``debug`` if
5322 :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise.
5323
5324 See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__
5325 for the values you could set in a recipe. Values such as ``plain``,
5326 ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow
5327 you to specify the inclusion of debugging symbols and the compiler
5328 optimizations (none, performance or size).
5329
5330 :term:`MESON_TARGET`
5331 A variable for the :ref:`ref-classes-meson` class, allowing to choose
5332 a Meson target to build in :ref:`ref-tasks-compile`. Otherwise, the
5333 default targets are built.
5334
5335 :term:`METADATA_BRANCH`
5336 The branch currently checked out for the OpenEmbedded-Core layer (path
5337 determined by :term:`COREBASE`).
5338
5339 :term:`METADATA_REVISION`
5340 The revision currently checked out for the OpenEmbedded-Core layer (path
5341 determined by :term:`COREBASE`).
5342
5343 :term:`MIME_XDG_PACKAGES`
5344 The current implementation of the :ref:`ref-classes-mime-xdg`
5345 class cannot detect ``.desktop`` files installed through absolute
5346 symbolic links. Use this setting to make the class create post-install
5347 and post-remove scripts for these packages anyway, to invoke the
5348 ``update-destop-database`` command.
5349
4646 :term:`MIRRORS` 5350 :term:`MIRRORS`
4647 Specifies additional paths from which the OpenEmbedded build system 5351 Specifies additional paths from which the OpenEmbedded build system
4648 gets source code. When the build system searches for source code, it 5352 gets source code. When the build system searches for source code, it
4649 first tries the local download directory. If that location fails, the 5353 first tries the local download directory. If that location fails, the
4650 build system tries locations defined by 5354 build system tries locations defined by
4651 :term:`PREMIRRORS`, the upstream source, and then 5355 :term:`PREMIRRORS`, the upstream source, and then
4652 locations specified by ``MIRRORS`` in that order. 5356 locations specified by :term:`MIRRORS` in that order.
4653 5357
4654 Assuming your distribution (:term:`DISTRO`) is "poky", 5358 The default value for :term:`MIRRORS` is defined in the
4655 the default value for ``MIRRORS`` is defined in the 5359 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
4656 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
4657 5360
4658 :term:`MLPREFIX` 5361 :term:`MLPREFIX`
4659 Specifies a prefix has been added to :term:`PN` to create a 5362 Specifies a prefix has been added to :term:`PN` to create a
4660 special version of a recipe or package (i.e. a Multilib version). The 5363 special version of a recipe or package (i.e. a Multilib version). The
4661 variable is used in places where the prefix needs to be added to or 5364 variable is used in places where the prefix needs to be added to or
4662 removed from a the name (e.g. the :term:`BPN` variable). 5365 removed from a name (e.g. the :term:`BPN` variable).
4663 ``MLPREFIX`` gets set when a prefix has been added to ``PN``. 5366 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`.
4664 5367
4665 .. note:: 5368 .. note::
4666 5369
4667 The "ML" in ``MLPREFIX`` stands for "MultiLib". This representation is 5370 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation
4668 historical and comes from a time when ``nativesdk`` was a suffix 5371 is historical and comes from a time when ":ref:`ref-classes-nativesdk`"
4669 rather than a prefix on the recipe name. When ``nativesdk`` was turned 5372 was a suffix rather than a prefix on the recipe name. When
4670 into a prefix, it made sense to set ``MLPREFIX`` for it as well. 5373 ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense
4671 5374 to set :term:`MLPREFIX` for it as well.
4672 To help understand when ``MLPREFIX`` might be needed, consider when 5375
4673 :term:`BBCLASSEXTEND` is used to provide a 5376 To help understand when :term:`MLPREFIX` might be needed, consider when
4674 ``nativesdk`` version of a recipe in addition to the target version. 5377 :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk`
4675 If that recipe declares build-time dependencies on tasks in other 5378 version of a recipe in addition to the target version. If that recipe
4676 recipes by using :term:`DEPENDS`, then a dependency on 5379 declares build-time dependencies on tasks in other recipes by using
4677 "foo" will automatically get rewritten to a dependency on 5380 :term:`DEPENDS`, then a dependency on "foo" will automatically get
4678 "nativesdk-foo". However, dependencies like the following will not 5381 rewritten to a dependency on "nativesdk-foo". However, dependencies like
4679 get rewritten automatically: 5382 the following will not get rewritten automatically::
4680 ::
4681 5383
4682 do_foo[depends] += "recipe:do_foo" 5384 do_foo[depends] += "recipe:do_foo"
4683 5385
4684 If you want such a dependency to also get transformed, you can do the 5386 If you want such a dependency to also get transformed, you can do the
4685 following: 5387 following::
4686 ::
4687 5388
4688 do_foo[depends] += "${MLPREFIX}recipe:do_foo" 5389 do_foo[depends] += "${MLPREFIX}recipe:do_foo"
4689 5390
4690 module_autoload 5391 :term:`module_autoload`
4691 This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` 5392 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
4692 variable. You should replace all occurrences of ``module_autoload`` 5393 variable. You should replace all occurrences of :term:`module_autoload`
4693 with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: 5394 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
4694 ::
4695 5395
4696 module_autoload_rfcomm = "rfcomm" 5396 module_autoload_rfcomm = "rfcomm"
4697 5397
4698 should now be replaced with: 5398 should now be replaced with::
4699 ::
4700 5399
4701 KERNEL_MODULE_AUTOLOAD += "rfcomm" 5400 KERNEL_MODULE_AUTOLOAD += "rfcomm"
4702 5401
4703 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. 5402 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
4704 5403
4705 module_conf 5404 :term:`module_conf`
4706 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_ 5405 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__
4707 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` 5406 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
4708 file. 5407 file.
4709 5408
@@ -4712,24 +5411,22 @@ system and gives an overview of their function and contents.
4712 configuration file, a distribution configuration file, an append file 5411 configuration file, a distribution configuration file, an append file
4713 for the recipe, or the recipe itself). If you use this variable, you 5412 for the recipe, or the recipe itself). If you use this variable, you
4714 must also be sure to list the module name in the 5413 must also be sure to list the module name in the
4715 :term:`KERNEL_MODULE_AUTOLOAD` 5414 :term:`KERNEL_MODULE_PROBECONF`
4716 variable. 5415 variable.
4717 5416
4718 Here is the general syntax: 5417 Here is the general syntax::
4719 ::
4720 5418
4721 module_conf_module_name = "modprobe.d-syntax" 5419 module_conf_module_name = "modprobe.d-syntax"
4722 5420
4723 You must use the kernel module name override. 5421 You must use the kernel module name override.
4724 5422
4725 Run ``man modprobe.d`` in the shell to find out more information on 5423 Run ``man modprobe.d`` in the shell to find out more information on
4726 the exact syntax you want to provide with ``module_conf``. 5424 the exact syntax you want to provide with :term:`module_conf`.
4727 5425
4728 Including ``module_conf`` causes the OpenEmbedded build system to 5426 Including :term:`module_conf` causes the OpenEmbedded build system to
4729 populate the ``/etc/modprobe.d/modname.conf`` file with 5427 populate the ``/etc/modprobe.d/modname.conf`` file with
4730 ``modprobe.d`` syntax lines. Here is an example that adds the options 5428 ``modprobe.d`` syntax lines. Here is an example that adds the options
4731 ``arg1`` and ``arg2`` to a module named ``mymodule``: 5429 ``arg1`` and ``arg2`` to a module named ``mymodule``::
4732 ::
4733 5430
4734 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" 5431 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
4735 5432
@@ -4743,15 +5440,13 @@ system and gives an overview of their function and contents.
4743 5440
4744 :term:`MODULE_TARBALL_LINK_NAME` 5441 :term:`MODULE_TARBALL_LINK_NAME`
4745 The link name of the kernel module tarball. This variable is set in 5442 The link name of the kernel module tarball. This variable is set in
4746 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 5443 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
4747 ::
4748 5444
4749 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" 5445 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4750 5446
4751 The value 5447 The value
4752 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the 5448 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
4753 same file, has the following value: 5449 same file, has the following value::
4754 ::
4755 5450
4756 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" 5451 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4757 5452
@@ -4759,16 +5454,16 @@ system and gives an overview of their function and contents.
4759 5454
4760 :term:`MODULE_TARBALL_NAME` 5455 :term:`MODULE_TARBALL_NAME`
4761 The base name of the kernel module tarball. This variable is set in 5456 The base name of the kernel module tarball. This variable is set in
4762 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 5457 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
4763 ::
4764 5458
4765 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" 5459 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4766 5460
4767 The value of the :term:`KERNEL_ARTIFACT_NAME` variable, 5461 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
4768 which is set in the same file, has the following value:
4769 ::
4770 5462
4771 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 5463 :term:`MOUNT_BASE`
5464 On non-systemd systems (where ``udev-extraconf`` is being used),
5465 specifies the base directory for auto-mounting filesystems. The
5466 default value is "/run/media".
4772 5467
4773 :term:`MULTIMACH_TARGET_SYS` 5468 :term:`MULTIMACH_TARGET_SYS`
4774 Uniquely identifies the type of the target system for which packages 5469 Uniquely identifies the type of the target system for which packages
@@ -4776,14 +5471,12 @@ system and gives an overview of their function and contents.
4776 target systems to be put into different subdirectories of the same 5471 target systems to be put into different subdirectories of the same
4777 output directory. 5472 output directory.
4778 5473
4779 The default value of this variable is: 5474 The default value of this variable is::
4780 ::
4781 5475
4782 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} 5476 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
4783 5477
4784 Some classes (e.g. 5478 Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the
4785 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the 5479 :term:`MULTIMACH_TARGET_SYS` value.
4786 ``MULTIMACH_TARGET_SYS`` value.
4787 5480
4788 See the :term:`STAMP` variable for an example. See the 5481 See the :term:`STAMP` variable for an example. See the
4789 :term:`STAGING_DIR_TARGET` variable for more information. 5482 :term:`STAGING_DIR_TARGET` variable for more information.
@@ -4808,23 +5501,21 @@ system and gives an overview of their function and contents.
4808 5501
4809 :term:`NO_GENERIC_LICENSE` 5502 :term:`NO_GENERIC_LICENSE`
4810 Avoids QA errors when you use a non-common, non-CLOSED license in a 5503 Avoids QA errors when you use a non-common, non-CLOSED license in a
4811 recipe. Packages exist, such as the linux-firmware package, with many 5504 recipe. There are packages, such as the linux-firmware package, with many
4812 licenses that are not in any way common. Also, new licenses are added 5505 licenses that are not in any way common. Also, new licenses are added
4813 occasionally to avoid introducing a lot of common license files, 5506 occasionally to avoid introducing a lot of common license files,
4814 which are only applicable to a specific package. 5507 which are only applicable to a specific package.
4815 ``NO_GENERIC_LICENSE`` is used to allow copying a license that does 5508 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does
4816 not exist in common licenses. 5509 not exist in common licenses.
4817 5510
4818 The following example shows how to add ``NO_GENERIC_LICENSE`` to a 5511 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
4819 recipe: 5512 recipe::
4820 ::
4821 5513
4822 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" 5514 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
4823 5515
4824 The following is an example that 5516 Here is an example that
4825 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched 5517 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
4826 source: 5518 source::
4827 ::
4828 5519
4829 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" 5520 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
4830 5521
@@ -4832,15 +5523,15 @@ system and gives an overview of their function and contents.
4832 Prevents installation of all "recommended-only" packages. 5523 Prevents installation of all "recommended-only" packages.
4833 Recommended-only packages are packages installed only through the 5524 Recommended-only packages are packages installed only through the
4834 :term:`RRECOMMENDS` variable). Setting the 5525 :term:`RRECOMMENDS` variable). Setting the
4835 ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: 5526 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
4836 5527
4837 NO_RECOMMENDATIONS = "1" 5528 NO_RECOMMENDATIONS = "1"
4838 5529
4839 You can set this variable globally in your ``local.conf`` file or you 5530 You can set this variable globally in your ``local.conf`` file or you
4840 can attach it to a specific image recipe by using the recipe name 5531 can attach it to a specific image recipe by using the recipe name
4841 override: :: 5532 override::
4842 5533
4843 NO_RECOMMENDATIONS_pn-target_image = "1" 5534 NO_RECOMMENDATIONS:pn-target_image = "1"
4844 5535
4845 It is important to realize that if you choose to not install packages 5536 It is important to realize that if you choose to not install packages
4846 using this variable and some other packages are dependent on them 5537 using this variable and some other packages are dependent on them
@@ -4854,8 +5545,8 @@ system and gives an overview of their function and contents.
4854 functionality, such as kernel modules. It is up to you to add 5545 functionality, such as kernel modules. It is up to you to add
4855 packages with the :term:`IMAGE_INSTALL` variable. 5546 packages with the :term:`IMAGE_INSTALL` variable.
4856 5547
4857 Support for this variable exists only when using the IPK and RPM 5548 This variable is only supported when using the IPK and RPM
4858 packaging backend. Support does not exist for DEB. 5549 packaging backends. DEB is not supported.
4859 5550
4860 See the :term:`BAD_RECOMMENDATIONS` and 5551 See the :term:`BAD_RECOMMENDATIONS` and
4861 the :term:`PACKAGE_EXCLUDE` variables for 5552 the :term:`PACKAGE_EXCLUDE` variables for
@@ -4863,15 +5554,21 @@ system and gives an overview of their function and contents.
4863 5554
4864 :term:`NOAUTOPACKAGEDEBUG` 5555 :term:`NOAUTOPACKAGEDEBUG`
4865 Disables auto package from splitting ``.debug`` files. If a recipe 5556 Disables auto package from splitting ``.debug`` files. If a recipe
4866 requires ``FILES_${PN}-dbg`` to be set manually, the 5557 requires ``FILES:${PN}-dbg`` to be set manually, the
4867 ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the 5558 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
4868 content of the debug package. For example: 5559 content of the debug package. For example::
4869 ::
4870 5560
4871 NOAUTOPACKAGEDEBUG = "1" 5561 NOAUTOPACKAGEDEBUG = "1"
4872 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" 5562 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
4873 FILES_${PN}-dbg = "/usr/src/debug/" 5563 FILES:${PN}-dbg = "/usr/src/debug/"
4874 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 5564 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
5565
5566 :term:`NON_MULTILIB_RECIPES`
5567 A list of recipes that should not be built for multilib. OE-Core's
5568 ``multilib.conf`` file defines a reasonable starting point for this
5569 list with::
5570
5571 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
4875 5572
4876 :term:`OBJCOPY` 5573 :term:`OBJCOPY`
4877 The minimal command and arguments to run ``objcopy``. 5574 The minimal command and arguments to run ``objcopy``.
@@ -4880,7 +5577,7 @@ system and gives an overview of their function and contents.
4880 The minimal command and arguments to run ``objdump``. 5577 The minimal command and arguments to run ``objdump``.
4881 5578
4882 :term:`OE_BINCONFIG_EXTRA_MANGLE` 5579 :term:`OE_BINCONFIG_EXTRA_MANGLE`
4883 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, 5580 When inheriting the :ref:`ref-classes-binconfig` class,
4884 this variable specifies additional arguments passed to the "sed" 5581 this variable specifies additional arguments passed to the "sed"
4885 command. The sed command alters any paths in configuration scripts 5582 command. The sed command alters any paths in configuration scripts
4886 that have been set up during compilation. Inheriting this class 5583 that have been set up during compilation. Inheriting this class
@@ -4888,11 +5585,19 @@ system and gives an overview of their function and contents.
4888 ``sysroots/`` directory so that all builds that use the script will 5585 ``sysroots/`` directory so that all builds that use the script will
4889 use the correct directories for the cross compiling layout. 5586 use the correct directories for the cross compiling layout.
4890 5587
4891 See the ``meta/classes/binconfig.bbclass`` in the 5588 See the ``meta/classes-recipe/binconfig.bbclass`` in the
4892 :term:`Source Directory` for details on how this class 5589 :term:`Source Directory` for details on how this class
4893 applies these additional sed command arguments. For general 5590 applies these additional sed command arguments.
4894 information on the ``binconfig`` class, see the 5591
4895 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. 5592 :term:`OECMAKE_GENERATOR`
5593 A variable for the :ref:`ref-classes-cmake` class, allowing to choose
5594 which back-end will be generated by CMake to build an application.
5595
5596 By default, this variable is set to ``Ninja``, which is faster than GNU
5597 make, but if building is broken with Ninja, a recipe can use this
5598 variable to use GNU make instead::
5599
5600 OECMAKE_GENERATOR = "Unix Makefiles"
4896 5601
4897 :term:`OE_IMPORTS` 5602 :term:`OE_IMPORTS`
4898 An internal variable used to tell the OpenEmbedded build system what 5603 An internal variable used to tell the OpenEmbedded build system what
@@ -4908,16 +5613,16 @@ system and gives an overview of their function and contents.
4908 value is "oe-init-build-env". 5613 value is "oe-init-build-env".
4909 5614
4910 If you use a custom script to set up your build environment, set the 5615 If you use a custom script to set up your build environment, set the
4911 ``OE_INIT_ENV_SCRIPT`` variable to its name. 5616 :term:`OE_INIT_ENV_SCRIPT` variable to its name.
4912 5617
4913 :term:`OE_TERMINAL` 5618 :term:`OE_TERMINAL`
4914 Controls how the OpenEmbedded build system spawns interactive 5619 Controls how the OpenEmbedded build system spawns interactive
4915 terminals on the host development system (e.g. using the BitBake 5620 terminals on the host development system (e.g. using the BitBake
4916 command with the ``-c devshell`` command-line option). For more 5621 command with the ``-c devshell`` command-line option). For more
4917 information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in 5622 information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in
4918 the Yocto Project Development Tasks Manual. 5623 the Yocto Project Development Tasks Manual.
4919 5624
4920 You can use the following values for the ``OE_TERMINAL`` variable: 5625 You can use the following values for the :term:`OE_TERMINAL` variable:
4921 5626
4922 - auto 5627 - auto
4923 - gnome 5628 - gnome
@@ -4931,12 +5636,26 @@ system and gives an overview of their function and contents.
4931 The directory from which the top-level build environment setup script 5636 The directory from which the top-level build environment setup script
4932 is sourced. The Yocto Project provides a top-level build environment 5637 is sourced. The Yocto Project provides a top-level build environment
4933 setup script: :ref:`structure-core-script`. When you run this 5638 setup script: :ref:`structure-core-script`. When you run this
4934 script, the ``OEROOT`` variable resolves to the directory that 5639 script, the :term:`OEROOT` variable resolves to the directory that
4935 contains the script. 5640 contains the script.
4936 5641
4937 For additional information on how this variable is used, see the 5642 For additional information on how this variable is used, see the
4938 initialization script. 5643 initialization script.
4939 5644
5645 :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE`
5646 Set the package manager(s) for build reproducibility testing.
5647 See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`
5648 and :doc:`/test-manual/reproducible-builds`.
5649
5650 :term:`OEQA_REPRODUCIBLE_TEST_TARGET`
5651 Set build target for build reproducibility testing. By default
5652 all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD`
5653 and :doc:`/test-manual/reproducible-builds`.
5654
5655 :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS`
5656 Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>`
5657 when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`.
5658
4940 :term:`OLDEST_KERNEL` 5659 :term:`OLDEST_KERNEL`
4941 Declares the oldest version of the Linux kernel that the produced 5660 Declares the oldest version of the Linux kernel that the produced
4942 binaries must support. This variable is passed into the build of the 5661 binaries must support. This variable is passed into the build of the
@@ -4947,53 +5666,133 @@ system and gives an overview of their function and contents.
4947 default by setting the variable in a custom distribution 5666 default by setting the variable in a custom distribution
4948 configuration file. 5667 configuration file.
4949 5668
5669 :term:`OVERLAYFS_ETC_DEVICE`
5670 When the :ref:`ref-classes-overlayfs-etc` class is
5671 inherited, specifies the device to be mounted for the read/write
5672 layer of ``/etc``. There is no default, so you must set this if you
5673 wish to enable :ref:`ref-classes-overlayfs-etc`, for
5674 example, assuming ``/dev/mmcblk0p2`` was the desired device::
5675
5676 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
5677
5678 :term:`OVERLAYFS_ETC_EXPOSE_LOWER`
5679 When the :ref:`ref-classes-overlayfs-etc` class is
5680 inherited, if set to "1" then a read-only access to the original
5681 ``/etc`` content will be provided as a ``lower/`` subdirectory of
5682 :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0".
5683
5684 :term:`OVERLAYFS_ETC_FSTYPE`
5685 When the :ref:`ref-classes-overlayfs-etc` class is
5686 inherited, specifies the file system type for the read/write
5687 layer of ``/etc``. There is no default, so you must set this if you
5688 wish to enable :ref:`ref-classes-overlayfs-etc`,
5689 for example, assuming the file system is ext4::
5690
5691 OVERLAYFS_ETC_FSTYPE = "ext4"
5692
5693 :term:`OVERLAYFS_ETC_MOUNT_OPTIONS`
5694 When the :ref:`ref-classes-overlayfs-etc` class is
5695 inherited, specifies the mount options for the read-write layer.
5696 The default value is "defaults".
5697
5698 :term:`OVERLAYFS_ETC_MOUNT_POINT`
5699 When the :ref:`ref-classes-overlayfs-etc` class is
5700 inherited, specifies the parent mount path for the filesystem layers.
5701 There is no default, so you must set this if you wish to enable
5702 :ref:`ref-classes-overlayfs-etc`, for example if the desired path is
5703 "/data"::
5704
5705 OVERLAYFS_ETC_MOUNT_POINT = "/data"
5706
5707 :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME`
5708 When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls
5709 how the generated init will be named. For more information, see the
5710 :ref:`ref-classes-overlayfs-etc` class documentation. The default value
5711 is "1".
5712
5713 :term:`OVERLAYFS_MOUNT_POINT`
5714 When inheriting the :ref:`ref-classes-overlayfs` class,
5715 specifies mount point(s) to be used. For example::
5716
5717 OVERLAYFS_MOUNT_POINT[data] = "/data"
5718
5719 The assumes you have a ``data.mount`` systemd unit defined elsewhere in
5720 your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed
5721 into the image. For more information see :ref:`ref-classes-overlayfs`.
5722
5723 .. note::
5724
5725 Although the :ref:`ref-classes-overlayfs` class is
5726 inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT`
5727 should be set in your machine configuration.
5728
5729 :term:`OVERLAYFS_QA_SKIP`
5730 When inheriting the :ref:`ref-classes-overlayfs` class,
5731 provides the ability to disable QA checks for particular overlayfs
5732 mounts. For example::
5733
5734 OVERLAYFS_QA_SKIP[data] = "mount-configured"
5735
5736 .. note::
5737
5738 Although the :ref:`ref-classes-overlayfs` class is
5739 inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP`
5740 should be set in your machine configuration.
5741
5742 :term:`OVERLAYFS_WRITABLE_PATHS`
5743 When inheriting the :ref:`ref-classes-overlayfs` class,
5744 specifies writable paths used at runtime for the recipe. For
5745 example::
5746
5747 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
5748
4950 :term:`OVERRIDES` 5749 :term:`OVERRIDES`
4951 A colon-separated list of overrides that currently apply. Overrides 5750 A colon-separated list of overrides that currently apply. Overrides
4952 are a BitBake mechanism that allows variables to be selectively 5751 are a BitBake mechanism that allows variables to be selectively
4953 overridden at the end of parsing. The set of overrides in 5752 overridden at the end of parsing. The set of overrides in
4954 ``OVERRIDES`` represents the "state" during building, which includes 5753 :term:`OVERRIDES` represents the "state" during building, which includes
4955 the current recipe being built, the machine for which it is being 5754 the current recipe being built, the machine for which it is being
4956 built, and so forth. 5755 built, and so forth.
4957 5756
4958 As an example, if the string "an-override" appears as an element in 5757 As an example, if the string "an-override" appears as an element in
4959 the colon-separated list in ``OVERRIDES``, then the following 5758 the colon-separated list in :term:`OVERRIDES`, then the following
4960 assignment will override ``FOO`` with the value "overridden" at the 5759 assignment will override ``FOO`` with the value "overridden" at the
4961 end of parsing: 5760 end of parsing::
4962 ::
4963 5761
4964 FOO_an-override = "overridden" 5762 FOO:an-override = "overridden"
4965 5763
4966 See the 5764 See the
4967 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 5765 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
4968 section in the BitBake User Manual for more information on the 5766 section in the BitBake User Manual for more information on the
4969 overrides mechanism. 5767 overrides mechanism.
4970 5768
4971 The default value of ``OVERRIDES`` includes the values of the 5769 The default value of :term:`OVERRIDES` includes the values of the
4972 :term:`CLASSOVERRIDE`, 5770 :term:`CLASSOVERRIDE`,
4973 :term:`MACHINEOVERRIDES`, and 5771 :term:`MACHINEOVERRIDES`, and
4974 :term:`DISTROOVERRIDES` variables. Another 5772 :term:`DISTROOVERRIDES` variables. Another
4975 important override included by default is ``pn-${PN}``. This override 5773 important override included by default is ``pn-${PN}``. This override
4976 allows variables to be set for a single recipe within configuration 5774 allows variables to be set for a single recipe within configuration
4977 (``.conf``) files. Here is an example: 5775 (``.conf``) files. Here is an example::
4978 ::
4979 5776
4980 FOO_pn-myrecipe = "myrecipe-specific value" 5777 FOO:pn-myrecipe = "myrecipe-specific value"
4981 5778
4982 .. note:: 5779 .. note::
4983 5780
4984 An easy way to see what overrides apply is to search for ``OVERRIDES`` 5781 An easy way to see what overrides apply is to search for :term:`OVERRIDES`
4985 in the output of the ``bitbake -e`` command. See the 5782 in the output of the ``bitbake -e`` command. See the
4986 ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto 5783 ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto
4987 Project Development Tasks Manual for more information. 5784 Project Development Tasks Manual for more information.
4988 5785
4989 :term:`P` 5786 :term:`P`
4990 The recipe name and version. ``P`` is comprised of the following: 5787 The recipe name and version. :term:`P` is comprised of the following::
4991 ::
4992 5788
4993 ${PN}-${PV} 5789 ${PN}-${PV}
4994 5790
5791 :term:`P4DIR`
5792 See :term:`bitbake:P4DIR` in the BitBake manual.
5793
4995 :term:`PACKAGE_ADD_METADATA` 5794 :term:`PACKAGE_ADD_METADATA`
4996 This variable defines additional metdata to add to packages. 5795 This variable defines additional metadata to add to packages.
4997 5796
4998 You may find you need to inject additional metadata into packages. 5797 You may find you need to inject additional metadata into packages.
4999 This variable allows you to do that by setting the injected data as 5798 This variable allows you to do that by setting the injected data as
@@ -5005,7 +5804,7 @@ system and gives an overview of their function and contents.
5005 specific by using the package name as a suffix. 5804 specific by using the package name as a suffix.
5006 5805
5007 You can find out more about applying this variable in the 5806 You can find out more about applying this variable in the
5008 ":ref:`dev-manual/common-tasks:adding custom metadata to packages`" 5807 ":ref:`dev-manual/packages:adding custom metadata to packages`"
5009 section in the Yocto Project Development Tasks Manual. 5808 section in the Yocto Project Development Tasks Manual.
5010 5809
5011 :term:`PACKAGE_ARCH` 5810 :term:`PACKAGE_ARCH`
@@ -5023,9 +5822,8 @@ system and gives an overview of their function and contents.
5023 5822
5024 However, if your recipe's output packages are built specific to the 5823 However, if your recipe's output packages are built specific to the
5025 target machine rather than generally for the architecture of the 5824 target machine rather than generally for the architecture of the
5026 machine, you should set ``PACKAGE_ARCH`` to the value of 5825 machine, you should set :term:`PACKAGE_ARCH` to the value of
5027 :term:`MACHINE_ARCH` in the recipe as follows: 5826 :term:`MACHINE_ARCH` in the recipe as follows::
5028 ::
5029 5827
5030 PACKAGE_ARCH = "${MACHINE_ARCH}" 5828 PACKAGE_ARCH = "${MACHINE_ARCH}"
5031 5829
@@ -5033,11 +5831,11 @@ system and gives an overview of their function and contents.
5033 Specifies a list of architectures compatible with the target machine. 5831 Specifies a list of architectures compatible with the target machine.
5034 This variable is set automatically and should not normally be 5832 This variable is set automatically and should not normally be
5035 hand-edited. Entries are separated using spaces and listed in order 5833 hand-edited. Entries are separated using spaces and listed in order
5036 of priority. The default value for ``PACKAGE_ARCHS`` is "all any 5834 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any
5037 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 5835 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5038 5836
5039 :term:`PACKAGE_BEFORE_PN` 5837 :term:`PACKAGE_BEFORE_PN`
5040 Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so 5838 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so
5041 that those added packages can pick up files that would normally be 5839 that those added packages can pick up files that would normally be
5042 included in the default package. 5840 included in the default package.
5043 5841
@@ -5048,21 +5846,14 @@ system and gives an overview of their function and contents.
5048 OpenEmbedded build system uses when packaging data. 5846 OpenEmbedded build system uses when packaging data.
5049 5847
5050 You can provide one or more of the following arguments for the 5848 You can provide one or more of the following arguments for the
5051 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk 5849 variable::
5052 package_tar"
5053
5054 .. note::
5055 5850
5056 While it is a legal option, the ``package_tar`` 5851 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
5057 class has limited functionality due to no support for package
5058 dependencies by that backend. Therefore, it is recommended that
5059 you do not use it.
5060 5852
5061 The build system uses only the first argument in the list as the 5853 The build system uses only the first argument in the list as the
5062 package manager when creating your image or SDK. However, packages 5854 package manager when creating your image or SDK. However, packages
5063 will be created using any additional packaging classes you specify. 5855 will be created using any additional packaging classes you specify.
5064 For example, if you use the following in your ``local.conf`` file: 5856 For example, if you use the following in your ``local.conf`` file::
5065 ::
5066 5857
5067 PACKAGE_CLASSES ?= "package_ipk" 5858 PACKAGE_CLASSES ?= "package_ipk"
5068 5859
@@ -5071,66 +5862,63 @@ system and gives an overview of their function and contents.
5071 5862
5072 For information on packaging and build performance effects as a 5863 For information on packaging and build performance effects as a
5073 result of the package manager in use, see the 5864 result of the package manager in use, see the
5074 ":ref:`package.bbclass <ref-classes-package>`" section. 5865 ":ref:`ref-classes-package`" section.
5075 5866
5076 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 5867 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
5077 Determines how to split up the binary and debug information when 5868 Determines how to split up and package debug and source information
5078 creating ``*-dbg`` packages to be used with the GNU Project Debugger 5869 when creating debugging packages to be used with the GNU Project
5079 (GDB). 5870 Debugger (GDB). In general, based on the value of this variable,
5080 5871 you can combine the source and debug info in a single package,
5081 With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control 5872 you can break out the source into a separate package that can be
5082 where debug information, which can include or exclude source files, 5873 installed independently, or you can choose to not have the source
5083 is stored: 5874 packaged at all.
5084 5875
5085 - ".debug": Debug symbol files are placed next to the binary in a 5876 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
5086 ``.debug`` directory on the target. For example, if a binary is 5877
5087 installed into ``/bin``, the corresponding debug symbol files are 5878 - "``.debug``": All debugging and source info is placed in a single
5088 installed in ``/bin/.debug``. Source files are placed in 5879 ``*-dbg`` package; debug symbol files are placed next to the
5089 ``/usr/src/debug``. 5880 binary in a ``.debug`` directory so that, if a binary is installed
5090 5881 into ``/bin``, the corresponding debug symbol file is installed
5091 - "debug-file-directory": Debug symbol files are placed under 5882 in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
5092 ``/usr/lib/debug`` on the target, and separated by the path from 5883 package under ``/usr/src/debug``.
5093 where the binary is installed. For example, if a binary is 5884
5094 installed in ``/bin``, the corresponding debug symbols are 5885 - "``debug-file-directory``": As above, all debugging and source info
5095 installed in ``/usr/lib/debug/bin``. Source files are placed in 5886 is placed in a single ``*-dbg`` package; debug symbol files are
5096 ``/usr/src/debug``. 5887 placed entirely under the directory ``/usr/lib/debug`` and separated
5097 5888 by the path from where the binary is installed, so that if a binary
5098 - "debug-without-src": The same behavior as ".debug" previously 5889 is installed in ``/bin``, the corresponding debug symbols are installed
5099 described with the exception that no source files are installed. 5890 in ``/usr/lib/debug/bin``, and so on. As above, source is installed
5100 5891 in the same package under ``/usr/src/debug``.
5101 - "debug-with-srcpkg": The same behavior as ".debug" previously 5892
5102 described with the exception that all source files are placed in a 5893 - "``debug-with-srcpkg``": Debugging info is placed in the standard
5103 separate ``*-src`` pkg. This is the default behavior. 5894 ``*-dbg`` package as with the ``.debug`` value, while source is
5895 placed in a separate ``*-src`` package, which can be installed
5896 independently. This is the default setting for this variable,
5897 as defined in Poky's ``bitbake.conf`` file.
5898
5899 - "``debug-without-src``": The same behavior as with the ``.debug``
5900 setting, but no source is packaged at all.
5104 5901
5105 You can find out more about debugging using GDB by reading the 5902 .. note::
5106 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section
5107 in the Yocto Project Development Tasks Manual.
5108 5903
5109 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` 5904 Much of the above package splitting can be overridden via
5110 Prevents specific packages from being installed when you are 5905 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable.
5111 installing complementary packages.
5112 5906
5113 You might find that you want to prevent installing certain packages 5907 You can find out more about debugging using GDB by reading the
5114 when you are installing complementary packages. For example, if you 5908 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section
5115 are using :term:`IMAGE_FEATURES` to install 5909 in the Yocto Project Development Tasks Manual.
5116 ``dev-pkgs``, you might not want to install all packages from a
5117 particular multilib. If you find yourself in this situation, you can
5118 use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular
5119 expressions to match the packages you want to exclude.
5120 5910
5121 :term:`PACKAGE_EXCLUDE` 5911 :term:`PACKAGE_EXCLUDE`
5122 Lists packages that should not be installed into an image. For 5912 Lists packages that should not be installed into an image. For
5123 example: 5913 example::
5124 ::
5125 5914
5126 PACKAGE_EXCLUDE = "package_name package_name package_name ..." 5915 PACKAGE_EXCLUDE = "package_name package_name package_name ..."
5127 5916
5128 You can set this variable globally in your ``local.conf`` file or you 5917 You can set this variable globally in your ``local.conf`` file or you
5129 can attach it to a specific image recipe by using the recipe name 5918 can attach it to a specific image recipe by using the recipe name
5130 override: 5919 override::
5131 ::
5132 5920
5133 PACKAGE_EXCLUDE_pn-target_image = "package_name" 5921 PACKAGE_EXCLUDE:pn-target_image = "package_name"
5134 5922
5135 If you choose to not install a package using this variable and some 5923 If you choose to not install a package using this variable and some
5136 other package is dependent on it (i.e. listed in a recipe's 5924 other package is dependent on it (i.e. listed in a recipe's
@@ -5140,13 +5928,25 @@ system and gives an overview of their function and contents.
5140 an iterative development process to remove specific components from a 5928 an iterative development process to remove specific components from a
5141 system. 5929 system.
5142 5930
5143 Support for this variable exists only when using the IPK and RPM 5931 This variable is supported only when using the IPK and RPM
5144 packaging backend. Support does not exist for DEB. 5932 packaging backends. DEB is not supported.
5145 5933
5146 See the :term:`NO_RECOMMENDATIONS` and the 5934 See the :term:`NO_RECOMMENDATIONS` and the
5147 :term:`BAD_RECOMMENDATIONS` variables for 5935 :term:`BAD_RECOMMENDATIONS` variables for
5148 related information. 5936 related information.
5149 5937
5938 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY`
5939 Prevents specific packages from being installed when you are
5940 installing complementary packages.
5941
5942 You might find that you want to prevent installing certain packages
5943 when you are installing complementary packages. For example, if you
5944 are using :term:`IMAGE_FEATURES` to install
5945 ``dev-pkgs``, you might not want to install all packages from a
5946 particular multilib. If you find yourself in this situation, you can
5947 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular
5948 expressions to match the packages you want to exclude.
5949
5150 :term:`PACKAGE_EXTRA_ARCHS` 5950 :term:`PACKAGE_EXTRA_ARCHS`
5151 Specifies the list of architectures compatible with the device CPU. 5951 Specifies the list of architectures compatible with the device CPU.
5152 This variable is useful when you build for several different devices 5952 This variable is useful when you build for several different devices
@@ -5155,7 +5955,7 @@ system and gives an overview of their function and contents.
5155 :term:`PACKAGE_FEED_ARCHS` 5955 :term:`PACKAGE_FEED_ARCHS`
5156 Optionally specifies the package architectures used as part of the 5956 Optionally specifies the package architectures used as part of the
5157 package feed URIs during the build. When used, the 5957 package feed URIs during the build. When used, the
5158 ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed 5958 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed
5159 URI, which is constructed using the 5959 URI, which is constructed using the
5160 :term:`PACKAGE_FEED_URIS` and 5960 :term:`PACKAGE_FEED_URIS` and
5161 :term:`PACKAGE_FEED_BASE_PATHS` 5961 :term:`PACKAGE_FEED_BASE_PATHS`
@@ -5163,17 +5963,16 @@ system and gives an overview of their function and contents.
5163 5963
5164 .. note:: 5964 .. note::
5165 5965
5166 You can use the ``PACKAGE_FEED_ARCHS`` 5966 You can use the :term:`PACKAGE_FEED_ARCHS`
5167 variable to whitelist specific package architectures. If you do 5967 variable to allow specific package architectures. If you do
5168 not need to whitelist specific architectures, which is a common 5968 not need to allow specific architectures, which is a common
5169 case, you can omit this variable. Omitting the variable results in 5969 case, you can omit this variable. Omitting the variable results in
5170 all available architectures for the current machine being included 5970 all available architectures for the current machine being included
5171 into remote package feeds. 5971 into remote package feeds.
5172 5972
5173 Consider the following example where the ``PACKAGE_FEED_URIS``, 5973 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5174 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 5974 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
5175 defined in your ``local.conf`` file: 5975 defined in your ``local.conf`` file::
5176 ::
5177 5976
5178 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 5977 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5179 https://example.com/packagerepos/updates" 5978 https://example.com/packagerepos/updates"
@@ -5195,15 +5994,14 @@ system and gives an overview of their function and contents.
5195 5994
5196 :term:`PACKAGE_FEED_BASE_PATHS` 5995 :term:`PACKAGE_FEED_BASE_PATHS`
5197 Specifies the base path used when constructing package feed URIs. The 5996 Specifies the base path used when constructing package feed URIs. The
5198 ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a 5997 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a
5199 package feed URI used by the OpenEmbedded build system. The base path 5998 package feed URI used by the OpenEmbedded build system. The base path
5200 lies between the :term:`PACKAGE_FEED_URIS` 5999 lies between the :term:`PACKAGE_FEED_URIS`
5201 and :term:`PACKAGE_FEED_ARCHS` variables. 6000 and :term:`PACKAGE_FEED_ARCHS` variables.
5202 6001
5203 Consider the following example where the ``PACKAGE_FEED_URIS``, 6002 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5204 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 6003 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
5205 defined in your ``local.conf`` file: 6004 defined in your ``local.conf`` file::
5206 ::
5207 6005
5208 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6006 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5209 https://example.com/packagerepos/updates" 6007 https://example.com/packagerepos/updates"
@@ -5226,14 +6024,13 @@ system and gives an overview of their function and contents.
5226 :term:`PACKAGE_FEED_URIS` 6024 :term:`PACKAGE_FEED_URIS`
5227 Specifies the front portion of the package feed URI used by the 6025 Specifies the front portion of the package feed URI used by the
5228 OpenEmbedded build system. Each final package feed URI is comprised 6026 OpenEmbedded build system. Each final package feed URI is comprised
5229 of ``PACKAGE_FEED_URIS``, 6027 of :term:`PACKAGE_FEED_URIS`,
5230 :term:`PACKAGE_FEED_BASE_PATHS`, and 6028 :term:`PACKAGE_FEED_BASE_PATHS`, and
5231 :term:`PACKAGE_FEED_ARCHS` variables. 6029 :term:`PACKAGE_FEED_ARCHS` variables.
5232 6030
5233 Consider the following example where the ``PACKAGE_FEED_URIS``, 6031 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5234 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 6032 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
5235 defined in your ``local.conf`` file: 6033 defined in your ``local.conf`` file::
5236 ::
5237 6034
5238 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ 6035 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5239 https://example.com/packagerepos/updates" 6036 https://example.com/packagerepos/updates"
@@ -5258,16 +6055,16 @@ system and gives an overview of their function and contents.
5258 installation into the image. 6055 installation into the image.
5259 6056
5260 Because the package manager controls actual installation of all 6057 Because the package manager controls actual installation of all
5261 packages, the list of packages passed using ``PACKAGE_INSTALL`` is 6058 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is
5262 not the final list of packages that are actually installed. This 6059 not the final list of packages that are actually installed. This
5263 variable is internal to the image construction code. Consequently, in 6060 variable is internal to the image construction code. Consequently, in
5264 general, you should use the 6061 general, you should use the
5265 :term:`IMAGE_INSTALL` variable to specify 6062 :term:`IMAGE_INSTALL` variable to specify
5266 packages for installation. The exception to this is when working with 6063 packages for installation. The exception to this is when working with
5267 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` 6064 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
5268 image. When working with an initial RAM filesystem (initramfs) image, 6065 image. When working with an initial RAM filesystem (:term:`Initramfs`) image,
5269 use the ``PACKAGE_INSTALL`` variable. For information on creating an 6066 use the :term:`PACKAGE_INSTALL` variable. For information on creating an
5270 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section 6067 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
5271 in the Yocto Project Development Tasks Manual. 6068 in the Yocto Project Development Tasks Manual.
5272 6069
5273 :term:`PACKAGE_INSTALL_ATTEMPTONLY` 6070 :term:`PACKAGE_INSTALL_ATTEMPTONLY`
@@ -5284,22 +6081,21 @@ system and gives an overview of their function and contents.
5284 :term:`PACKAGE_WRITE_DEPS` 6081 :term:`PACKAGE_WRITE_DEPS`
5285 Specifies a list of dependencies for post-installation and 6082 Specifies a list of dependencies for post-installation and
5286 pre-installation scripts on native/cross tools. If your 6083 pre-installation scripts on native/cross tools. If your
5287 post-installation or pre-installation script can execute at rootfs 6084 post-installation or pre-installation script can execute at root filesystem
5288 creation time rather than on the target but depends on a native tool 6085 creation time rather than on the target but depends on a native tool
5289 in order to execute, you need to list the tools in 6086 in order to execute, you need to list the tools in
5290 ``PACKAGE_WRITE_DEPS``. 6087 :term:`PACKAGE_WRITE_DEPS`.
5291 6088
5292 For information on running post-installation scripts, see the 6089 For information on running post-installation scripts, see the
5293 ":ref:`dev-manual/common-tasks:post-installation scripts`" 6090 ":ref:`dev-manual/new-recipe:post-installation scripts`"
5294 section in the Yocto Project Development Tasks Manual. 6091 section in the Yocto Project Development Tasks Manual.
5295 6092
5296 :term:`PACKAGECONFIG` 6093 :term:`PACKAGECONFIG`
5297 This variable provides a means of enabling or disabling features of a 6094 This variable provides a means of enabling or disabling features of a
5298 recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in 6095 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
5299 recipes when you specify features and then arguments that define 6096 recipes when you specify features and then arguments that define
5300 feature behaviors. Here is the basic block structure (broken over 6097 feature behaviors. Here is the basic block structure (broken over
5301 multiple lines for readability): 6098 multiple lines for readability)::
5302 ::
5303 6099
5304 PACKAGECONFIG ??= "f1 f2 f3 ..." 6100 PACKAGECONFIG ??= "f1 f2 f3 ..."
5305 PACKAGECONFIG[f1] = "\ 6101 PACKAGECONFIG[f1] = "\
@@ -5312,117 +6108,140 @@ system and gives an overview of their function and contents.
5312 PACKAGECONFIG[f2] = "\ 6108 PACKAGECONFIG[f2] = "\
5313 ... and so on and so on ... 6109 ... and so on and so on ...
5314 6110
5315 The ``PACKAGECONFIG`` variable itself specifies a space-separated 6111 The :term:`PACKAGECONFIG` variable itself specifies a space-separated
5316 list of the features to enable. Following the features, you can 6112 list of the features to enable. Following the features, you can
5317 determine the behavior of each feature by providing up to six 6113 determine the behavior of each feature by providing up to six
5318 order-dependent arguments, which are separated by commas. You can 6114 order-dependent arguments, which are separated by commas. You can
5319 omit any argument you like but must retain the separating commas. The 6115 omit any argument you like but must retain the separating commas. The
5320 order is important and specifies the following: 6116 order is important and specifies the following:
5321 6117
5322 1. Extra arguments that should be added to the configure script 6118 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
5323 argument list (:term:`EXTRA_OECONF` or 6119 if the feature is enabled.
5324 :term:`PACKAGECONFIG_CONFARGS`) if
5325 the feature is enabled.
5326 6120
5327 2. Extra arguments that should be added to ``EXTRA_OECONF`` or 6121 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
5328 ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. 6122 if the feature is disabled.
5329 6123
5330 3. Additional build dependencies (:term:`DEPENDS`) 6124 #. Additional build dependencies (:term:`DEPENDS`)
5331 that should be added if the feature is enabled. 6125 that should be added if the feature is enabled.
5332 6126
5333 4. Additional runtime dependencies (:term:`RDEPENDS`) 6127 #. Additional runtime dependencies (:term:`RDEPENDS`)
5334 that should be added if the feature is enabled. 6128 that should be added if the feature is enabled.
5335 6129
5336 5. Additional runtime recommendations 6130 #. Additional runtime recommendations
5337 (:term:`RRECOMMENDS`) that should be added if 6131 (:term:`RRECOMMENDS`) that should be added if
5338 the feature is enabled. 6132 the feature is enabled.
5339 6133
5340 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` 6134 #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
5341 settings for this feature. 6135 settings for this feature.
5342 6136
5343 Consider the following ``PACKAGECONFIG`` block taken from the 6137 Consider the following :term:`PACKAGECONFIG` block taken from the
5344 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 6138 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
5345 three arguments that determine the feature's behavior. 6139 three arguments that determine the feature's behavior::
5346 ::
5347 6140
5348 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" 6141 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
5349 6142
5350 The 6143 The
5351 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 6144 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
5352 enabled. In this case, ``--with-gtk3`` is added to the configure 6145 enabled. In this case, ``--with-gtk3`` is added to the configure
5353 script argument list and ``gtk+3`` is added to ``DEPENDS``. On the 6146 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the
5354 other hand, if the feature is disabled say through a ``.bbappend`` 6147 other hand, if the feature is disabled say through a ``.bbappend``
5355 file in another layer, then the second argument ``--without-gtk3`` is 6148 file in another layer, then the second argument ``--without-gtk3`` is
5356 added to the configure script instead. 6149 added to the configure script instead.
5357 6150
5358 The basic ``PACKAGECONFIG`` structure previously described holds true 6151 The basic :term:`PACKAGECONFIG` structure previously described holds true
5359 regardless of whether you are creating a block or changing a block. 6152 regardless of whether you are creating a block or changing a block.
5360 When creating a block, use the structure inside your recipe. 6153 When creating a block, use the structure inside your recipe.
5361 6154
5362 If you want to change an existing ``PACKAGECONFIG`` block, you can do 6155 If you want to change an existing :term:`PACKAGECONFIG` block, you can do
5363 so one of two ways: 6156 so one of two ways:
5364 6157
5365 - *Append file:* Create an append file named 6158 - *Append file:* Create an append file named
5366 recipename\ ``.bbappend`` in your layer and override the value of 6159 ``recipename.bbappend`` in your layer and override the value of
5367 ``PACKAGECONFIG``. You can either completely override the 6160 :term:`PACKAGECONFIG`. You can either completely override the
5368 variable: 6161 variable::
5369 ::
5370 6162
5371 PACKAGECONFIG = "f4 f5" 6163 PACKAGECONFIG = "f4 f5"
5372 6164
5373 Or, you can just append the variable: 6165 Or, you can just append the variable::
5374 ::
5375 6166
5376 PACKAGECONFIG_append = " f4" 6167 PACKAGECONFIG:append = " f4"
5377 6168
5378 - *Configuration file:* This method is identical to changing the 6169 - *Configuration file:* This method is identical to changing the
5379 block through an append file except you edit your ``local.conf`` 6170 block through an append file except you edit your ``local.conf``
5380 or ``mydistro.conf`` file. As with append files previously 6171 or ``mydistro.conf`` file. As with append files previously
5381 described, you can either completely override the variable: 6172 described, you can either completely override the variable::
5382 :: 6173
6174 PACKAGECONFIG:pn-recipename = "f4 f5"
6175
6176 Or, you can just amend the variable::
6177
6178 PACKAGECONFIG:append:pn-recipename = " f4"
5383 6179
5384 PACKAGECONFIG_pn-recipename = "f4 f5" 6180 Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service
6181 in which :term:`PACKAGECONFIG` is used to transform the systemd service
6182 into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`::
5385 6183
5386 Or, you can just amend the variable: 6184 example.c
5387 :: 6185 example.service
6186 CMakeLists.txt
5388 6187
5389 PACKAGECONFIG_append_pn-recipename = " f4" 6188 The ``CMakeLists.txt`` file contains::
6189
6190 if(WITH_SYSTEMD)
6191 install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
6192 endif(WITH_SYSTEMD)
6193
6194 In order to enable the installation of ``example.service`` we need to
6195 ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command
6196 execution. Recipes that have ``CMakeLists.txt`` generally inherit the
6197 :ref:`ref-classes-cmake` class, that runs ``cmake`` with
6198 :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be
6199 appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is
6200 automatically filled with either the first or second element of
6201 :term:`PACKAGECONFIG` flag value, the recipe would be like::
6202
6203 inherit cmake
6204 PACKAGECONFIG = "systemd"
6205 PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
6206
6207 A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
6208 or not::
6209
6210 PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
5390 6211
5391 :term:`PACKAGECONFIG_CONFARGS` 6212 :term:`PACKAGECONFIG_CONFARGS`
5392 A space-separated list of configuration options generated from the 6213 A space-separated list of configuration options generated from the
5393 :term:`PACKAGECONFIG` setting. 6214 :term:`PACKAGECONFIG` setting.
5394 6215
5395 Classes such as :ref:`autotools <ref-classes-autotools>` and 6216 Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake`
5396 :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to 6217 use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options
5397 pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, 6218 to ``configure`` and ``cmake``, respectively. If you are using
5398 respectively. If you are using ``PACKAGECONFIG`` but not a class that 6219 :term:`PACKAGECONFIG` but not a class that handles the
5399 handles the ``do_configure`` task, then you need to use 6220 :ref:`ref-tasks-configure` task, then you need to use
5400 ``PACKAGECONFIG_CONFARGS`` appropriately. 6221 :term:`PACKAGECONFIG_CONFARGS` appropriately.
5401 6222
5402 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` 6223 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY`
5403 For recipes inheriting the 6224 For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting
5404 :ref:`packagegroup <ref-classes-packagegroup>` class, setting 6225 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the
5405 ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the
5406 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) 6226 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
5407 should not be automatically created by the ``packagegroup`` recipe, 6227 should not be automatically created by the ``packagegroup`` recipe,
5408 which is the default behavior. 6228 which is the default behavior.
5409 6229
5410 :term:`PACKAGES` 6230 :term:`PACKAGES`
5411 The list of packages the recipe creates. The default value is the 6231 The list of packages the recipe creates. The default value is the
5412 following: 6232 following::
5413 ::
5414 6233
5415 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} 6234 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5416 6235
5417 During packaging, the :ref:`ref-tasks-package` task 6236 During packaging, the :ref:`ref-tasks-package` task
5418 goes through ``PACKAGES`` and uses the :term:`FILES` 6237 goes through :term:`PACKAGES` and uses the :term:`FILES`
5419 variable corresponding to each package to assign files to the 6238 variable corresponding to each package to assign files to the
5420 package. If a file matches the ``FILES`` variable for more than one 6239 package. If a file matches the :term:`FILES` variable for more than one
5421 package in ``PACKAGES``, it will be assigned to the earliest 6240 package in :term:`PACKAGES`, it will be assigned to the earliest
5422 (leftmost) package. 6241 (leftmost) package.
5423 6242
5424 Packages in the variable's list that are empty (i.e. where none of 6243 Packages in the variable's list that are empty (i.e. where none of
5425 the patterns in ``FILES_``\ pkg match any files installed by the 6244 the patterns in ``FILES:``\ pkg match any files installed by the
5426 :ref:`ref-tasks-install` task) are not generated, 6245 :ref:`ref-tasks-install` task) are not generated,
5427 unless generation is forced through the 6246 unless generation is forced through the
5428 :term:`ALLOW_EMPTY` variable. 6247 :term:`ALLOW_EMPTY` variable.
@@ -5430,10 +6249,10 @@ system and gives an overview of their function and contents.
5430 :term:`PACKAGES_DYNAMIC` 6249 :term:`PACKAGES_DYNAMIC`
5431 A promise that your recipe satisfies runtime dependencies for 6250 A promise that your recipe satisfies runtime dependencies for
5432 optional modules that are found in other recipes. 6251 optional modules that are found in other recipes.
5433 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it 6252 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
5434 only states that they should be satisfied. For example, if a hard, 6253 only states that they should be satisfied. For example, if a hard,
5435 runtime dependency (:term:`RDEPENDS`) of another 6254 runtime dependency (:term:`RDEPENDS`) of another
5436 package is satisfied at build time through the ``PACKAGES_DYNAMIC`` 6255 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC`
5437 variable, but a package with the module name is never actually 6256 variable, but a package with the module name is never actually
5438 produced, then the other package will be broken. Thus, if you attempt 6257 produced, then the other package will be broken. Thus, if you attempt
5439 to include that package in an image, you will get a dependency 6258 to include that package in an image, you will get a dependency
@@ -5443,11 +6262,11 @@ system and gives an overview of their function and contents.
5443 Typically, if there is a chance that such a situation can occur and 6262 Typically, if there is a chance that such a situation can occur and
5444 the package that is not created is valid without the dependency being 6263 the package that is not created is valid without the dependency being
5445 satisfied, then you should use :term:`RRECOMMENDS` 6264 satisfied, then you should use :term:`RRECOMMENDS`
5446 (a soft runtime dependency) instead of ``RDEPENDS``. 6265 (a soft runtime dependency) instead of :term:`RDEPENDS`.
5447 6266
5448 For an example of how to use the ``PACKAGES_DYNAMIC`` variable when 6267 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when
5449 you are splitting packages, see the 6268 you are splitting packages, see the
5450 ":ref:`dev-manual/common-tasks:handling optional module packaging`" 6269 ":ref:`dev-manual/packages:handling optional module packaging`"
5451 section in the Yocto Project Development Tasks Manual. 6270 section in the Yocto Project Development Tasks Manual.
5452 6271
5453 :term:`PACKAGESPLITFUNCS` 6272 :term:`PACKAGESPLITFUNCS`
@@ -5461,17 +6280,20 @@ system and gives an overview of their function and contents.
5461 desired splitting. 6280 desired splitting.
5462 6281
5463 :term:`PARALLEL_MAKE` 6282 :term:`PARALLEL_MAKE`
5464 Extra options passed to the ``make`` command during the 6283
5465 :ref:`ref-tasks-compile` task in order to specify 6284 Extra options passed to the build tool command (``make``,
5466 parallel compilation on the local build host. This variable is 6285 ``ninja`` or more specific build engines, like the Go language one)
5467 usually in the form "-j x", where x represents the maximum number of 6286 during the :ref:`ref-tasks-compile` task, to specify parallel compilation
5468 parallel threads ``make`` can run. 6287 on the local build host. This variable is usually in the form "-j x",
6288 where x represents the maximum number of parallel threads such engines
6289 can run.
5469 6290
5470 .. note:: 6291 .. note::
5471 6292
5472 In order for ``PARALLEL_MAKE`` to be effective, ``make`` must be 6293 For software compiled by ``make``, in order for :term:`PARALLEL_MAKE`
5473 called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure 6294 to be effective, ``make`` must be called with
5474 this is to use the ``oe_runmake`` function. 6295 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6296 way to ensure this is to use the ``oe_runmake`` function.
5475 6297
5476 By default, the OpenEmbedded build system automatically sets this 6298 By default, the OpenEmbedded build system automatically sets this
5477 variable to be equal to the number of cores the build system uses. 6299 variable to be equal to the number of cores the build system uses.
@@ -5479,40 +6301,41 @@ system and gives an overview of their function and contents.
5479 .. note:: 6301 .. note::
5480 6302
5481 If the software being built experiences dependency issues during 6303 If the software being built experiences dependency issues during
5482 the ``do_compile`` task that result in race conditions, you can clear 6304 the :ref:`ref-tasks-compile` task that result in race conditions, you can clear
5483 the ``PARALLEL_MAKE`` variable within the recipe as a workaround. For 6305 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For
5484 information on addressing race conditions, see the 6306 information on addressing race conditions, see the
5485 ":ref:`dev-manual/common-tasks:debugging parallel make races`" 6307 ":ref:`dev-manual/debugging:debugging parallel make races`"
5486 section in the Yocto Project Development Tasks Manual. 6308 section in the Yocto Project Development Tasks Manual.
5487 6309
5488 For single socket systems (i.e. one CPU), you should not have to 6310 For single socket systems (i.e. one CPU), you should not have to
5489 override this variable to gain optimal parallelism during builds. 6311 override this variable to gain optimal parallelism during builds.
5490 However, if you have very large systems that employ multiple physical 6312 However, if you have very large systems that employ multiple physical
5491 CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is 6313 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is
5492 not set higher than "-j 20". 6314 not set higher than "-j 20".
5493 6315
5494 For more information on speeding up builds, see the 6316 For more information on speeding up builds, see the
5495 ":ref:`dev-manual/common-tasks:speeding up a build`" 6317 ":ref:`dev-manual/speeding-up-build:speeding up a build`"
5496 section in the Yocto Project Development Tasks Manual. 6318 section in the Yocto Project Development Tasks Manual.
5497 6319
5498 :term:`PARALLEL_MAKEINST` 6320 :term:`PARALLEL_MAKEINST`
5499 Extra options passed to the ``make install`` command during the 6321 Extra options passed to the build tool install command
5500 :ref:`ref-tasks-install` task in order to specify 6322 (``make install``, ``ninja install`` or more specific ones)
6323 during the :ref:`ref-tasks-install` task in order to specify
5501 parallel installation. This variable defaults to the value of 6324 parallel installation. This variable defaults to the value of
5502 :term:`PARALLEL_MAKE`. 6325 :term:`PARALLEL_MAKE`.
5503 6326
5504 .. note:: 6327 .. note::
5505 6328
5506 In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must 6329 For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST`
5507 be called with 6330 to be effective, ``make`` must be called with
5508 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 6331 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
5509 way to ensure this is to use the ``oe_runmake`` function. 6332 way to ensure this is to use the ``oe_runmake`` function.
5510 6333
5511 If the software being built experiences dependency issues during 6334 If the software being built experiences dependency issues during
5512 the ``do_install`` task that result in race conditions, you can 6335 the :ref:`ref-tasks-install` task that result in race conditions, you can
5513 clear the ``PARALLEL_MAKEINST`` variable within the recipe as a 6336 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
5514 workaround. For information on addressing race conditions, see the 6337 workaround. For information on addressing race conditions, see the
5515 ":ref:`dev-manual/common-tasks:debugging parallel make races`" 6338 ":ref:`dev-manual/debugging:debugging parallel make races`"
5516 section in the Yocto Project Development Tasks Manual. 6339 section in the Yocto Project Development Tasks Manual.
5517 6340
5518 :term:`PATCHRESOLVE` 6341 :term:`PATCHRESOLVE`
@@ -5536,8 +6359,7 @@ system and gives an overview of their function and contents.
5536 patched, it uses "patch". 6359 patched, it uses "patch".
5537 6360
5538 If you wish to use an alternative patching tool, set the variable in 6361 If you wish to use an alternative patching tool, set the variable in
5539 the recipe using one of the following: 6362 the recipe using one of the following::
5540 ::
5541 6363
5542 PATCHTOOL = "patch" 6364 PATCHTOOL = "patch"
5543 PATCHTOOL = "quilt" 6365 PATCHTOOL = "quilt"
@@ -5548,7 +6370,15 @@ system and gives an overview of their function and contents.
5548 variable is used to make upgrades possible when the versioning scheme 6370 variable is used to make upgrades possible when the versioning scheme
5549 changes in some backwards incompatible way. 6371 changes in some backwards incompatible way.
5550 6372
5551 ``PE`` is the default value of the :term:`PKGE` variable. 6373 :term:`PE` is the default value of the :term:`PKGE` variable.
6374
6375 :term:`PEP517_WHEEL_PATH`
6376 When used by recipes that inherit the :ref:`ref-classes-python_pep517`
6377 class, denotes the path to ``dist/`` (short for distribution) where the
6378 binary archive ``wheel`` is built.
6379
6380 :term:`PERSISTENT_DIR`
6381 See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual.
5552 6382
5553 :term:`PF` 6383 :term:`PF`
5554 Specifies the recipe or package name and includes all version and 6384 Specifies the recipe or package name and includes all version and
@@ -5557,10 +6387,11 @@ system and gives an overview of their function and contents.
5557 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} 6387 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
5558 6388
5559 :term:`PIXBUF_PACKAGES` 6389 :term:`PIXBUF_PACKAGES`
5560 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` 6390 When inheriting the :ref:`ref-classes-pixbufcache`
5561 class, this variable identifies packages that contain the pixbuf 6391 class, this variable identifies packages that contain the pixbuf
5562 loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` 6392 loaders used with ``gdk-pixbuf``. By default, the
5563 class assumes that the loaders are in the recipe's main package (i.e. 6393 :ref:`ref-classes-pixbufcache` class assumes that
6394 the loaders are in the recipe's main package (i.e.
5564 ``${``\ :term:`PN`\ ``}``). Use this variable if the 6395 ``${``\ :term:`PN`\ ``}``). Use this variable if the
5565 loaders you need are in a package other than that main package. 6396 loaders you need are in a package other than that main package.
5566 6397
@@ -5570,11 +6401,10 @@ system and gives an overview of their function and contents.
5570 6401
5571 .. note:: 6402 .. note::
5572 6403
5573 When using the ``PKG`` variable, you must use a package name override. 6404 When using the :term:`PKG` variable, you must use a package name override.
5574 6405
5575 For example, when the :ref:`debian <ref-classes-debian>` class 6406 For example, when the :ref:`ref-classes-debian` class renames the output
5576 renames the output package, it does so by setting 6407 package, it does so by setting ``PKG:packagename``.
5577 ``PKG_packagename``.
5578 6408
5579 :term:`PKG_CONFIG_PATH` 6409 :term:`PKG_CONFIG_PATH`
5580 The path to ``pkg-config`` files for the current build context. 6410 The path to ``pkg-config`` files for the current build context.
@@ -5583,8 +6413,7 @@ system and gives an overview of their function and contents.
5583 :term:`PKGD` 6413 :term:`PKGD`
5584 Points to the destination directory for files to be packaged before 6414 Points to the destination directory for files to be packaged before
5585 they are split into individual packages. This directory defaults to 6415 they are split into individual packages. This directory defaults to
5586 the following: 6416 the following::
5587 ::
5588 6417
5589 ${WORKDIR}/package 6418 ${WORKDIR}/package
5590 6419
@@ -5596,15 +6425,14 @@ system and gives an overview of their function and contents.
5596 :ref:`ref-tasks-packagedata` task packages data 6425 :ref:`ref-tasks-packagedata` task packages data
5597 for each recipe and installs it into this temporary, shared area. 6426 for each recipe and installs it into this temporary, shared area.
5598 This directory defaults to the following, which you should not 6427 This directory defaults to the following, which you should not
5599 change: 6428 change::
5600 ::
5601 6429
5602 ${STAGING_DIR_HOST}/pkgdata 6430 ${STAGING_DIR_HOST}/pkgdata
5603 6431
5604 For examples of how this data is used, see the 6432 For examples of how this data is used, see the
5605 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6433 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
5606 section in the Yocto Project Overview and Concepts Manual and the 6434 section in the Yocto Project Overview and Concepts Manual and the
5607 ":ref:`dev-manual/common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" 6435 ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``"
5608 section in the Yocto Project Development Tasks Manual. For more 6436 section in the Yocto Project Development Tasks Manual. For more
5609 information on the shared, global-state directory, see 6437 information on the shared, global-state directory, see
5610 :term:`STAGING_DIR_HOST`. 6438 :term:`STAGING_DIR_HOST`.
@@ -5612,8 +6440,7 @@ system and gives an overview of their function and contents.
5612 :term:`PKGDEST` 6440 :term:`PKGDEST`
5613 Points to the parent directory for files to be packaged after they 6441 Points to the parent directory for files to be packaged after they
5614 have been split into individual packages. This directory defaults to 6442 have been split into individual packages. This directory defaults to
5615 the following: 6443 the following::
5616 ::
5617 6444
5618 ${WORKDIR}/packages-split 6445 ${WORKDIR}/packages-split
5619 6446
@@ -5624,68 +6451,53 @@ system and gives an overview of their function and contents.
5624 :term:`PKGDESTWORK` 6451 :term:`PKGDESTWORK`
5625 Points to a temporary work area where the 6452 Points to a temporary work area where the
5626 :ref:`ref-tasks-package` task saves package metadata. 6453 :ref:`ref-tasks-package` task saves package metadata.
5627 The ``PKGDESTWORK`` location defaults to the following: 6454 The :term:`PKGDESTWORK` location defaults to the following::
5628 ::
5629 6455
5630 ${WORKDIR}/pkgdata 6456 ${WORKDIR}/pkgdata
5631 6457
5632 Do not change this default. 6458 Do not change this default.
5633 6459
5634 The :ref:`ref-tasks-packagedata` task copies the 6460 The :ref:`ref-tasks-packagedata` task copies the
5635 package metadata from ``PKGDESTWORK`` to 6461 package metadata from :term:`PKGDESTWORK` to
5636 :term:`PKGDATA_DIR` to make it available globally. 6462 :term:`PKGDATA_DIR` to make it available globally.
5637 6463
5638 :term:`PKGE` 6464 :term:`PKGE`
5639 The epoch of the package(s) built by the recipe. By default, ``PKGE`` 6465 The epoch of the package(s) built by the recipe. By default, :term:`PKGE`
5640 is set to :term:`PE`. 6466 is set to :term:`PE`.
5641 6467
5642 :term:`PKGR` 6468 :term:`PKGR`
5643 The revision of the package(s) built by the recipe. By default, 6469 The revision of the package(s) built by the recipe. By default,
5644 ``PKGR`` is set to :term:`PR`. 6470 :term:`PKGR` is set to :term:`PR`.
5645 6471
5646 :term:`PKGV` 6472 :term:`PKGV`
5647 The version of the package(s) built by the recipe. By default, 6473 The version of the package(s) built by the recipe. By default,
5648 ``PKGV`` is set to :term:`PV`. 6474 :term:`PKGV` is set to :term:`PV`.
5649 6475
5650 :term:`PN` 6476 :term:`PN`
5651 This variable can have two separate functions depending on the 6477 This variable can have two separate functions depending on the
5652 context: a recipe name or a resulting package name. 6478 context: a recipe name or a resulting package name.
5653 6479
5654 ``PN`` refers to a recipe name in the context of a file used by the 6480 :term:`PN` refers to a recipe name in the context of a file used by the
5655 OpenEmbedded build system as input to create a package. The name is 6481 OpenEmbedded build system as input to create a package. The name is
5656 normally extracted from the recipe file name. For example, if the 6482 normally extracted from the recipe file name. For example, if the
5657 recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` 6483 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN`
5658 will be "expat". 6484 will be "expat".
5659 6485
5660 The variable refers to a package name in the context of a file 6486 The variable refers to a package name in the context of a file
5661 created or produced by the OpenEmbedded build system. 6487 created or produced by the OpenEmbedded build system.
5662 6488
5663 If applicable, the ``PN`` variable also contains any special suffix 6489 If applicable, the :term:`PN` variable also contains any special suffix
5664 or prefix. For example, using ``bash`` to build packages for the 6490 or prefix. For example, using ``bash`` to build packages for the
5665 native machine, ``PN`` is ``bash-native``. Using ``bash`` to build 6491 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build
5666 packages for the target and for Multilib, ``PN`` would be ``bash`` 6492 packages for the target and for Multilib, :term:`PN` would be ``bash``
5667 and ``lib64-bash``, respectively. 6493 and ``lib64-bash``, respectively.
5668 6494
5669 :term:`PNBLACKLIST`
5670 Lists recipes you do not want the OpenEmbedded build system to build.
5671 This variable works in conjunction with the
5672 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited
5673 globally.
5674
5675 To prevent a recipe from being built, use the ``PNBLACKLIST``
5676 variable in your ``local.conf`` file. Here is an example that
5677 prevents ``myrecipe`` from being built:
5678 ::
5679
5680 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5681
5682 :term:`POPULATE_SDK_POST_HOST_COMMAND` 6495 :term:`POPULATE_SDK_POST_HOST_COMMAND`
5683 Specifies a list of functions to call once the OpenEmbedded build 6496 Specifies a list of functions to call once the OpenEmbedded build
5684 system has created the host part of the SDK. You can specify 6497 system has created the host part of the SDK. You can specify
5685 functions separated by semicolons: 6498 functions separated by spaces::
5686 ::
5687 6499
5688 POPULATE_SDK_POST_HOST_COMMAND += "function; ... " 6500 POPULATE_SDK_POST_HOST_COMMAND += "function"
5689 6501
5690 If you need to pass the SDK path to a command within a function, you 6502 If you need to pass the SDK path to a command within a function, you
5691 can use ``${SDK_DIR}``, which points to the parent directory used by 6503 can use ``${SDK_DIR}``, which points to the parent directory used by
@@ -5695,10 +6507,9 @@ system and gives an overview of their function and contents.
5695 :term:`POPULATE_SDK_POST_TARGET_COMMAND` 6507 :term:`POPULATE_SDK_POST_TARGET_COMMAND`
5696 Specifies a list of functions to call once the OpenEmbedded build 6508 Specifies a list of functions to call once the OpenEmbedded build
5697 system has created the target part of the SDK. You can specify 6509 system has created the target part of the SDK. You can specify
5698 functions separated by semicolons: 6510 functions separated by spaces::
5699 ::
5700 6511
5701 POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " 6512 POPULATE_SDK_POST_TARGET_COMMAND += "function"
5702 6513
5703 If you need to pass the SDK path to a command within a function, you 6514 If you need to pass the SDK path to a command within a function, you
5704 can use ``${SDK_DIR}``, which points to the parent directory used by 6515 can use ``${SDK_DIR}``, which points to the parent directory used by
@@ -5709,35 +6520,35 @@ system and gives an overview of their function and contents.
5709 The revision of the recipe. The default value for this variable is 6520 The revision of the recipe. The default value for this variable is
5710 "r0". Subsequent revisions of the recipe conventionally have the 6521 "r0". Subsequent revisions of the recipe conventionally have the
5711 values "r1", "r2", and so forth. When :term:`PV` increases, 6522 values "r1", "r2", and so forth. When :term:`PV` increases,
5712 ``PR`` is conventionally reset to "r0". 6523 :term:`PR` is conventionally reset to "r0".
5713 6524
5714 .. note:: 6525 .. note::
5715 6526
5716 The OpenEmbedded build system does not need the aid of ``PR`` 6527 The OpenEmbedded build system does not need the aid of :term:`PR`
5717 to know when to rebuild a recipe. The build system uses the task 6528 to know when to rebuild a recipe. The build system uses the task
5718 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the 6529 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the
5719 :ref:`stamp <structure-build-tmp-stamps>` and 6530 :ref:`stamp <structure-build-tmp-stamps>` and
5720 :ref:`overview-manual/concepts:shared state cache` 6531 :ref:`overview-manual/concepts:shared state cache`
5721 mechanisms. 6532 mechanisms.
5722 6533
5723 The ``PR`` variable primarily becomes significant when a package 6534 The :term:`PR` variable primarily becomes significant when a package
5724 manager dynamically installs packages on an already built image. In 6535 manager dynamically installs packages on an already built image. In
5725 this case, ``PR``, which is the default value of 6536 this case, :term:`PR`, which is the default value of
5726 :term:`PKGR`, helps the package manager distinguish which 6537 :term:`PKGR`, helps the package manager distinguish which
5727 package is the most recent one in cases where many packages have the 6538 package is the most recent one in cases where many packages have the
5728 same ``PV`` (i.e. ``PKGV``). A component having many packages with 6539 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with
5729 the same ``PV`` usually means that the packages all install the same 6540 the same :term:`PV` usually means that the packages all install the same
5730 upstream version, but with later (``PR``) version packages including 6541 upstream version, but with later (:term:`PR`) version packages including
5731 packaging fixes. 6542 packaging fixes.
5732 6543
5733 .. note:: 6544 .. note::
5734 6545
5735 ``PR`` does not need to be increased for changes that do not change the 6546 :term:`PR` does not need to be increased for changes that do not change the
5736 package contents or metadata. 6547 package contents or metadata.
5737 6548
5738 Because manually managing ``PR`` can be cumbersome and error-prone, 6549 Because manually managing :term:`PR` can be cumbersome and error-prone,
5739 an automated solution exists. See the 6550 an automated solution exists. See the
5740 ":ref:`dev-manual/common-tasks:working with a pr service`" section 6551 ":ref:`dev-manual/packages:working with a pr service`" section
5741 in the Yocto Project Development Tasks Manual for more information. 6552 in the Yocto Project Development Tasks Manual for more information.
5742 6553
5743 :term:`PREFERRED_PROVIDER` 6554 :term:`PREFERRED_PROVIDER`
@@ -5746,45 +6557,46 @@ system and gives an overview of their function and contents.
5746 preferred provider). You should always suffix this variable with the 6557 preferred provider). You should always suffix this variable with the
5747 name of the provided item. And, you should define the variable using 6558 name of the provided item. And, you should define the variable using
5748 the preferred recipe's name (:term:`PN`). Here is a common 6559 the preferred recipe's name (:term:`PN`). Here is a common
5749 example: 6560 example::
5750 ::
5751 6561
5752 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 6562 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5753 6563
5754 In the previous example, multiple recipes are providing "virtual/kernel". 6564 In the previous example, multiple recipes are providing "virtual/kernel".
5755 The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of 6565 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of
5756 the recipe you prefer to provide "virtual/kernel". 6566 the recipe you prefer to provide "virtual/kernel".
5757 6567
5758 Following are more examples: 6568 Here are more examples::
5759 ::
5760 6569
5761 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" 6570 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5762 PREFERRED_PROVIDER_virtual/libgl ?= "mesa" 6571 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5763 6572
5764 For more 6573 For more
5765 information, see the ":ref:`dev-manual/common-tasks:using virtual providers`" 6574 information, see the ":ref:`dev-manual/new-recipe:using virtual providers`"
5766 section in the Yocto Project Development Tasks Manual. 6575 section in the Yocto Project Development Tasks Manual.
5767 6576
5768 .. note:: 6577 .. note::
5769 6578
5770 If you use a ``virtual/\*`` item with ``PREFERRED_PROVIDER``, then any 6579 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any
5771 recipe that :term:`PROVIDES` that item but is not selected (defined) 6580 recipe that :term:`PROVIDES` that item but is not selected (defined)
5772 by ``PREFERRED_PROVIDER`` is prevented from building, which is usually 6581 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually
5773 desirable since this mechanism is designed to select between mutually 6582 desirable since this mechanism is designed to select between mutually
5774 exclusive alternative providers. 6583 exclusive alternative providers.
5775 6584
6585 :term:`PREFERRED_PROVIDERS`
6586 See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual.
6587
5776 :term:`PREFERRED_VERSION` 6588 :term:`PREFERRED_VERSION`
5777 If multiple versions of recipes exist, this variable determines which 6589 If there are multiple versions of a recipe available, this variable
5778 version is given preference. You must always suffix the variable with 6590 determines which version should be given preference. You must always
5779 the :term:`PN` you want to select, and you should set the 6591 suffix the variable with the :term:`PN` you want to select (`python` in
5780 :term:`PV` accordingly for precedence. 6592 the first example below), and you should specify the :term:`PV`
6593 accordingly (`3.4.0` in the example).
5781 6594
5782 The ``PREFERRED_VERSION`` variable supports limited wildcard use 6595 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
5783 through the "``%``" character. You can use the character to match any 6596 through the "``%``" character. You can use the character to match any
5784 number of characters, which can be useful when specifying versions 6597 number of characters, which can be useful when specifying versions
5785 that contain long revision numbers that potentially change. Here are 6598 that contain long revision numbers that potentially change. Here are
5786 two examples: 6599 two examples::
5787 ::
5788 6600
5789 PREFERRED_VERSION_python = "3.4.0" 6601 PREFERRED_VERSION_python = "3.4.0"
5790 PREFERRED_VERSION_linux-yocto = "5.0%" 6602 PREFERRED_VERSION_linux-yocto = "5.0%"
@@ -5798,66 +6610,63 @@ system and gives an overview of their function and contents.
5798 The specified version is matched against :term:`PV`, which 6610 The specified version is matched against :term:`PV`, which
5799 does not necessarily match the version part of the recipe's filename. 6611 does not necessarily match the version part of the recipe's filename.
5800 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` 6612 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
5801 where ``foo_git.bb`` contains the following assignment: 6613 where ``foo_git.bb`` contains the following assignment::
5802 ::
5803 6614
5804 PV = "1.1+git${SRCPV}" 6615 PV = "1.1+git${SRCPV}"
5805 6616
5806 In this case, the correct way to select 6617 In this case, the correct way to select
5807 ``foo_git.bb`` is by using an assignment such as the following: 6618 ``foo_git.bb`` is by using an assignment such as the following::
5808 ::
5809 6619
5810 PREFERRED_VERSION_foo = "1.1+git%" 6620 PREFERRED_VERSION_foo = "1.1+git%"
5811 6621
5812 Compare that previous example 6622 Compare that previous example
5813 against the following incorrect example, which does not work: 6623 against the following incorrect example, which does not work::
5814 ::
5815 6624
5816 PREFERRED_VERSION_foo = "git" 6625 PREFERRED_VERSION_foo = "git"
5817 6626
5818 Sometimes the ``PREFERRED_VERSION`` variable can be set by 6627 Sometimes the :term:`PREFERRED_VERSION` variable can be set by
5819 configuration files in a way that is hard to change. You can use 6628 configuration files in a way that is hard to change. You can use
5820 :term:`OVERRIDES` to set a machine-specific 6629 :term:`OVERRIDES` to set a machine-specific
5821 override. Here is an example: 6630 override. Here is an example::
5822 ::
5823 6631
5824 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" 6632 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
5825 6633
5826 Although not recommended, worst case, you can also use the 6634 Although not recommended, worst case, you can also use the
5827 "forcevariable" override, which is the strongest override possible. 6635 "forcevariable" override, which is the strongest override possible.
5828 Here is an example: 6636 Here is an example::
5829 ::
5830 6637
5831 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" 6638 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
5832 6639
5833 .. note:: 6640 .. note::
5834 6641
5835 The ``\_forcevariable`` override is not handled specially. This override 6642 The ``:forcevariable`` override is not handled specially. This override
5836 only works because the default value of ``OVERRIDES`` includes "forcevariable". 6643 only works because the default value of :term:`OVERRIDES` includes "forcevariable".
6644
6645 If a recipe with the specified version is not available, a warning
6646 message will be shown. See :term:`REQUIRED_VERSION` if you want this
6647 to be an error instead.
5837 6648
5838 :term:`PREMIRRORS` 6649 :term:`PREMIRRORS`
5839 Specifies additional paths from which the OpenEmbedded build system 6650 Specifies additional paths from which the OpenEmbedded build system
5840 gets source code. When the build system searches for source code, it 6651 gets source code. When the build system searches for source code, it
5841 first tries the local download directory. If that location fails, the 6652 first tries the local download directory. If that location fails, the
5842 build system tries locations defined by ``PREMIRRORS``, the upstream 6653 build system tries locations defined by :term:`PREMIRRORS`, the upstream
5843 source, and then locations specified by 6654 source, and then locations specified by
5844 :term:`MIRRORS` in that order. 6655 :term:`MIRRORS` in that order.
5845 6656
5846 Assuming your distribution (:term:`DISTRO`) is "poky", 6657 The default value for :term:`PREMIRRORS` is defined in the
5847 the default value for ``PREMIRRORS`` is defined in the 6658 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
5848 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
5849 6659
5850 Typically, you could add a specific server for the build system to 6660 Typically, you could add a specific server for the build system to
5851 attempt before any others by adding something like the following to 6661 attempt before any others by adding something like the following to
5852 the ``local.conf`` configuration file in the 6662 the ``local.conf`` configuration file in the
5853 :term:`Build Directory`: 6663 :term:`Build Directory`::
5854 ::
5855 6664
5856 PREMIRRORS_prepend = "\ 6665 PREMIRRORS:prepend = "\
5857 git://.*/.* http://www.yoctoproject.org/sources/ \n \ 6666 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
5858 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ 6667 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
5859 http://.*/.* http://www.yoctoproject.org/sources/ \n \ 6668 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
5860 https://.*/.* http://www.yoctoproject.org/sources/ \n" 6669 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
5861 6670
5862 These changes cause the 6671 These changes cause the
5863 build system to intercept Git, FTP, HTTP, and HTTPS requests and 6672 build system to intercept Git, FTP, HTTP, and HTTPS requests and
@@ -5868,12 +6677,12 @@ system and gives an overview of their function and contents.
5868 :term:`PRIORITY` 6677 :term:`PRIORITY`
5869 Indicates the importance of a package. 6678 Indicates the importance of a package.
5870 6679
5871 ``PRIORITY`` is considered to be part of the distribution policy 6680 :term:`PRIORITY` is considered to be part of the distribution policy
5872 because the importance of any given recipe depends on the purpose for 6681 because the importance of any given recipe depends on the purpose for
5873 which the distribution is being produced. Thus, ``PRIORITY`` is not 6682 which the distribution is being produced. Thus, :term:`PRIORITY` is not
5874 normally set within recipes. 6683 normally set within recipes.
5875 6684
5876 You can set ``PRIORITY`` to "required", "standard", "extra", and 6685 You can set :term:`PRIORITY` to "required", "standard", "extra", and
5877 "optional", which is the default. 6686 "optional", which is the default.
5878 6687
5879 :term:`PRIVATE_LIBS` 6688 :term:`PRIVATE_LIBS`
@@ -5887,8 +6696,7 @@ system and gives an overview of their function and contents.
5887 standard version of the library. 6696 standard version of the library.
5888 6697
5889 Libraries specified in this variable should be specified by their 6698 Libraries specified in this variable should be specified by their
5890 file name. For example, from the Firefox recipe in meta-browser: 6699 file name. For example, from the Firefox recipe in meta-browser::
5891 ::
5892 6700
5893 PRIVATE_LIBS = "libmozjs.so \ 6701 PRIVATE_LIBS = "libmozjs.so \
5894 libxpcom.so \ 6702 libxpcom.so \
@@ -5904,35 +6712,34 @@ system and gives an overview of their function and contents.
5904 6712
5905 :term:`PROVIDES` 6713 :term:`PROVIDES`
5906 A list of aliases by which a particular recipe can be known. By 6714 A list of aliases by which a particular recipe can be known. By
5907 default, a recipe's own ``PN`` is implicitly already in its 6715 default, a recipe's own :term:`PN` is implicitly already in its
5908 ``PROVIDES`` list and therefore does not need to mention that it 6716 :term:`PROVIDES` list and therefore does not need to mention that it
5909 provides itself. If a recipe uses ``PROVIDES``, the additional 6717 provides itself. If a recipe uses :term:`PROVIDES`, the additional
5910 aliases are synonyms for the recipe and can be useful for satisfying 6718 aliases are synonyms for the recipe and can be useful for satisfying
5911 dependencies of other recipes during the build as specified by 6719 dependencies of other recipes during the build as specified by
5912 ``DEPENDS``. 6720 :term:`DEPENDS`.
5913 6721
5914 Consider the following example ``PROVIDES`` statement from the recipe 6722 Consider the following example :term:`PROVIDES` statement from the recipe
5915 file ``eudev_3.2.9.bb``: 6723 file ``eudev_3.2.9.bb``::
5916 ::
5917 6724
5918 PROVIDES += "udev" 6725 PROVIDES += "udev"
5919 6726
5920 The ``PROVIDES`` statement 6727 The :term:`PROVIDES` statement
5921 results in the "eudev" recipe also being available as simply "udev". 6728 results in the "eudev" recipe also being available as simply "udev".
5922 6729
5923 .. note:: 6730 .. note::
5924 6731
5925 A recipe's own recipe name (:term:`PN`) is always implicitly prepended 6732 A recipe's own recipe name (:term:`PN`) is always implicitly prepended
5926 to `PROVIDES`, so while using "+=" in the above example may not be 6733 to :term:`PROVIDES`, so while using "+=" in the above example may not be
5927 strictly necessary it is recommended to avoid confusion. 6734 strictly necessary it is recommended to avoid confusion.
5928 6735
5929 In addition to providing recipes under alternate names, the 6736 In addition to providing recipes under alternate names, the
5930 ``PROVIDES`` mechanism is also used to implement virtual targets. A 6737 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
5931 virtual target is a name that corresponds to some particular 6738 virtual target is a name that corresponds to some particular
5932 functionality (e.g. a Linux kernel). Recipes that provide the 6739 functionality (e.g. a Linux kernel). Recipes that provide the
5933 functionality in question list the virtual target in ``PROVIDES``. 6740 functionality in question list the virtual target in :term:`PROVIDES`.
5934 Recipes that depend on the functionality in question can include the 6741 Recipes that depend on the functionality in question can include the
5935 virtual target in ``DEPENDS`` to leave the choice of provider open. 6742 virtual target in :term:`DEPENDS` to leave the choice of provider open.
5936 6743
5937 Conventionally, virtual targets have names on the form 6744 Conventionally, virtual targets have names on the form
5938 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 6745 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
@@ -5943,15 +6750,14 @@ system and gives an overview of their function and contents.
5943 6750
5944 .. note:: 6751 .. note::
5945 6752
5946 A corresponding mechanism for virtual runtime dependencies 6753 A corresponding mechanism for virtual runtime dependencies (packages)
5947 (packages) exists. However, the mechanism does not depend on any 6754 exists. However, the mechanism does not depend on any special
5948 special functionality beyond ordinary variable assignments. For 6755 functionality beyond ordinary variable assignments. For example,
5949 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of 6756 :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the
5950 the component that manages the ``/dev`` directory. 6757 package of the component that manages the ``/dev`` directory.
5951 6758
5952 Setting the "preferred provider" for runtime dependencies is as 6759 Setting the "preferred provider" for runtime dependencies is as
5953 simple as using the following assignment in a configuration file: 6760 simple as using the following assignment in a configuration file::
5954 ::
5955 6761
5956 VIRTUAL-RUNTIME_dev_manager = "udev" 6762 VIRTUAL-RUNTIME_dev_manager = "udev"
5957 6763
@@ -5959,17 +6765,16 @@ system and gives an overview of their function and contents.
5959 :term:`PRSERV_HOST` 6765 :term:`PRSERV_HOST`
5960 The network based :term:`PR` service host and port. 6766 The network based :term:`PR` service host and port.
5961 6767
5962 The ``conf/local.conf.sample.extended`` configuration file in the 6768 The ``conf/templates/default/local.conf.sample.extended`` configuration
5963 :term:`Source Directory` shows how the 6769 file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST`
5964 ``PRSERV_HOST`` variable is set: 6770 variable is set::
5965 ::
5966 6771
5967 PRSERV_HOST = "localhost:0" 6772 PRSERV_HOST = "localhost:0"
5968 6773
5969 You must 6774 You must
5970 set the variable if you want to automatically start a local :ref:`PR 6775 set the variable if you want to automatically start a local :ref:`PR
5971 service <dev-manual/common-tasks:working with a pr service>`. You can 6776 service <dev-manual/packages:working with a pr service>`. You can
5972 set ``PRSERV_HOST`` to other values to use a remote PR service. 6777 set :term:`PRSERV_HOST` to other values to use a remote PR service.
5973 6778
5974 6779
5975 :term:`PSEUDO_IGNORE_PATHS` 6780 :term:`PSEUDO_IGNORE_PATHS`
@@ -5982,7 +6787,7 @@ system and gives an overview of their function and contents.
5982 6787
5983 :term:`PTEST_ENABLED` 6788 :term:`PTEST_ENABLED`
5984 Specifies whether or not :ref:`Package 6789 Specifies whether or not :ref:`Package
5985 Test <dev-manual/common-tasks:testing packages with ptest>` (ptest) 6790 Test <dev-manual/packages:testing packages with ptest>` (ptest)
5986 functionality is enabled when building a recipe. You should not set 6791 functionality is enabled when building a recipe. You should not set
5987 this variable directly. Enabling and disabling building Package Tests 6792 this variable directly. Enabling and disabling building Package Tests
5988 at build time should be done by adding "ptest" to (or removing it 6793 at build time should be done by adding "ptest" to (or removing it
@@ -5991,49 +6796,52 @@ system and gives an overview of their function and contents.
5991 :term:`PV` 6796 :term:`PV`
5992 The version of the recipe. The version is normally extracted from the 6797 The version of the recipe. The version is normally extracted from the
5993 recipe filename. For example, if the recipe is named 6798 recipe filename. For example, if the recipe is named
5994 ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". 6799 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1".
5995 ``PV`` is generally not overridden within a recipe unless it is 6800 :term:`PV` is generally not overridden within a recipe unless it is
5996 building an unstable (i.e. development) version from a source code 6801 building an unstable (i.e. development) version from a source code
5997 repository (e.g. Git or Subversion). 6802 repository (e.g. Git or Subversion).
5998 6803
5999 ``PV`` is the default value of the :term:`PKGV` variable. 6804 :term:`PV` is the default value of the :term:`PKGV` variable.
6805
6806 :term:`PYPI_PACKAGE`
6807 When inheriting the :ref:`ref-classes-pypi` class, specifies the
6808 `PyPI <https://pypi.org/>`__ package name to be built. The default value
6809 is set based upon :term:`BPN` (stripping any "python-" or "python3-"
6810 prefix off if present), however for some packages it will need to be set
6811 explicitly if that will not match the package name (e.g. where the
6812 package name has a prefix, underscores, uppercase letters etc.)
6000 6813
6001 :term:`PYTHON_ABI` 6814 :term:`PYTHON_ABI`
6002 When used by recipes that inherit the 6815 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
6003 :ref:`distutils3 <ref-classes-distutils3>`, 6816 class, denotes the Application Binary Interface (ABI) currently in use
6004 :ref:`setuptools3 <ref-classes-setuptools3>`, 6817 for Python. By default, the ABI is "m". You do not have to set this
6005 :ref:`distutils <ref-classes-distutils>`, or 6818 variable as the OpenEmbedded build system sets it for you.
6006 :ref:`setuptools <ref-classes-setuptools>` classes, denotes the
6007 Application Binary Interface (ABI) currently in use for Python. By
6008 default, the ABI is "m". You do not have to set this variable as the
6009 OpenEmbedded build system sets it for you.
6010 6819
6011 The OpenEmbedded build system uses the ABI to construct directory 6820 The OpenEmbedded build system uses the ABI to construct directory
6012 names used when installing the Python headers and libraries in 6821 names used when installing the Python headers and libraries in
6013 sysroot (e.g. ``.../python3.3m/...``). 6822 sysroot (e.g. ``.../python3.3m/...``).
6014 6823
6015 Recipes that inherit the ``distutils`` class during cross-builds also 6824 :term:`QA_EMPTY_DIRS`
6016 use this variable to locate the headers and libraries of the 6825 Specifies a list of directories that are expected to be empty when
6017 appropriate Python that the extension is targeting. 6826 packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or
6827 :term:`WARN_QA` these will be checked and an error or warning
6828 (respectively) will be produced.
6829
6830 The default :term:`QA_EMPTY_DIRS` value is set in
6831 :ref:`insane.bbclass <ref-classes-insane>`.
6018 6832
6019 :term:`PYTHON_PN` 6833 :term:`QA_EMPTY_DIRS_RECOMMENDATION`
6020 When used by recipes that inherit the 6834 Specifies a recommendation for why a directory must be empty,
6021 `distutils3 <ref-classes-distutils3>`, 6835 which will be included in the error message if a specific directory
6022 :ref:`setuptools3 <ref-classes-setuptools3>`, 6836 is found to contain files. Must be overridden with the directory
6023 :ref:`distutils <ref-classes-distutils>`, or 6837 path to match on.
6024 :ref:`setuptools <ref-classes-setuptools>` classes, specifies the
6025 major Python version being built. For Python 3.x, ``PYTHON_PN`` would
6026 be "python3". You do not have to set this variable as the
6027 OpenEmbedded build system automatically sets it for you.
6028 6838
6029 The variable allows recipes to use common infrastructure such as the 6839 If no recommendation is specified for a directory, then the default
6030 following: 6840 "but it is expected to be empty" will be used.
6031 ::
6032 6841
6033 DEPENDS += "${PYTHON_PN}-native" 6842 An example message shows if files were present in '/dev'::
6034 6843
6035 In the previous example, 6844 QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"
6036 the version of the dependency is ``PYTHON_PN``.
6037 6845
6038 :term:`RANLIB` 6846 :term:`RANLIB`
6039 The minimal command and arguments to run ``ranlib``. 6847 The minimal command and arguments to run ``ranlib``.
@@ -6043,19 +6851,17 @@ system and gives an overview of their function and contents.
6043 will not be installed if conflicting packages are not first removed. 6851 will not be installed if conflicting packages are not first removed.
6044 6852
6045 Like all package-controlling variables, you must always use them in 6853 Like all package-controlling variables, you must always use them in
6046 conjunction with a package name override. Here is an example: 6854 conjunction with a package name override. Here is an example::
6047 ::
6048 6855
6049 RCONFLICTS_${PN} = "another_conflicting_package_name" 6856 RCONFLICTS:${PN} = "another_conflicting_package_name"
6050 6857
6051 BitBake, which the OpenEmbedded build system uses, supports 6858 BitBake, which the OpenEmbedded build system uses, supports
6052 specifying versioned dependencies. Although the syntax varies 6859 specifying versioned dependencies. Although the syntax varies
6053 depending on the packaging format, BitBake hides these differences 6860 depending on the packaging format, BitBake hides these differences
6054 from you. Here is the general syntax to specify versions with the 6861 from you. Here is the general syntax to specify versions with the
6055 ``RCONFLICTS`` variable: 6862 :term:`RCONFLICTS` variable::
6056 ::
6057 6863
6058 RCONFLICTS_${PN} = "package (operator version)" 6864 RCONFLICTS:${PN} = "package (operator version)"
6059 6865
6060 For ``operator``, you can specify the following: 6866 For ``operator``, you can specify the following:
6061 6867
@@ -6066,32 +6872,30 @@ system and gives an overview of their function and contents.
6066 - >= 6872 - >=
6067 6873
6068 For example, the following sets up a dependency on version 1.2 or 6874 For example, the following sets up a dependency on version 1.2 or
6069 greater of the package ``foo``: 6875 greater of the package ``foo``::
6070 ::
6071 6876
6072 RCONFLICTS_${PN} = "foo (>= 1.2)" 6877 RCONFLICTS:${PN} = "foo (>= 1.2)"
6073 6878
6074 :term:`RDEPENDS` 6879 :term:`RDEPENDS`
6075 Lists runtime dependencies of a package. These dependencies are other 6880 Lists runtime dependencies of a package. These dependencies are other
6076 packages that must be installed in order for the package to function 6881 packages that must be installed in order for the package to function
6077 correctly. As an example, the following assignment declares that the 6882 correctly. As an example, the following assignment declares that the
6078 package ``foo`` needs the packages ``bar`` and ``baz`` to be 6883 package ``foo`` needs the packages ``bar`` and ``baz`` to be
6079 installed: 6884 installed::
6080 ::
6081 6885
6082 RDEPENDS_foo = "bar baz" 6886 RDEPENDS:foo = "bar baz"
6083 6887
6084 The most common types of package 6888 The most common types of package
6085 runtime dependencies are automatically detected and added. Therefore, 6889 runtime dependencies are automatically detected and added. Therefore,
6086 most recipes do not need to set ``RDEPENDS``. For more information, 6890 most recipes do not need to set :term:`RDEPENDS`. For more information,
6087 see the 6891 see the
6088 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 6892 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
6089 section in the Yocto Project Overview and Concepts Manual. 6893 section in the Yocto Project Overview and Concepts Manual.
6090 6894
6091 The practical effect of the above ``RDEPENDS`` assignment is that 6895 The practical effect of the above :term:`RDEPENDS` assignment is that
6092 ``bar`` and ``baz`` will be declared as dependencies inside the 6896 ``bar`` and ``baz`` will be declared as dependencies inside the
6093 package ``foo`` when it is written out by one of the 6897 package ``foo`` when it is written out by one of the
6094 :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks. 6898 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks.
6095 Exactly how this is done depends on which package format is used, 6899 Exactly how this is done depends on which package format is used,
6096 which is determined by 6900 which is determined by
6097 :term:`PACKAGE_CLASSES`. When the 6901 :term:`PACKAGE_CLASSES`. When the
@@ -6099,59 +6903,57 @@ system and gives an overview of their function and contents.
6099 also install the packages on which it depends. 6903 also install the packages on which it depends.
6100 6904
6101 To ensure that the packages ``bar`` and ``baz`` get built, the 6905 To ensure that the packages ``bar`` and ``baz`` get built, the
6102 previous ``RDEPENDS`` assignment also causes a task dependency to be 6906 previous :term:`RDEPENDS` assignment also causes a task dependency to be
6103 added. This dependency is from the recipe's 6907 added. This dependency is from the recipe's
6104 :ref:`ref-tasks-build` (not to be confused with 6908 :ref:`ref-tasks-build` (not to be confused with
6105 :ref:`ref-tasks-compile`) task to the 6909 :ref:`ref-tasks-compile`) task to the
6106 ``do_package_write_*`` task of the recipes that build ``bar`` and 6910 :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and
6107 ``baz``. 6911 ``baz``.
6108 6912
6109 The names of the packages you list within ``RDEPENDS`` must be the 6913 The names of the packages you list within :term:`RDEPENDS` must be the
6110 names of other packages - they cannot be recipe names. Although 6914 names of other packages --- they cannot be recipe names. Although
6111 package names and recipe names usually match, the important point 6915 package names and recipe names usually match, the important point
6112 here is that you are providing package names within the ``RDEPENDS`` 6916 here is that you are providing package names within the :term:`RDEPENDS`
6113 variable. For an example of the default list of packages created from 6917 variable. For an example of the default list of packages created from
6114 a recipe, see the :term:`PACKAGES` variable. 6918 a recipe, see the :term:`PACKAGES` variable.
6115 6919
6116 Because the ``RDEPENDS`` variable applies to packages being built, 6920 Because the :term:`RDEPENDS` variable applies to packages being built,
6117 you should always use the variable in a form with an attached package 6921 you should always use the variable in a form with an attached package
6118 name (remember that a single recipe can build multiple packages). For 6922 name (remember that a single recipe can build multiple packages). For
6119 example, suppose you are building a development package that depends 6923 example, suppose you are building a development package that depends
6120 on the ``perl`` package. In this case, you would use the following 6924 on the ``perl`` package. In this case, you would use the following
6121 ``RDEPENDS`` statement: 6925 :term:`RDEPENDS` statement::
6122 ::
6123 6926
6124 RDEPENDS_${PN}-dev += "perl" 6927 RDEPENDS:${PN}-dev += "perl"
6125 6928
6126 In the example, 6929 In the example,
6127 the development package depends on the ``perl`` package. Thus, the 6930 the development package depends on the ``perl`` package. Thus, the
6128 ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of 6931 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of
6129 the variable. 6932 the variable.
6130 6933
6131 .. note:: 6934 .. note::
6132 6935
6133 ``RDEPENDS_${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` 6936 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}``
6134 by default. This default is set in the BitBake configuration file 6937 by default. This default is set in the BitBake configuration file
6135 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove 6938 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove
6136 ``${PN}`` when modifying ``RDEPENDS_${PN}-dev``. Use the "+=" operator 6939 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator
6137 rather than the "=" operator. 6940 rather than the "=" operator.
6138 6941
6139 The package names you use with ``RDEPENDS`` must appear as they would 6942 The package names you use with :term:`RDEPENDS` must appear as they would
6140 in the ``PACKAGES`` variable. The :term:`PKG` variable 6943 in the :term:`PACKAGES` variable. The :term:`PKG` variable
6141 allows a different name to be used for the final package (e.g. the 6944 allows a different name to be used for the final package (e.g. the
6142 :ref:`debian <ref-classes-debian>` class uses this to rename 6945 :ref:`ref-classes-debian` class uses this to rename
6143 packages), but this final package name cannot be used with 6946 packages), but this final package name cannot be used with
6144 ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be 6947 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be
6145 independent of the package format used. 6948 independent of the package format used.
6146 6949
6147 BitBake, which the OpenEmbedded build system uses, supports 6950 BitBake, which the OpenEmbedded build system uses, supports
6148 specifying versioned dependencies. Although the syntax varies 6951 specifying versioned dependencies. Although the syntax varies
6149 depending on the packaging format, BitBake hides these differences 6952 depending on the packaging format, BitBake hides these differences
6150 from you. Here is the general syntax to specify versions with the 6953 from you. Here is the general syntax to specify versions with the
6151 ``RDEPENDS`` variable: 6954 :term:`RDEPENDS` variable::
6152 ::
6153 6955
6154 RDEPENDS_${PN} = "package (operator version)" 6956 RDEPENDS:${PN} = "package (operator version)"
6155 6957
6156 For ``operator``, you can specify the following: 6958 For ``operator``, you can specify the following:
6157 6959
@@ -6165,43 +6967,105 @@ system and gives an overview of their function and contents.
6165 6967
6166 .. note:: 6968 .. note::
6167 6969
6168 You can use ``EXTENDPKGV`` to provide a full package version 6970 You can use :term:`EXTENDPKGV` to provide a full package version
6169 specification. 6971 specification.
6170 6972
6171 For example, the following sets up a dependency on version 1.2 or 6973 For example, the following sets up a dependency on version 1.2 or
6172 greater of the package ``foo``: 6974 greater of the package ``foo``::
6173 ::
6174 6975
6175 RDEPENDS_${PN} = "foo (>= 1.2)" 6976 RDEPENDS:${PN} = "foo (>= 1.2)"
6176 6977
6177 For information on build-time dependencies, see the 6978 For information on build-time dependencies, see the :term:`DEPENDS`
6178 :term:`DEPENDS` variable. You can also see the 6979 variable. You can also see the
6179 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and 6980 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
6180 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the 6981 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
6181 BitBake User Manual for additional information on tasks and 6982 BitBake User Manual for additional information on tasks and dependencies.
6182 dependencies. 6983
6984 :term:`RECIPE_MAINTAINER`
6985 This variable defines the name and e-mail address of the maintainer of a
6986 recipe. Such information can be used by human users submitted changes,
6987 and by automated tools to send notifications, for example about
6988 vulnerabilities or source updates.
6989
6990 The variable can be defined in a global distribution :oe_git:`maintainers.inc
6991 </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file::
6992
6993 meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>"
6994
6995 It can also be directly defined in a recipe,
6996 for example in the ``libgpiod`` one::
6997
6998 RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>"
6999
7000 :term:`RECIPE_NO_UPDATE_REASON`
7001 If a recipe should not be replaced by a more recent upstream version,
7002 putting the reason why in this variable in a recipe allows
7003 ``devtool check-upgrade-status`` command to display it, as explained
7004 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`"
7005 section.
7006
7007 :term:`RECIPE_SYSROOT`
7008 This variable points to the directory that holds all files populated from
7009 recipes specified in :term:`DEPENDS`. As the name indicates,
7010 think of this variable as a custom root (``/``) for the recipe that will be
7011 used by the compiler in order to find headers and other files needed to complete
7012 its job.
7013
7014 This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
7015 according to the type of the recipe and the build target.
7016
7017 To better understand this variable, consider the following examples:
7018
7019 - For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"``
7020
7021 - For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"``
7022 or other library sysroot directories.
7023
7024 The default value is ``"${WORKDIR}/recipe-sysroot"``.
7025 Do not modify it.
7026
7027 :term:`RECIPE_SYSROOT_NATIVE`
7028 This is similar to :term:`RECIPE_SYSROOT` but the populated files are from
7029 ``-native`` recipes. This allows a recipe built for the target machine to
7030 use ``native`` tools.
7031
7032 This variable is related to :term:`STAGING_DIR_NATIVE`.
7033
7034 The default value is ``"${WORKDIR}/recipe-sysroot-native"``.
7035 Do not modify it.
7036
7037 :term:`REPODIR`
7038 See :term:`bitbake:REPODIR` in the BitBake manual.
6183 7039
6184 :term:`REQUIRED_DISTRO_FEATURES` 7040 :term:`REQUIRED_DISTRO_FEATURES`
6185 When inheriting the 7041 When inheriting the :ref:`ref-classes-features_check`
6186 :ref:`features_check <ref-classes-features_check>`
6187 class, this variable identifies distribution features that must exist 7042 class, this variable identifies distribution features that must exist
6188 in the current configuration in order for the OpenEmbedded build 7043 in the current configuration in order for the OpenEmbedded build
6189 system to build the recipe. In other words, if the 7044 system to build the recipe. In other words, if the
6190 ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not 7045 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not
6191 appear in ``DISTRO_FEATURES`` within the current configuration, then 7046 appear in :term:`DISTRO_FEATURES` within the current configuration, then
6192 the recipe will be skipped, and if the build system attempts to build 7047 the recipe will be skipped, and if the build system attempts to build
6193 the recipe then an error will be triggered. 7048 the recipe then an error will be triggered.
6194 7049
7050 :term:`REQUIRED_VERSION`
7051 If there are multiple versions of a recipe available, this variable
7052 determines which version should be given preference.
7053 :term:`REQUIRED_VERSION` works in exactly the same manner as
7054 :term:`PREFERRED_VERSION`, except that if the specified version is not
7055 available then an error message is shown and the build fails
7056 immediately.
7057
7058 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
7059 for the same recipe, the :term:`REQUIRED_VERSION` value applies.
7060
6195 :term:`RM_WORK_EXCLUDE` 7061 :term:`RM_WORK_EXCLUDE`
6196 With ``rm_work`` enabled, this variable specifies a list of recipes 7062 With :ref:`ref-classes-rm-work` enabled, this variable
6197 whose work directories should not be removed. See the 7063 specifies a list of recipes whose work directories should not be removed.
6198 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more 7064 See the ":ref:`ref-classes-rm-work`" section for more details.
6199 details.
6200 7065
6201 :term:`ROOT_HOME` 7066 :term:`ROOT_HOME`
6202 Defines the root home directory. By default, this directory is set as 7067 Defines the root home directory. By default, this directory is set as
6203 follows in the BitBake configuration file: 7068 follows in the BitBake configuration file::
6204 ::
6205 7069
6206 ROOT_HOME ??= "/home/root" 7070 ROOT_HOME ??= "/home/root"
6207 7071
@@ -6214,8 +7078,7 @@ system and gives an overview of their function and contents.
6214 You can override the default by setting the variable in any layer or 7078 You can override the default by setting the variable in any layer or
6215 in the ``local.conf`` file. Because the default is set using a "weak" 7079 in the ``local.conf`` file. Because the default is set using a "weak"
6216 assignment (i.e. "??="), you can use either of the following forms to 7080 assignment (i.e. "??="), you can use either of the following forms to
6217 define your override: 7081 define your override::
6218 ::
6219 7082
6220 ROOT_HOME = "/root" 7083 ROOT_HOME = "/root"
6221 ROOT_HOME ?= "/root" 7084 ROOT_HOME ?= "/root"
@@ -6227,16 +7090,15 @@ system and gives an overview of their function and contents.
6227 :term:`ROOTFS` 7090 :term:`ROOTFS`
6228 Indicates a filesystem image to include as the root filesystem. 7091 Indicates a filesystem image to include as the root filesystem.
6229 7092
6230 The ``ROOTFS`` variable is an optional variable used with the 7093 The :term:`ROOTFS` variable is an optional variable used with the
6231 :ref:`image-live <ref-classes-image-live>` class. 7094 :ref:`ref-classes-image-live` class.
6232 7095
6233 :term:`ROOTFS_POSTINSTALL_COMMAND` 7096 :term:`ROOTFS_POSTINSTALL_COMMAND`
6234 Specifies a list of functions to call after the OpenEmbedded build 7097 Specifies a list of functions to call after the OpenEmbedded build
6235 system has installed packages. You can specify functions separated by 7098 system has installed packages. You can specify functions separated by
6236 semicolons: 7099 spaces::
6237 ::
6238 7100
6239 ROOTFS_POSTINSTALL_COMMAND += "function; ... " 7101 ROOTFS_POSTINSTALL_COMMAND += "function"
6240 7102
6241 If you need to pass the root filesystem path to a command within a 7103 If you need to pass the root filesystem path to a command within a
6242 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7104 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -6247,10 +7109,9 @@ system and gives an overview of their function and contents.
6247 :term:`ROOTFS_POSTPROCESS_COMMAND` 7109 :term:`ROOTFS_POSTPROCESS_COMMAND`
6248 Specifies a list of functions to call once the OpenEmbedded build 7110 Specifies a list of functions to call once the OpenEmbedded build
6249 system has created the root filesystem. You can specify functions 7111 system has created the root filesystem. You can specify functions
6250 separated by semicolons: 7112 separated by spaces::
6251 ::
6252 7113
6253 ROOTFS_POSTPROCESS_COMMAND += "function; ... " 7114 ROOTFS_POSTPROCESS_COMMAND += "function"
6254 7115
6255 If you need to pass the root filesystem path to a command within a 7116 If you need to pass the root filesystem path to a command within a
6256 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7117 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -6263,10 +7124,9 @@ system and gives an overview of their function and contents.
6263 system has removed unnecessary packages. When runtime package 7124 system has removed unnecessary packages. When runtime package
6264 management is disabled in the image, several packages are removed 7125 management is disabled in the image, several packages are removed
6265 including ``base-passwd``, ``shadow``, and ``update-alternatives``. 7126 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
6266 You can specify functions separated by semicolons: 7127 You can specify functions separated by spaces::
6267 ::
6268 7128
6269 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " 7129 ROOTFS_POSTUNINSTALL_COMMAND += "function"
6270 7130
6271 If you need to pass the root filesystem path to a command within a 7131 If you need to pass the root filesystem path to a command within a
6272 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7132 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -6277,10 +7137,9 @@ system and gives an overview of their function and contents.
6277 :term:`ROOTFS_PREPROCESS_COMMAND` 7137 :term:`ROOTFS_PREPROCESS_COMMAND`
6278 Specifies a list of functions to call before the OpenEmbedded build 7138 Specifies a list of functions to call before the OpenEmbedded build
6279 system has created the root filesystem. You can specify functions 7139 system has created the root filesystem. You can specify functions
6280 separated by semicolons: 7140 separated by spaces::
6281 ::
6282 7141
6283 ROOTFS_PREPROCESS_COMMAND += "function; ... " 7142 ROOTFS_PREPROCESS_COMMAND += "function"
6284 7143
6285 If you need to pass the root filesystem path to a command within a 7144 If you need to pass the root filesystem path to a command within a
6286 function, you can use ``${IMAGE_ROOTFS}``, which points to the 7145 function, you can use ``${IMAGE_ROOTFS}``, which points to the
@@ -6292,64 +7151,61 @@ system and gives an overview of their function and contents.
6292 A list of package name aliases that a package also provides. These 7151 A list of package name aliases that a package also provides. These
6293 aliases are useful for satisfying runtime dependencies of other 7152 aliases are useful for satisfying runtime dependencies of other
6294 packages both during the build and on the target (as specified by 7153 packages both during the build and on the target (as specified by
6295 ``RDEPENDS``). 7154 :term:`RDEPENDS`).
6296 7155
6297 .. note:: 7156 .. note::
6298 7157
6299 A package's own name is implicitly already in its ``RPROVIDES`` list. 7158 A package's own name is implicitly already in its :term:`RPROVIDES` list.
6300 7159
6301 As with all package-controlling variables, you must always use the 7160 As with all package-controlling variables, you must always use the
6302 variable in conjunction with a package name override. Here is an 7161 variable in conjunction with a package name override. Here is an
6303 example: 7162 example::
6304 ::
6305 7163
6306 RPROVIDES_${PN} = "widget-abi-2" 7164 RPROVIDES:${PN} = "widget-abi-2"
6307 7165
6308 :term:`RRECOMMENDS` 7166 :term:`RRECOMMENDS`
6309 A list of packages that extends the usability of a package being 7167 A list of packages that extends the usability of a package being
6310 built. The package being built does not depend on this list of 7168 built. The package being built does not depend on this list of
6311 packages in order to successfully build, but rather uses them for 7169 packages in order to successfully build, but rather uses them for
6312 extended usability. To specify runtime dependencies for packages, see 7170 extended usability. To specify runtime dependencies for packages, see
6313 the ``RDEPENDS`` variable. 7171 the :term:`RDEPENDS` variable.
6314 7172
6315 The package manager will automatically install the ``RRECOMMENDS`` 7173 The package manager will automatically install the :term:`RRECOMMENDS`
6316 list of packages when installing the built package. However, you can 7174 list of packages when installing the built package. However, you can
6317 prevent listed packages from being installed by using the 7175 prevent listed packages from being installed by using the
6318 :term:`BAD_RECOMMENDATIONS`, 7176 :term:`BAD_RECOMMENDATIONS`,
6319 :term:`NO_RECOMMENDATIONS`, and 7177 :term:`NO_RECOMMENDATIONS`, and
6320 :term:`PACKAGE_EXCLUDE` variables. 7178 :term:`PACKAGE_EXCLUDE` variables.
6321 7179
6322 Packages specified in ``RRECOMMENDS`` need not actually be produced. 7180 Packages specified in :term:`RRECOMMENDS` need not actually be produced.
6323 However, a recipe must exist that provides each package, either 7181 However, there must be a recipe providing each package, either
6324 through the :term:`PACKAGES` or 7182 through the :term:`PACKAGES` or
6325 :term:`PACKAGES_DYNAMIC` variables or the 7183 :term:`PACKAGES_DYNAMIC` variables or the
6326 :term:`RPROVIDES` variable, or an error will occur 7184 :term:`RPROVIDES` variable, or an error will occur
6327 during the build. If such a recipe does exist and the package is not 7185 during the build. If such a recipe does exist and the package is not
6328 produced, the build continues without error. 7186 produced, the build continues without error.
6329 7187
6330 Because the ``RRECOMMENDS`` variable applies to packages being built, 7188 Because the :term:`RRECOMMENDS` variable applies to packages being built,
6331 you should always attach an override to the variable to specify the 7189 you should always attach an override to the variable to specify the
6332 particular package whose usability is being extended. For example, 7190 particular package whose usability is being extended. For example,
6333 suppose you are building a development package that is extended to 7191 suppose you are building a development package that is extended to
6334 support wireless functionality. In this case, you would use the 7192 support wireless functionality. In this case, you would use the
6335 following: 7193 following::
6336 ::
6337 7194
6338 RRECOMMENDS_${PN}-dev += "wireless_package_name" 7195 RRECOMMENDS:${PN}-dev += "wireless_package_name"
6339 7196
6340 In the 7197 In the
6341 example, the package name (``${PN}-dev``) must appear as it would in 7198 example, the package name (``${PN}-dev``) must appear as it would in
6342 the ``PACKAGES`` namespace before any renaming of the output package 7199 the :term:`PACKAGES` namespace before any renaming of the output package
6343 by classes such as ``debian.bbclass``. 7200 by classes such as :ref:`ref-classes-debian`.
6344 7201
6345 BitBake, which the OpenEmbedded build system uses, supports 7202 BitBake, which the OpenEmbedded build system uses, supports
6346 specifying versioned recommends. Although the syntax varies depending 7203 specifying versioned recommends. Although the syntax varies depending
6347 on the packaging format, BitBake hides these differences from you. 7204 on the packaging format, BitBake hides these differences from you.
6348 Here is the general syntax to specify versions with the 7205 Here is the general syntax to specify versions with the
6349 ``RRECOMMENDS`` variable: 7206 :term:`RRECOMMENDS` variable::
6350 ::
6351 7207
6352 RRECOMMENDS_${PN} = "package (operator version)" 7208 RRECOMMENDS:${PN} = "package (operator version)"
6353 7209
6354 For ``operator``, you can specify the following: 7210 For ``operator``, you can specify the following:
6355 7211
@@ -6360,32 +7216,29 @@ system and gives an overview of their function and contents.
6360 - >= 7216 - >=
6361 7217
6362 For example, the following sets up a recommend on version 1.2 or 7218 For example, the following sets up a recommend on version 1.2 or
6363 greater of the package ``foo``: 7219 greater of the package ``foo``::
6364 ::
6365 7220
6366 RRECOMMENDS_${PN} = "foo (>= 1.2)" 7221 RRECOMMENDS:${PN} = "foo (>= 1.2)"
6367 7222
6368 :term:`RREPLACES` 7223 :term:`RREPLACES`
6369 A list of packages replaced by a package. The package manager uses 7224 A list of packages replaced by a package. The package manager uses
6370 this variable to determine which package should be installed to 7225 this variable to determine which package should be installed to
6371 replace other package(s) during an upgrade. In order to also have the 7226 replace other package(s) during an upgrade. In order to also have the
6372 other package(s) removed at the same time, you must add the name of 7227 other package(s) removed at the same time, you must add the name of
6373 the other package to the ``RCONFLICTS`` variable. 7228 the other package to the :term:`RCONFLICTS` variable.
6374 7229
6375 As with all package-controlling variables, you must use this variable 7230 As with all package-controlling variables, you must use this variable
6376 in conjunction with a package name override. Here is an example: 7231 in conjunction with a package name override. Here is an example::
6377 ::
6378 7232
6379 RREPLACES_${PN} = "other_package_being_replaced" 7233 RREPLACES:${PN} = "other_package_being_replaced"
6380 7234
6381 BitBake, which the OpenEmbedded build system uses, supports 7235 BitBake, which the OpenEmbedded build system uses, supports
6382 specifying versioned replacements. Although the syntax varies 7236 specifying versioned replacements. Although the syntax varies
6383 depending on the packaging format, BitBake hides these differences 7237 depending on the packaging format, BitBake hides these differences
6384 from you. Here is the general syntax to specify versions with the 7238 from you. Here is the general syntax to specify versions with the
6385 ``RREPLACES`` variable: 7239 :term:`RREPLACES` variable::
6386 ::
6387 7240
6388 RREPLACES_${PN} = "package (operator version)" 7241 RREPLACES:${PN} = "package (operator version)"
6389 7242
6390 For ``operator``, you can specify the following: 7243 For ``operator``, you can specify the following:
6391 7244
@@ -6396,10 +7249,9 @@ system and gives an overview of their function and contents.
6396 - >= 7249 - >=
6397 7250
6398 For example, the following sets up a replacement using version 1.2 7251 For example, the following sets up a replacement using version 1.2
6399 or greater of the package ``foo``: 7252 or greater of the package ``foo``::
6400 ::
6401 7253
6402 RREPLACES_${PN} = "foo (>= 1.2)" 7254 RREPLACES:${PN} = "foo (>= 1.2)"
6403 7255
6404 :term:`RSUGGESTS` 7256 :term:`RSUGGESTS`
6405 A list of additional packages that you can suggest for installation 7257 A list of additional packages that you can suggest for installation
@@ -6408,10 +7260,14 @@ system and gives an overview of their function and contents.
6408 7260
6409 As with all package-controlling variables, you must always use this 7261 As with all package-controlling variables, you must always use this
6410 variable in conjunction with a package name override. Here is an 7262 variable in conjunction with a package name override. Here is an
6411 example: 7263 example::
6412 :: 7264
7265 RSUGGESTS:${PN} = "useful_package another_package"
6413 7266
6414 RSUGGESTS_${PN} = "useful_package another_package" 7267 :term:`RUST_CHANNEL`
7268 Specifies which version of Rust to build - "stable", "beta" or "nightly".
7269 The default value is "stable". Set this at your own risk, as values other
7270 than "stable" are not guaranteed to work at a given time.
6415 7271
6416 :term:`S` 7272 :term:`S`
6417 The location in the :term:`Build Directory` where 7273 The location in the :term:`Build Directory` where
@@ -6421,14 +7277,13 @@ system and gives an overview of their function and contents.
6421 version. If the source tarball extracts the code to a directory named 7277 version. If the source tarball extracts the code to a directory named
6422 anything other than ``${BPN}-${PV}``, or if the source code is 7278 anything other than ``${BPN}-${PV}``, or if the source code is
6423 fetched from an SCM such as Git or Subversion, then you must set 7279 fetched from an SCM such as Git or Subversion, then you must set
6424 ``S`` in the recipe so that the OpenEmbedded build system knows where 7280 :term:`S` in the recipe so that the OpenEmbedded build system knows where
6425 to find the unpacked source. 7281 to find the unpacked source.
6426 7282
6427 As an example, assume a :term:`Source Directory` 7283 As an example, assume a :term:`Source Directory`
6428 top-level folder named ``poky`` and a default Build Directory at 7284 top-level folder named ``poky`` and a default :term:`Build Directory` at
6429 ``poky/build``. In this case, the work directory the build system 7285 ``poky/build``. In this case, the work directory the build system
6430 uses to keep the unpacked recipe for ``db`` is the following: 7286 uses to keep the unpacked recipe for ``db`` is the following::
6431 ::
6432 7287
6433 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 7288 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6434 7289
@@ -6437,11 +7292,10 @@ system and gives an overview of their function and contents.
6437 This next example assumes a Git repository. By default, Git 7292 This next example assumes a Git repository. By default, Git
6438 repositories are cloned to ``${WORKDIR}/git`` during 7293 repositories are cloned to ``${WORKDIR}/git`` during
6439 :ref:`ref-tasks-fetch`. Since this path is different 7294 :ref:`ref-tasks-fetch`. Since this path is different
6440 from the default value of ``S``, you must set it specifically so the 7295 from the default value of :term:`S`, you must set it specifically so the
6441 source can be located: 7296 source can be located::
6442 ::
6443 7297
6444 SRC_URI = "git://path/to/repo.git" 7298 SRC_URI = "git://path/to/repo.git;branch=main"
6445 S = "${WORKDIR}/git" 7299 S = "${WORKDIR}/git"
6446 7300
6447 :term:`SANITY_REQUIRED_UTILITIES` 7301 :term:`SANITY_REQUIRED_UTILITIES`
@@ -6455,7 +7309,7 @@ system and gives an overview of their function and contents.
6455 been tested against. Identifiers consist of the host distributor ID 7309 been tested against. Identifiers consist of the host distributor ID
6456 followed by the release, as reported by the ``lsb_release`` tool or 7310 followed by the release, as reported by the ``lsb_release`` tool or
6457 as read from ``/etc/lsb-release``. Separate the list items with 7311 as read from ``/etc/lsb-release``. Separate the list items with
6458 explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is 7312 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is
6459 not empty and the current value of 7313 not empty and the current value of
6460 :term:`NATIVELSBSTRING` does not appear in the 7314 :term:`NATIVELSBSTRING` does not appear in the
6461 list, then the build system reports a warning that indicates the 7315 list, then the build system reports a warning that indicates the
@@ -6465,12 +7319,29 @@ system and gives an overview of their function and contents.
6465 The target architecture for the SDK. Typically, you do not directly 7319 The target architecture for the SDK. Typically, you do not directly
6466 set this variable. Instead, use :term:`SDKMACHINE`. 7320 set this variable. Instead, use :term:`SDKMACHINE`.
6467 7321
7322 :term:`SDK_ARCHIVE_TYPE`
7323 Specifies the type of archive to create for the SDK. Valid values:
7324
7325 - ``tar.xz`` (default)
7326 - ``zip``
7327
7328 Only one archive type can be specified.
7329
7330 :term:`SDK_BUILDINFO_FILE`
7331 When using the :ref:`ref-classes-image-buildinfo` class,
7332 specifies the file in the SDK to write the build information into. The
7333 default value is "``/buildinfo``".
7334
7335 :term:`SDK_CUSTOM_TEMPLATECONF`
7336 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
7337 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory`
7338 (:term:`TOPDIR`) then this will be copied into the SDK.
7339
6468 :term:`SDK_DEPLOY` 7340 :term:`SDK_DEPLOY`
6469 The directory set up and used by the 7341 The directory set up and used by the
6470 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which 7342 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the
6471 the SDK is deployed. The ``populate_sdk_base`` class defines 7343 SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>`
6472 ``SDK_DEPLOY`` as follows: 7344 class defines :term:`SDK_DEPLOY` as follows::
6473 ::
6474 7345
6475 SDK_DEPLOY = "${TMPDIR}/deploy/sdk" 7346 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
6476 7347
@@ -6478,15 +7349,14 @@ system and gives an overview of their function and contents.
6478 The parent directory used by the OpenEmbedded build system when 7349 The parent directory used by the OpenEmbedded build system when
6479 creating SDK output. The 7350 creating SDK output. The
6480 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines 7351 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
6481 the variable as follows: 7352 the variable as follows::
6482 ::
6483 7353
6484 SDK_DIR = "${WORKDIR}/sdk" 7354 SDK_DIR = "${WORKDIR}/sdk"
6485 7355
6486 .. note:: 7356 .. note::
6487 7357
6488 The ``SDK_DIR`` directory is a temporary directory as it is part of 7358 The :term:`SDK_DIR` directory is a temporary directory as it is part of
6489 ``WORKDIR``. The final output directory is :term:`SDK_DEPLOY`. 7359 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`.
6490 7360
6491 :term:`SDK_EXT_TYPE` 7361 :term:`SDK_EXT_TYPE`
6492 Controls whether or not shared state artifacts are copied into the 7362 Controls whether or not shared state artifacts are copied into the
@@ -6504,14 +7374,12 @@ system and gives an overview of their function and contents.
6504 The manifest file for the host part of the SDK. This file lists all 7374 The manifest file for the host part of the SDK. This file lists all
6505 the installed packages that make up the host part of the SDK. The 7375 the installed packages that make up the host part of the SDK. The
6506 file contains package information on a line-per-package basis as 7376 file contains package information on a line-per-package basis as
6507 follows: 7377 follows::
6508 ::
6509 7378
6510 packagename packagearch version 7379 packagename packagearch version
6511 7380
6512 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7381 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
6513 defines the manifest file as follows: 7382 defines the manifest file as follows::
6514 ::
6515 7383
6516 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" 7384 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
6517 7385
@@ -6527,7 +7395,7 @@ system and gives an overview of their function and contents.
6527 7395
6528 .. note:: 7396 .. note::
6529 7397
6530 Enabling the ``SDK_INCLUDE_PKGDATA`` 7398 Enabling the :term:`SDK_INCLUDE_PKGDATA`
6531 variable significantly increases build time because all of world 7399 variable significantly increases build time because all of world
6532 needs to be built. Enabling the variable also slightly increases 7400 needs to be built. Enabling the variable also slightly increases
6533 the size of the extensible SDK. 7401 the size of the extensible SDK.
@@ -6541,82 +7409,21 @@ system and gives an overview of their function and contents.
6541 IDE or from other tools and you do not want to perform additional 7409 IDE or from other tools and you do not want to perform additional
6542 steps to install the toolchain. 7410 steps to install the toolchain.
6543 7411
6544 The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if 7412 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if
6545 ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if 7413 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
6546 ``SDK_EXT_TYPE`` is set to "full". 7414 :term:`SDK_EXT_TYPE` is set to "full".
6547
6548 :term:`SDK_INHERIT_BLACKLIST`
6549 A list of classes to remove from the :term:`INHERIT`
6550 value globally within the extensible SDK configuration. The
6551 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
6552 default value:
6553 ::
6554
6555 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
6556
6557 Some classes are not generally applicable within the extensible SDK
6558 context. You can use this variable to disable those classes.
6559
6560 For additional information on how to customize the extensible SDK's
6561 configuration, see the
6562 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
6563 section in the Yocto Project Application Development and the
6564 Extensible Software Development Kit (eSDK) manual.
6565
6566 :term:`SDK_LOCAL_CONF_BLACKLIST`
6567 A list of variables not allowed through from the OpenEmbedded build
6568 system configuration into the extensible SDK configuration. Usually,
6569 these are variables that are specific to the machine on which the
6570 build system is running and thus would be potentially problematic
6571 within the extensible SDK.
6572
6573 By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the
6574 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
6575 excludes the following variables:
6576
6577 - :term:`CONF_VERSION`
6578 - :term:`BB_NUMBER_THREADS`
6579 - :term:`bitbake:BB_NUMBER_PARSE_THREADS`
6580 - :term:`PARALLEL_MAKE`
6581 - :term:`PRSERV_HOST`
6582 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
6583 - :term:`SSTATE_DIR` :term:`TMPDIR`
6584 - :term:`BB_SERVER_TIMEOUT`
6585
6586 For additional information on how to customize the extensible SDK's
6587 configuration, see the
6588 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
6589 section in the Yocto Project Application Development and the
6590 Extensible Software Development Kit (eSDK) manual.
6591
6592 :term:`SDK_LOCAL_CONF_WHITELIST`
6593 A list of variables allowed through from the OpenEmbedded build
6594 system configuration into the extensible SDK configuration. By
6595 default, the list of variables is empty and is set in the
6596 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
6597
6598 This list overrides the variables specified using the
6599 :term:`SDK_LOCAL_CONF_BLACKLIST`
6600 variable as well as any variables identified by automatic
6601 blacklisting due to the "/" character being found at the start of the
6602 value, which is usually indicative of being a path and thus might not
6603 be valid on the system where the SDK is installed.
6604
6605 For additional information on how to customize the extensible SDK's
6606 configuration, see the
6607 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
6608 section in the Yocto Project Application Development and the
6609 Extensible Software Development Kit (eSDK) manual.
6610 7415
6611 :term:`SDK_NAME` 7416 :term:`SDK_NAME`
6612 The base name for SDK output files. The name is derived from the 7417 The base name for SDK output files. The default value (as set in
6613 :term:`DISTRO`, :term:`TCLIBC`, 7418 ``meta-poky/conf/distro/poky.conf``) is derived from the
6614 :term:`SDK_ARCH`, 7419 :term:`DISTRO`,
6615 :term:`IMAGE_BASENAME`, and 7420 :term:`TCLIBC`,
6616 :term:`TUNE_PKGARCH` variables: 7421 :term:`SDKMACHINE`,
6617 :: 7422 :term:`IMAGE_BASENAME`,
7423 :term:`TUNE_PKGARCH`, and
7424 :term:`MACHINE` variables::
6618 7425
6619 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" 7426 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"
6620 7427
6621 :term:`SDK_OS` 7428 :term:`SDK_OS`
6622 Specifies the operating system for which the SDK will be built. The 7429 Specifies the operating system for which the SDK will be built. The
@@ -6625,8 +7432,7 @@ system and gives an overview of their function and contents.
6625 :term:`SDK_OUTPUT` 7432 :term:`SDK_OUTPUT`
6626 The location used by the OpenEmbedded build system when creating SDK 7433 The location used by the OpenEmbedded build system when creating SDK
6627 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 7434 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
6628 class defines the variable as follows: 7435 class defines the variable as follows::
6629 ::
6630 7436
6631 SDK_DIR = "${WORKDIR}/sdk" 7437 SDK_DIR = "${WORKDIR}/sdk"
6632 SDK_OUTPUT = "${SDK_DIR}/image" 7438 SDK_OUTPUT = "${SDK_DIR}/image"
@@ -6634,7 +7440,7 @@ system and gives an overview of their function and contents.
6634 7440
6635 .. note:: 7441 .. note::
6636 7442
6637 The ``SDK_OUTPUT`` directory is a temporary directory as it is part of 7443 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of
6638 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is 7444 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is
6639 :term:`SDK_DEPLOY`. 7445 :term:`SDK_DEPLOY`.
6640 7446
@@ -6642,13 +7448,15 @@ system and gives an overview of their function and contents.
6642 Specifies a list of architectures compatible with the SDK machine. 7448 Specifies a list of architectures compatible with the SDK machine.
6643 This variable is set automatically and should not normally be 7449 This variable is set automatically and should not normally be
6644 hand-edited. Entries are separated using spaces and listed in order 7450 hand-edited. Entries are separated using spaces and listed in order
6645 of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any 7451 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any
6646 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". 7452 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
6647 7453
6648 :term:`SDK_POSTPROCESS_COMMAND` 7454 :term:`SDK_POSTPROCESS_COMMAND`
6649 Specifies a list of functions to call once the OpenEmbedded build 7455 Specifies a list of functions to call once the OpenEmbedded build
6650 system creates the SDK. You can specify functions separated by 7456 system creates the SDK. You can specify functions separated by
6651 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " 7457 spaces:
7458
7459 SDK_POSTPROCESS_COMMAND += "function"
6652 7460
6653 If you need to pass an SDK path to a command within a function, you 7461 If you need to pass an SDK path to a command within a function, you
6654 can use ``${SDK_DIR}``, which points to the parent directory used by 7462 can use ``${SDK_DIR}``, which points to the parent directory used by
@@ -6656,8 +7464,9 @@ system and gives an overview of their function and contents.
6656 :term:`SDK_DIR` variable for more information. 7464 :term:`SDK_DIR` variable for more information.
6657 7465
6658 :term:`SDK_PREFIX` 7466 :term:`SDK_PREFIX`
6659 The toolchain binary prefix used for ``nativesdk`` recipes. The 7467 The toolchain binary prefix used for
6660 OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the 7468 :ref:`ref-classes-nativesdk` recipes. The
7469 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the
6661 :term:`TARGET_PREFIX` when building 7470 :term:`TARGET_PREFIX` when building
6662 ``nativesdk`` recipes. The default value is "${SDK_SYS}-". 7471 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
6663 7472
@@ -6665,15 +7474,15 @@ system and gives an overview of their function and contents.
6665 A list of shared state tasks added to the extensible SDK. By default, 7474 A list of shared state tasks added to the extensible SDK. By default,
6666 the following tasks are added: 7475 the following tasks are added:
6667 7476
6668 - do_populate_lic 7477 - :ref:`ref-tasks-populate_lic`
6669 - do_package_qa 7478 - :ref:`ref-tasks-package_qa`
6670 - do_populate_sysroot 7479 - :ref:`ref-tasks-populate_sysroot`
6671 - do_deploy 7480 - :ref:`ref-tasks-deploy`
6672 7481
6673 Despite the default value of "" for the 7482 Despite the default value of "" for the
6674 ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added 7483 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added
6675 to the SDK. To specify tasks beyond these four, you need to use the 7484 to the SDK. To specify tasks beyond these four, you need to use the
6676 ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional 7485 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional
6677 tasks that are needed in order to build 7486 tasks that are needed in order to build
6678 :term:`SDK_TARGETS`). 7487 :term:`SDK_TARGETS`).
6679 7488
@@ -6684,21 +7493,19 @@ system and gives an overview of their function and contents.
6684 The OpenEmbedded build system automatically sets this variable based 7493 The OpenEmbedded build system automatically sets this variable based
6685 on :term:`SDK_ARCH`, 7494 on :term:`SDK_ARCH`,
6686 :term:`SDK_VENDOR`, and 7495 :term:`SDK_VENDOR`, and
6687 :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` 7496 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS`
6688 variable yourself. 7497 variable yourself.
6689 7498
6690 :term:`SDK_TARGET_MANIFEST` 7499 :term:`SDK_TARGET_MANIFEST`
6691 The manifest file for the target part of the SDK. This file lists all 7500 The manifest file for the target part of the SDK. This file lists all
6692 the installed packages that make up the target part of the SDK. The 7501 the installed packages that make up the target part of the SDK. The
6693 file contains package information on a line-per-package basis as 7502 file contains package information on a line-per-package basis as
6694 follows: 7503 follows::
6695 ::
6696 7504
6697 packagename packagearch version 7505 packagename packagearch version
6698 7506
6699 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 7507 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
6700 defines the manifest file as follows: 7508 defines the manifest file as follows::
6701 ::
6702 7509
6703 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" 7510 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
6704 7511
@@ -6710,7 +7517,7 @@ system and gives an overview of their function and contents.
6710 standard or extensible SDK installation. The default value is "${PN}" 7517 standard or extensible SDK installation. The default value is "${PN}"
6711 (i.e. the image from which the SDK is built). 7518 (i.e. the image from which the SDK is built).
6712 7519
6713 The ``SDK_TARGETS`` variable is an internal variable and typically 7520 The :term:`SDK_TARGETS` variable is an internal variable and typically
6714 would not be changed. 7521 would not be changed.
6715 7522
6716 :term:`SDK_TITLE` 7523 :term:`SDK_TITLE`
@@ -6718,19 +7525,22 @@ system and gives an overview of their function and contents.
6718 this title is based on the :term:`DISTRO_NAME` or 7525 this title is based on the :term:`DISTRO_NAME` or
6719 :term:`DISTRO` variable and is set in the 7526 :term:`DISTRO` variable and is set in the
6720 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7527 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
6721 follows: 7528 follows::
6722 ::
6723 7529
6724 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" 7530 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
6725 7531
6726 For the default distribution "poky", 7532 For the default distribution "poky",
6727 ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". 7533 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)".
6728 7534
6729 For information on how to change this default title, see the 7535 For information on how to change this default title, see the
6730 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" 7536 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`"
6731 section in the Yocto Project Application Development and the 7537 section in the Yocto Project Application Development and the
6732 Extensible Software Development Kit (eSDK) manual. 7538 Extensible Software Development Kit (eSDK) manual.
6733 7539
7540 :term:`SDK_TOOLCHAIN_LANGS`
7541 Specifies programming languages to support in the SDK, as a
7542 space-separated list. Currently supported items are ``rust`` and ``go``.
7543
6734 :term:`SDK_UPDATE_URL` 7544 :term:`SDK_UPDATE_URL`
6735 An optional URL for an update server for the extensible SDK. If set, 7545 An optional URL for an update server for the extensible SDK. If set,
6736 the value is used as the default update server when running 7546 the value is used as the default update server when running
@@ -6740,29 +7550,32 @@ system and gives an overview of their function and contents.
6740 Specifies the name of the SDK vendor. 7550 Specifies the name of the SDK vendor.
6741 7551
6742 :term:`SDK_VERSION` 7552 :term:`SDK_VERSION`
6743 Specifies the version of the SDK. The distribution configuration file 7553 Specifies the version of the SDK. The Poky distribution configuration file
6744 (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the 7554 (``/meta-poky/conf/distro/poky.conf``) sets the default
6745 ``SDK_VERSION`` as follows: 7555 :term:`SDK_VERSION` as follows::
6746 ::
6747 7556
6748 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" 7557 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
6749 7558
6750 For additional information, see the 7559 For additional information, see the
6751 :term:`DISTRO_VERSION` and 7560 :term:`DISTRO_VERSION` and
6752 :term:`DATE` variables. 7561 :term:`METADATA_REVISION` variables.
7562
7563 :term:`SDK_ZIP_OPTIONS`
7564 Specifies extra options to pass to the ``zip`` command when zipping the SDK
7565 (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is
7566 "-y".
6753 7567
6754 :term:`SDKEXTPATH` 7568 :term:`SDKEXTPATH`
6755 The default installation directory for the Extensible SDK. By 7569 The default installation directory for the Extensible SDK. By
6756 default, this directory is based on the :term:`DISTRO` 7570 default, this directory is based on the :term:`DISTRO`
6757 variable and is set in the 7571 variable and is set in the
6758 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 7572 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
6759 follows: 7573 follows::
6760 ::
6761 7574
6762 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" 7575 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
6763 7576
6764 For the 7577 For the
6765 default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". 7578 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk".
6766 7579
6767 For information on how to change this default directory, see the 7580 For information on how to change this default directory, see the
6768 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" 7581 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`"
@@ -6770,32 +7583,33 @@ system and gives an overview of their function and contents.
6770 Extensible Software Development Kit (eSDK) manual. 7583 Extensible Software Development Kit (eSDK) manual.
6771 7584
6772 :term:`SDKIMAGE_FEATURES` 7585 :term:`SDKIMAGE_FEATURES`
6773 Equivalent to ``IMAGE_FEATURES``. However, this variable applies to 7586 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to
6774 the SDK generated from an image using the following command: 7587 the SDK generated from an image using the following command::
6775 ::
6776 7588
6777 $ bitbake -c populate_sdk imagename 7589 $ bitbake -c populate_sdk imagename
6778 7590
6779 :term:`SDKMACHINE` 7591 :term:`SDKMACHINE`
6780 The machine for which the SDK is built. In other words, the SDK is 7592 The machine for which the SDK is built. In other words, the SDK is built
6781 built such that it runs on the target you specify with the 7593 such that it runs on the target you specify with the :term:`SDKMACHINE`
6782 ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` 7594 value. The value points to a corresponding ``.conf`` file under
6783 file under ``conf/machine-sdk/``. 7595 ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``,
7596 ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are
7597 :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`.
6784 7598
6785 You can use "i686" and "x86_64" as possible values for this variable. 7599 The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the
6786 The variable defaults to "i686" and is set in the local.conf file in 7600 architecture of the build machine.
6787 the Build Directory.
6788 ::
6789
6790 SDKMACHINE ?= "i686"
6791 7601
6792 .. note:: 7602 .. note::
6793 7603
6794 You cannot set the ``SDKMACHINE`` 7604 You cannot set the :term:`SDKMACHINE`
6795 variable in your distribution configuration file. If you do, the 7605 variable in your distribution configuration file. If you do, the
6796 configuration will not take affect. 7606 configuration will not take effect.
6797 7607
6798 :term:`SDKPATH` 7608 :term:`SDKPATH`
7609 Defines the path used to collect the SDK components and build the
7610 installer.
7611
7612 :term:`SDKPATHINSTALL`
6799 Defines the path offered to the user for installation of the SDK that 7613 Defines the path offered to the user for installation of the SDK that
6800 is generated by the OpenEmbedded build system. The path appears as 7614 is generated by the OpenEmbedded build system. The path appears as
6801 the default location for installing the SDK when you run the SDK's 7615 the default location for installing the SDK when you run the SDK's
@@ -6805,7 +7619,7 @@ system and gives an overview of their function and contents.
6805 :term:`SDKTARGETSYSROOT` 7619 :term:`SDKTARGETSYSROOT`
6806 The full path to the sysroot used for cross-compilation within an SDK 7620 The full path to the sysroot used for cross-compilation within an SDK
6807 as it will be when installed into the default 7621 as it will be when installed into the default
6808 :term:`SDKPATH`. 7622 :term:`SDKPATHINSTALL`.
6809 7623
6810 :term:`SECTION` 7624 :term:`SECTION`
6811 The section in which packages should be categorized. Package 7625 The section in which packages should be categorized. Package
@@ -6816,50 +7630,43 @@ system and gives an overview of their function and contents.
6816 building for the target. The flags are passed through the default 7630 building for the target. The flags are passed through the default
6817 value of the :term:`TARGET_CFLAGS` variable. 7631 value of the :term:`TARGET_CFLAGS` variable.
6818 7632
6819 The ``SELECTED_OPTIMIZATION`` variable takes the value of 7633 The :term:`SELECTED_OPTIMIZATION` variable takes the value of
6820 ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the 7634 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which
6821 case, the value of ``DEBUG_OPTIMIZATION`` is used. 7635 case the value of :term:`DEBUG_OPTIMIZATION` is used.
6822
6823 :term:`SERIAL_CONSOLE`
6824 Defines a serial console (TTY) to enable using
6825 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6826 value that specifies the baud rate followed by the TTY device name
6827 separated by a space. You cannot specify more than one TTY device:
6828 ::
6829
6830 SERIAL_CONSOLE = "115200 ttyS0"
6831
6832 .. note::
6833
6834 The ``SERIAL_CONSOLE`` variable is deprecated. Please use the
6835 :term:`SERIAL_CONSOLES` variable.
6836 7636
6837 :term:`SERIAL_CONSOLES` 7637 :term:`SERIAL_CONSOLES`
6838 Defines a serial console (TTY) to enable using 7638 Defines a serial console (TTY) to enable using
6839 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a 7639 :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the
6840 value that specifies the baud rate followed by the TTY device name 7640 baud rate followed by the TTY device name separated by a semicolon.
6841 separated by a semicolon. Use spaces to separate multiple devices: 7641 Use spaces to separate multiple devices::
6842 ::
6843 7642
6844 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 7643 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6845 7644
6846 :term:`SERIAL_CONSOLES_CHECK` 7645 :term:`SETUPTOOLS_BUILD_ARGS`
6847 Specifies serial consoles, which must be listed in 7646 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
6848 :term:`SERIAL_CONSOLES`, to check against 7647 class, this variable can be used to specify additional arguments to be
6849 ``/proc/console`` before enabling them using getty. This variable 7648 passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task.
6850 allows aliasing in the format: <device>:<alias>. If a device was
6851 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in
6852 ``/proc/console``, you would do the following: ::
6853 7649
6854 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" 7650 :term:`SETUPTOOLS_INSTALL_ARGS`
7651 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7652 class, this variable can be used to specify additional arguments to be
7653 passed to ``setup.py install`` in the ``setuptools3_do_install()`` task.
6855 7654
6856 This variable is currently only supported with SysVinit (i.e. not 7655 :term:`SETUPTOOLS_SETUP_PATH`
6857 with systemd). 7656 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7657 class, this variable should be used to specify the directory in which
7658 the ``setup.py`` file is located if it is not at the root of the source
7659 tree (as specified by :term:`S`). For example, in a recipe where the
7660 sources are fetched from a Git repository and ``setup.py`` is in a
7661 ``python/pythonmodule`` subdirectory, you would have this::
7662
7663 S = "${WORKDIR}/git"
7664 SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule"
6858 7665
6859 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` 7666 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
6860 A list of recipe dependencies that should not be used to determine 7667 A list of recipe dependencies that should not be used to determine
6861 signatures of tasks from one recipe when they depend on tasks from 7668 signatures of tasks from one recipe when they depend on tasks from
6862 another recipe. For example: :: 7669 another recipe. For example::
6863 7670
6864 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" 7671 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6865 7672
@@ -6867,7 +7674,7 @@ system and gives an overview of their function and contents.
6867 7674
6868 You can use the special token ``"*"`` on the left-hand side of the 7675 You can use the special token ``"*"`` on the left-hand side of the
6869 dependency to match all recipes except the one on the right-hand 7676 dependency to match all recipes except the one on the right-hand
6870 side. Here is an example: :: 7677 side. Here is an example::
6871 7678
6872 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" 7679 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
6873 7680
@@ -6912,15 +7719,27 @@ system and gives an overview of their function and contents.
6912 7719
6913 To enable file removal, set the variable to "1" in your 7720 To enable file removal, set the variable to "1" in your
6914 ``conf/local.conf`` configuration file in your: 7721 ``conf/local.conf`` configuration file in your:
6915 :term:`Build Directory`. 7722 :term:`Build Directory`::
6916 ::
6917 7723
6918 SKIP_FILEDEPS = "1" 7724 SKIP_FILEDEPS = "1"
6919 7725
7726 :term:`SKIP_RECIPE`
7727 Used to prevent the OpenEmbedded build system from building a given
7728 recipe. Specify the :term:`PN` value as a variable flag (``varflag``)
7729 and provide a reason, which will be reported when attempting to
7730 build the recipe.
7731
7732 To prevent a recipe from being built, use the :term:`SKIP_RECIPE`
7733 variable in your ``local.conf`` file or distribution configuration.
7734 Here is an example which prevents ``myrecipe`` from being built::
7735
7736 SKIP_RECIPE[myrecipe] = "Not supported by our organization."
7737
6920 :term:`SOC_FAMILY` 7738 :term:`SOC_FAMILY`
6921 Groups together machines based upon the same family of SOC (System On 7739 A colon-separated list grouping together machines based upon the same
6922 Chip). You typically set this variable in a common ``.inc`` file that 7740 family of SoC (System On Chip). You typically set this variable in a
6923 you include in the configuration files of all the machines. 7741 common ``.inc`` file that you include in the configuration files of all
7742 the machines.
6924 7743
6925 .. note:: 7744 .. note::
6926 7745
@@ -6933,7 +7752,7 @@ system and gives an overview of their function and contents.
6933 defined in the ``meta/conf/bitbake.conf`` configuration file. 7752 defined in the ``meta/conf/bitbake.conf`` configuration file.
6934 7753
6935 You will see this variable referenced in the default values of 7754 You will see this variable referenced in the default values of
6936 ``FILES_${PN}``. 7755 ``FILES:${PN}``.
6937 7756
6938 :term:`SOLIBSDEV` 7757 :term:`SOLIBSDEV`
6939 Defines the suffix for the development symbolic link (symlink) for 7758 Defines the suffix for the development symbolic link (symlink) for
@@ -6942,11 +7761,28 @@ system and gives an overview of their function and contents.
6942 ``meta/conf/bitbake.conf`` configuration file. 7761 ``meta/conf/bitbake.conf`` configuration file.
6943 7762
6944 You will see this variable referenced in the default values of 7763 You will see this variable referenced in the default values of
6945 ``FILES_${PN}-dev``. 7764 ``FILES:${PN}-dev``.
7765
7766 :term:`SOURCE_DATE_EPOCH`
7767 This defines a date expressed in number of seconds since
7768 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by
7769 multiple build systems to force a timestamp in built binaries.
7770 Many upstream projects already support this variable.
7771
7772 You will find more details in the `official specifications
7773 <https://reproducible-builds.org/specs/source-date-epoch/>`__.
7774
7775 A value for each recipe is computed from the sources by
7776 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`.
7777
7778 If a recipe wishes to override the default behavior, it should set its
7779 own :term:`SOURCE_DATE_EPOCH` value::
7780
7781 SOURCE_DATE_EPOCH = "1613559011"
6946 7782
6947 :term:`SOURCE_MIRROR_FETCH` 7783 :term:`SOURCE_MIRROR_FETCH`
6948 When you are fetching files to create a mirror of sources (i.e. 7784 When you are fetching files to create a mirror of sources (i.e.
6949 creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in 7785 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in
6950 your ``local.conf`` configuration file ensures the source for all 7786 your ``local.conf`` configuration file ensures the source for all
6951 recipes are fetched regardless of whether or not a recipe is 7787 recipes are fetched regardless of whether or not a recipe is
6952 compatible with the configuration. A recipe is considered 7788 compatible with the configuration. A recipe is considered
@@ -6958,7 +7794,7 @@ system and gives an overview of their function and contents.
6958 7794
6959 .. note:: 7795 .. note::
6960 7796
6961 Do not set the ``SOURCE_MIRROR_FETCH`` 7797 Do not set the :term:`SOURCE_MIRROR_FETCH`
6962 variable unless you are creating a source mirror. In other words, 7798 variable unless you are creating a source mirror. In other words,
6963 do not set the variable during a normal build. 7799 do not set the variable during a normal build.
6964 7800
@@ -6968,20 +7804,132 @@ system and gives an overview of their function and contents.
6968 specified in :term:`SRC_URI`. 7804 specified in :term:`SRC_URI`.
6969 7805
6970 To use this variable, you must globally inherit the 7806 To use this variable, you must globally inherit the
6971 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide 7807 :ref:`ref-classes-own-mirrors` class and then provide
6972 the URL to your mirrors. Here is the general syntax: 7808 the URL to your mirrors. Here is the general syntax::
6973 ::
6974 7809
6975 INHERIT += "own-mirrors" 7810 INHERIT += "own-mirrors"
6976 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" 7811 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
6977 7812
6978 .. note:: 7813 .. note::
6979 7814
6980 You can specify only a single URL in ``SOURCE_MIRROR_URL``. 7815 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`.
7816
7817 :term:`SPDX_ARCHIVE_PACKAGED`
7818 This option allows to add to :term:`SPDX` output compressed archives
7819 of the files in the generated target packages.
7820
7821 Such archives are available in
7822 ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst``
7823 under the :term:`Build Directory`.
7824
7825 Enable this option as follows::
7826
7827 SPDX_ARCHIVE_PACKAGED = "1"
7828
7829 According to our tests on release 4.1 "langdale", building
7830 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this
7831 option multiplied the size of the ``tmp/deploy/spdx`` directory by a
7832 factor of 13 (+1.6 GiB for this image), compared to just using the
7833 :ref:`ref-classes-create-spdx` class with no option.
7834
7835 Note that this option doesn't increase the size of :term:`SPDX`
7836 files in ``tmp/deploy/images/MACHINE``.
7837
7838 :term:`SPDX_ARCHIVE_SOURCES`
7839 This option allows to add to :term:`SPDX` output compressed archives
7840 of the sources for packages installed on the target. It currently
7841 only works when :term:`SPDX_INCLUDE_SOURCES` is set.
7842
7843 This is one way of fulfilling "source code access" license
7844 requirements.
7845
7846 Such source archives are available in
7847 ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst``
7848 under the :term:`Build Directory`.
7849
7850 Enable this option as follows::
7851
7852 SPDX_INCLUDE_SOURCES = "1"
7853 SPDX_ARCHIVE_SOURCES = "1"
7854
7855 According to our tests on release 4.1 "langdale", building
7856 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
7857 these options multiplied the size of the ``tmp/deploy/spdx``
7858 directory by a factor of 11 (+1.4 GiB for this image),
7859 compared to just using the :ref:`ref-classes-create-spdx`
7860 class with no option.
7861
7862 Note that using this option only marginally increases the size
7863 of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/``
7864 (+ 0.07\% with the tested image), compared to just enabling
7865 :term:`SPDX_INCLUDE_SOURCES`.
7866
7867 :term:`SPDX_CUSTOM_ANNOTATION_VARS`
7868 This option allows to associate `SPDX annotations
7869 <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
7870 using the values of variables in the recipe::
7871
7872 ANNOTATION1 = "First annotation for recipe"
7873 ANNOTATION2 = "Second annotation for recipe"
7874 SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"
7875
7876 This will add a new block to the recipe ``.sdpx.json`` output::
7877
7878 "annotations": [
7879 {
7880 "annotationDate": "2023-04-18T08:32:12Z",
7881 "annotationType": "OTHER",
7882 "annotator": "Tool: oe-spdx-creator - 1.0",
7883 "comment": "ANNOTATION1=First annotation for recipe"
7884 },
7885 {
7886 "annotationDate": "2023-04-18T08:32:12Z",
7887 "annotationType": "OTHER",
7888 "annotator": "Tool: oe-spdx-creator - 1.0",
7889 "comment": "ANNOTATION2=Second annotation for recipe"
7890 }
7891 ],
7892
7893 :term:`SPDX_INCLUDE_SOURCES`
7894 This option allows to add a description of the source files used to build
7895 the host tools and the target packages, to the ``spdx.json`` files in
7896 ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`.
7897 As a consequence, the ``spdx.json`` files under the ``by-namespace`` and
7898 ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also
7899 modified to include references to such source file descriptions.
7900
7901 Enable this option as follows::
7902
7903 SPDX_INCLUDE_SOURCES = "1"
7904
7905 According to our tests on release 4.1 "langdale", building
7906 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
7907 this option multiplied the total size of the ``tmp/deploy/spdx``
7908 directory by a factor of 3 (+291 MiB for this image),
7909 and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in
7910 ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this
7911 image), compared to just using the :ref:`ref-classes-create-spdx` class
7912 with no option.
7913
7914 :term:`SPDX_NAMESPACE_PREFIX`
7915 This option could be used in order to change the prefix of ``spdxDocument``
7916 and the prefix of ``documentNamespace``. It is set by default to
7917 ``http://spdx.org/spdxdoc``.
7918
7919 :term:`SPDX_PRETTY`
7920 This option makes the SPDX output more human-readable, using
7921 identation and newlines, instead of the default output in a
7922 single line::
7923
7924 SPDX_PRETTY = "1"
7925
7926 The generated SPDX files are approximately 20% bigger, but
7927 this option is recommended if you want to inspect the SPDX
7928 output files with a text editor.
6981 7929
6982 :term:`SPDXLICENSEMAP` 7930 :term:`SPDXLICENSEMAP`
6983 Maps commonly used license names to their SPDX counterparts found in 7931 Maps commonly used license names to their SPDX counterparts found in
6984 ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` 7932 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
6985 mappings, see the ``meta/conf/licenses.conf`` file. 7933 mappings, see the ``meta/conf/licenses.conf`` file.
6986 7934
6987 For additional information, see the :term:`LICENSE` 7935 For additional information, see the :term:`LICENSE`
@@ -7001,8 +7949,7 @@ system and gives an overview of their function and contents.
7001 U-Boot recipe. 7949 U-Boot recipe.
7002 7950
7003 The SPL file type is set to "null" by default in the ``u-boot.inc`` 7951 The SPL file type is set to "null" by default in the ``u-boot.inc``
7004 file as follows: 7952 file as follows::
7005 ::
7006 7953
7007 # Some versions of u-boot build an SPL (Second Program Loader) image that 7954 # Some versions of u-boot build an SPL (Second Program Loader) image that
7008 # should be packaged along with the u-boot binary as well as placed in the 7955 # should be packaged along with the u-boot binary as well as placed in the
@@ -7013,171 +7960,132 @@ system and gives an overview of their function and contents.
7013 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" 7960 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
7014 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" 7961 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
7015 7962
7016 The ``SPL_BINARY`` variable helps form 7963 The :term:`SPL_BINARY` variable helps form
7017 various ``SPL_*`` variables used by the OpenEmbedded build system. 7964 various ``SPL_*`` variables used by the OpenEmbedded build system.
7018 7965
7019 See the BeagleBone machine configuration example in the 7966 See the BeagleBone machine configuration example in the
7020 ":ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" 7967 ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`"
7021 section in the Yocto Project Board Support Package Developer's Guide 7968 section in the Yocto Project Board Support Package Developer's Guide
7022 for additional information. 7969 for additional information.
7023 7970
7024 :term:`SRC_URI` 7971 :term:`SPL_MKIMAGE_DTCOPTS`
7025 The list of source files - local or remote. This variable tells the 7972 Options for the device tree compiler passed to ``mkimage -D`` feature
7026 OpenEmbedded build system which bits to pull in for the build and how 7973 while creating a FIT image with the :ref:`ref-classes-uboot-sign`
7027 to pull them in. For example, if the recipe or append file only needs 7974 class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the
7028 to fetch a tarball from the Internet, the recipe or append file uses 7975 :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option
7029 a single ``SRC_URI`` entry. On the other hand, if the recipe or 7976 to ``mkimage``.
7030 append file needs to fetch a tarball, apply two patches, and include
7031 a custom file, the recipe or append file would include four instances
7032 of the variable.
7033
7034 The following list explains the available URI protocols. URI
7035 protocols are highly dependent on particular BitBake Fetcher
7036 submodules. Depending on the fetcher BitBake uses, various URL
7037 parameters are employed. For specifics on the supported Fetchers, see
7038 the ":ref:`Fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`" section in the
7039 BitBake User Manual.
7040
7041 - ``file://`` - Fetches files, which are usually files shipped
7042 with the :term:`Metadata`, from the local machine (e.g.
7043 :ref:`patch <overview-manual/concepts:patching>` files).
7044 The path is relative to the :term:`FILESPATH`
7045 variable. Thus, the build system searches, in order, from the
7046 following directories, which are assumed to be a subdirectories of
7047 the directory in which the recipe file (``.bb``) or append file
7048 (``.bbappend``) resides:
7049
7050 - ``${BPN}`` - The base recipe name without any special suffix
7051 or version numbers.
7052
7053 - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and
7054 version but without any special package name suffix.
7055
7056 - *files -* Files within a directory, which is named ``files``
7057 and is also alongside the recipe or append file.
7058 7977
7059 .. note:: 7978 The default value is set to "" by the :ref:`ref-classes-uboot-config`
7979 class.
7980
7981 :term:`SPL_SIGN_ENABLE`
7982 Enable signing of the U-Boot FIT image. The default value is "0".
7983 This variable is used by the :ref:`ref-classes-uboot-sign` class.
7984
7985 :term:`SPL_SIGN_KEYDIR`
7986 Location of the directory containing the RSA key and certificate used for
7987 signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign`
7988 class.
7060 7989
7061 If you want the build system to pick up files specified through 7990 :term:`SPL_SIGN_KEYNAME`
7062 a 7991 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
7063 SRC_URI 7992 for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR`
7064 statement from your append file, you need to be sure to extend 7993 directory. If we have for example a ``dev.key`` key and a ``dev.crt``
7065 the 7994 certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will
7066 FILESPATH 7995 have to set :term:`SPL_SIGN_KEYNAME` to ``dev``.
7067 variable by also using the
7068 FILESEXTRAPATHS
7069 variable from within your append file.
7070 7996
7071 - ``bzr://`` - Fetches files from a Bazaar revision control 7997 :term:`SPLASH`
7072 repository. 7998 This variable, used by the :ref:`ref-classes-image` class, allows
7999 to choose splashscreen applications. Set it to the names of packages
8000 for such applications to use. This variable is set by default to
8001 ``psplash``.
7073 8002
7074 - ``git://`` - Fetches files from a Git revision control 8003 :term:`SPLASH_IMAGES`
7075 repository. 8004 This variable, used by the ``psplash`` recipe, allows to customize
8005 the default splashscreen image.
7076 8006
7077 - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) 8007 Specified images in PNG format are converted to ``.h`` files by the recipe,
7078 revision control repository. 8008 and are included in the ``psplash`` binary, so you won't find them in
8009 the root filesystem.
7079 8010
7080 - ``repo://`` - Fetches files from a repo (Git) repository. 8011 To make such a change, it is recommended to customize the
8012 ``psplash`` recipe in a custom layer. Here is an example structure for
8013 an ``ACME`` board::
7081 8014
7082 - ``ccrc://`` - Fetches files from a ClearCase repository. 8015 meta-acme/recipes-core/psplash
8016 ├── files
8017 │   └── logo-acme.png
8018 └── psplash_%.bbappend
7083 8019
7084 - ``http://`` - Fetches files from the Internet using ``http``. 8020 And here are the contents of the ``psplash_%.bbappend`` file in
8021 this example::
7085 8022
7086 - ``https://`` - Fetches files from the Internet using ``https``. 8023 SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
8024 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
7087 8025
7088 - ``ftp://`` - Fetches files from the Internet using ``ftp``. 8026 You could even add specific configuration options for ``psplash``,
8027 for example::
7089 8028
7090 - ``cvs://`` - Fetches files from a CVS revision control 8029 EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"
7091 repository.
7092 8030
7093 - ``hg://`` - Fetches files from a Mercurial (``hg``) revision 8031 For information on append files, see the
7094 control repository. 8032 ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
8033 section.
7095 8034
7096 - ``p4://`` - Fetches files from a Perforce (``p4``) revision 8035 :term:`SRCREV_FORMAT`
7097 control repository. 8036 See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual.
7098 8037
7099 - ``ssh://`` - Fetches files from a secure shell. 8038 :term:`SRC_URI`
7100 8039
7101 - ``svn://`` - Fetches files from a Subversion (``svn``) revision 8040 See the BitBake manual for the initial description for this variable:
7102 control repository. 8041 :term:`bitbake:SRC_URI`.
7103 8042
7104 - ``npm://`` - Fetches JavaScript modules from a registry. 8043 The following features are added by OpenEmbedded and the Yocto Project.
7105 8044
7106 Standard and recipe-specific options for ``SRC_URI`` exist. Here are 8045 There are standard and recipe-specific options. Here are standard ones:
7107 standard options:
7108 8046
7109 - ``apply`` - Whether to apply the patch or not. The default 8047 - ``apply`` --- whether to apply the patch or not. The default
7110 action is to apply the patch. 8048 action is to apply the patch.
7111 8049
7112 - ``striplevel`` - Which striplevel to use when applying the 8050 - ``striplevel`` --- which striplevel to use when applying the
7113 patch. The default level is 1. 8051 patch. The default level is 1.
7114 8052
7115 - ``patchdir`` - Specifies the directory in which the patch should 8053 - ``patchdir`` --- specifies the directory in which the patch should
7116 be applied. The default is ``${``\ :term:`S`\ ``}``. 8054 be applied. The default is ``${``\ :term:`S`\ ``}``.
7117 8055
7118 Here are options specific to recipes building code from a revision 8056 Here are options specific to recipes building code from a revision
7119 control system: 8057 control system:
7120 8058
7121 - ``mindate`` - Apply the patch only if 8059 - ``mindate`` --- apply the patch only if
7122 :term:`SRCDATE` is equal to or greater than 8060 :term:`SRCDATE` is equal to or greater than
7123 ``mindate``. 8061 ``mindate``.
7124 8062
7125 - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later 8063 - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later
7126 than ``maxdate``. 8064 than ``maxdate``.
7127 8065
7128 - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or 8066 - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or
7129 greater than ``minrev``. 8067 greater than ``minrev``.
7130 8068
7131 - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later 8069 - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later
7132 than ``maxrev``. 8070 than ``maxrev``.
7133 8071
7134 - ``rev`` - Apply the patch only if ``SRCREV`` is equal to 8072 - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to
7135 ``rev``. 8073 ``rev``.
7136 8074
7137 - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to 8075 - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to
7138 ``rev``. 8076 ``rev``.
7139 8077
7140 Here are some additional options worth mentioning: 8078 .. note::
7141
7142 - ``unpack`` - Controls whether or not to unpack the file if it is
7143 an archive. The default action is to unpack the file.
7144
7145 - ``destsuffix`` - Places the file (or extracts its contents) into
7146 the specified subdirectory of :term:`WORKDIR` when
7147 the Git fetcher is used.
7148
7149 - ``subdir`` - Places the file (or extracts its contents) into the
7150 specified subdirectory of ``WORKDIR`` when the local (``file://``)
7151 fetcher is used.
7152
7153 - ``localdir`` - Places the file (or extracts its contents) into
7154 the specified subdirectory of ``WORKDIR`` when the CVS fetcher is
7155 used.
7156
7157 - ``subpath`` - Limits the checkout to a specific subpath of the
7158 tree when using the Git fetcher is used.
7159
7160 - ``name`` - Specifies a name to be used for association with
7161 ``SRC_URI`` checksums or :term:`SRCREV` when you have more than one
7162 file or git repository specified in ``SRC_URI``. For example:
7163 ::
7164
7165 SRC_URI = "git://example.com/foo.git;name=first \
7166 git://example.com/bar.git;name=second \
7167 http://example.com/file.tar.gz;name=third"
7168
7169 SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
7170 SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f"
7171 SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"
7172
7173 8079
7174 - ``downloadfilename`` - Specifies the filename used when storing 8080 If you want the build system to pick up files specified through
7175 the downloaded file. 8081 a :term:`SRC_URI` statement from your append file, you need to be
8082 sure to extend the :term:`FILESPATH` variable by also using the
8083 :term:`FILESEXTRAPATHS` variable from within your append file.
7176 8084
7177 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` 8085 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
7178 By default, the OpenEmbedded build system automatically detects 8086 By default, the OpenEmbedded build system automatically detects
7179 whether ``SRC_URI`` contains files that are machine-specific. If so, 8087 whether :term:`SRC_URI` contains files that are machine-specific. If so,
7180 the build system automatically changes ``PACKAGE_ARCH``. Setting this 8088 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this
7181 variable to "0" disables this behavior. 8089 variable to "0" disables this behavior.
7182 8090
7183 :term:`SRCDATE` 8091 :term:`SRCDATE`
@@ -7189,18 +8097,16 @@ system and gives an overview of their function and contents.
7189 Returns the version string of the current package. This string is 8097 Returns the version string of the current package. This string is
7190 used to help define the value of :term:`PV`. 8098 used to help define the value of :term:`PV`.
7191 8099
7192 The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` 8100 The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf``
7193 configuration file in the :term:`Source Directory` as 8101 configuration file in the :term:`Source Directory` as
7194 follows: 8102 follows::
7195 ::
7196 8103
7197 SRCPV = "${@bb.fetch2.get_srcrev(d)}" 8104 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7198 8105
7199 Recipes that need to define ``PV`` do so with the help of the 8106 Recipes that need to define :term:`PV` do so with the help of the
7200 ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) 8107 :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``)
7201 located in ``meta/recipes-connectivity`` in the Source Directory 8108 located in ``meta/recipes-connectivity`` in the Source Directory
7202 defines ``PV`` as follows: 8109 defines :term:`PV` as follows::
7203 ::
7204 8110
7205 PV = "0.12-git${SRCPV}" 8111 PV = "0.12-git${SRCPV}"
7206 8112
@@ -7209,26 +8115,76 @@ system and gives an overview of their function and contents.
7209 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note 8115 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
7210 that if you want to build a fixed revision and you want to avoid 8116 that if you want to build a fixed revision and you want to avoid
7211 performing a query on the remote repository every time BitBake parses 8117 performing a query on the remote repository every time BitBake parses
7212 your recipe, you should specify a ``SRCREV`` that is a full revision 8118 your recipe, you should specify a :term:`SRCREV` that is a full revision
7213 identifier and not just a tag. 8119 identifier (e.g. the full SHA hash in git) and not just a tag.
7214 8120
7215 .. note:: 8121 .. note::
7216 8122
7217 For information on limitations when inheriting the latest revision 8123 For information on limitations when inheriting the latest revision
7218 of software using ``SRCREV``, see the :term:`AUTOREV` variable 8124 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable
7219 description and the 8125 description and the
7220 ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" 8126 ":ref:`dev-manual/packages:automatically incrementing a package version number`"
7221 section, which is in the Yocto Project Development Tasks Manual. 8127 section, which is in the Yocto Project Development Tasks Manual.
7222 8128
8129 :term:`SRCTREECOVEREDTASKS`
8130 A list of tasks that are typically not relevant (and therefore skipped)
8131 when building using the :ref:`ref-classes-externalsrc`
8132 class. The default value as set in that class file is the set of tasks
8133 that are rarely needed when using external source::
8134
8135 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
8136
8137 The notable exception is when processing external kernel source as
8138 defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for
8139 aesthetics)::
8140
8141 SRCTREECOVEREDTASKS += "\
8142 do_validate_branches \
8143 do_kernel_configcheck \
8144 do_kernel_checkout \
8145 do_fetch \
8146 do_unpack \
8147 do_patch \
8148 "
8149
8150 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD`
8151 variables for more information.
8152
7223 :term:`SSTATE_DIR` 8153 :term:`SSTATE_DIR`
7224 The directory for the shared state cache. 8154 The directory for the shared state cache.
7225 8155
8156 :term:`SSTATE_EXCLUDEDEPS_SYSROOT`
8157 This variable allows to specify indirect dependencies to exclude
8158 from sysroots, for example to avoid the situations when a dependency on
8159 any ``-native`` recipe will pull in all dependencies of that recipe
8160 in the recipe sysroot. This behaviour might not always be wanted,
8161 for example when that ``-native`` recipe depends on build tools
8162 that are not relevant for the current recipe.
8163
8164 This way, irrelevant dependencies are ignored, which could have
8165 prevented the reuse of prebuilt artifacts stored in the Shared
8166 State Cache.
8167
8168 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular
8169 expressions of recipe and dependency to ignore. An example
8170 is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`::
8171
8172 # Nothing needs to depend on libc-initial
8173 # base-passwd/shadow-sysroot don't need their dependencies
8174 SSTATE_EXCLUDEDEPS_SYSROOT += "\
8175 .*->.*-initial.* \
8176 .*(base-passwd|shadow-sysroot)->.* \
8177 "
8178
8179 The ``->`` substring represents the dependency between
8180 the two regular expressions.
8181
7226 :term:`SSTATE_MIRROR_ALLOW_NETWORK` 8182 :term:`SSTATE_MIRROR_ALLOW_NETWORK`
7227 If set to "1", allows fetches from mirrors that are specified in 8183 If set to "1", allows fetches from mirrors that are specified in
7228 :term:`SSTATE_MIRRORS` to work even when 8184 :term:`SSTATE_MIRRORS` to work even when
7229 fetching from the network is disabled by setting ``BB_NO_NETWORK`` to 8185 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to
7230 "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if 8186 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if
7231 you have set ``SSTATE_MIRRORS`` to point to an internal server for 8187 you have set :term:`SSTATE_MIRRORS` to point to an internal server for
7232 your shared state cache, but you want to disable any other fetching 8188 your shared state cache, but you want to disable any other fetching
7233 from the network. 8189 from the network.
7234 8190
@@ -7246,26 +8202,33 @@ system and gives an overview of their function and contents.
7246 8202
7247 When pointing to sstate build artifacts on another machine that uses 8203 When pointing to sstate build artifacts on another machine that uses
7248 a different GCC version for native builds, you must configure 8204 a different GCC version for native builds, you must configure
7249 ``SSTATE_MIRRORS`` with a regular expression that maps local search 8205 :term:`SSTATE_MIRRORS` with a regular expression that maps local search
7250 paths to server paths. The paths need to take into account 8206 paths to server paths. The paths need to take into account
7251 :term:`NATIVELSBSTRING` set by the 8207 :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class.
7252 :ref:`uninative <ref-classes-uninative>` class. For example, the 8208 For example, the following maps the local search path ``universal-4.9``
7253 following maps the local search path ``universal-4.9`` to the 8209 to the server-provided path server_url_sstate_path::
7254 server-provided path server_url_sstate_path:
7255 ::
7256 8210
7257 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" 8211 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1"
7258 8212
7259 If a mirror uses the same structure as 8213 If a mirror uses the same structure as
7260 :term:`SSTATE_DIR`, you need to add "PATH" at the 8214 :term:`SSTATE_DIR`, you need to add "PATH" at the
7261 end as shown in the examples below. The build system substitutes the 8215 end as shown in the examples below. The build system substitutes the
7262 correct path within the directory structure. 8216 correct path within the directory structure::
7263 ::
7264 8217
7265 SSTATE_MIRRORS ?= "\ 8218 SSTATE_MIRRORS ?= "\
7266 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ 8219 file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \
7267 file://.* file:///some-local-dir/sstate/PATH" 8220 file://.* file:///some-local-dir/sstate/PATH"
7268 8221
8222 The Yocto Project actually shares the cache data objects built by its
8223 autobuilder::
8224
8225 SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH"
8226
8227 As such binary artifacts are built for the generic QEMU machines
8228 supported by the various Poky releases, they are less likely to be
8229 reusable in real projects building binaries optimized for a specific
8230 CPU family.
8231
7269 :term:`SSTATE_SCAN_FILES` 8232 :term:`SSTATE_SCAN_FILES`
7270 Controls the list of files the OpenEmbedded build system scans for 8233 Controls the list of files the OpenEmbedded build system scans for
7271 hardcoded installation paths. The variable uses a space-separated 8234 hardcoded installation paths. The variable uses a space-separated
@@ -7276,14 +8239,12 @@ system and gives an overview of their function and contents.
7276 (sstate) object during the first stage of preparing the sysroots. 8239 (sstate) object during the first stage of preparing the sysroots.
7277 That object is scanned for hardcoded paths for original installation 8240 That object is scanned for hardcoded paths for original installation
7278 locations. The list of files that are scanned for paths is controlled 8241 locations. The list of files that are scanned for paths is controlled
7279 by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files 8242 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files
7280 they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather 8243 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather
7281 than the variable being comprehensively set. The 8244 than the variable being comprehensively set. The
7282 :ref:`sstate <ref-classes-sstate>` class specifies the default list 8245 :ref:`ref-classes-sstate` class specifies the default list of files.
7283 of files.
7284 8246
7285 For details on the process, see the 8247 For details on the process, see the :ref:`ref-classes-staging` class.
7286 :ref:`staging <ref-classes-staging>` class.
7287 8248
7288 :term:`STAGING_BASE_LIBDIR_NATIVE` 8249 :term:`STAGING_BASE_LIBDIR_NATIVE`
7289 Specifies the path to the ``/lib`` subdirectory of the sysroot 8250 Specifies the path to the ``/lib`` subdirectory of the sysroot
@@ -7339,7 +8300,7 @@ system and gives an overview of their function and contents.
7339 8300
7340 .. note:: 8301 .. note::
7341 8302
7342 Recipes should never write files directly under the ``STAGING_DIR`` 8303 Recipes should never write files directly under the :term:`STAGING_DIR`
7343 directory because the OpenEmbedded build system manages the 8304 directory because the OpenEmbedded build system manages the
7344 directory automatically. Instead, files should be installed to 8305 directory automatically. Instead, files should be installed to
7345 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` 8306 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install`
@@ -7352,9 +8313,9 @@ system and gives an overview of their function and contents.
7352 For most recipes, this sysroot is the one in which that recipe's 8313 For most recipes, this sysroot is the one in which that recipe's
7353 :ref:`ref-tasks-populate_sysroot` task copies 8314 :ref:`ref-tasks-populate_sysroot` task copies
7354 files. Exceptions include ``-native`` recipes, where the 8315 files. Exceptions include ``-native`` recipes, where the
7355 ``do_populate_sysroot`` task instead uses 8316 :ref:`ref-tasks-populate_sysroot` task instead uses
7356 :term:`STAGING_DIR_NATIVE`. Depending on 8317 :term:`STAGING_DIR_NATIVE`. Depending on
7357 the type of recipe and the build target, ``STAGING_DIR_HOST`` can 8318 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
7358 have the following values: 8319 have the following values:
7359 8320
7360 - For recipes building for the target machine, the value is 8321 - For recipes building for the target machine, the value is
@@ -7368,11 +8329,11 @@ system and gives an overview of their function and contents.
7368 8329
7369 ``-native`` recipes are not installed into host paths like such 8330 ``-native`` recipes are not installed into host paths like such
7370 as ``/usr``. Rather, these recipes are installed into 8331 as ``/usr``. Rather, these recipes are installed into
7371 ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, 8332 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
7372 standard build environment variables such as 8333 standard build environment variables such as
7373 :term:`CPPFLAGS` and 8334 :term:`CPPFLAGS` and
7374 :term:`CFLAGS` are set up so that both host paths 8335 :term:`CFLAGS` are set up so that both host paths
7375 and ``STAGING_DIR_NATIVE`` are searched for libraries and 8336 and :term:`STAGING_DIR_NATIVE` are searched for libraries and
7376 headers using, for example, GCC's ``-isystem`` option. 8337 headers using, for example, GCC's ``-isystem`` option.
7377 8338
7378 Thus, the emphasis is that the ``STAGING_DIR*`` variables 8339 Thus, the emphasis is that the ``STAGING_DIR*`` variables
@@ -7380,28 +8341,33 @@ system and gives an overview of their function and contents.
7380 :ref:`ref-tasks-configure`, 8341 :ref:`ref-tasks-configure`,
7381 :ref:`ref-tasks-compile`, and 8342 :ref:`ref-tasks-compile`, and
7382 :ref:`ref-tasks-install`. Having the real system 8343 :ref:`ref-tasks-install`. Having the real system
7383 root correspond to ``STAGING_DIR_HOST`` makes conceptual sense 8344 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
7384 for ``-native`` recipes, as they make use of host headers and 8345 for ``-native`` recipes, as they make use of host headers and
7385 libraries. 8346 libraries.
7386 8347
8348 Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`.
8349
7387 :term:`STAGING_DIR_NATIVE` 8350 :term:`STAGING_DIR_NATIVE`
7388 Specifies the path to the sysroot directory used when building 8351 Specifies the path to the sysroot directory used when building
7389 components that run on the build host itself. 8352 components that run on the build host itself.
7390 8353
8354 The default value is ``"${RECIPE_SYSROOT_NATIVE}"``,
8355 check :term:`RECIPE_SYSROOT_NATIVE`.
8356
7391 :term:`STAGING_DIR_TARGET` 8357 :term:`STAGING_DIR_TARGET`
7392 Specifies the path to the sysroot used for the system for which the 8358 Specifies the path to the sysroot used for the system for which the
7393 component generates code. For components that do not generate code, 8359 component generates code. For components that do not generate code,
7394 which is the majority, ``STAGING_DIR_TARGET`` is set to match 8360 which is the majority, :term:`STAGING_DIR_TARGET` is set to match
7395 :term:`STAGING_DIR_HOST`. 8361 :term:`STAGING_DIR_HOST`.
7396 8362
7397 Some recipes build binaries that can run on the target system but 8363 Some recipes build binaries that can run on the target system but those
7398 those binaries in turn generate code for another different system 8364 binaries in turn generate code for another different system (e.g.
7399 (e.g. cross-canadian recipes). Using terminology from GNU, the 8365 :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU,
7400 primary system is referred to as the "HOST" and the secondary, or 8366 the primary system is referred to as the "HOST" and the secondary, or
7401 different, system is referred to as the "TARGET". Thus, the binaries 8367 different, system is referred to as the "TARGET". Thus, the binaries
7402 run on the "HOST" system and generate binaries for the "TARGET" 8368 run on the "HOST" system and generate binaries for the "TARGET"
7403 system. The ``STAGING_DIR_HOST`` variable points to the sysroot used 8369 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used
7404 for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the 8370 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the
7405 sysroot used for the "TARGET" system. 8371 sysroot used for the "TARGET" system.
7406 8372
7407 :term:`STAGING_ETCDIR_NATIVE` 8373 :term:`STAGING_ETCDIR_NATIVE`
@@ -7426,7 +8392,7 @@ system and gives an overview of their function and contents.
7426 Points to the directory containing the kernel build artifacts. 8392 Points to the directory containing the kernel build artifacts.
7427 Recipes building software that needs to access kernel build artifacts 8393 Recipes building software that needs to access kernel build artifacts
7428 (e.g. ``systemtap-uprobes``) can look in the directory specified with 8394 (e.g. ``systemtap-uprobes``) can look in the directory specified with
7429 the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts 8395 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts
7430 after the kernel has been built. 8396 after the kernel has been built.
7431 8397
7432 :term:`STAGING_KERNEL_DIR` 8398 :term:`STAGING_KERNEL_DIR`
@@ -7446,9 +8412,8 @@ system and gives an overview of their function and contents.
7446 Specifies the base path used to create recipe stamp files. The path 8412 Specifies the base path used to create recipe stamp files. The path
7447 to an actual stamp file is constructed by evaluating this string and 8413 to an actual stamp file is constructed by evaluating this string and
7448 then appending additional information. Currently, the default 8414 then appending additional information. Currently, the default
7449 assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` 8415 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
7450 file is: 8416 file is::
7451 ::
7452 8417
7453 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 8418 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7454 8419
@@ -7463,6 +8428,9 @@ system and gives an overview of their function and contents.
7463 :term:`PV`, and :term:`PR` for related variable 8428 :term:`PV`, and :term:`PR` for related variable
7464 information. 8429 information.
7465 8430
8431 :term:`STAMPCLEAN`
8432 See :term:`bitbake:STAMPCLEAN` in the BitBake manual.
8433
7466 :term:`STAMPS_DIR` 8434 :term:`STAMPS_DIR`
7467 Specifies the base directory in which the OpenEmbedded build system 8435 Specifies the base directory in which the OpenEmbedded build system
7468 places stamps. The default directory is ``${TMPDIR}/stamps``. 8436 places stamps. The default directory is ``${TMPDIR}/stamps``.
@@ -7474,8 +8442,8 @@ system and gives an overview of their function and contents.
7474 :term:`SUMMARY` 8442 :term:`SUMMARY`
7475 The short (72 characters or less) summary of the binary package for 8443 The short (72 characters or less) summary of the binary package for
7476 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 8444 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
7477 ``SUMMARY`` is used to define the 8445 :term:`SUMMARY` is used to define the
7478 :term:`DESCRIPTION` variable if ``DESCRIPTION`` is 8446 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is
7479 not set in the recipe. 8447 not set in the recipe.
7480 8448
7481 :term:`SVNDIR` 8449 :term:`SVNDIR`
@@ -7485,12 +8453,11 @@ system and gives an overview of their function and contents.
7485 :term:`SYSLINUX_DEFAULT_CONSOLE` 8453 :term:`SYSLINUX_DEFAULT_CONSOLE`
7486 Specifies the kernel boot default console. If you want to use a 8454 Specifies the kernel boot default console. If you want to use a
7487 console other than the default, set this variable in your recipe as 8455 console other than the default, set this variable in your recipe as
7488 follows where "X" is the console number you want to use: 8456 follows where "X" is the console number you want to use::
7489 ::
7490 8457
7491 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 8458 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7492 8459
7493 The :ref:`syslinux <ref-classes-syslinux>` class initially sets 8460 The :ref:`ref-classes-syslinux` class initially sets
7494 this variable to null but then checks for a value later. 8461 this variable to null but then checks for a value later.
7495 8462
7496 :term:`SYSLINUX_OPTS` 8463 :term:`SYSLINUX_OPTS`
@@ -7498,15 +8465,14 @@ system and gives an overview of their function and contents.
7498 this variable in your recipe. If you want to list multiple options, 8465 this variable in your recipe. If you want to list multiple options,
7499 separate the options with a semicolon character (``;``). 8466 separate the options with a semicolon character (``;``).
7500 8467
7501 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable 8468 The :ref:`ref-classes-syslinux` class uses this variable
7502 to create a set of options. 8469 to create a set of options.
7503 8470
7504 :term:`SYSLINUX_SERIAL` 8471 :term:`SYSLINUX_SERIAL`
7505 Specifies the alternate serial port or turns it off. To turn off 8472 Specifies the alternate serial port or turns it off. To turn off
7506 serial, set this variable to an empty string in your recipe. The 8473 serial, set this variable to an empty string in your recipe. The
7507 variable's default value is set in the 8474 variable's default value is set in the
7508 :ref:`syslinux <ref-classes-syslinux>` class as follows: 8475 :ref:`ref-classes-syslinux` class as follows::
7509 ::
7510 8476
7511 SYSLINUX_SERIAL ?= "0 115200" 8477 SYSLINUX_SERIAL ?= "0 115200"
7512 8478
@@ -7514,9 +8480,8 @@ system and gives an overview of their function and contents.
7514 8480
7515 :term:`SYSLINUX_SERIAL_TTY` 8481 :term:`SYSLINUX_SERIAL_TTY`
7516 Specifies the alternate console=tty... kernel boot argument. The 8482 Specifies the alternate console=tty... kernel boot argument. The
7517 variable's default value is set in the 8483 variable's default value is set in the :ref:`ref-classes-syslinux`
7518 :ref:`syslinux <ref-classes-syslinux>` class as follows: 8484 class as follows::
7519 ::
7520 8485
7521 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 8486 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7522 8487
@@ -7526,7 +8491,7 @@ system and gives an overview of their function and contents.
7526 An ``.LSS`` file used as the background for the VGA boot menu when 8491 An ``.LSS`` file used as the background for the VGA boot menu when
7527 you use the boot menu. You need to set this variable in your recipe. 8492 you use the boot menu. You need to set this variable in your recipe.
7528 8493
7529 The :ref:`syslinux <ref-classes-syslinux>` class checks for this 8494 The :ref:`ref-classes-syslinux` class checks for this
7530 variable and if found, the OpenEmbedded build system installs the 8495 variable and if found, the OpenEmbedded build system installs the
7531 splash screen. 8496 splash screen.
7532 8497
@@ -7539,8 +8504,7 @@ system and gives an overview of their function and contents.
7539 :term:`SYSROOT_DIRS` 8504 :term:`SYSROOT_DIRS`
7540 Directories that are staged into the sysroot by the 8505 Directories that are staged into the sysroot by the
7541 :ref:`ref-tasks-populate_sysroot` task. By 8506 :ref:`ref-tasks-populate_sysroot` task. By
7542 default, the following directories are staged: 8507 default, the following directories are staged::
7543 ::
7544 8508
7545 SYSROOT_DIRS = " \ 8509 SYSROOT_DIRS = " \
7546 ${includedir} \ 8510 ${includedir} \
@@ -7548,33 +8512,67 @@ system and gives an overview of their function and contents.
7548 ${base_libdir} \ 8512 ${base_libdir} \
7549 ${nonarch_base_libdir} \ 8513 ${nonarch_base_libdir} \
7550 ${datadir} \ 8514 ${datadir} \
8515 /sysroot-only \
7551 " 8516 "
7552 8517
7553 :term:`SYSROOT_DIRS_BLACKLIST` 8518 :term:`SYSROOT_DIRS_IGNORE`
7554 Directories that are not staged into the sysroot by the 8519 Directories that are not staged into the sysroot by the
7555 :ref:`ref-tasks-populate_sysroot` task. You 8520 :ref:`ref-tasks-populate_sysroot` task. You
7556 can use this variable to exclude certain subdirectories of 8521 can use this variable to exclude certain subdirectories of
7557 directories listed in :term:`SYSROOT_DIRS` from 8522 directories listed in :term:`SYSROOT_DIRS` from
7558 staging. By default, the following directories are not staged: 8523 staging. By default, the following directories are not staged::
7559 ::
7560 8524
7561 SYSROOT_DIRS_BLACKLIST = " \ 8525 SYSROOT_DIRS_IGNORE = " \
7562 ${mandir} \ 8526 ${mandir} \
7563 ${docdir} \ 8527 ${docdir} \
7564 ${infodir} \ 8528 ${infodir} \
7565 ${datadir}/locale \ 8529 ${datadir}/X11/locale \
7566 ${datadir}/applications \ 8530 ${datadir}/applications \
8531 ${datadir}/bash-completion \
7567 ${datadir}/fonts \ 8532 ${datadir}/fonts \
8533 ${datadir}/gtk-doc/html \
8534 ${datadir}/installed-tests \
8535 ${datadir}/locale \
7568 ${datadir}/pixmaps \ 8536 ${datadir}/pixmaps \
8537 ${datadir}/terminfo \
8538 ${libdir}/${BPN}/ptest \
7569 " 8539 "
7570 8540
8541 Consider the following example in which you need to manipulate this variable.
8542 Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is
8543 installed into a custom folder other than "``${libdir}``"
8544 or "``${base_libdir}``", let's say "``/opt/lib``".
8545
8546 .. note::
8547
8548 This is not a recommended way to deal with shared libraries, but this
8549 is just to show the usefulness of setting :term:`SYSROOT_DIRS`.
8550
8551 When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in
8552 :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``B``
8553 into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``".
8554
8555 Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to
8556 ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So,
8557 the linking process will fail.
8558
8559 To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`::
8560
8561 SYSROOT_DIRS:append = " /opt/lib"
8562
8563 .. note::
8564 Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail
8565 because the linker does not know that location, since :term:`TARGET_LDFLAGS`
8566 doesn't contain it (if your recipe is for the target). Therefore, so you should add::
8567
8568 TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"
8569
7571 :term:`SYSROOT_DIRS_NATIVE` 8570 :term:`SYSROOT_DIRS_NATIVE`
7572 Extra directories staged into the sysroot by the 8571 Extra directories staged into the sysroot by the
7573 :ref:`ref-tasks-populate_sysroot` task for 8572 :ref:`ref-tasks-populate_sysroot` task for
7574 ``-native`` recipes, in addition to those specified in 8573 ``-native`` recipes, in addition to those specified in
7575 :term:`SYSROOT_DIRS`. By default, the following 8574 :term:`SYSROOT_DIRS`. By default, the following
7576 extra directories are staged: 8575 extra directories are staged::
7577 ::
7578 8576
7579 SYSROOT_DIRS_NATIVE = " \ 8577 SYSROOT_DIRS_NATIVE = " \
7580 ${bindir} \ 8578 ${bindir} \
@@ -7598,13 +8596,12 @@ system and gives an overview of their function and contents.
7598 processing on the staged files, or to stage additional files. 8596 processing on the staged files, or to stage additional files.
7599 8597
7600 :term:`SYSTEMD_AUTO_ENABLE` 8598 :term:`SYSTEMD_AUTO_ENABLE`
7601 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 8599 When inheriting the :ref:`ref-classes-systemd` class,
7602 this variable specifies whether the specified service in 8600 this variable specifies whether the specified service in
7603 :term:`SYSTEMD_SERVICE` should start 8601 :term:`SYSTEMD_SERVICE` should start
7604 automatically or not. By default, the service is enabled to 8602 automatically or not. By default, the service is enabled to
7605 automatically start at boot time. The default setting is in the 8603 automatically start at boot time. The default setting is in the
7606 :ref:`systemd <ref-classes-systemd>` class as follows: 8604 :ref:`ref-classes-systemd` class as follows::
7607 ::
7608 8605
7609 SYSTEMD_AUTO_ENABLE ??= "enable" 8606 SYSTEMD_AUTO_ENABLE ??= "enable"
7610 8607
@@ -7612,25 +8609,22 @@ system and gives an overview of their function and contents.
7612 8609
7613 :term:`SYSTEMD_BOOT_CFG` 8610 :term:`SYSTEMD_BOOT_CFG`
7614 When :term:`EFI_PROVIDER` is set to 8611 When :term:`EFI_PROVIDER` is set to
7615 "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the 8612 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
7616 configuration file that should be used. By default, the 8613 configuration file that should be used. By default, the
7617 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 8614 :ref:`ref-classes-systemd-boot` class sets the
7618 ``SYSTEMD_BOOT_CFG`` as follows: 8615 :term:`SYSTEMD_BOOT_CFG` as follows::
7619 ::
7620 8616
7621 SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" 8617 SYSTEMD_BOOT_CFG ?= "${S}/loader.conf"
7622 8618
7623 For information on Systemd-boot, see the `Systemd-boot 8619 For information on Systemd-boot, see the `Systemd-boot
7624 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8620 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
7625 8621
7626 :term:`SYSTEMD_BOOT_ENTRIES` 8622 :term:`SYSTEMD_BOOT_ENTRIES`
7627 When :term:`EFI_PROVIDER` is set to 8623 When :term:`EFI_PROVIDER` is set to
7628 "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a 8624 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
7629 list of entry files (``*.conf``) to install that contain one boot 8625 list of entry files (``*.conf``) to install that contain one boot
7630 entry per file. By default, the 8626 entry per file. By default, the :ref:`ref-classes-systemd-boot` class
7631 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 8627 sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows::
7632 ``SYSTEMD_BOOT_ENTRIES`` as follows:
7633 ::
7634 8628
7635 SYSTEMD_BOOT_ENTRIES ?= "" 8629 SYSTEMD_BOOT_ENTRIES ?= ""
7636 8630
@@ -7639,58 +8633,75 @@ system and gives an overview of their function and contents.
7639 8633
7640 :term:`SYSTEMD_BOOT_TIMEOUT` 8634 :term:`SYSTEMD_BOOT_TIMEOUT`
7641 When :term:`EFI_PROVIDER` is set to 8635 When :term:`EFI_PROVIDER` is set to
7642 "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the 8636 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
7643 boot menu timeout in seconds. By default, the 8637 boot menu timeout in seconds. By default, the
7644 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 8638 :ref:`ref-classes-systemd-boot` class sets the
7645 ``SYSTEMD_BOOT_TIMEOUT`` as follows: 8639 :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
7646 ::
7647 8640
7648 SYSTEMD_BOOT_TIMEOUT ?= "10" 8641 SYSTEMD_BOOT_TIMEOUT ?= "10"
7649 8642
7650 For information on Systemd-boot, see the `Systemd-boot 8643 For information on Systemd-boot, see the `Systemd-boot
7651 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 8644 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
7652 8645
8646 :term:`SYSTEMD_DEFAULT_TARGET`
8647
8648 This variable allows to set the default unit that systemd starts at bootup.
8649 Usually, this is either ``multi-user.target`` or ``graphical.target``.
8650 This works by creating a ``default.target`` symbolic link to the chosen systemd
8651 target file.
8652
8653 See `systemd's documentation
8654 <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__
8655 for details.
8656
8657 For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb
8658 </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`
8659 recipe::
8660
8661 SYSTEMD_DEFAULT_TARGET = "graphical.target"
8662
7653 :term:`SYSTEMD_PACKAGES` 8663 :term:`SYSTEMD_PACKAGES`
7654 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 8664 When inheriting the :ref:`ref-classes-systemd` class,
7655 this variable locates the systemd unit files when they are not found 8665 this variable locates the systemd unit files when they are not found
7656 in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` 8666 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
7657 variable is set such that the systemd unit files are assumed to 8667 variable is set such that the systemd unit files are assumed to
7658 reside in the recipes main package: 8668 reside in the recipes main package::
7659 ::
7660 8669
7661 SYSTEMD_PACKAGES ?= "${PN}" 8670 SYSTEMD_PACKAGES ?= "${PN}"
7662 8671
7663 If these unit files are not in this recipe's main package, you need 8672 If these unit files are not in this recipe's main package, you need
7664 to use ``SYSTEMD_PACKAGES`` to list the package or packages in which 8673 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which
7665 the build system can find the systemd unit files. 8674 the build system can find the systemd unit files.
7666 8675
7667 :term:`SYSTEMD_SERVICE` 8676 :term:`SYSTEMD_SERVICE`
7668 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 8677 When inheriting the :ref:`ref-classes-systemd` class,
7669 this variable specifies the systemd service name for a package. 8678 this variable specifies the systemd service name for a package.
7670 8679
8680 Multiple services can be specified, each one separated by a space.
8681
7671 When you specify this file in your recipe, use a package name 8682 When you specify this file in your recipe, use a package name
7672 override to indicate the package to which the value applies. Here is 8683 override to indicate the package to which the value applies. Here is
7673 an example from the connman recipe: 8684 an example from the connman recipe::
7674 :: 8685
8686 SYSTEMD_SERVICE:${PN} = "connman.service"
7675 8687
7676 SYSTEMD_SERVICE_${PN} = "connman.service" 8688 The package overrides that can be specified are directly related to the value of
8689 :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES`
8690 will be silently ignored.
7677 8691
7678 :term:`SYSVINIT_ENABLED_GETTYS` 8692 :term:`SYSVINIT_ENABLED_GETTYS`
7679 When using 8693 When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
7680 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`,
7681 specifies a space-separated list of the virtual terminals that should 8694 specifies a space-separated list of the virtual terminals that should
7682 run a `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ 8695 run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming
7683 (allowing login), assuming :term:`USE_VT` is not set to 8696 :term:`USE_VT` is not set to "0".
7684 "0".
7685 8697
7686 The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only 8698 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only
7687 run a getty on the first virtual terminal). 8699 run a getty on the first virtual terminal).
7688 8700
7689 :term:`T` 8701 :term:`T`
7690 This variable points to a directory were BitBake places temporary 8702 This variable points to a directory were BitBake places temporary
7691 files, which consist mostly of task logs and scripts, when building a 8703 files, which consist mostly of task logs and scripts, when building a
7692 particular recipe. The variable is typically set as follows: 8704 particular recipe. The variable is typically set as follows::
7693 ::
7694 8705
7695 T = "${WORKDIR}/temp" 8706 T = "${WORKDIR}/temp"
7696 8707
@@ -7698,7 +8709,7 @@ system and gives an overview of their function and contents.
7698 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 8709 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
7699 file sets this variable. 8710 file sets this variable.
7700 8711
7701 The ``T`` variable is not to be confused with the 8712 The :term:`T` variable is not to be confused with the
7702 :term:`TMPDIR` variable, which points to the root of 8713 :term:`TMPDIR` variable, which points to the root of
7703 the directory tree where BitBake places the output of an entire 8714 the directory tree where BitBake places the output of an entire
7704 build. 8715 build.
@@ -7722,29 +8733,28 @@ system and gives an overview of their function and contents.
7722 8733
7723 :term:`TARGET_AS_ARCH` 8734 :term:`TARGET_AS_ARCH`
7724 Specifies architecture-specific assembler flags for the target 8735 Specifies architecture-specific assembler flags for the target
7725 system. ``TARGET_AS_ARCH`` is initialized from 8736 system. :term:`TARGET_AS_ARCH` is initialized from
7726 :term:`TUNE_ASARGS` by default in the BitBake 8737 :term:`TUNE_ASARGS` by default in the BitBake
7727 configuration file (``meta/conf/bitbake.conf``): 8738 configuration file (``meta/conf/bitbake.conf``)::
7728 ::
7729 8739
7730 TARGET_AS_ARCH = "${TUNE_ASARGS}" 8740 TARGET_AS_ARCH = "${TUNE_ASARGS}"
7731 8741
7732 :term:`TARGET_CC_ARCH` 8742 :term:`TARGET_CC_ARCH`
7733 Specifies architecture-specific C compiler flags for the target 8743 Specifies architecture-specific C compiler flags for the target
7734 system. ``TARGET_CC_ARCH`` is initialized from 8744 system. :term:`TARGET_CC_ARCH` is initialized from
7735 :term:`TUNE_CCARGS` by default. 8745 :term:`TUNE_CCARGS` by default.
7736 8746
7737 .. note:: 8747 .. note::
7738 8748
7739 It is a common workaround to append :term:`LDFLAGS` to 8749 It is a common workaround to append :term:`LDFLAGS` to
7740 ``TARGET_CC_ARCH`` in recipes that build software for the target that 8750 :term:`TARGET_CC_ARCH` in recipes that build software for the target that
7741 would not otherwise respect the exported ``LDFLAGS`` variable. 8751 would not otherwise respect the exported :term:`LDFLAGS` variable.
7742 8752
7743 :term:`TARGET_CC_KERNEL_ARCH` 8753 :term:`TARGET_CC_KERNEL_ARCH`
7744 This is a specific kernel compiler flag for a CPU or Application 8754 This is a specific kernel compiler flag for a CPU or Application
7745 Binary Interface (ABI) tune. The flag is used rarely and only for 8755 Binary Interface (ABI) tune. The flag is used rarely and only for
7746 cases where a userspace :term:`TUNE_CCARGS` is not 8756 cases where a userspace :term:`TUNE_CCARGS` is not
7747 compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` 8757 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH`
7748 variable allows the kernel (and associated modules) to use a 8758 variable allows the kernel (and associated modules) to use a
7749 different configuration. See the 8759 different configuration. See the
7750 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 8760 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
@@ -7756,8 +8766,8 @@ system and gives an overview of their function and contents.
7756 :term:`CFLAGS` is set to the value of this variable by 8766 :term:`CFLAGS` is set to the value of this variable by
7757 default. 8767 default.
7758 8768
7759 Additionally, the SDK's environment setup script sets the ``CFLAGS`` 8769 Additionally, the SDK's environment setup script sets the :term:`CFLAGS`
7760 variable in the environment to the ``TARGET_CFLAGS`` value so that 8770 variable in the environment to the :term:`TARGET_CFLAGS` value so that
7761 executables built using the SDK also have the flags applied. 8771 executables built using the SDK also have the flags applied.
7762 8772
7763 :term:`TARGET_CPPFLAGS` 8773 :term:`TARGET_CPPFLAGS`
@@ -7767,7 +8777,7 @@ system and gives an overview of their function and contents.
7767 value of this variable by default. 8777 value of this variable by default.
7768 8778
7769 Additionally, the SDK's environment setup script sets the 8779 Additionally, the SDK's environment setup script sets the
7770 ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` 8780 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS`
7771 value so that executables built using the SDK also have the flags 8781 value so that executables built using the SDK also have the flags
7772 applied. 8782 applied.
7773 8783
@@ -7778,7 +8788,7 @@ system and gives an overview of their function and contents.
7778 by default. 8788 by default.
7779 8789
7780 Additionally, the SDK's environment setup script sets the 8790 Additionally, the SDK's environment setup script sets the
7781 ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` 8791 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS`
7782 value so that executables built using the SDK also have the flags 8792 value so that executables built using the SDK also have the flags
7783 applied. 8793 applied.
7784 8794
@@ -7790,10 +8800,9 @@ system and gives an overview of their function and contents.
7790 8800
7791 :term:`TARGET_LD_ARCH` 8801 :term:`TARGET_LD_ARCH`
7792 Specifies architecture-specific linker flags for the target system. 8802 Specifies architecture-specific linker flags for the target system.
7793 ``TARGET_LD_ARCH`` is initialized from 8803 :term:`TARGET_LD_ARCH` is initialized from
7794 :term:`TUNE_LDARGS` by default in the BitBake 8804 :term:`TUNE_LDARGS` by default in the BitBake
7795 configuration file (``meta/conf/bitbake.conf``): 8805 configuration file (``meta/conf/bitbake.conf``)::
7796 ::
7797 8806
7798 TARGET_LD_ARCH = "${TUNE_LDARGS}" 8807 TARGET_LD_ARCH = "${TUNE_LDARGS}"
7799 8808
@@ -7805,29 +8814,29 @@ system and gives an overview of their function and contents.
7805 8814
7806 Additionally, the SDK's environment setup script sets the 8815 Additionally, the SDK's environment setup script sets the
7807 :term:`LDFLAGS` variable in the environment to the 8816 :term:`LDFLAGS` variable in the environment to the
7808 ``TARGET_LDFLAGS`` value so that executables built using the SDK also 8817 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also
7809 have the flags applied. 8818 have the flags applied.
7810 8819
7811 :term:`TARGET_OS` 8820 :term:`TARGET_OS`
7812 Specifies the target's operating system. The variable can be set to 8821 Specifies the target's operating system. The variable can be set to
7813 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 8822 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
7814 for musl libc. For ARM/EABI targets, "linux-gnueabi" and 8823 for musl libc. For ARM/EABI targets, the possible values are
7815 "linux-musleabi" possible values exist. 8824 "linux-gnueabi" and "linux-musleabi".
7816 8825
7817 :term:`TARGET_PREFIX` 8826 :term:`TARGET_PREFIX`
7818 Specifies the prefix used for the toolchain binary target tools. 8827 Specifies the prefix used for the toolchain binary target tools.
7819 8828
7820 Depending on the type of recipe and the build target, 8829 Depending on the type of recipe and the build target,
7821 ``TARGET_PREFIX`` is set as follows: 8830 :term:`TARGET_PREFIX` is set as follows:
7822 8831
7823 - For recipes building for the target machine, the value is 8832 - For recipes building for the target machine, the value is
7824 "${:term:`TARGET_SYS`}-". 8833 "${:term:`TARGET_SYS`}-".
7825 8834
7826 - For native recipes, the build system sets the variable to the 8835 - For native recipes, the build system sets the variable to the
7827 value of ``BUILD_PREFIX``. 8836 value of :term:`BUILD_PREFIX`.
7828 8837
7829 - For native SDK recipes (``nativesdk``), the build system sets the 8838 - For native SDK recipes (:ref:`ref-classes-nativesdk`),
7830 variable to the value of ``SDK_PREFIX``. 8839 the build system sets the variable to the value of :term:`SDK_PREFIX`.
7831 8840
7832 :term:`TARGET_SYS` 8841 :term:`TARGET_SYS`
7833 Specifies the system, including the architecture and the operating 8842 Specifies the system, including the architecture and the operating
@@ -7841,7 +8850,7 @@ system and gives an overview of their function and contents.
7841 8850
7842 .. note:: 8851 .. note::
7843 8852
7844 You do not need to set the ``TARGET_SYS`` variable yourself. 8853 You do not need to set the :term:`TARGET_SYS` variable yourself.
7845 8854
7846 Consider these two examples: 8855 Consider these two examples:
7847 8856
@@ -7856,27 +8865,25 @@ system and gives an overview of their function and contents.
7856 8865
7857 :term:`TCLIBC` 8866 :term:`TCLIBC`
7858 Specifies the GNU standard C library (``libc``) variant to use during 8867 Specifies the GNU standard C library (``libc``) variant to use during
7859 the build process. This variable replaces ``POKYLIBC``, which is no 8868 the build process.
7860 longer supported.
7861 8869
7862 You can select "glibc", "musl", "newlib", or "baremetal" 8870 You can select "glibc", "musl", "newlib", or "baremetal".
7863 8871
7864 :term:`TCLIBCAPPEND` 8872 :term:`TCLIBCAPPEND`
7865 Specifies a suffix to be appended onto the 8873 Specifies a suffix to be appended onto the :term:`TMPDIR` value. The
7866 :term:`TMPDIR` value. The suffix identifies the 8874 suffix identifies the ``libc`` variant for building. When you are
7867 ``libc`` variant for building. When you are building for multiple 8875 building for multiple variants with the same :term:`Build Directory`,
7868 variants with the same :term:`Build Directory`, this 8876 this mechanism ensures that output for different ``libc`` variants is
7869 mechanism ensures that output for different ``libc`` variants is kept 8877 kept separate to avoid potential conflicts.
7870 separate to avoid potential conflicts.
7871 8878
7872 In the ``defaultsetup.conf`` file, the default value of 8879 In the ``defaultsetup.conf`` file, the default value of
7873 ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, 8880 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky,
7874 which normally only support one ``libc`` variant, set 8881 which normally only support one ``libc`` variant, set
7875 ``TCLIBCAPPEND`` to "" in their distro configuration file resulting 8882 :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting
7876 in no suffix being applied. 8883 in no suffix being applied.
7877 8884
7878 :term:`TCMODE` 8885 :term:`TCMODE`
7879 Specifies the toolchain selector. ``TCMODE`` controls the 8886 Specifies the toolchain selector. :term:`TCMODE` controls the
7880 characteristics of the generated packages and images by telling the 8887 characteristics of the generated packages and images by telling the
7881 OpenEmbedded build system which toolchain profile to use. By default, 8888 OpenEmbedded build system which toolchain profile to use. By default,
7882 the OpenEmbedded build system builds its own internal toolchain. The 8889 the OpenEmbedded build system builds its own internal toolchain. The
@@ -7885,17 +8892,15 @@ system and gives an overview of their function and contents.
7885 8892
7886 .. note:: 8893 .. note::
7887 8894
7888 If ``TCMODE`` is set to a value other than "default", then it is your 8895 If :term:`TCMODE` is set to a value other than "default", then it is your
7889 responsibility to ensure that the toolchain is compatible with the 8896 responsibility to ensure that the toolchain is compatible with the
7890 default toolchain. Using older or newer versions of these 8897 default toolchain. Using older or newer versions of these
7891 components might cause build problems. See the Release Notes for 8898 components might cause build problems. See
7892 the Yocto Project release for the specific components with which 8899 :doc:`Release Information </migration-guides/index>` for your
7893 the toolchain must be compatible. To access the Release Notes, go 8900 version of the Yocto Project, to find the specific components with
7894 to the :yocto_home:`Downloads </software-overview/downloads>` 8901 which the toolchain must be compatible.
7895 page on the Yocto Project website and click on the "RELEASE 8902
7896 INFORMATION" link for the appropriate release. 8903 The :term:`TCMODE` variable is similar to :term:`TCLIBC`,
7897
7898 The ``TCMODE`` variable is similar to :term:`TCLIBC`,
7899 which controls the variant of the GNU standard C library (``libc``) 8904 which controls the variant of the GNU standard C library (``libc``)
7900 used during the build process: ``glibc`` or ``musl``. 8905 used during the build process: ``glibc`` or ``musl``.
7901 8906
@@ -7906,22 +8911,47 @@ system and gives an overview of their function and contents.
7906 https://github.com/MentorEmbedded/meta-sourcery/. 8911 https://github.com/MentorEmbedded/meta-sourcery/.
7907 8912
7908 The layer's ``README`` file contains information on how to use the 8913 The layer's ``README`` file contains information on how to use the
7909 Sourcery G++ Toolchain as an external toolchain. In summary, you must 8914 Sourcery G++ Toolchain as an external toolchain. You will have to
7910 be sure to add the layer to your ``bblayers.conf`` file in front of 8915 add the layer to your ``bblayers.conf`` file and then set the
7911 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable 8916 :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to
7912 in your ``local.conf`` file to the location in which you installed 8917 the location of the toolchain.
7913 the toolchain.
7914 8918
7915 The fundamentals used for this example apply to any external 8919 The fundamentals used for this example apply to any external
7916 toolchain. You can use ``meta-sourcery`` as a template for adding 8920 toolchain. You can use ``meta-sourcery`` as a template for adding
7917 support for other external toolchains. 8921 support for other external toolchains.
7918 8922
8923 In addition to toolchain configuration, you will also need a
8924 corresponding toolchain recipe file. This recipe file needs to package
8925 up any pre-built objects in the toolchain such as ``libgcc``,
8926 ``libstdcc++``, any locales, and ``libc``.
8927
8928 :term:`TC_CXX_RUNTIME`
8929 Specifies the C/C++ STL and runtime variant to use during
8930 the build process. Default value is 'gnu'
8931
8932 You can select "gnu", "llvm", or "android".
8933
8934 :term:`TEMPLATECONF`
8935 Specifies the directory used by the build system to find templates
8936 from which to build the ``bblayers.conf`` and ``local.conf`` files.
8937 Use this variable if you wish to customize such files, and the default
8938 BitBake targets shown when sourcing the ``oe-init-build-env`` script.
8939
8940 For details, see the
8941 :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`
8942 section in the Yocto Project Development Tasks manual.
8943
8944 .. note::
8945
8946 You must set this variable in the external environment in order
8947 for it to work.
8948
7919 :term:`TEST_EXPORT_DIR` 8949 :term:`TEST_EXPORT_DIR`
7920 The location the OpenEmbedded build system uses to export tests when 8950 The location the OpenEmbedded build system uses to export tests when
7921 the :term:`TEST_EXPORT_ONLY` variable is set 8951 the :term:`TEST_EXPORT_ONLY` variable is set
7922 to "1". 8952 to "1".
7923 8953
7924 The ``TEST_EXPORT_DIR`` variable defaults to 8954 The :term:`TEST_EXPORT_DIR` variable defaults to
7925 ``"${TMPDIR}/testimage/${PN}"``. 8955 ``"${TMPDIR}/testimage/${PN}"``.
7926 8956
7927 :term:`TEST_EXPORT_ONLY` 8957 :term:`TEST_EXPORT_ONLY`
@@ -7931,7 +8961,7 @@ system and gives an overview of their function and contents.
7931 8961
7932 :term:`TEST_LOG_DIR` 8962 :term:`TEST_LOG_DIR`
7933 Holds the SSH log and the boot log for QEMU machines. The 8963 Holds the SSH log and the boot log for QEMU machines. The
7934 ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. 8964 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``.
7935 8965
7936 .. note:: 8966 .. note::
7937 8967
@@ -7951,7 +8981,7 @@ system and gives an overview of their function and contents.
7951 For automated hardware testing, specifies additional arguments to 8981 For automated hardware testing, specifies additional arguments to
7952 pass through to the command specified in 8982 pass through to the command specified in
7953 :term:`TEST_POWERCONTROL_CMD`. Setting 8983 :term:`TEST_POWERCONTROL_CMD`. Setting
7954 ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you 8984 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you
7955 wish, for example, to separate the machine-specific and 8985 wish, for example, to separate the machine-specific and
7956 non-machine-specific parts of the arguments. 8986 non-machine-specific parts of the arguments.
7957 8987
@@ -7963,7 +8993,7 @@ system and gives an overview of their function and contents.
7963 file. 8993 file.
7964 8994
7965 For more information on testing images, see the 8995 For more information on testing images, see the
7966 ":ref:`dev-manual/common-tasks:performing automated runtime testing`" 8996 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
7967 section in the Yocto Project Development Tasks Manual. 8997 section in the Yocto Project Development Tasks Manual.
7968 8998
7969 :term:`TEST_SERIALCONTROL_CMD` 8999 :term:`TEST_SERIALCONTROL_CMD`
@@ -7974,8 +9004,7 @@ system and gives an overview of their function and contents.
7974 program does. 9004 program does.
7975 9005
7976 For example, to use the Picocom terminal program on serial device 9006 For example, to use the Picocom terminal program on serial device
7977 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: 9007 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
7978 ::
7979 9008
7980 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 9009 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
7981 9010
@@ -7983,7 +9012,7 @@ system and gives an overview of their function and contents.
7983 For automated hardware testing, specifies additional arguments to 9012 For automated hardware testing, specifies additional arguments to
7984 pass through to the command specified in 9013 pass through to the command specified in
7985 :term:`TEST_SERIALCONTROL_CMD`. Setting 9014 :term:`TEST_SERIALCONTROL_CMD`. Setting
7986 ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you 9015 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you
7987 wish, for example, to separate the machine-specific and 9016 wish, for example, to separate the machine-specific and
7988 non-machine-specific parts of the command. 9017 non-machine-specific parts of the command.
7989 9018
@@ -7995,7 +9024,7 @@ system and gives an overview of their function and contents.
7995 9024
7996 .. note:: 9025 .. note::
7997 9026
7998 The ``TEST_SERVER_IP`` variable is only used for a small number of 9027 The :term:`TEST_SERVER_IP` variable is only used for a small number of
7999 tests such as the "dnf" test suite, which needs to download packages 9028 tests such as the "dnf" test suite, which needs to download packages
8000 from ``WORKDIR/oe-rootfs-repo``. 9029 from ``WORKDIR/oe-rootfs-repo``.
8001 9030
@@ -8012,18 +9041,16 @@ system and gives an overview of their function and contents.
8012 QEMU. 9041 QEMU.
8013 9042
8014 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 9043 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
8015 your own tests to the list of tests by appending ``TEST_SUITES`` as 9044 your own tests to the list of tests by appending :term:`TEST_SUITES` as
8016 follows: 9045 follows::
8017 ::
8018 9046
8019 TEST_SUITES_append = " mytest" 9047 TEST_SUITES:append = " mytest"
8020 9048
8021 Alternatively, you can 9049 Alternatively, you can
8022 provide the "auto" option to have all applicable tests run against 9050 provide the "auto" option to have all applicable tests run against
8023 the image. 9051 the image::
8024 ::
8025 9052
8026 TEST_SUITES_append = " auto" 9053 TEST_SUITES:append = " auto"
8027 9054
8028 Using this option causes the 9055 Using this option causes the
8029 build system to automatically run tests that are applicable to the 9056 build system to automatically run tests that are applicable to the
@@ -8033,19 +9060,17 @@ system and gives an overview of their function and contents.
8033 another test must appear later in the list than the test on which 9060 another test must appear later in the list than the test on which
8034 they depend. For example, if you append the list of tests with two 9061 they depend. For example, if you append the list of tests with two
8035 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 9062 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
8036 ``test_A``, then you must order the tests as follows: 9063 ``test_A``, then you must order the tests as follows::
8037 ::
8038 9064
8039 TEST_SUITES = "test_A test_B" 9065 TEST_SUITES = "test_A test_B"
8040 9066
8041 For more information on testing images, see the 9067 For more information on testing images, see the
8042 ":ref:`dev-manual/common-tasks:performing automated runtime testing`" 9068 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
8043 section in the Yocto Project Development Tasks Manual. 9069 section in the Yocto Project Development Tasks Manual.
8044 9070
8045 :term:`TEST_TARGET` 9071 :term:`TEST_TARGET`
8046 Specifies the target controller to use when running tests against a 9072 Specifies the target controller to use when running tests against a
8047 test image. The default controller to use is "qemu": 9073 test image. The default controller to use is "qemu"::
8048 ::
8049 9074
8050 TEST_TARGET = "qemu" 9075 TEST_TARGET = "qemu"
8051 9076
@@ -8054,12 +9079,12 @@ system and gives an overview of their function and contents.
8054 the controllers by adding a module in the layer's 9079 the controllers by adding a module in the layer's
8055 ``/lib/oeqa/controllers`` directory and by inheriting the 9080 ``/lib/oeqa/controllers`` directory and by inheriting the
8056 ``BaseTarget`` class, which is an abstract class that cannot be used 9081 ``BaseTarget`` class, which is an abstract class that cannot be used
8057 as a value of ``TEST_TARGET``. 9082 as a value of :term:`TEST_TARGET`.
8058 9083
8059 You can provide the following arguments with ``TEST_TARGET``: 9084 You can provide the following arguments with :term:`TEST_TARGET`:
8060 9085
8061 - *"qemu":* Boots a QEMU image and runs the tests. See the 9086 - *"qemu":* Boots a QEMU image and runs the tests. See the
8062 ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section 9087 ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section
8063 in the Yocto Project Development Tasks Manual for more 9088 in the Yocto Project Development Tasks Manual for more
8064 information. 9089 information.
8065 9090
@@ -8075,17 +9100,16 @@ system and gives an overview of their function and contents.
8075 ``meta/lib/oeqa/controllers/simpleremote.py``. 9100 ``meta/lib/oeqa/controllers/simpleremote.py``.
8076 9101
8077 For information on running tests on hardware, see the 9102 For information on running tests on hardware, see the
8078 ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`" 9103 ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`"
8079 section in the Yocto Project Development Tasks Manual. 9104 section in the Yocto Project Development Tasks Manual.
8080 9105
8081 :term:`TEST_TARGET_IP` 9106 :term:`TEST_TARGET_IP`
8082 The IP address of your hardware under test. The ``TEST_TARGET_IP`` 9107 The IP address of your hardware under test. The :term:`TEST_TARGET_IP`
8083 variable has no effect when :term:`TEST_TARGET` is 9108 variable has no effect when :term:`TEST_TARGET` is
8084 set to "qemu". 9109 set to "qemu".
8085 9110
8086 When you specify the IP address, you can also include a port. Here is 9111 When you specify the IP address, you can also include a port. Here is
8087 an example: 9112 an example::
8088 ::
8089 9113
8090 TEST_TARGET_IP = "192.168.1.4:2201" 9114 TEST_TARGET_IP = "192.168.1.4:2201"
8091 9115
@@ -8097,7 +9121,7 @@ system and gives an overview of their function and contents.
8097 9121
8098 :term:`TESTIMAGE_AUTO` 9122 :term:`TESTIMAGE_AUTO`
8099 Automatically runs the series of automated tests for images when an 9123 Automatically runs the series of automated tests for images when an
8100 image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes 9124 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes
8101 any image that successfully builds to automatically boot under QEMU. 9125 any image that successfully builds to automatically boot under QEMU.
8102 Using the variable also adds in dependencies so that any SDK for 9126 Using the variable also adds in dependencies so that any SDK for
8103 which testing is requested is automatically built first. 9127 which testing is requested is automatically built first.
@@ -8113,9 +9137,9 @@ system and gives an overview of their function and contents.
8113 9137
8114 For more information 9138 For more information
8115 on enabling, running, and writing these tests, see the 9139 on enabling, running, and writing these tests, see the
8116 ":ref:`dev-manual/common-tasks:performing automated runtime testing`" 9140 ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
8117 section in the Yocto Project Development Tasks Manual and the 9141 section in the Yocto Project Development Tasks Manual and the
8118 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. 9142 ":ref:`ref-classes-testimage`" section.
8119 9143
8120 :term:`THISDIR` 9144 :term:`THISDIR`
8121 The directory in which the file BitBake is currently parsing is 9145 The directory in which the file BitBake is currently parsing is
@@ -8129,24 +9153,23 @@ system and gives an overview of their function and contents.
8129 :term:`TMPDIR` 9153 :term:`TMPDIR`
8130 This variable is the base directory the OpenEmbedded build system 9154 This variable is the base directory the OpenEmbedded build system
8131 uses for all build output and intermediate files (other than the 9155 uses for all build output and intermediate files (other than the
8132 shared state cache). By default, the ``TMPDIR`` variable points to 9156 shared state cache). By default, the :term:`TMPDIR` variable points to
8133 ``tmp`` within the :term:`Build Directory`. 9157 ``tmp`` within the :term:`Build Directory`.
8134 9158
8135 If you want to establish this directory in a location other than the 9159 If you want to establish this directory in a location other than the
8136 default, you can uncomment and edit the following statement in the 9160 default, you can uncomment and edit the following statement in the
8137 ``conf/local.conf`` file in the :term:`Source Directory`: 9161 ``conf/local.conf`` file in the :term:`Source Directory`::
8138 ::
8139 9162
8140 #TMPDIR = "${TOPDIR}/tmp" 9163 #TMPDIR = "${TOPDIR}/tmp"
8141 9164
8142 An example use for this scenario is to set ``TMPDIR`` to a local disk, 9165 An example use for this scenario is to set :term:`TMPDIR` to a local disk,
8143 which does not use NFS, while having the Build Directory use NFS. 9166 which does not use NFS, while having the :term:`Build Directory` use NFS.
8144 9167
8145 The filesystem used by ``TMPDIR`` must have standard filesystem 9168 The filesystem used by :term:`TMPDIR` must have standard filesystem
8146 semantics (i.e. mixed-case files are unique, POSIX file locking, and 9169 semantics (i.e. mixed-case files are unique, POSIX file locking, and
8147 persistent inodes). Due to various issues with NFS and bugs in some 9170 persistent inodes). Due to various issues with NFS and bugs in some
8148 implementations, NFS does not meet this minimum requirement. 9171 implementations, NFS does not meet this minimum requirement.
8149 Consequently, ``TMPDIR`` cannot be on NFS. 9172 Consequently, :term:`TMPDIR` cannot be on NFS.
8150 9173
8151 :term:`TOOLCHAIN_HOST_TASK` 9174 :term:`TOOLCHAIN_HOST_TASK`
8152 This variable lists packages the OpenEmbedded build system uses when 9175 This variable lists packages the OpenEmbedded build system uses when
@@ -8154,8 +9177,7 @@ system and gives an overview of their function and contents.
8154 packages specified by this variable are part of the toolchain set 9177 packages specified by this variable are part of the toolchain set
8155 that runs on the :term:`SDKMACHINE`, and each 9178 that runs on the :term:`SDKMACHINE`, and each
8156 package should usually have the prefix ``nativesdk-``. For example, 9179 package should usually have the prefix ``nativesdk-``. For example,
8157 consider the following command when building an SDK: 9180 consider the following command when building an SDK::
8158 ::
8159 9181
8160 $ bitbake -c populate_sdk imagename 9182 $ bitbake -c populate_sdk imagename
8161 9183
@@ -8173,11 +9195,29 @@ system and gives an overview of their function and contents.
8173 information on setting up a cross-development environment, see the 9195 information on setting up a cross-development environment, see the
8174 :doc:`/sdk-manual/index` manual. 9196 :doc:`/sdk-manual/index` manual.
8175 9197
9198 Note that this variable applies to building an SDK, not an eSDK,
9199 in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be
9200 used instead.
9201
9202 :term:`TOOLCHAIN_HOST_TASK_ESDK`
9203 This variable allows to extend what is installed in the host
9204 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
9205 applying to SDKs.
9206
9207 :term:`TOOLCHAIN_OPTIONS`
9208 This variable holds extra options passed to the compiler and the linker
9209 for non ``-native`` recipes as they have to point to their custom
9210 ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`::
9211
9212 TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"
9213
9214 Native recipes don't need this variable to be set, as they are
9215 built for the host machine with the native compiler.
9216
8176 :term:`TOOLCHAIN_OUTPUTNAME` 9217 :term:`TOOLCHAIN_OUTPUTNAME`
8177 This variable defines the name used for the toolchain output. The 9218 This variable defines the name used for the toolchain output. The
8178 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets 9219 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
8179 the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: 9220 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
8180 ::
8181 9221
8182 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" 9222 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
8183 9223
@@ -8204,16 +9244,14 @@ system and gives an overview of their function and contents.
8204 :doc:`/sdk-manual/index` manual. 9244 :doc:`/sdk-manual/index` manual.
8205 9245
8206 :term:`TOPDIR` 9246 :term:`TOPDIR`
8207 The top-level :term:`Build Directory`. BitBake 9247 See :term:`bitbake:TOPDIR` in the BitBake manual.
8208 automatically sets this variable when you initialize your build
8209 environment using :ref:`structure-core-script`.
8210 9248
8211 :term:`TRANSLATED_TARGET_ARCH` 9249 :term:`TRANSLATED_TARGET_ARCH`
8212 A sanitized version of :term:`TARGET_ARCH`. This 9250 A sanitized version of :term:`TARGET_ARCH`. This
8213 variable is used where the architecture is needed in a value where 9251 variable is used where the architecture is needed in a value where
8214 underscores are not allowed, for example within package filenames. In 9252 underscores are not allowed, for example within package filenames. In
8215 this case, dash characters replace any underscore characters used in 9253 this case, dash characters replace any underscore characters used in
8216 ``TARGET_ARCH``. 9254 :term:`TARGET_ARCH`.
8217 9255
8218 Do not edit this variable. 9256 Do not edit this variable.
8219 9257
@@ -8222,19 +9260,18 @@ system and gives an overview of their function and contents.
8222 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 9260 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
8223 this value to setup configuration. 9261 this value to setup configuration.
8224 9262
8225 ``TUNE_ARCH`` definitions are specific to a given architecture. The 9263 :term:`TUNE_ARCH` definitions are specific to a given architecture. The
8226 definitions can be a single static definition, or can be dynamically 9264 definitions can be a single static definition, or can be dynamically
8227 adjusted. You can see details for a given CPU family by looking at 9265 adjusted. You can see details for a given CPU family by looking at
8228 the architecture's ``README`` file. For example, the 9266 the architecture's ``README`` file. For example, the
8229 ``meta/conf/machine/include/mips/README`` file in the 9267 ``meta/conf/machine/include/mips/README`` file in the
8230 :term:`Source Directory` provides information for 9268 :term:`Source Directory` provides information for
8231 ``TUNE_ARCH`` specific to the ``mips`` architecture. 9269 :term:`TUNE_ARCH` specific to the ``mips`` architecture.
8232 9270
8233 ``TUNE_ARCH`` is tied closely to 9271 :term:`TUNE_ARCH` is tied closely to
8234 :term:`TARGET_ARCH`, which defines the target 9272 :term:`TARGET_ARCH`, which defines the target
8235 machine's architecture. The BitBake configuration file 9273 machine's architecture. The BitBake configuration file
8236 (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: 9274 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
8237 ::
8238 9275
8239 TARGET_ARCH = "${TUNE_ARCH}" 9276 TARGET_ARCH = "${TUNE_ARCH}"
8240 9277
@@ -8252,12 +9289,11 @@ system and gives an overview of their function and contents.
8252 :term:`TUNE_ASARGS` 9289 :term:`TUNE_ASARGS`
8253 Specifies architecture-specific assembler flags for the target 9290 Specifies architecture-specific assembler flags for the target
8254 system. The set of flags is based on the selected tune features. 9291 system. The set of flags is based on the selected tune features.
8255 ``TUNE_ASARGS`` is set using the tune include files, which are 9292 :term:`TUNE_ASARGS` is set using the tune include files, which are
8256 typically under ``meta/conf/machine/include/`` and are influenced 9293 typically under ``meta/conf/machine/include/`` and are influenced
8257 through :term:`TUNE_FEATURES`. For example, the 9294 through :term:`TUNE_FEATURES`. For example, the
8258 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9295 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
8259 for the x86 architecture as follows: 9296 for the x86 architecture as follows::
8260 ::
8261 9297
8262 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 9298 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
8263 9299
@@ -8270,7 +9306,7 @@ system and gives an overview of their function and contents.
8270 :term:`TUNE_CCARGS` 9306 :term:`TUNE_CCARGS`
8271 Specifies architecture-specific C compiler flags for the target 9307 Specifies architecture-specific C compiler flags for the target
8272 system. The set of flags is based on the selected tune features. 9308 system. The set of flags is based on the selected tune features.
8273 ``TUNE_CCARGS`` is set using the tune include files, which are 9309 :term:`TUNE_CCARGS` is set using the tune include files, which are
8274 typically under ``meta/conf/machine/include/`` and are influenced 9310 typically under ``meta/conf/machine/include/`` and are influenced
8275 through :term:`TUNE_FEATURES`. 9311 through :term:`TUNE_FEATURES`.
8276 9312
@@ -8290,22 +9326,20 @@ system and gives an overview of their function and contents.
8290 are not conflicting and that they are supported. 9326 are not conflicting and that they are supported.
8291 9327
8292 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 9328 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
8293 ``TUNE_FEATURES`` as follows: 9329 :term:`TUNE_FEATURES` as follows::
8294 ::
8295 9330
8296 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" 9331 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"
8297 9332
8298 See the :term:`DEFAULTTUNE` variable for more information. 9333 See the :term:`DEFAULTTUNE` variable for more information.
8299 9334
8300 :term:`TUNE_LDARGS` 9335 :term:`TUNE_LDARGS`
8301 Specifies architecture-specific linker flags for the target system. 9336 Specifies architecture-specific linker flags for the target system.
8302 The set of flags is based on the selected tune features. 9337 The set of flags is based on the selected tune features.
8303 ``TUNE_LDARGS`` is set using the tune include files, which are 9338 :term:`TUNE_LDARGS` is set using the tune include files, which are
8304 typically under ``meta/conf/machine/include/`` and are influenced 9339 typically under ``meta/conf/machine/include/`` and are influenced
8305 through :term:`TUNE_FEATURES`. For example, the 9340 through :term:`TUNE_FEATURES`. For example, the
8306 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 9341 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
8307 for the x86 architecture as follows: 9342 for the x86 architecture as follows::
8308 ::
8309 9343
8310 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" 9344 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
8311 9345
@@ -8318,51 +9352,15 @@ system and gives an overview of their function and contents.
8318 :term:`TUNE_PKGARCH` 9352 :term:`TUNE_PKGARCH`
8319 The package architecture understood by the packaging system to define 9353 The package architecture understood by the packaging system to define
8320 the architecture, ABI, and tuning of output packages. The specific 9354 the architecture, ABI, and tuning of output packages. The specific
8321 tune is defined using the "_tune" override as follows: 9355 tune is defined using the "_tune" override as follows::
8322 ::
8323 9356
8324 TUNE_PKGARCH_tune-tune = "tune" 9357 TUNE_PKGARCH:tune-tune = "tune"
8325 9358
8326 These tune-specific package architectures are defined in the machine 9359 These tune-specific package architectures are defined in the machine
8327 include files. Here is an example of the "core2-32" tuning as used in 9360 include files. Here is an example of the "core2-32" tuning as used in
8328 the ``meta/conf/machine/include/tune-core2.inc`` file: 9361 the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
8329 :: 9362
8330 9363 TUNE_PKGARCH:tune-core2-32 = "core2-32"
8331 TUNE_PKGARCH_tune-core2-32 = "core2-32"
8332
8333 :term:`TUNEABI`
8334 An underlying Application Binary Interface (ABI) used by a particular
8335 tuning in a given toolchain layer. Providers that use prebuilt
8336 libraries can use the ``TUNEABI``,
8337 :term:`TUNEABI_OVERRIDE`, and
8338 :term:`TUNEABI_WHITELIST` variables to check
8339 compatibility of tunings against their selection of libraries.
8340
8341 If ``TUNEABI`` is undefined, then every tuning is allowed. See the
8342 :ref:`sanity <ref-classes-sanity>` class to see how the variable is
8343 used.
8344
8345 :term:`TUNEABI_OVERRIDE`
8346 If set, the OpenEmbedded system ignores the
8347 :term:`TUNEABI_WHITELIST` variable.
8348 Providers that use prebuilt libraries can use the
8349 ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and
8350 :term:`TUNEABI` variables to check compatibility of a
8351 tuning against their selection of libraries.
8352
8353 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8354 variable is used.
8355
8356 :term:`TUNEABI_WHITELIST`
8357 A whitelist of permissible :term:`TUNEABI` values. If
8358 ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers
8359 that use prebuilt libraries can use the ``TUNEABI_WHITELIST``,
8360 :term:`TUNEABI_OVERRIDE`, and ``TUNEABI``
8361 variables to check compatibility of a tuning against their selection
8362 of libraries.
8363
8364 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8365 variable is used.
8366 9364
8367 :term:`TUNECONFLICTS[feature]` 9365 :term:`TUNECONFLICTS[feature]`
8368 Specifies CPU or Application Binary Interface (ABI) tuning features 9366 Specifies CPU or Application Binary Interface (ABI) tuning features
@@ -8372,8 +9370,7 @@ system and gives an overview of their function and contents.
8372 the :term:`Source Directory`. Here is an example from 9370 the :term:`Source Directory`. Here is an example from
8373 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 9371 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
8374 that lists the "o32" and "n64" features as conflicting with the "n32" 9372 that lists the "o32" and "n64" features as conflicting with the "n32"
8375 feature: 9373 feature::
8376 ::
8377 9374
8378 TUNECONFLICTS[n32] = "o32 n64" 9375 TUNECONFLICTS[n32] = "o32 n64"
8379 9376
@@ -8382,65 +9379,164 @@ system and gives an overview of their function and contents.
8382 feature. The specified feature is stored as a flag. Valid features 9379 feature. The specified feature is stored as a flag. Valid features
8383 are specified in the machine include files (e.g. 9380 are specified in the machine include files (e.g.
8384 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 9381 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
8385 from that file: 9382 from that file::
8386 ::
8387 9383
8388 TUNEVALID[bigendian] = "Enable big-endian mode." 9384 TUNEVALID[bigendian] = "Enable big-endian mode."
8389 9385
8390 See the machine include files in the :term:`Source Directory` 9386 See the machine include files in the :term:`Source Directory`
8391 for these features. 9387 for these features.
8392 9388
8393 :term:`UBOOT_CONFIG` 9389 :term:`UBOOT_BINARY`
8394 Configures the :term:`UBOOT_MACHINE` and can 9390 Specifies the name of the binary build by U-Boot.
8395 also define :term:`IMAGE_FSTYPES` for individual
8396 cases.
8397
8398 Following is an example from the ``meta-fsl-arm`` layer. ::
8399 9391
8400 UBOOT_CONFIG ??= "sd" 9392 :term:`UBOOT_CONFIG`
8401 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" 9393 Configures one or more U-Boot configurations to build. Each
8402 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" 9394 configuration can define the :term:`UBOOT_MACHINE` and optionally the
8403 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" 9395 :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`.
8404 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" 9396
8405 9397 Here is an example from the ``meta-freescale`` layer. ::
8406 In this example, "sd" is selected as the configuration of the possible four for the 9398
8407 ``UBOOT_MACHINE``. The "sd" configuration defines 9399 UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"
8408 "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the 9400 UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig"
8409 "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-Boot image. 9401 UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin"
8410 9402 UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin"
8411 For more information on how the ``UBOOT_CONFIG`` is handled, see the 9403 UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig"
8412 :ref:`uboot-config <ref-classes-uboot-config>` 9404 UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig"
8413 class. 9405 UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig"
9406 UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin"
9407
9408 In this example, all possible seven configurations are selected. Each
9409 configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and
9410 the "sd..." configurations define an individual name for
9411 :term:`UBOOT_BINARY`. No configuration defines a second parameter for
9412 :term:`IMAGE_FSTYPES` to use for the U-Boot image.
9413
9414 For more information on how the :term:`UBOOT_CONFIG` is handled, see the
9415 :ref:`ref-classes-uboot-config` class.
8414 9416
8415 :term:`UBOOT_DTB_LOADADDRESS` 9417 :term:`UBOOT_DTB_LOADADDRESS`
8416 Specifies the load address for the dtb image used by U-Boot. During FIT 9418 Specifies the load address for the dtb image used by U-Boot. During FIT
8417 image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in 9419 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in
8418 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify 9420 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
8419 the load address to be used in 9421 used in creating the dtb sections of Image Tree Source for the FIT image.
8420 creating the dtb sections of Image Tree Source for the FIT image.
8421 9422
8422 :term:`UBOOT_DTBO_LOADADDRESS` 9423 :term:`UBOOT_DTBO_LOADADDRESS`
8423 Specifies the load address for the dtbo image used by U-Boot. During FIT 9424 Specifies the load address for the dtbo image used by U-Boot. During FIT
8424 image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in 9425 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in
8425 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in 9426 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
8426 creating the dtbo sections of Image Tree Source for the FIT image. 9427 used in creating the dtbo sections of Image Tree Source for the FIT image.
8427 9428
8428 :term:`UBOOT_ENTRYPOINT` 9429 :term:`UBOOT_ENTRYPOINT`
8429 Specifies the entry point for the U-Boot image. During U-Boot image 9430 Specifies the entry point for the U-Boot image. During U-Boot image
8430 creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a 9431 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a
8431 command-line parameter to the ``uboot-mkimage`` utility. 9432 command-line parameter to the ``uboot-mkimage`` utility.
8432 9433
9434 To pass a 64 bit address for FIT image creation, you will need to set:
9435 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9436 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
9437
9438 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9439 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9440 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9441 classes.
9442
9443 :term:`UBOOT_FIT_ADDRESS_CELLS`
9444 Specifies the value of the ``#address-cells`` value for the
9445 description of the U-Boot FIT image.
9446
9447 The default value is set to "1" by the :ref:`ref-classes-uboot-sign`
9448 class, which corresponds to 32 bit addresses.
9449
9450 For platforms that need to set 64 bit addresses in
9451 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
9452 set this value to "2", as two 32 bit values (cells) will be needed
9453 to represent such addresses.
9454
9455 Here is an example setting "0x400000000" as a load address::
9456
9457 UBOOT_FIT_ADDRESS_CELLS = "2"
9458 UBOOT_LOADADDRESS= "0x04 0x00000000"
9459
9460 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
9461
9462 :term:`UBOOT_FIT_DESC`
9463 Specifies the description string encoded into a U-Boot fitImage. The default
9464 value is set by the :ref:`ref-classes-uboot-sign` class as follows::
9465
9466 UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
9467
9468 :term:`UBOOT_FIT_GENERATE_KEYS`
9469 Decides whether to generate the keys for signing the U-Boot fitImage if
9470 they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`.
9471 The default value is "0".
9472
9473 Enable this as follows::
9474
9475 UBOOT_FIT_GENERATE_KEYS = "1"
9476
9477 This variable is used in the :ref:`ref-classes-uboot-sign` class.
9478
9479 :term:`UBOOT_FIT_HASH_ALG`
9480 Specifies the hash algorithm used in creating the U-Boot FIT Image.
9481 It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign`
9482 class.
9483
9484 :term:`UBOOT_FIT_KEY_GENRSA_ARGS`
9485 Arguments to ``openssl genrsa`` for generating a RSA private key for
9486 signing the U-Boot FIT image. The default value of this variable
9487 is set to "-F4" by the :ref:`ref-classes-uboot-sign` class.
9488
9489 :term:`UBOOT_FIT_KEY_REQ_ARGS`
9490 Arguments to ``openssl req`` for generating a certificate for signing
9491 the U-Boot FIT image. The default value is "-batch -new" by the
9492 :ref:`ref-classes-uboot-sign` class, "batch" for
9493 non interactive mode and "new" for generating new keys.
9494
9495 :term:`UBOOT_FIT_KEY_SIGN_PKCS`
9496 Format for the public key certificate used for signing the U-Boot FIT
9497 image. The default value is set to "x509" by the
9498 :ref:`ref-classes-uboot-sign` class.
9499
9500 :term:`UBOOT_FIT_SIGN_ALG`
9501 Specifies the signature algorithm used in creating the U-Boot FIT Image.
9502 This variable is set by default to "rsa2048" by the
9503 :ref:`ref-classes-uboot-sign` class.
9504
9505 :term:`UBOOT_FIT_SIGN_NUMBITS`
9506 Size of the private key used in signing the U-Boot FIT image, in number
9507 of bits. The default value for this variable is set to "2048"
9508 by the :ref:`ref-classes-uboot-sign` class.
9509
9510 :term:`UBOOT_FITIMAGE_ENABLE`
9511 This variable allows to generate a FIT image for U-Boot, which is one
9512 of the ways to implement a verified boot process.
9513
9514 Its default value is "0", so set it to "1" to enable this functionality::
9515
9516 UBOOT_FITIMAGE_ENABLE = "1"
9517
9518 See the :ref:`ref-classes-uboot-sign` class for details.
9519
8433 :term:`UBOOT_LOADADDRESS` 9520 :term:`UBOOT_LOADADDRESS`
8434 Specifies the load address for the U-Boot image. During U-Boot image 9521 Specifies the load address for the U-Boot image. During U-Boot image
8435 creation, the ``UBOOT_LOADADDRESS`` variable is passed as a 9522 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a
8436 command-line parameter to the ``uboot-mkimage`` utility. 9523 command-line parameter to the ``uboot-mkimage`` utility.
8437 9524
9525 To pass a 64 bit address, you will also need to set:
9526
9527 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9528 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
9529
9530 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9531 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9532 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9533 classes.
9534
8438 :term:`UBOOT_LOCALVERSION` 9535 :term:`UBOOT_LOCALVERSION`
8439 Appends a string to the name of the local version of the U-Boot 9536 Appends a string to the name of the local version of the U-Boot
8440 image. For example, assuming the version of the U-Boot image built 9537 image. For example, assuming the version of the U-Boot image built
8441 was "2013.10", the full version string reported by U-Boot would be 9538 was "2013.10", the full version string reported by U-Boot would be
8442 "2013.10-yocto" given the following statement: 9539 "2013.10-yocto" given the following statement::
8443 ::
8444 9540
8445 UBOOT_LOCALVERSION = "-yocto" 9541 UBOOT_LOCALVERSION = "-yocto"
8446 9542
@@ -8459,56 +9555,65 @@ system and gives an overview of their function and contents.
8459 9555
8460 :term:`UBOOT_MKIMAGE` 9556 :term:`UBOOT_MKIMAGE`
8461 Specifies the name of the mkimage command as used by the 9557 Specifies the name of the mkimage command as used by the
8462 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble 9558 :ref:`ref-classes-kernel-fitimage` class to assemble
8463 the FIT image. This can be used to substitute an alternative command, wrapper 9559 the FIT image. This can be used to substitute an alternative command, wrapper
8464 script or function if desired. The default is "uboot-mkimage". 9560 script or function if desired. The default is "uboot-mkimage".
8465 9561
8466 :term:`UBOOT_MKIMAGE_DTCOPTS` 9562 :term:`UBOOT_MKIMAGE_DTCOPTS`
8467 Options for the device tree compiler passed to mkimage '-D' 9563 Options for the device tree compiler passed to ``mkimage -D`` feature
8468 feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class. 9564 while creating a FIT image with the :ref:`ref-classes-kernel-fitimage`
8469 If ``UBOOT_MKIMAGE_DTCOPTS`` is not set then kernel-fitimage will not 9565 class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the
8470 pass the ``-D`` option to mkimage. 9566 :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option
9567 to ``mkimage``.
9568
9569 This variable is also used by the :ref:`ref-classes-uboot-sign` class.
9570
9571 :term:`UBOOT_MKIMAGE_KERNEL_TYPE`
9572 Specifies the type argument for the kernel as passed to ``uboot-mkimage``.
9573 The default value is "kernel".
8471 9574
8472 :term:`UBOOT_MKIMAGE_SIGN` 9575 :term:`UBOOT_MKIMAGE_SIGN`
8473 Specifies the name of the mkimage command as used by the 9576 Specifies the name of the mkimage command as used by the
8474 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign 9577 :ref:`ref-classes-kernel-fitimage` class to sign
8475 the FIT image after it has been assembled (if enabled). This can be used 9578 the FIT image after it has been assembled (if enabled). This can be used
8476 to substitute an alternative command, wrapper script or function if 9579 to substitute an alternative command, wrapper script or function if
8477 desired. The default is "${:term:`UBOOT_MKIMAGE`}". 9580 desired. The default is "${:term:`UBOOT_MKIMAGE`}".
8478 9581
8479 :term:`UBOOT_MKIMAGE_SIGN_ARGS` 9582 :term:`UBOOT_MKIMAGE_SIGN_ARGS`
8480 Optionally specifies additional arguments for the 9583 Optionally specifies additional arguments for the
8481 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the 9584 :ref:`ref-classes-kernel-fitimage` class to pass to the
8482 mkimage command when signing the FIT image. 9585 mkimage command when signing the FIT image.
8483 9586
8484 :term:`UBOOT_RD_ENTRYPOINT` 9587 :term:`UBOOT_RD_ENTRYPOINT`
8485 Specifies the entrypoint for the RAM disk image. 9588 Specifies the entrypoint for the RAM disk image. During FIT image
8486 During FIT image creation, the 9589 creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in
8487 ``UBOOT_RD_ENTRYPOINT`` variable is used 9590 :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be
8488 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the 9591 used in creating the Image Tree Source for the FIT image.
8489 entrypoint to be used in creating the Image Tree Source for
8490 the FIT image.
8491 9592
8492 :term:`UBOOT_RD_LOADADDRESS` 9593 :term:`UBOOT_RD_LOADADDRESS`
8493 Specifies the load address for the RAM disk image. 9594 Specifies the load address for the RAM disk image. During FIT image
8494 During FIT image creation, the 9595 creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in
8495 ``UBOOT_RD_LOADADDRESS`` variable is used 9596 :ref:`ref-classes-kernel-fitimage` class to specify the load address to
8496 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the 9597 be used in creating the Image Tree Source for the FIT image.
8497 load address to be used in creating the Image Tree Source for
8498 the FIT image.
8499 9598
8500 :term:`UBOOT_SIGN_ENABLE` 9599 :term:`UBOOT_SIGN_ENABLE`
8501 Enable signing of FIT image. The default value is "0". 9600 Enable signing of FIT image. The default value is "0".
8502 9601
9602 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9603 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9604 classes.
9605
8503 :term:`UBOOT_SIGN_KEYDIR` 9606 :term:`UBOOT_SIGN_KEYDIR`
8504 Location of the directory containing the RSA key and 9607 Location of the directory containing the RSA key and certificate used for
8505 certificate used for signing FIT image. 9608 signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and
9609 :ref:`ref-classes-uboot-sign` classes.
8506 9610
8507 :term:`UBOOT_SIGN_KEYNAME` 9611 :term:`UBOOT_SIGN_KEYNAME`
8508 The name of keys used for signing U-Boot FIT image stored in 9612 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
8509 :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt 9613 for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR`
8510 certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have 9614 directory. If we have for example a ``dev.key`` key and a ``dev.crt``
8511 :term:`UBOOT_SIGN_KEYNAME` set to "dev". 9615 certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will
9616 have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``.
8512 9617
8513 :term:`UBOOT_SUFFIX` 9618 :term:`UBOOT_SUFFIX`
8514 Points to the generated U-Boot extension. For example, ``u-boot.sb`` 9619 Points to the generated U-Boot extension. For example, ``u-boot.sb``
@@ -8523,104 +9628,123 @@ system and gives an overview of their function and contents.
8523 passes and uses "all" for the target during the U-Boot building 9628 passes and uses "all" for the target during the U-Boot building
8524 process. 9629 process.
8525 9630
8526 :term:`UNKNOWN_CONFIGURE_WHITELIST` 9631 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
8527 Specifies a list of options that, if reported by the configure script 9632 Specifies a list of options that, if reported by the configure script
8528 as being invalid, should not generate a warning during the 9633 as being invalid, should not generate a warning during the
8529 :ref:`ref-tasks-configure` task. Normally, invalid 9634 :ref:`ref-tasks-configure` task. Normally, invalid
8530 configure options are simply not passed to the configure script (e.g. 9635 configure options are simply not passed to the configure script (e.g.
8531 should be removed from :term:`EXTRA_OECONF` or 9636 should be removed from :term:`EXTRA_OECONF` or
8532 :term:`PACKAGECONFIG_CONFARGS`). 9637 :term:`PACKAGECONFIG_CONFARGS`).
8533 However, common options, for example, exist that are passed to all 9638 However, there are common options that are passed to all
8534 configure scripts at a class level that might not be valid for some 9639 configure scripts at a class level, but might not be valid for some
8535 configure scripts. It follows that no benefit exists in seeing a 9640 configure scripts. Therefore warnings about these options are useless.
8536 warning about these options. For these cases, the options are added 9641 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`.
8537 to ``UNKNOWN_CONFIGURE_WHITELIST``.
8538 9642
8539 The configure arguments check that uses 9643 The configure arguments check that uses
8540 ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the 9644 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the
8541 :ref:`insane <ref-classes-insane>` class and is only enabled if the 9645 :ref:`ref-classes-insane` class and is only enabled if the
8542 recipe inherits the :ref:`autotools <ref-classes-autotools>` class. 9646 recipe inherits the :ref:`ref-classes-autotools` class.
8543 9647
8544 :term:`UPDATERCPN` 9648 :term:`UPDATERCPN`
8545 For recipes inheriting the 9649 For recipes inheriting the
8546 :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` 9650 :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN`
8547 specifies the package that contains the initscript that is enabled. 9651 specifies the package that contains the initscript that is enabled.
8548 9652
8549 The default value is "${PN}". Given that almost all recipes that 9653 The default value is "${PN}". Given that almost all recipes that
8550 install initscripts package them in the main package for the recipe, 9654 install initscripts package them in the main package for the recipe,
8551 you rarely need to set this variable in individual recipes. 9655 you rarely need to set this variable in individual recipes.
8552 9656
9657 :term:`UPSTREAM_CHECK_COMMITS`
9658 You can perform a per-recipe check for what the latest upstream
9659 source code version is by calling ``devtool latest-version recipe``. If
9660 the recipe source code is provided from Git repositories, but
9661 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS`
9662 to ``1`` in the recipe, and the OpenEmbedded build system
9663 will compare the latest commit with the one currently specified
9664 by the recipe (:term:`SRCREV`)::
9665
9666 UPSTREAM_CHECK_COMMITS = "1"
9667
8553 :term:`UPSTREAM_CHECK_GITTAGREGEX` 9668 :term:`UPSTREAM_CHECK_GITTAGREGEX`
8554 You can perform a per-recipe check for what the latest upstream 9669 You can perform a per-recipe check for what the latest upstream
8555 source code version is by calling ``bitbake -c checkpkg`` recipe. If 9670 source code version is by calling ``devtool latest-version recipe``. If
8556 the recipe source code is provided from Git repositories, the 9671 the recipe source code is provided from Git repositories, the
8557 OpenEmbedded build system determines the latest upstream version by 9672 OpenEmbedded build system determines the latest upstream version by
8558 picking the latest tag from the list of all repository tags. 9673 picking the latest tag from the list of all repository tags.
8559 9674
8560 You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a 9675 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
8561 regular expression to filter only the relevant tags should the 9676 regular expression to filter only the relevant tags should the
8562 default filter not work correctly. 9677 default filter not work correctly::
8563 ::
8564 9678
8565 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" 9679 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
8566 9680
8567 :term:`UPSTREAM_CHECK_REGEX` 9681 :term:`UPSTREAM_CHECK_REGEX`
8568 Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different 9682 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
8569 regular expression instead of the default one when the package 9683 regular expression instead of the default one when the package
8570 checking system is parsing the page found using 9684 checking system is parsing the page found using
8571 :term:`UPSTREAM_CHECK_URI`. 9685 :term:`UPSTREAM_CHECK_URI`::
8572 ::
8573 9686
8574 UPSTREAM_CHECK_REGEX = "package_regex" 9687 UPSTREAM_CHECK_REGEX = "package_regex"
8575 9688
8576 :term:`UPSTREAM_CHECK_URI` 9689 :term:`UPSTREAM_CHECK_URI`
8577 You can perform a per-recipe check for what the latest upstream 9690 You can perform a per-recipe check for what the latest upstream
8578 source code version is by calling ``bitbake -c checkpkg`` recipe. If 9691 source code version is by calling ``devtool latest-version recipe``. If
8579 the source code is provided from tarballs, the latest version is 9692 the source code is provided from tarballs, the latest version is
8580 determined by fetching the directory listing where the tarball is and 9693 determined by fetching the directory listing where the tarball is and
8581 attempting to find a later tarball. When this approach does not work, 9694 attempting to find a later tarball. When this approach does not work,
8582 you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that 9695 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
8583 contains the link to the latest tarball. 9696 contains the link to the latest tarball::
8584 ::
8585 9697
8586 UPSTREAM_CHECK_URI = "recipe_url" 9698 UPSTREAM_CHECK_URI = "recipe_url"
8587 9699
9700 :term:`UPSTREAM_VERSION_UNKNOWN`
9701 You can perform a per-recipe check for what the latest upstream
9702 source code version is by calling ``devtool latest-version recipe``.
9703 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`,
9704 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
9705 the recipe allows to determine what the latest upstream version is,
9706 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe
9707 to acknowledge that the check cannot be performed::
9708
9709 UPSTREAM_VERSION_UNKNOWN = "1"
9710
8588 :term:`USE_DEVFS` 9711 :term:`USE_DEVFS`
8589 Determines if ``devtmpfs`` is used for ``/dev`` population. The 9712 Determines if ``devtmpfs`` is used for ``/dev`` population. The
8590 default value used for ``USE_DEVFS`` is "1" when no value is 9713 default value used for :term:`USE_DEVFS` is "1" when no value is
8591 specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a 9714 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a
8592 statically populated ``/dev`` directory. 9715 statically populated ``/dev`` directory.
8593 9716
8594 See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in 9717 See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in
8595 the Yocto Project Development Tasks Manual for information on how to 9718 the Yocto Project Development Tasks Manual for information on how to
8596 use this variable. 9719 use this variable.
8597 9720
8598 :term:`USE_VT` 9721 :term:`USE_VT`
8599 When using 9722 When using
8600 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, 9723 :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
8601 determines whether or not to run a 9724 determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>`
8602 `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any 9725 on any virtual terminals in order to enable logging in through those
8603 virtual terminals in order to enable logging in through those
8604 terminals. 9726 terminals.
8605 9727
8606 The default value used for ``USE_VT`` is "1" when no default value is 9728 The default value used for :term:`USE_VT` is "1" when no default value is
8607 specifically set. Typically, you would set ``USE_VT`` to "0" in the 9729 specifically set. Typically, you would set :term:`USE_VT` to "0" in the
8608 machine configuration file for machines that do not have a graphical 9730 machine configuration file for machines that do not have a graphical
8609 display attached and therefore do not need virtual terminal 9731 display attached and therefore do not need virtual terminal
8610 functionality. 9732 functionality.
8611 9733
8612 :term:`USER_CLASSES` 9734 :term:`USER_CLASSES`
8613 A list of classes to globally inherit. These classes are used by the 9735 A list of classes to globally inherit. These classes are used by the
8614 OpenEmbedded build system to enable extra features (e.g. 9736 OpenEmbedded build system to enable extra features.
8615 ``buildstats``, ``image-mklibs``, and so forth). 9737
9738 Classes inherited using :term:`USER_CLASSES` must be located in the
9739 ``classes-global/`` or ``classes/`` subdirectories.
8616 9740
8617 The default list is set in your ``local.conf`` file: 9741 The default list is set in your ``local.conf`` file::
8618 ::
8619 9742
8620 USER_CLASSES ?= "buildstats image-mklibs image-prelink" 9743 USER_CLASSES ?= "buildstats"
8621 9744
8622 For more information, see 9745 For more information, see
8623 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. 9746 ``meta-poky/conf/templates/default/local.conf.sample`` in the
9747 :term:`Source Directory`.
8624 9748
8625 :term:`USERADD_ERROR_DYNAMIC` 9749 :term:`USERADD_ERROR_DYNAMIC`
8626 If set to ``error``, forces the OpenEmbedded build system to produce 9750 If set to ``error``, forces the OpenEmbedded build system to produce
@@ -8632,11 +9756,10 @@ system and gives an overview of their function and contents.
8632 9756
8633 The default behavior for the build system is to dynamically apply 9757 The default behavior for the build system is to dynamically apply
8634 ``uid`` and ``gid`` values. Consequently, the 9758 ``uid`` and ``gid`` values. Consequently, the
8635 ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan 9759 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
8636 on using statically assigned ``gid`` and ``uid`` values, you should 9760 on using statically assigned ``gid`` and ``uid`` values, you should
8637 set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` 9761 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
8638 file as follows: 9762 file as follows::
8639 ::
8640 9763
8641 USERADD_ERROR_DYNAMIC = "error" 9764 USERADD_ERROR_DYNAMIC = "error"
8642 9765
@@ -8650,7 +9773,7 @@ system and gives an overview of their function and contents.
8650 .. note:: 9773 .. note::
8651 9774
8652 There is a difference in behavior between setting 9775 There is a difference in behavior between setting
8653 ``USERADD_ERROR_DYNAMIC`` to ``error`` and setting it to ``warn``. 9776 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``.
8654 When it is set to ``warn``, the build system will report a warning for 9777 When it is set to ``warn``, the build system will report a warning for
8655 every undefined ``uid`` and ``gid`` in any recipe. But when it is set 9778 every undefined ``uid`` and ``gid`` in any recipe. But when it is set
8656 to ``error``, it will only report errors for recipes that are actually 9779 to ``error``, it will only report errors for recipes that are actually
@@ -8666,8 +9789,7 @@ system and gives an overview of their function and contents.
8666 When applying static group identification (``gid``) values, the 9789 When applying static group identification (``gid``) values, the
8667 OpenEmbedded build system looks in :term:`BBPATH` for a 9790 OpenEmbedded build system looks in :term:`BBPATH` for a
8668 ``files/group`` file and then applies those ``uid`` values. Set the 9791 ``files/group`` file and then applies those ``uid`` values. Set the
8669 variable as follows in your ``local.conf`` file: 9792 variable as follows in your ``local.conf`` file::
8670 ::
8671 9793
8672 9794
8673 USERADD_GID_TABLES = "files/group" 9795 USERADD_GID_TABLES = "files/group"
@@ -8678,33 +9800,31 @@ system and gives an overview of their function and contents.
8678 causes the build system to use static ``gid`` values. 9800 causes the build system to use static ``gid`` values.
8679 9801
8680 :term:`USERADD_PACKAGES` 9802 :term:`USERADD_PACKAGES`
8681 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 9803 When inheriting the :ref:`ref-classes-useradd` class,
8682 this variable specifies the individual packages within the recipe 9804 this variable specifies the individual packages within the recipe
8683 that require users and/or groups to be added. 9805 that require users and/or groups to be added.
8684 9806
8685 You must set this variable if the recipe inherits the class. For 9807 You must set this variable if the recipe inherits the class. For
8686 example, the following enables adding a user for the main package in 9808 example, the following enables adding a user for the main package in
8687 a recipe: 9809 a recipe::
8688 ::
8689 9810
8690 USERADD_PACKAGES = "${PN}" 9811 USERADD_PACKAGES = "${PN}"
8691 9812
8692 .. note:: 9813 .. note::
8693 9814
8694 It follows that if you are going to use the ``USERADD_PACKAGES`` 9815 It follows that if you are going to use the :term:`USERADD_PACKAGES`
8695 variable, you need to set one or more of the :term:`USERADD_PARAM`, 9816 variable, you need to set one or more of the :term:`USERADD_PARAM`,
8696 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. 9817 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables.
8697 9818
8698 :term:`USERADD_PARAM` 9819 :term:`USERADD_PARAM`
8699 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 9820 When inheriting the :ref:`ref-classes-useradd` class,
8700 this variable specifies for a package what parameters should pass to 9821 this variable specifies for a package what parameters should pass to
8701 the ``useradd`` command if you add a user to the system when the 9822 the ``useradd`` command if you add a user to the system when the
8702 package is installed. 9823 package is installed.
8703 9824
8704 Here is an example from the ``dbus`` recipe: 9825 Here is an example from the ``dbus`` recipe::
8705 ::
8706 9826
8707 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ 9827 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
8708 --no-create-home --shell /bin/false \ 9828 --no-create-home --shell /bin/false \
8709 --user-group messagebus" 9829 --user-group messagebus"
8710 9830
@@ -8720,8 +9840,7 @@ system and gives an overview of their function and contents.
8720 When applying static user identification (``uid``) values, the 9840 When applying static user identification (``uid``) values, the
8721 OpenEmbedded build system looks in :term:`BBPATH` for a 9841 OpenEmbedded build system looks in :term:`BBPATH` for a
8722 ``files/passwd`` file and then applies those ``uid`` values. Set the 9842 ``files/passwd`` file and then applies those ``uid`` values. Set the
8723 variable as follows in your ``local.conf`` file: 9843 variable as follows in your ``local.conf`` file::
8724 ::
8725 9844
8726 USERADD_UID_TABLES = "files/passwd" 9845 USERADD_UID_TABLES = "files/passwd"
8727 9846
@@ -8752,48 +9871,95 @@ system and gives an overview of their function and contents.
8752 Additionally, you should also set the 9871 Additionally, you should also set the
8753 :term:`USERADD_ERROR_DYNAMIC` variable. 9872 :term:`USERADD_ERROR_DYNAMIC` variable.
8754 9873
9874 :term:`VIRTUAL-RUNTIME`
9875 :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual
9876 packages for runtime usage, typically for use in :term:`RDEPENDS`
9877 or in image definitions.
9878
9879 An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible
9880 to either use BusyBox based utilities::
9881
9882 VIRTUAL-RUNTIME_base-utils = "busybox"
9883
9884 or their full featured implementations from GNU Coreutils
9885 and other projects::
9886
9887 VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"
9888
9889 Here are two examples using this virtual runtime package. The
9890 first one is in :yocto_git:`initramfs-framework_1.0.bb
9891 </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`::
9892
9893 RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"
9894
9895 The second example is in the :yocto_git:`core-image-initramfs-boot
9896 </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>`
9897 image definition::
9898
9899 PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
9900
8755 :term:`VOLATILE_LOG_DIR` 9901 :term:`VOLATILE_LOG_DIR`
8756 Specifies the persistence of the target's ``/var/log`` directory, 9902 Specifies the persistence of the target's ``/var/log`` directory,
8757 which is used to house postinstall target log files. 9903 which is used to house postinstall target log files.
8758 9904
8759 By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the 9905 By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the
8760 file is not persistent. You can override this setting by setting the 9906 file is not persistent. You can override this setting by setting the
8761 variable to "no" to make the log directory persistent. 9907 variable to "no" to make the log directory persistent.
8762 9908
9909 :term:`VOLATILE_TMP_DIR`
9910 Specifies the persistence of the target's ``/tmp`` directory.
9911
9912 By default, :term:`VOLATILE_TMP_DIR` is set to "yes", in which case
9913 ``/tmp`` links to a directory which resides in RAM in a ``tmpfs``
9914 filesystem.
9915
9916 If instead, you want the ``/tmp`` directory to be persistent, set the
9917 variable to "no" to make it a regular directory in the root filesystem.
9918
9919 This supports both sysvinit and systemd based systems.
9920
8763 :term:`WARN_QA` 9921 :term:`WARN_QA`
8764 Specifies the quality assurance checks whose failures are reported as 9922 Specifies the quality assurance checks whose failures are reported as
8765 warnings by the OpenEmbedded build system. You set this variable in 9923 warnings by the OpenEmbedded build system. You set this variable in
8766 your distribution configuration file. For a list of the checks you 9924 your distribution configuration file. For a list of the checks you
8767 can control with this variable, see the 9925 can control with this variable, see the
8768 ":ref:`insane.bbclass <ref-classes-insane>`" section. 9926 ":ref:`ref-classes-insane`" section.
9927
9928 :term:`WATCHDOG_TIMEOUT`
9929 Specifies the timeout in seconds used by the ``watchdog`` recipe and
9930 also by ``systemd`` during reboot. The default is 60 seconds.
9931
9932 :term:`WIRELESS_DAEMON`
9933 For ``connman`` and ``packagegroup-base``, specifies the wireless
9934 daemon to use. The default is "wpa-supplicant" (note that the value
9935 uses a dash and not an underscore).
8769 9936
8770 :term:`WKS_FILE` 9937 :term:`WKS_FILE`
8771 Specifies the location of the Wic kickstart file that is used by the 9938 Specifies the location of the Wic kickstart file that is used by the
8772 OpenEmbedded build system to create a partitioned image 9939 OpenEmbedded build system to create a partitioned image
8773 (image\ ``.wic``). For information on how to create a partitioned 9940 (``image.wic``). For information on how to create a partitioned
8774 image, see the 9941 image, see the
8775 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" 9942 ":ref:`dev-manual/wic:creating partitioned images using wic`"
8776 section in the Yocto Project Development Tasks Manual. For details on 9943 section in the Yocto Project Development Tasks Manual. For details on
8777 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. 9944 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter.
8778 9945
8779 :term:`WKS_FILE_DEPENDS` 9946 :term:`WKS_FILE_DEPENDS`
8780 When placed in the recipe that builds your image, this variable lists 9947 When placed in the recipe that builds your image, this variable lists
8781 build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only 9948 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only
8782 applicable when Wic images are active (i.e. when 9949 applicable when Wic images are active (i.e. when
8783 :term:`IMAGE_FSTYPES` contains entries related 9950 :term:`IMAGE_FSTYPES` contains entries related
8784 to Wic). If your recipe does not create Wic images, the variable has 9951 to Wic). If your recipe does not create Wic images, the variable has
8785 no effect. 9952 no effect.
8786 9953
8787 The ``WKS_FILE_DEPENDS`` variable is similar to the 9954 The :term:`WKS_FILE_DEPENDS` variable is similar to the
8788 :term:`DEPENDS` variable. When you use the variable in 9955 :term:`DEPENDS` variable. When you use the variable in
8789 your recipe that builds the Wic image, dependencies you list in the 9956 your recipe that builds the Wic image, dependencies you list in the
8790 ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. 9957 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable.
8791 9958
8792 With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to 9959 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
8793 specify a list of additional dependencies (e.g. native tools, 9960 specify a list of additional dependencies (e.g. native tools,
8794 bootloaders, and so forth), that are required to build Wic images. 9961 bootloaders, and so forth), that are required to build Wic images.
8795 Following is an example: 9962 Here is an example::
8796 ::
8797 9963
8798 WKS_FILE_DEPENDS = "some-native-tool" 9964 WKS_FILE_DEPENDS = "some-native-tool"
8799 9965
@@ -8801,14 +9967,26 @@ system and gives an overview of their function and contents.
8801 previous example, some-native-tool would be replaced with an actual 9967 previous example, some-native-tool would be replaced with an actual
8802 native tool on which the build would depend. 9968 native tool on which the build would depend.
8803 9969
9970 :term:`WKS_FILES`
9971 Specifies a list of candidate Wic kickstart files to be used by the
9972 OpenEmbedded build system to create a partitioned image. Only the
9973 first one that is found, from left to right, will be used.
9974
9975 This is only useful when there are multiple ``.wks`` files that can be
9976 used to produce an image. A typical case is when multiple layers are
9977 used for different hardware platforms, each supplying a different
9978 ``.wks`` file. In this case, you specify all possible ones through
9979 :term:`WKS_FILES`.
9980
9981 If only one ``.wks`` file is used, set :term:`WKS_FILE` instead.
9982
8804 :term:`WORKDIR` 9983 :term:`WORKDIR`
8805 The pathname of the work directory in which the OpenEmbedded build 9984 The pathname of the work directory in which the OpenEmbedded build
8806 system builds a recipe. This directory is located within the 9985 system builds a recipe. This directory is located within the
8807 :term:`TMPDIR` directory structure and is specific to 9986 :term:`TMPDIR` directory structure and is specific to
8808 the recipe being built and the system for which it is being built. 9987 the recipe being built and the system for which it is being built.
8809 9988
8810 The ``WORKDIR`` directory is defined as follows: 9989 The :term:`WORKDIR` directory is defined as follows::
8811 ::
8812 9990
8813 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 9991 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8814 9992
@@ -8817,18 +9995,17 @@ system and gives an overview of their function and contents.
8817 - :term:`TMPDIR`: The top-level build output directory 9995 - :term:`TMPDIR`: The top-level build output directory
8818 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier 9996 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier
8819 - :term:`PN`: The recipe name 9997 - :term:`PN`: The recipe name
8820 - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which 9998 - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which
8821 is usually the case for most recipes, then `EXTENDPE` is blank) 9999 is usually the case for most recipes, then :term:`EXTENDPE` is blank.
8822 - :term:`PV`: The recipe version 10000 - :term:`PV`: The recipe version
8823 - :term:`PR`: The recipe revision 10001 - :term:`PR`: The recipe revision
8824 10002
8825 As an example, assume a Source Directory top-level folder name 10003 As an example, assume a Source Directory top-level folder name
8826 ``poky``, a default Build Directory at ``poky/build``, and a 10004 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a
8827 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 10005 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
8828 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 10006 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
8829 directory the build system uses to build the package would be as 10007 directory the build system uses to build the package would be as
8830 follows: 10008 follows::
8831 ::
8832 10009
8833 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 10010 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8834 10011
@@ -8839,6 +10016,37 @@ system and gives an overview of their function and contents.
8839 indirectly, includes "x11-base" in 10016 indirectly, includes "x11-base" in
8840 :term:`IMAGE_FEATURES`. 10017 :term:`IMAGE_FEATURES`.
8841 10018
8842 The default value of ``XSERVER``, if not specified in the machine 10019 The default value of :term:`XSERVER`, if not specified in the machine
8843 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 10020 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
8844 10021
10022 :term:`XZ_THREADS`
10023 Specifies the number of parallel threads that should be used when
10024 using xz compression.
10025
10026 By default this scales with core count, but is never set less than 2
10027 to ensure that multi-threaded mode is always used so that the output
10028 file contents are deterministic. Builds will work with a value of 1
10029 but the output will differ compared to the output from the compression
10030 generated when more than one thread is used.
10031
10032 On systems where many tasks run in parallel, setting a limit to this
10033 can be helpful in controlling system resource usage.
10034
10035 :term:`XZ_MEMLIMIT`
10036 Specifies the maximum memory the xz compression should use as a percentage
10037 of system memory. If unconstrained the xz compressor can use large amounts of
10038 memory and become problematic with parallelism elsewhere in the build.
10039 "50%" has been found to be a good value.
10040
10041 :term:`ZSTD_THREADS`
10042 Specifies the number of parallel threads that should be used when
10043 using ZStandard compression.
10044
10045 By default this scales with core count, but is never set less than 2
10046 to ensure that multi-threaded mode is always used so that the output
10047 file contents are deterministic. Builds will work with a value of 1
10048 but the output will differ compared to the output from the compression
10049 generated when more than one thread is used.
10050
10051 On systems where many tasks run in parallel, setting a limit to this
10052 can be helpful in controlling system resource usage.
diff --git a/documentation/ref-manual/varlocality.rst b/documentation/ref-manual/varlocality.rst
index 5f7dba8775..e2c086ffa0 100644
--- a/documentation/ref-manual/varlocality.rst
+++ b/documentation/ref-manual/varlocality.rst
@@ -113,7 +113,7 @@ This section lists variables that are required for recipes.
113 113
114- :term:`LIC_FILES_CHKSUM` 114- :term:`LIC_FILES_CHKSUM`
115 115
116- :term:`SRC_URI` - used in recipes that fetch local or remote files. 116- :term:`SRC_URI` --- used in recipes that fetch local or remote files.
117 117
118.. _ref-varlocality-recipe-dependencies: 118.. _ref-varlocality-recipe-dependencies:
119 119