diff options
Diffstat (limited to 'documentation/ref-manual')
43 files changed, 8505 insertions, 10416 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 @@ | |||
1 | Handbook 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 f47b6e3875..ab71cbe40c 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst | |||
@@ -13,8 +13,14 @@ some default behavior. | |||
13 | 13 | ||
14 | Any :term:`Metadata` usually found in a recipe can also be | 14 | Any :term:`Metadata` usually found in a recipe can also be |
15 | placed in a class file. Class files are identified by the extension | 15 | placed 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 |
17 | the ``meta*/`` directory found in the :term:`Source Directory`. | 17 | beneath 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 | |||
18 | Class files can also be pointed to by | 24 | Class 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`` | |||
22 | files are searched. | 28 | files are searched. |
23 | 29 | ||
24 | This chapter discusses only the most useful and important classes. Other | 30 | This chapter discusses only the most useful and important classes. Other |
25 | classes do exist within the ``meta/classes`` directory in the Source | 31 | classes do exist within the ``meta/classes*`` directories in the Source |
26 | Directory. You can reference the ``.bbclass`` files directly for more | 32 | Directory. You can reference the ``.bbclass`` files directly for more |
27 | information. | 33 | information. |
28 | 34 | ||
29 | .. _ref-classes-allarch: | 35 | .. _ref-classes-allarch: |
30 | 36 | ||
31 | ``allarch.bbclass`` | 37 | ``allarch`` |
32 | =================== | 38 | =========== |
33 | 39 | ||
34 | The ``allarch`` class is inherited by recipes that do not produce | 40 | The :ref:`ref-classes-allarch` class is inherited by recipes that do not produce |
35 | architecture-specific output. The class disables functionality that is | 41 | architecture-specific output. The class disables functionality that is |
36 | normally needed for recipes that produce executable binaries (such as | 42 | normally needed for recipes that produce executable binaries (such as |
37 | building the cross-compiler and a C library as pre-requisites, and | 43 | building 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 | ||
55 | By default, all recipes inherit the :ref:`base <ref-classes-base>` and | 61 | By 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 |
57 | functionality needed for recipes that produce executable output. If your | 63 | functionality needed for recipes that produce executable output. If your |
58 | recipe, for example, only produces packages that contain configuration | 64 | recipe, for example, only produces packages that contain configuration |
59 | files, media files, or scripts (e.g. Python and Perl), then it should | 65 | files, media files, or scripts (e.g. Python and Perl), then it should |
60 | inherit the ``allarch`` class. | 66 | inherit 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 | ||
67 | The ``archiver`` class supports releasing source code and other | 73 | The :ref:`ref-classes-archiver` class supports releasing source code and other |
68 | materials with the binaries. | 74 | materials with the binaries. |
69 | 75 | ||
70 | For more details on the source archiver, see the | 76 | For 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`" |
72 | section in the Yocto Project Development Tasks Manual. You can also see | 78 | section in the Yocto Project Development Tasks Manual. You can also see |
73 | the :term:`ARCHIVER_MODE` variable for information | 79 | the :term:`ARCHIVER_MODE` variable for information |
74 | about the variable flags (varflags) that help control archive creation. | 80 | about 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 | ||
81 | The ``autotools*`` classes support Autotooled packages. | 87 | The :ref:`autotools* <ref-classes-autotools>` classes support packages built with the |
88 | :wikipedia:`GNU Autotools <GNU_Autotools>`. | ||
82 | 89 | ||
83 | The ``autoconf``, ``automake``, and ``libtool`` packages bring | 90 | The ``autoconf``, ``automake``, and ``libtool`` packages bring |
84 | standardization. This class defines a set of tasks (e.g. ``configure``, | 91 | standardization. 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``, | |||
86 | should usually be enough to define a few standard variables and then | 93 | should usually be enough to define a few standard variables and then |
87 | simply ``inherit autotools``. These classes can also work with software | 94 | simply ``inherit autotools``. These classes can also work with software |
88 | that emulates Autotools. For more information, see the | 95 | that 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 |
90 | in the Yocto Project Development Tasks Manual. | 97 | in the Yocto Project Development Tasks Manual. |
91 | 98 | ||
92 | By default, the ``autotools*`` classes use out-of-tree builds (i.e. | 99 | By 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 | ||
95 | If the software being built by a recipe does not support using | 102 | If the software being built by a recipe does not support using |
96 | out-of-tree builds, you should have the recipe inherit the | 103 | out-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 |
98 | the same as the ``autotools`` class but builds with :term:`B` | 105 | the 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 |
100 | support is either not present or is broken. | 107 | support 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 | ||
107 | It's useful to have some idea of how the tasks defined by the | 114 | It'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 | ||
129 | The ``base`` class is special in that every ``.bb`` file implicitly | 136 | The :ref:`ref-classes-base` class is special in that every ``.bb`` file implicitly |
130 | inherits the class. This class contains definitions for standard basic | 137 | inherits the class. This class contains definitions for standard basic |
131 | tasks such as fetching, unpacking, configuring (empty by default), | 138 | tasks such as fetching, unpacking, configuring (empty by default), |
132 | compiling (runs any ``Makefile`` present), installing (empty by default) | 139 | compiling (runs any ``Makefile`` present), installing (empty by default) |
133 | and packaging (empty by default). These classes are often overridden or | 140 | and packaging (empty by default). These tasks are often overridden or |
134 | extended by other classes such as the | 141 | extended 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 | ||
138 | The class also contains some commonly used functions such as | 144 | The 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 | ||
148 | Sets up packaging and dependencies appropriate for recipes that build | 154 | Sets up packaging and dependencies appropriate for recipes that build |
149 | software that includes bash-completion data. | 155 | software 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 | ||
156 | The ``bin_package`` class is a helper class for recipes that extract the | 162 | The :ref:`ref-classes-bin-package` class is a helper class for recipes that extract the |
157 | contents of a binary package (e.g. an RPM) and install those contents | 163 | contents of a binary package (e.g. an RPM) and install those contents |
158 | rather than building the binary from source. The binary package is | 164 | rather than building the binary from source. The binary package is |
159 | extracted and new packages in the configured output package format are | 165 | extracted 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 | ||
185 | The ``binconfig`` class helps to correct paths in shell scripts. | 189 | The :ref:`ref-classes-binconfig` class helps to correct paths in shell scripts. |
186 | 190 | ||
187 | Before ``pkg-config`` had become widespread, libraries shipped shell | 191 | Before ``pkg-config`` had become widespread, libraries shipped shell |
188 | scripts to give information about the libraries and include paths needed | 192 | scripts 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 | ||
205 | An alternative version of the :ref:`binconfig <ref-classes-binconfig>` | 209 | An alternative version of the :ref:`ref-classes-binconfig` |
206 | class, which disables binary configuration scripts by making them return | 210 | class, which disables binary configuration scripts by making them return |
207 | an error in favor of using ``pkg-config`` to query the information. The | 211 | an error in favor of using ``pkg-config`` to query the information. The |
208 | scripts to be disabled should be specified using the | 212 | scripts to be disabled should be specified using the :term:`BINCONFIG` |
209 | :term:`BINCONFIG` variable within the recipe inheriting | 213 | variable within the recipe inheriting the class. |
210 | the class. | ||
211 | |||
212 | .. _ref-classes-blacklist: | ||
213 | |||
214 | ``blacklist.bbclass`` | ||
215 | ===================== | ||
216 | |||
217 | The ``blacklist`` class prevents the OpenEmbedded build system from | ||
218 | building specific recipes (blacklists them). To use this class, inherit | ||
219 | the class globally and set :term:`PNBLACKLIST` for | ||
220 | each recipe you wish to blacklist. Specify the :term:`PN` | ||
221 | value as a variable flag (varflag) and provide a reason, which is | ||
222 | reported, if the package is requested to be built as the value. For | ||
223 | example, if you want to blacklist a recipe called "exoticware", you add | ||
224 | the 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 | ||
235 | The ``buildhistory`` class records a history of build output metadata, | 220 | The :ref:`ref-classes-buildhistory` class records a history of build output metadata, |
236 | which can be used to detect possible regressions as well as used for | 221 | which can be used to detect possible regressions as well as used for |
237 | analysis of the build output. For more information on using Build | 222 | analysis of the build output. For more information on using Build |
238 | History, see the | 223 | History, see the |
239 | ":ref:`dev-manual/common-tasks:maintaining build output quality`" | 224 | ":ref:`dev-manual/build-quality:maintaining build output quality`" |
240 | section in the Yocto Project Development Tasks Manual. | 225 | section 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 | ||
247 | The ``buildstats`` class records performance statistics about each task | 232 | The :ref:`ref-classes-buildstats` class records performance statistics about each task |
248 | executed during the build (e.g. elapsed time, CPU usage, and I/O usage). | 233 | executed during the build (e.g. elapsed time, CPU usage, and I/O usage). |
249 | 234 | ||
250 | When you use this class, the output goes into the | 235 | When 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 |
260 | enable the class. However, if you want to disable the class, simply | 245 | enable the class. However, if you want to disable the class, simply |
261 | remove "buildstats" from the ``USER_CLASSES`` list. | 246 | remove ":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 | ||
268 | When inherited globally, prints statistics at the end of the build on | 253 | When inherited globally, prints statistics at the end of the build on |
269 | sstate re-use. In order to function, this class requires the | 254 | sstate 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 | |||
262 | The :ref:`ref-classes-cargo` class allows to compile Rust language programs | ||
263 | using `Cargo <https://doc.rust-lang.org/cargo/>`__. Cargo is Rust's package | ||
264 | manager, allowing to fetch package dependencies and build your program. | ||
265 | |||
266 | Using this class makes it very easy to build Rust programs. All you need | ||
267 | is to use the :term:`SRC_URI` variable to point to a source repository | ||
268 | which 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`` | ||
270 | subdirectory. | ||
271 | |||
272 | If 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 | |||
275 | You 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>` | ||
277 | recipe. Another example, with only crate dependencies, is the | ||
278 | :oe_git:`uutils-coreutils </meta-openembedded/tree/meta-oe/recipes-core/uutils-coreutils>` | ||
279 | recipe, which was generated by the `cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ | ||
280 | tool. | ||
281 | |||
282 | This class inherits the :ref:`ref-classes-cargo_common` class. | ||
283 | |||
284 | .. _ref-classes-cargo_c: | ||
285 | |||
286 | ``cargo_c`` | ||
287 | =========== | ||
288 | |||
289 | The :ref:`ref-classes-cargo_c` class can be inherited by a recipe to generate | ||
290 | a Rust library that can be called by C/C++ code. The recipe which inherits this | ||
291 | class has to only replace ``inherit cargo`` by ``inherit cargo_c``. | ||
292 | |||
293 | See the :yocto_git:`rust-c-lib-example_git.bb | ||
294 | </poky/tree/meta-selftest/recipes-devtools/rust/rust-c-lib-example_git.bb>` | ||
295 | example recipe. | ||
296 | |||
297 | .. _ref-classes-cargo_common: | ||
298 | |||
299 | ``cargo_common`` | ||
300 | ================ | ||
301 | |||
302 | The :ref:`ref-classes-cargo_common` class is an internal class | ||
303 | that is not intended to be used directly. | ||
304 | |||
305 | An exception is the "rust" recipe, to build the Rust compiler and runtime | ||
306 | library, which is built by Cargo but cannot use the :ref:`ref-classes-cargo` | ||
307 | class. This is why this class was introduced. | ||
308 | |||
309 | .. _ref-classes-cargo-update-recipe-crates: | ||
310 | |||
311 | ``cargo-update-recipe-crates`` | ||
312 | =============================== | ||
313 | |||
314 | The :ref:`ref-classes-cargo-update-recipe-crates` class allows | ||
315 | recipe developers to update the list of Cargo crates in :term:`SRC_URI` | ||
316 | by reading the ``Cargo.lock`` file in the source tree. | ||
317 | |||
318 | To do so, create a recipe for your program, for example using | ||
319 | :doc:`devtool </ref-manual/devtool-reference>`, | ||
320 | make 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 | |||
325 | This creates a ``recipe-crates.inc`` file that you can include in your | ||
326 | recipe:: | ||
327 | |||
328 | require ${BPN}-crates.inc | ||
329 | |||
330 | That'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 | ||
277 | The ``ccache`` class enables the C/C++ Compiler Cache for the build. | 338 | The :ref:`ref-classes-ccache` class enables the C/C++ Compiler Cache for the build. |
278 | This class is used to give a minor performance boost during the build. | 339 | This class is used to give a minor performance boost during the build. |
279 | However, using the class can lead to unexpected side-effects. Thus, it | 340 | |
280 | is recommended that you do not use this class. See | 341 | See https://ccache.samba.org/ for information on the C/C++ Compiler |
281 | https://ccache.samba.org/ for information on the C/C++ Compiler | 342 | Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>` |
282 | Cache. | 343 | file for details about how to enable this mechanism in your configuration |
344 | file, how to disable it for specific recipes, and how to share ``ccache`` | ||
345 | files between builds. | ||
346 | |||
347 | However, using the class can lead to unexpected side-effects. Thus, using | ||
348 | this 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 | ||
289 | The ``chrpath`` class is a wrapper around the "chrpath" utility, which | 355 | The :ref:`ref-classes-chrpath` class is a wrapper around the "chrpath" utility, which |
290 | is used during the build process for ``nativesdk``, ``cross``, and | 356 | is 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 |
292 | in order to make them relocatable. | 358 | in 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 | ||
299 | The ``clutter`` class consolidates the major and minor version naming | 365 | The :ref:`ref-classes-cmake` class allows recipes to build software using the |
300 | and 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 | ||
368 | pass to the ``cmake`` command line. | ||
301 | 369 | ||
302 | .. note:: | 370 | By default, the :ref:`ref-classes-cmake` class uses |
371 | `Ninja <https://ninja-build.org/>`__ instead of GNU make for building, which | ||
372 | offers better build performance. If a recipe is broken with Ninja, then the | ||
373 | recipe can set the :term:`OECMAKE_GENERATOR` variable to ``Unix Makefiles`` to | ||
374 | use GNU make instead. | ||
303 | 375 | ||
304 | Unlike some other classes related to specific libraries, recipes | 376 | If 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 | 377 | being built, you should install them (during :ref:`ref-tasks-install`) to the |
306 | class unless they use the same recipe versioning scheme that the | 378 | preferred 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 | ||
314 | The ``cmake`` class allows for recipes that need to build software using | 385 | The :ref:`ref-classes-cmake-qemu` class might be used instead of the |
315 | the `CMake <https://cmake.org/overview/>`__ build system. You can use | 386 | :ref:`ref-classes-cmake` class. In addition to the features provided by the |
316 | the :term:`EXTRA_OECMAKE` variable to specify | 387 | :ref:`ref-classes-cmake` class, the :ref:`ref-classes-cmake-qemu` class passes |
317 | additional configuration options to be passed using the ``cmake`` | 388 | the ``CMAKE_CROSSCOMPILING_EMULATOR`` setting to ``cmake``. This allows to use |
318 | command line. | 389 | QEMU user-mode emulation for the execution of cross-compiled binaries on the |
390 | host machine. For more information about ``CMAKE_CROSSCOMPILING_EMULATOR`` | ||
391 | please refer to the `related section of the CMake documentation | ||
392 | <https://cmake.org/cmake/help/latest/variable/CMAKE_CROSSCOMPILING_EMULATOR.html>`__. | ||
319 | 393 | ||
320 | On the occasion that you would be installing custom CMake toolchain | 394 | Not all platforms are supported by QEMU. This class only works for machines with |
321 | files supplied by the application being built, you should install them | 395 | ``qemu-usermode`` in the :ref:`ref-features-machine`. Using QEMU user-mode therefore |
322 | to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` | 396 | involves a certain risk, which is also the reason why this feature is not part of |
323 | Modules during | 397 | the main :ref:`ref-classes-cmake` class by default. |
324 | :ref:`ref-tasks-install`. | 398 | |
399 | One use case is the execution of cross-compiled unit tests with CTest on the build | ||
400 | machine. If ``CMAKE_CROSSCOMPILING_EMULATOR`` is configured:: | ||
401 | |||
402 | cmake --build --target test | ||
403 | |||
404 | works transparently with QEMU user-mode. | ||
405 | |||
406 | If the CMake project is developed with this use case in mind this works very nicely. | ||
407 | This 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 | ||
331 | The ``cml1`` class provides basic support for the Linux kernel style | 414 | The :ref:`ref-classes-cml1` class provides basic support for the Linux kernel style |
332 | build configuration system. | 415 | build configuration system. "cml" stands for "Configuration Menu Language", which |
416 | originates from the Linux kernel but is also used in other projects such as U-Boot | ||
417 | and 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 | ||
339 | Enables compression for man pages and info pages. This class is intended | 424 | Enables compression for manual and info pages. This class is intended |
340 | to be inherited globally. The default compression mechanism is gz (gzip) | 425 | to be inherited globally. The default compression mechanism is gz (gzip) |
341 | but you can select an alternative mechanism by setting the | 426 | but 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 | ||
349 | The ``copyleft_compliance`` class preserves source code for the purposes | 434 | The :ref:`ref-classes-copyleft_compliance` class preserves source code for the purposes |
350 | of license compliance. This class is an alternative to the ``archiver`` | 435 | of license compliance. This class is an alternative to the :ref:`ref-classes-archiver` |
351 | class and is still used by some users even though it has been deprecated | 436 | class and is still used by some users even though it has been deprecated |
352 | in favor of the :ref:`archiver <ref-classes-archiver>` class. | 437 | in 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 | ||
359 | A class used by the :ref:`archiver <ref-classes-archiver>` and | 444 | A 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 |
361 | for filtering licenses. The ``copyleft_filter`` class is an internal | 446 | for filtering licenses. The ``copyleft_filter`` class is an internal |
362 | class and is not intended to be used directly. | 447 | class 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 | ||
369 | The ``core-image`` class provides common definitions for the | 454 | The :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 | ||
378 | The ``cpan*`` classes support Perl modules. | 463 | The :ref:`cpan* <ref-classes-cpan>` classes support Perl modules. |
379 | 464 | ||
380 | Recipes for Perl modules are simple. These recipes usually only need to | 465 | Recipes for Perl modules are simple. These recipes usually only need to |
381 | point to the source's archive and then inherit the proper class file. | 466 | point 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 | ||
391 | Both build methods inherit the ``cpan-base`` class for basic Perl | 476 | Both build methods inherit the :ref:`cpan-base <ref-classes-cpan>` class for basic Perl |
392 | support. | 477 | support. |
393 | 478 | ||
479 | .. _ref-classes-create-spdx: | ||
480 | |||
481 | ``create-spdx`` | ||
482 | =============== | ||
483 | |||
484 | The :ref:`ref-classes-create-spdx` class provides support for | ||
485 | automatically creating :term:`SPDX` :term:`SBOM` documents based upon image | ||
486 | and SDK contents. | ||
487 | |||
488 | This class is meant to be inherited globally from a configuration file:: | ||
489 | |||
490 | INHERIT += "create-spdx" | ||
491 | |||
492 | The 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, | ||
495 | as well as in ``tmp/deploy/spdx``. | ||
496 | |||
497 | The exact behaviour of this class, and the amount of output can be controlled | ||
498 | by the :term:`SPDX_PRETTY`, :term:`SPDX_ARCHIVE_PACKAGED`, | ||
499 | :term:`SPDX_ARCHIVE_SOURCES` and :term:`SPDX_INCLUDE_SOURCES` variables. | ||
500 | |||
501 | See the description of these variables and the | ||
502 | ":ref:`dev-manual/sbom:creating a software bill of materials`" | ||
503 | section 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 | ||
399 | The ``cross`` class provides support for the recipes that build the | 510 | The :ref:`ref-classes-cross` class provides support for the recipes that build the |
400 | cross-compilation tools. | 511 | cross-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 | ||
407 | The ``cross-canadian`` class provides support for the recipes that build | 518 | The :ref:`ref-classes-cross-canadian` class provides support for the recipes that build |
408 | the Canadian Cross-compilation tools for SDKs. See the | 519 | the 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`" |
410 | section in the Yocto Project Overview and Concepts Manual for more | 521 | section 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 | ||
418 | The ``crosssdk`` class provides support for the recipes that build the | 529 | The :ref:`ref-classes-crosssdk` class provides support for the recipes that build the |
419 | cross-compilation tools used for building SDKs. See the | 530 | cross-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`" |
421 | section in the Yocto Project Overview and Concepts Manual for more | 532 | section in the Yocto Project Overview and Concepts Manual for more |
422 | discussion on these cross-compilation tools. | 533 | discussion on these cross-compilation tools. |
423 | 534 | ||
535 | .. _ref-classes-cve-check: | ||
536 | |||
537 | ``cve-check`` | ||
538 | ============= | ||
539 | |||
540 | The :ref:`ref-classes-cve-check` class looks for known CVEs (Common Vulnerabilities | ||
541 | and Exposures) while building with BitBake. This class is meant to be | ||
542 | inherited globally from a configuration file:: | ||
543 | |||
544 | INHERIT += "cve-check" | ||
545 | |||
546 | To filter out obsolete CVE database entries which are known not to impact software from Poky and OE-Core, | ||
547 | add following line to the build configuration file:: | ||
548 | |||
549 | include cve-extra-exclusions.inc | ||
550 | |||
551 | You can also look for vulnerabilities in specific packages by passing | ||
552 | ``-c cve_check`` to BitBake. | ||
553 | |||
554 | After building the software with Bitbake, CVE check output reports are available in ``tmp/deploy/cve`` | ||
555 | and image specific summaries in ``tmp/deploy/images/*.cve`` or ``tmp/deploy/images/*.json`` files. | ||
556 | |||
557 | When building, the CVE checker will emit build time warnings for any detected | ||
558 | issues which are in the state ``Unpatched``, meaning that CVE issue seems to affect the software component | ||
559 | and version being compiled and no patches to address the issue are applied. Other states | ||
560 | for detected CVE issues are: ``Patched`` meaning that a patch to address the issue is already | ||
561 | applied, and ``Ignored`` meaning that the issue can be ignored. | ||
562 | |||
563 | The ``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 | ||
565 | CVE metadata of format ``CVE: CVE-ID`` in the commit message of the patch file. | ||
566 | |||
567 | If the recipe adds ``CVE-ID`` as flag of the :term:`CVE_STATUS` variable with status | ||
568 | mapped 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 | |||
572 | If CVE check reports that a recipe contains false positives or false negatives, these may be | ||
573 | fixed 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 | ||
575 | database vendor and product pairs using the syntax:: | ||
576 | |||
577 | CVE_PRODUCT = "flex_project:flex" | ||
578 | |||
579 | where ``flex_project`` is the CVE database vendor name and ``flex`` is the product name. Similarly | ||
580 | if the default recipe version :term:`PV` does not match the version numbers of the software component | ||
581 | in upstream releases or the CVE database, then the :term:`CVE_VERSION` variable can be used to set the | ||
582 | CVE database compatible version number, for example:: | ||
583 | |||
584 | CVE_VERSION = "2.39" | ||
585 | |||
586 | Any bugs or missing or incomplete information in the CVE database entries should be fixed in the CVE database | ||
587 | via the `NVD feedback form <https://nvd.nist.gov/info/contact-form>`__. | ||
588 | |||
589 | Users should note that security is a process, not a product, and thus also CVE checking, analyzing results, | ||
590 | patching and updating the software should be done as a regular process. The data and assumptions | ||
591 | required for CVE checker to reliably detect issues are frequently broken in various ways. | ||
592 | These can only be detected by reviewing the details of the issues and iterating over the generated reports, | ||
593 | and following what happens in other Linux distributions and in the greater open source community. | ||
594 | |||
595 | You will find some more details in the | ||
596 | ":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`" | ||
597 | section 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 | ||
429 | The ``debian`` class renames output packages so that they follow the | 604 | The :ref:`ref-classes-debian` class renames output packages so that they follow the |
430 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and | 605 | Debian 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 |
432 | name and version as part of the package name. | 607 | name 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 | ||
444 | The ``deploy`` class handles deploying files to the | 619 | The :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 |
446 | function of this class is to allow the deploy step to be accelerated by | 621 | function of this class is to allow the deploy step to be accelerated by |
447 | shared state. Recipes that inherit this class should define their own | 622 | shared state. Recipes that inherit this class should define their own |
@@ -450,113 +625,109 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to | |||
450 | add the task at the appropriate place, which is usually after | 625 | add 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 |
453 | staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. | 628 | staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`. |
629 | |||
630 | .. _ref-classes-devicetree: | ||
631 | |||
632 | ``devicetree`` | ||
633 | ============== | ||
634 | |||
635 | The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles | ||
636 | device tree source files that are not in the kernel tree. | ||
637 | |||
638 | The compilation of out-of-tree device tree sources is the same as the kernel | ||
639 | in-tree device tree compilation process. This includes the ability to include | ||
640 | sources from the kernel such as SoC ``dtsi`` files as well as C header files, | ||
641 | such as ``gpio.h``. | ||
642 | |||
643 | The :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 | |||
650 | This class deploys the generated device tree binaries into | ||
651 | ``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}/devicetree/``. This is similar to | ||
652 | what the :ref:`ref-classes-kernel-devicetree` class does, with the added | ||
653 | ``devicetree`` subdirectory to avoid name clashes. Additionally, the device | ||
654 | trees are populated into the sysroot for access via the sysroot from within | ||
655 | other recipes. | ||
656 | |||
657 | By default, all device tree sources located in :term:`DT_FILES_PATH` directory | ||
658 | are compiled. To select only particular sources, set :term:`DT_FILES` to | ||
659 | a space-separated list of files (relative to :term:`DT_FILES_PATH`). For | ||
660 | convenience, both ``.dts`` and ``.dtb`` extensions can be used. | ||
661 | |||
662 | An extra padding is appended to non-overlay device trees binaries. This | ||
663 | can typically be used as extra space for adding extra properties at boot time. | ||
664 | The padding size can be modified by setting :term:`DT_PADDING_SIZE` | ||
665 | to the desired size, in bytes. | ||
666 | |||
667 | See :oe_git:`devicetree.bbclass sources | ||
668 | </openembedded-core/tree/meta/classes-recipe/devicetree.bbclass>` | ||
669 | for further variables controlling this class. | ||
670 | |||
671 | Here is an excerpt of an example ``recipes-kernel/linux/devicetree-acme.bb`` | ||
672 | recipe 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 | ||
460 | The ``devshell`` class adds the ``do_devshell`` task. Distribution | 683 | The :ref:`ref-classes-devshell` class adds the :ref:`ref-tasks-devshell` task. Distribution |
461 | policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`" | 684 | policy dictates whether to include this class. See the ":ref:`dev-manual/development-shell:using a development shell`" |
462 | section in the Yocto Project Development Tasks Manual for more | 685 | section in the Yocto Project Development Tasks Manual for more |
463 | information about using ``devshell``. | 686 | information 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 | ||
470 | The ``devupstream`` class uses | 693 | The :ref:`ref-classes-devupstream` class uses |
471 | :term:`BBCLASSEXTEND` to add a variant of the | 694 | :term:`BBCLASSEXTEND` to add a variant of the |
472 | recipe that fetches from an alternative URI (e.g. Git) instead of a | 695 | recipe that fetches from an alternative URI (e.g. Git) instead of a |
473 | tarball. Following is an example: | 696 | tarball. 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 | ||
480 | Adding the above statements to your recipe creates a variant that has | 702 | Adding 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". |
482 | Consequently, you need to select the variant of the recipe to use it. | 704 | Consequently, you need to select the variant of the recipe to use it. |
483 | Any development-specific adjustments can be done by using the | 705 | Any 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 | ||
492 | The class | 713 | The class |
493 | currently only supports creating a development variant of the target | 714 | currently only supports creating a development variant of the target |
494 | recipe, not ``native`` or ``nativesdk`` variants. | 715 | recipe, not :ref:`ref-classes-native` or :ref:`ref-classes-nativesdk` variants. |
495 | 716 | ||
496 | The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides | 717 | The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides |
497 | support for ``native`` and ``nativesdk`` variants. Consequently, this | 718 | support for :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk` variants. Consequently, this |
498 | functionality can be added in a future release. | 719 | functionality can be added in a future release. |
499 | 720 | ||
500 | Support for other version control systems such as Subversion is limited | 721 | Support for other version control systems such as Subversion is limited |
501 | due to BitBake's automatic fetch dependencies (e.g. | 722 | due 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 | |||
509 | The ``distutils*`` classes support recipes for Python version 2.x | ||
510 | extensions, which are simple. These recipes usually only need to point | ||
511 | to the source's archive and then inherit the proper class. Building is | ||
512 | split into two methods depending on which method the module authors | ||
513 | used. | ||
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 | |||
524 | The ``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 | |||
532 | The ``distutils3*`` classes support recipes for Python version 3.x | ||
533 | extensions, which are simple. These recipes usually only need to point | ||
534 | to the source's archive and then inherit the proper class. Building is | ||
535 | split into three methods depending on which method the module authors | ||
536 | used. | ||
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 | |||
548 | The ``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 | ||
551 | the 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 | ||
559 | The ``externalsrc`` class supports building software from source code | 730 | The :ref:`ref-classes-externalsrc` class supports building software from source code |
560 | that is external to the OpenEmbedded build system. Building software | 731 | that is external to the OpenEmbedded build system. Building software |
561 | from an external source tree means that the build system's normal fetch, | 732 | from an external source tree means that the build system's normal fetch, |
562 | unpack, and patch process is not used. | 733 | unpack, and patch process is not used. |
@@ -564,37 +735,34 @@ unpack, and patch process is not used. | |||
564 | By default, the OpenEmbedded build system uses the :term:`S` | 735 | By default, the OpenEmbedded build system uses the :term:`S` |
565 | and :term:`B` variables to locate unpacked recipe source code | 736 | and :term:`B` variables to locate unpacked recipe source code |
566 | and to build it, respectively. When your recipe inherits the | 737 | and 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 | 740 | ultimately define :term:`S` and :term:`B`. |
570 | ultimately define ``S`` and ``B``. | ||
571 | 741 | ||
572 | By default, this class expects the source code to support recipe builds | 742 | By default, this class expects the source code to support recipe builds |
573 | that use the :term:`B` variable to point to the directory in | 743 | that use the :term:`B` variable to point to the directory in |
574 | which the OpenEmbedded build system places the generated objects built | 744 | which the OpenEmbedded build system places the generated objects built |
575 | from the recipes. By default, the ``B`` directory is set to the | 745 | from the recipes. By default, the :term:`B` directory is set to the |
576 | following, which is separate from the source directory (``S``): | 746 | following, which is separate from the source directory (:term:`S`):: |
577 | :: | ||
578 | 747 | ||
579 | ${WORKDIR}/${BPN}/{PV}/ | 748 | ${WORKDIR}/${BPN}-{PV}/ |
580 | 749 | ||
581 | See these variables for more information: | 750 | See 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 | ||
585 | For more information on the ``externalsrc`` class, see the comments in | 754 | For 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`. |
587 | For information on how to use the | 756 | For 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`" | ||
590 | section in the Yocto Project Development Tasks Manual. | 758 | section 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 | ||
597 | The ``extrausers`` class allows additional user and group configuration | 765 | The :ref:`ref-classes-extrausers` class allows additional user and group configuration |
598 | to be applied at the image level. Inheriting this class either globally | 766 | to be applied at the image level. Inheriting this class either globally |
599 | or from an image recipe allows additional user and group operations to | 767 | or from an image recipe allows additional user and group operations to |
600 | be performed using the | 768 | be 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 | ||
613 | Here is an example that uses this class in an image recipe: | 779 | Here 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 | ||
626 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns | 791 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns |
627 | passwords: | 792 | passwords. First on host, create the (escaped) password hash:: |
628 | :: | 793 | |
794 | printf "%q" $(mkpasswd -m sha256crypt tester01) | ||
795 | |||
796 | The 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 | ||
636 | Finally, here is an example that sets the root password to "1876*18": | 805 | Finally, 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 | ||
649 | The ``features_check`` class allows individual recipes to check | 825 | The :ref:`ref-classes-features_check` class allows individual recipes to check |
650 | for required and conflicting | 826 | for required and conflicting :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` |
651 | :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`. | 827 | or :term:`COMBINED_FEATURES`. |
652 | 828 | ||
653 | This class provides support for the following variables: | 829 | This 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 | ||
675 | The ``fontcache`` class generates the proper post-install and | 851 | The :ref:`ref-classes-fontcache` class generates the proper post-install and |
676 | post-remove (postinst and postrm) scriptlets for font packages. These | 852 | post-remove (postinst and postrm) scriptlets for font packages. These |
677 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts | 853 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts |
678 | to the font information cache. Since the cache files are | 854 | to 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 | ||
691 | The ``fs-uuid`` class extracts UUID from | 867 | The :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 |
693 | by the time that this function gets called. The ``fs-uuid`` class only | 869 | by the time that this function gets called. The :ref:`ref-classes-fs-uuid` class only |
694 | works on ``ext`` file systems and depends on ``tune2fs``. | 870 | works 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 | ||
701 | The ``gconf`` class provides common functionality for recipes that need | 877 | The :ref:`ref-classes-gconf` class provides common functionality for recipes that need |
702 | to install GConf schemas. The schemas will be put into a separate | 878 | to install GConf schemas. The schemas will be put into a separate |
703 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created | 879 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created |
704 | automatically when this class is inherited. This package uses the | 880 | automatically 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 | ||
713 | The ``gettext`` class provides support for building software that uses | 889 | The :ref:`ref-classes-gettext` class provides support for building |
714 | the GNU ``gettext`` internationalization and localization system. All | 890 | software that uses the GNU ``gettext`` internationalization and localization |
715 | recipes building software that use ``gettext`` should inherit this | 891 | system. All recipes building software that use ``gettext`` should inherit this |
716 | class. | 892 | class. |
717 | 893 | ||
894 | .. _ref-classes-github-releases: | ||
895 | |||
896 | ``github-releases`` | ||
897 | =================== | ||
898 | |||
899 | For recipes that fetch release tarballs from github, the :ref:`ref-classes-github-releases` | ||
900 | class sets up a standard way for checking available upstream versions | ||
901 | (to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)). | ||
902 | |||
903 | To use it, add ":ref:`ref-classes-github-releases`" to the inherit line in the recipe, | ||
904 | and if the default value of :term:`GITHUB_BASE_URI` is not suitable, | ||
905 | then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}`` | ||
906 | in 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 | ||
723 | The ``gnomebase`` class is the base class for recipes that build | 913 | The :ref:`ref-classes-gnomebase` class is the base class for recipes that build |
724 | software from the GNOME stack. This class sets | 914 | software 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 |
726 | mirrors as well as extending :term:`FILES` with the typical | 916 | mirrors as well as extending :term:`FILES` with the typical |
727 | GNOME installation paths. | 917 | GNOME installation paths. |
728 | 918 | ||
919 | .. _ref-classes-go: | ||
920 | |||
921 | ``go`` | ||
922 | ====== | ||
923 | |||
924 | The :ref:`ref-classes-go` class supports building Go programs. The behavior of | ||
925 | this class is controlled by the mandatory :term:`GO_IMPORT` variable, and | ||
926 | by the optional :term:`GO_INSTALL` and :term:`GO_INSTALL_FILTEROUT` ones. | ||
927 | |||
928 | To 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>` | ||
930 | recipe as an example. | ||
931 | |||
932 | .. _ref-classes-go-mod: | ||
933 | |||
934 | ``go-mod`` | ||
935 | ========== | ||
936 | |||
937 | The :ref:`ref-classes-go-mod` class allows to use Go modules, and inherits the | ||
938 | :ref:`ref-classes-go` class. | ||
939 | |||
940 | See 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 | ||
734 | Provides support for recipes building software that supports GObject | 947 | Provides support for recipes building software that supports GObject |
735 | introspection. This functionality is only enabled if the | 948 | introspection. 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 | ||
752 | The ``grub-efi`` class provides ``grub-efi``-specific functions for | 966 | The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for |
753 | building bootable images. | 967 | building bootable images. |
754 | 968 | ||
755 | This class supports several variables: | 969 | This 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 | ||
784 | The ``gsettings`` class provides common functionality for recipes that | 998 | The :ref:`ref-classes-gsettings` class provides common functionality for recipes that |
785 | need to install GSettings (glib) schemas. The schemas are assumed to be | 999 | need to install GSettings (glib) schemas. The schemas are assumed to be |
786 | part of the main package. Appropriate post-install and post-remove | 1000 | part 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 | ||
795 | The ``gtk-doc`` class is a helper class to pull in the appropriate | 1009 | The :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 | ||
803 | The ``gtk-icon-cache`` class generates the proper post-install and | 1017 | The :ref:`ref-classes-gtk-icon-cache` class generates the proper post-install and |
804 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and | 1018 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and |
805 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add | 1019 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add |
806 | the fonts to GTK+'s icon cache. Since the cache files are | 1020 | the 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 | ||
816 | The ``gtk-immodules-cache`` class generates the proper post-install and | 1030 | The :ref:`ref-classes-gtk-immodules-cache` class generates the proper post-install and |
817 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ | 1031 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ |
818 | input method modules for virtual keyboards. These scriptlets call | 1032 | input 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 | ||
834 | The ``gzipnative`` class enables the use of different native versions of | 1048 | The :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 |
836 | build host. | 1050 | build host. |
837 | 1051 | ||
838 | .. _ref-classes-icecc: | 1052 | .. _ref-classes-icecc: |
839 | 1053 | ||
840 | ``icecc.bbclass`` | 1054 | ``icecc`` |
841 | ================= | 1055 | ========= |
842 | 1056 | ||
843 | The ``icecc`` class supports | 1057 | The :ref:`ref-classes-icecc` class supports |
844 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates | 1058 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates |
845 | taking compile jobs and distributing them among remote machines. | 1059 | taking 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 |
849 | configure or compile, the OpenEmbedded build system adds the directories | 1063 | configure or compile, the OpenEmbedded build system adds the directories |
850 | at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and | 1064 | at 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`` |
852 | compilers, respectively. | 1066 | compilers, respectively. |
853 | 1067 | ||
854 | For the cross compiler, the class creates a ``tar.gz`` file that | 1068 | For 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 | |||
856 | is the version of the cross-compiler used in the cross-development | 1070 | is the version of the cross-compiler used in the cross-development |
857 | toolchain, accordingly. | 1071 | toolchain, accordingly. |
858 | 1072 | ||
859 | The class handles all three different compile stages (i.e native | 1073 | The class handles all three different compile stages (i.e native, |
860 | ,cross-kernel and target) and creates the necessary environment | 1074 | cross-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 |
862 | supports SDK generation. | 1076 | supports SDK generation. |
863 | 1077 | ||
@@ -867,67 +1081,66 @@ using ``which``. If :term:`ICECC_ENV_EXEC` is set | |||
867 | in your ``local.conf`` file, the variable should point to the | 1081 | in 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 |
869 | a user-provided script, the build system uses the default script | 1083 | a user-provided script, the build system uses the default script |
870 | provided by the recipe ``icecc-create-env-native.bb``. | 1084 | provided 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 | ||
877 | If you do not want the Icecream distributed compile support to apply to | 1092 | If you do not want the Icecream distributed compile support to apply to |
878 | specific recipes or classes, you can effectively "blacklist" them by | 1093 | specific recipes or classes, you can ask them to be ignored by Icecream |
879 | listing the recipes and classes using the | 1094 | by 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, |
882 | respectively, in your ``local.conf`` file. Doing so causes the | 1097 | respectively, in your ``local.conf`` file. Doing so causes the |
883 | OpenEmbedded build system to handle these compilations locally. | 1098 | OpenEmbedded build system to handle these compilations locally. |
884 | 1099 | ||
885 | Additionally, you can list recipes using the | 1100 | Additionally, you can list recipes using the |
886 | :term:`ICECC_USER_PACKAGE_WL` variable in | 1101 | :term:`ICECC_RECIPE_ENABLE` variable in |
887 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes | 1102 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes |
888 | using an empty :term:`PARALLEL_MAKE` variable. | 1103 | using an empty :term:`PARALLEL_MAKE` variable. |
889 | 1104 | ||
890 | Inheriting the ``icecc`` class changes all sstate signatures. | 1105 | Inheriting the :ref:`ref-classes-icecc` class changes all sstate signatures. |
891 | Consequently, if a development team has a dedicated build system that | 1106 | Consequently, if a development team has a dedicated build system that |
892 | populates :term:`SSTATE_MIRRORS` and they want to | 1107 | populates :term:`SSTATE_MIRRORS` and they want to |
893 | reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build | 1108 | reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build |
894 | system need to either inherit the ``icecc`` class or nobody should. | 1109 | system need to either inherit the :ref:`ref-classes-icecc` class or nobody should. |
895 | 1110 | ||
896 | At the distribution level, you can inherit the ``icecc`` class to be | 1111 | At the distribution level, you can inherit the :ref:`ref-classes-icecc` class to be |
897 | sure that all builders start with the same sstate signatures. After | 1112 | sure that all builders start with the same sstate signatures. After |
898 | inheriting the class, you can then disable the feature by setting the | 1113 | inheriting 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 | ||
905 | This practice | 1119 | This practice |
906 | makes sure everyone is using the same signatures but also requires | 1120 | makes sure everyone is using the same signatures but also requires |
907 | individuals that do want to use Icecream to enable the feature | 1121 | individuals that do want to use Icecream to enable the feature |
908 | individually as follows in your ``local.conf`` file: | 1122 | individually 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 | ||
918 | The ``image`` class helps support creating images in different formats. | 1131 | The :ref:`ref-classes-image` class helps support creating images in different formats. |
919 | First, the root filesystem is created from packages using one of the | 1132 | First, 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 |
921 | then one or more image files are created. | 1134 | then 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 | ||
929 | For information on customizing images, see the | 1142 | For information on customizing images, see the |
930 | ":ref:`dev-manual/common-tasks:customizing images`" section | 1143 | ":ref:`dev-manual/customizing-images:customizing images`" section |
931 | in the Yocto Project Development Tasks Manual. For information on how | 1144 | in the Yocto Project Development Tasks Manual. For information on how |
932 | images are created, see the | 1145 | images 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 | |||
1154 | The :ref:`ref-classes-image-buildinfo` class writes a plain text file containing | ||
1155 | build information to the target filesystem at ``${sysconfdir}/buildinfo`` | ||
1156 | by default (as specified by :term:`IMAGE_BUILDINFO_FILE`). | ||
1157 | This can be useful for manually determining the origin of any given | ||
1158 | image. 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 | ||
941 | The ``image-buildinfo`` class writes information to the target | 1164 | #. `Layer Revisions`: the revisions of all of the layers used in the |
942 | filesystem on ``/etc/build``. | 1165 | build. |
1166 | |||
1167 | Additionally, when building an SDK it will write the same contents | ||
1168 | to ``/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 | ||
949 | The ``image_types`` class defines all of the standard image output types | 1176 | The :ref:`ref-classes-image_types` class defines all of the standard image output types |
950 | that you can enable through the | 1177 | that you can enable through the |
951 | :term:`IMAGE_FSTYPES` variable. You can use this | 1178 | :term:`IMAGE_FSTYPES` variable. You can use this |
952 | class as a reference on how to add support for custom image output | 1179 | class as a reference on how to add support for custom image output |
953 | types. | 1180 | types. |
954 | 1181 | ||
955 | By default, the :ref:`image <ref-classes-image>` class automatically | 1182 | By default, the :ref:`ref-classes-image` class automatically |
956 | enables the ``image_types`` class. The ``image`` class uses the | 1183 | enables 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 | ||
969 | The ``image_types`` class also handles conversion and compression of images. | 1199 | The :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 | ||
982 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live | 1212 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live |
983 | images contain syslinux for legacy booting, as well as the bootloader | 1213 | images contain syslinux for legacy booting, as well as the bootloader |
@@ -987,43 +1217,12 @@ specified by :term:`EFI_PROVIDER` if | |||
987 | Normally, you do not use this class directly. Instead, you add "live" to | 1217 | Normally, 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 | |||
995 | The ``image-mklibs`` class enables the use of the ``mklibs`` utility | ||
996 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
997 | the size of libraries contained in the image. | ||
998 | |||
999 | By default, the class is enabled in the ``local.conf.template`` using | ||
1000 | the :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 | |||
1010 | The ``image-prelink`` class enables the use of the ``prelink`` utility | ||
1011 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
1012 | the dynamic linking of shared libraries to reduce executable startup | ||
1013 | time. | ||
1014 | |||
1015 | By default, the class is enabled in the ``local.conf.template`` using | ||
1016 | the :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 | ||
1026 | The ``insane`` class adds a step to the package generation process so | 1225 | The :ref:`ref-classes-insane` class adds a step to the package generation process so |
1027 | that output quality assurance checks are generated by the OpenEmbedded | 1226 | that output quality assurance checks are generated by the OpenEmbedded |
1028 | build system. A range of checks are performed that check the build's | 1227 | build system. A range of checks are performed that check the build's |
1029 | output for common problems that show up during runtime. Distribution | 1228 | output for common problems that show up during runtime. Distribution |
@@ -1043,17 +1242,16 @@ configuration). However, to skip one or more checks in recipes, you | |||
1043 | should use :term:`INSANE_SKIP`. For example, to skip | 1242 | should use :term:`INSANE_SKIP`. For example, to skip |
1044 | the check for symbolic link ``.so`` files in the main package of a | 1243 | the check for symbolic link ``.so`` files in the main package of a |
1045 | recipe, add the following to the recipe. You need to realize that the | 1244 | recipe, add the following to the recipe. You need to realize that the |
1046 | package name override, in this example ``${PN}``, must be used: | 1245 | package 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 | ||
1051 | Please keep in mind that the QA checks | 1249 | Please keep in mind that the QA checks |
1052 | exist in order to detect real or potential problems in the packaged | 1250 | are meant to detect real or potential problems in the packaged |
1053 | output. So exercise caution when disabling these checks. | 1251 | output. So exercise caution when disabling these checks. |
1054 | 1252 | ||
1055 | The following list shows the tests you can list with the ``WARN_QA`` and | 1253 | The 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,162 +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 | |||
1323 | The ``insserv`` class uses the ``insserv`` utility to update the order | ||
1324 | of symbolic links in ``/etc/rc?.d/`` within an image based on | ||
1325 | dependencies specified by LSB headers in the ``init.d`` scripts | ||
1326 | themselves. | ||
1327 | |||
1328 | .. _ref-classes-kernel: | 1579 | .. _ref-classes-kernel: |
1329 | 1580 | ||
1330 | ``kernel.bbclass`` | 1581 | ``kernel`` |
1331 | ================== | 1582 | ========== |
1332 | 1583 | ||
1333 | The ``kernel`` class handles building Linux kernels. The class contains | 1584 | The :ref:`ref-classes-kernel` class handles building Linux kernels. The class contains |
1334 | code to build all kernel trees. All needed headers are staged into the | 1585 | code 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 |
1336 | using the :ref:`module <ref-classes-module>` class. | 1587 | using the :ref:`ref-classes-module` class. |
1337 | 1588 | ||
1338 | This means that each built kernel module is packaged separately and | 1589 | If a file named ``defconfig`` is listed in :term:`SRC_URI`, then by default |
1339 | inter-module dependencies are created by parsing the ``modinfo`` output. | 1590 | :ref:`ref-tasks-configure` copies it as ``.config`` in the build directory, |
1340 | If all modules are required, then installing the ``kernel-modules`` | 1591 | so it is automatically used as the kernel configuration for the build. This |
1341 | package installs all packages with modules and various other kernel | 1592 | copy is not performed in case ``.config`` already exists there: this allows |
1342 | packages such as ``kernel-vmlinux``. | 1593 | recipes to produce a configuration by other means in |
1343 | 1594 | ``do_configure:prepend``. | |
1344 | The ``kernel`` class contains logic that allows you to embed an initial | 1595 | |
1345 | RAM filesystem (initramfs) image when you build the kernel image. For | 1596 | Each built kernel module is packaged separately and inter-module |
1346 | information on how to build an initramfs, see the | 1597 | dependencies 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 | 1598 | are required, then installing the ``kernel-modules`` package installs all |
1599 | packages with modules and various other kernel packages such as | ||
1600 | ``kernel-vmlinux``. | ||
1601 | |||
1602 | The :ref:`ref-classes-kernel` class contains logic that allows you to embed an initial | ||
1603 | RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For | ||
1604 | information on how to build an :term:`Initramfs`, see the | ||
1605 | ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section in | ||
1348 | the Yocto Project Development Tasks Manual. | 1606 | the Yocto Project Development Tasks Manual. |
1349 | 1607 | ||
1350 | Various other classes are used by the ``kernel`` and ``module`` classes | 1608 | Various other classes are used by the :ref:`ref-classes-kernel` and :ref:`ref-classes-module` classes |
1351 | internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`, | 1609 | internally 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 | ||
1360 | The ``kernel-arch`` class sets the ``ARCH`` environment variable for | 1617 | The :ref:`ref-classes-kernel-arch` class sets the ``ARCH`` environment variable for |
1361 | Linux kernel compilation (including modules). | 1618 | Linux 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 | ||
1368 | The ``kernel-devicetree`` class, which is inherited by the | 1625 | The :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. |
1370 | generation. | 1627 | |
1628 | Its 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 | ||
1377 | The ``kernel-fitimage`` class provides support to pack a kernel image, | 1641 | The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image, |
1378 | device trees and a RAM disk into a single FIT image. In theory, a FIT | 1642 | device trees, a U-boot script, an :term:`Initramfs` bundle and a RAM disk |
1379 | image can support any number of kernels, RAM disks and device trees. | 1643 | into a single FIT image. In theory, a FIT image can support any number |
1380 | However, ``kernel-fitimage`` currently only supports | 1644 | of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees. |
1381 | limited usescases: just one kernel image, an optional RAM disk, and | 1645 | However, :ref:`ref-classes-kernel-fitimage` currently only supports |
1382 | any number of device trees. | 1646 | limited usecases: just one kernel image, an optional U-boot script, |
1647 | an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of | ||
1648 | device trees. | ||
1383 | 1649 | ||
1384 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` | 1650 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` |
1385 | is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` | 1651 | is set to include ":ref:`ref-classes-kernel-fitimage`" and one of :term:`KERNEL_IMAGETYPE`, |
1386 | is set to "fitImage". | 1652 | :term:`KERNEL_ALT_IMAGETYPE` or :term:`KERNEL_IMAGETYPES` to include "fitImage". |
1387 | 1653 | ||
1388 | The options for the device tree compiler passed to ``mkimage -D`` | 1654 | The options for the device tree compiler passed to ``mkimage -D`` |
1389 | when creating the FIT image are specified using the | 1655 | when creating the FIT image are specified using the |
1390 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. | 1656 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. |
1391 | 1657 | ||
1392 | Only a single kernel can be added to the FIT image created by | 1658 | Only a single kernel can be added to the FIT image created by |
1393 | ``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 |
1394 | address where the kernel image is to be loaded by U-Boot is | 1660 | address where the kernel image is to be loaded by U-Boot is |
1395 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by | 1661 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by |
1396 | :term:`UBOOT_ENTRYPOINT`. | 1662 | :term:`UBOOT_ENTRYPOINT`. Setting :term:`FIT_ADDRESS_CELLS` to "2" |
1663 | is necessary if such addresses are 64 bit ones. | ||
1397 | 1664 | ||
1398 | Multiple device trees can be added to the FIT image created by | 1665 | Multiple device trees can be added to the FIT image created by |
1399 | ``kernel-fitimage`` and the device tree is optional. | 1666 | :ref:`ref-classes-kernel-fitimage` and the device tree is optional. |
1400 | The address where the device tree is to be loaded by U-Boot is | 1667 | The address where the device tree is to be loaded by U-Boot is |
1401 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays | 1668 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays |
1402 | and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. | 1669 | and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. |
1403 | 1670 | ||
1404 | Only a single RAM disk can be added to the FIT image created by | 1671 | Only a single RAM disk can be added to the FIT image created by |
1405 | ``kernel-fitimage`` and the RAM disk in FIT is optional. | 1672 | :ref:`ref-classes-kernel-fitimage` and the RAM disk in FIT is optional. |
1406 | The address where the RAM disk image is to be loaded by U-Boot | 1673 | The address where the RAM disk image is to be loaded by U-Boot |
1407 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by | 1674 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by |
1408 | :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 |
1409 | :term:`INITRAMFS_IMAGE` is specified. | 1676 | :term:`INITRAMFS_IMAGE` is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE` |
1410 | 1677 | is not set to 1. | |
1411 | The FIT image generated by ``kernel-fitimage`` class is signed when the | 1678 | |
1679 | Only a single :term:`Initramfs` bundle can be added to the FIT image created by | ||
1680 | :ref:`ref-classes-kernel-fitimage` and the :term:`Initramfs` bundle in FIT is optional. | ||
1681 | In case of :term:`Initramfs`, the kernel is configured to be bundled with the root filesystem | ||
1682 | in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin). | ||
1683 | When the kernel is copied to RAM and executed, it unpacks the :term:`Initramfs` root filesystem. | ||
1684 | The :term:`Initramfs` bundle can be enabled when :term:`INITRAMFS_IMAGE` | ||
1685 | is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1. | ||
1686 | The address where the :term:`Initramfs` bundle is to be loaded by U-boot is specified | ||
1687 | by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`. | ||
1688 | |||
1689 | Only a single U-boot boot script can be added to the FIT image created by | ||
1690 | :ref:`ref-classes-kernel-fitimage` and the boot script is optional. | ||
1691 | The boot script is specified in the ITS file as a text file containing | ||
1692 | U-boot commands. When using a boot script the user should configure the | ||
1693 | U-boot :ref:`ref-tasks-install` task to copy the script to sysroot. | ||
1694 | So the script can be included in the FIT image by the :ref:`ref-classes-kernel-fitimage` | ||
1695 | class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to | ||
1696 | load the boot script from the FIT image and execute it. | ||
1697 | |||
1698 | The FIT image generated by the :ref:`ref-classes-kernel-fitimage` class is signed when the | ||
1412 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, | 1699 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, |
1413 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set | 1700 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set |
1414 | appropriately. The default values used for :term:`FIT_HASH_ALG` and | 1701 | appropriately. The default values used for :term:`FIT_HASH_ALG` and |
1415 | :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and | 1702 | :term:`FIT_SIGN_ALG` in :ref:`ref-classes-kernel-fitimage` are "sha256" and |
1416 | "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 |
1417 | the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and | 1704 | the :ref:`ref-classes-kernel-fitimage` class when both :term:`FIT_GENERATE_KEYS` and |
1418 | :term:`UBOOT_SIGN_ENABLE` are set to "1". | 1705 | :term:`UBOOT_SIGN_ENABLE` are set to "1". |
1419 | 1706 | ||
1420 | 1707 | ||
1421 | .. _ref-classes-kernel-grub: | 1708 | .. _ref-classes-kernel-grub: |
1422 | 1709 | ||
1423 | ``kernel-grub.bbclass`` | 1710 | ``kernel-grub`` |
1424 | ======================= | 1711 | =============== |
1425 | 1712 | ||
1426 | The ``kernel-grub`` class updates the boot area and the boot menu with | 1713 | The :ref:`ref-classes-kernel-grub` class updates the boot area and the boot menu with |
1427 | the kernel as the priority boot mechanism while installing a RPM to | 1714 | the kernel as the priority boot mechanism while installing a RPM to |
1428 | update the kernel on a deployed target. | 1715 | update the kernel on a deployed target. |
1429 | 1716 | ||
1430 | .. _ref-classes-kernel-module-split: | 1717 | .. _ref-classes-kernel-module-split: |
1431 | 1718 | ||
1432 | ``kernel-module-split.bbclass`` | 1719 | ``kernel-module-split`` |
1433 | =============================== | 1720 | ======================= |
1434 | 1721 | ||
1435 | The ``kernel-module-split`` class provides common functionality for | 1722 | The :ref:`ref-classes-kernel-module-split` class provides common functionality for |
1436 | splitting Linux kernel modules into separate packages. | 1723 | splitting Linux kernel modules into separate packages. |
1437 | 1724 | ||
1438 | .. _ref-classes-kernel-uboot: | 1725 | .. _ref-classes-kernel-uboot: |
1439 | 1726 | ||
1440 | ``kernel-uboot.bbclass`` | 1727 | ``kernel-uboot`` |
1441 | ======================== | 1728 | ================ |
1442 | 1729 | ||
1443 | The ``kernel-uboot`` class provides support for building from | 1730 | The :ref:`ref-classes-kernel-uboot` class provides support for building from |
1444 | vmlinux-style kernel sources. | 1731 | vmlinux-style kernel sources. |
1445 | 1732 | ||
1446 | .. _ref-classes-kernel-uimage: | 1733 | .. _ref-classes-kernel-uimage: |
1447 | 1734 | ||
1448 | ``kernel-uimage.bbclass`` | 1735 | ``kernel-uimage`` |
1449 | ========================= | 1736 | ================= |
1450 | 1737 | ||
1451 | The ``kernel-uimage`` class provides support to pack uImage. | 1738 | The :ref:`ref-classes-kernel-uimage` class provides support to pack uImage. |
1452 | 1739 | ||
1453 | .. _ref-classes-kernel-yocto: | 1740 | .. _ref-classes-kernel-yocto: |
1454 | 1741 | ||
1455 | ``kernel-yocto.bbclass`` | 1742 | ``kernel-yocto`` |
1456 | ======================== | 1743 | ================ |
1457 | 1744 | ||
1458 | The ``kernel-yocto`` class provides common functionality for building | 1745 | The :ref:`ref-classes-kernel-yocto` class provides common functionality for building |
1459 | from linux-yocto style kernel source repositories. | 1746 | from linux-yocto style kernel source repositories. |
1460 | 1747 | ||
1461 | .. _ref-classes-kernelsrc: | 1748 | .. _ref-classes-kernelsrc: |
1462 | 1749 | ||
1463 | ``kernelsrc.bbclass`` | 1750 | ``kernelsrc`` |
1464 | ===================== | 1751 | ============= |
1465 | 1752 | ||
1466 | The ``kernelsrc`` class sets the Linux kernel source and version. | 1753 | The :ref:`ref-classes-kernelsrc` class sets the Linux kernel source and version. |
1467 | 1754 | ||
1468 | .. _ref-classes-lib_package: | 1755 | .. _ref-classes-lib_package: |
1469 | 1756 | ||
1470 | ``lib_package.bbclass`` | 1757 | ``lib_package`` |
1471 | ======================= | 1758 | =============== |
1472 | 1759 | ||
1473 | The ``lib_package`` class supports recipes that build libraries and | 1760 | The :ref:`ref-classes-lib_package` class supports recipes that build libraries and |
1474 | produce executable binaries, where those binaries should not be | 1761 | produce executable binaries, where those binaries should not be |
1475 | installed by default along with the library. Instead, the binaries are | 1762 | installed by default along with the library. Instead, the binaries are |
1476 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to | 1763 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to |
@@ -1478,40 +1765,40 @@ make their installation optional. | |||
1478 | 1765 | ||
1479 | .. _ref-classes-libc*: | 1766 | .. _ref-classes-libc*: |
1480 | 1767 | ||
1481 | ``libc*.bbclass`` | 1768 | ``libc*`` |
1482 | ================= | 1769 | ========= |
1483 | 1770 | ||
1484 | The ``libc*`` classes support recipes that build packages with ``libc``: | 1771 | The :ref:`ref-classes-libc*` classes support recipes that build packages with ``libc``: |
1485 | 1772 | ||
1486 | - 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 |
1487 | ``libc``. | 1774 | ``libc``. |
1488 | 1775 | ||
1489 | - The ``libc-package`` class supports packaging up ``glibc`` and | 1776 | - The :ref:`libc-package <ref-classes-libc*>` class supports packaging up ``glibc`` and |
1490 | ``eglibc``. | 1777 | ``eglibc``. |
1491 | 1778 | ||
1492 | .. _ref-classes-license: | 1779 | .. _ref-classes-license: |
1493 | 1780 | ||
1494 | ``license.bbclass`` | 1781 | ``license`` |
1495 | =================== | 1782 | =========== |
1496 | 1783 | ||
1497 | The ``license`` class provides license manifest creation and license | 1784 | The :ref:`ref-classes-license` class provides license manifest creation and license |
1498 | exclusion. This class is enabled by default using the default value for | 1785 | exclusion. This class is enabled by default using the default value for |
1499 | the :term:`INHERIT_DISTRO` variable. | 1786 | the :term:`INHERIT_DISTRO` variable. |
1500 | 1787 | ||
1501 | .. _ref-classes-linux-kernel-base: | 1788 | .. _ref-classes-linux-kernel-base: |
1502 | 1789 | ||
1503 | ``linux-kernel-base.bbclass`` | 1790 | ``linux-kernel-base`` |
1504 | ============================= | 1791 | ===================== |
1505 | 1792 | ||
1506 | The ``linux-kernel-base`` class provides common functionality for | 1793 | The :ref:`ref-classes-linux-kernel-base` class provides common functionality for |
1507 | recipes that build out of the Linux kernel source tree. These builds | 1794 | recipes that build out of the Linux kernel source tree. These builds |
1508 | goes beyond the kernel itself. For example, the Perf recipe also | 1795 | goes beyond the kernel itself. For example, the Perf recipe also |
1509 | inherits this class. | 1796 | inherits this class. |
1510 | 1797 | ||
1511 | .. _ref-classes-linuxloader: | 1798 | .. _ref-classes-linuxloader: |
1512 | 1799 | ||
1513 | ``linuxloader.bbclass`` | 1800 | ``linuxloader`` |
1514 | ======================= | 1801 | =============== |
1515 | 1802 | ||
1516 | Provides the function ``linuxloader()``, which gives the value of the | 1803 | Provides the function ``linuxloader()``, which gives the value of the |
1517 | dynamic loader/linker provided on the platform. This value is used by a | 1804 | dynamic loader/linker provided on the platform. This value is used by a |
@@ -1519,80 +1806,101 @@ number of other classes. | |||
1519 | 1806 | ||
1520 | .. _ref-classes-logging: | 1807 | .. _ref-classes-logging: |
1521 | 1808 | ||
1522 | ``logging.bbclass`` | 1809 | ``logging`` |
1523 | =================== | 1810 | =========== |
1524 | 1811 | ||
1525 | The ``logging`` class provides the standard shell functions used to log | 1812 | The :ref:`ref-classes-logging` class provides the standard shell functions used to log |
1526 | messages for various BitBake severity levels (i.e. ``bbplain``, | 1813 | messages for various BitBake severity levels (i.e. ``bbplain``, |
1527 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). | 1814 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). |
1528 | 1815 | ||
1529 | This class is enabled by default since it is inherited by the ``base`` | 1816 | This class is enabled by default since it is inherited by the :ref:`ref-classes-base` |
1530 | class. | 1817 | class. |
1531 | 1818 | ||
1532 | .. _ref-classes-meta: | 1819 | .. _ref-classes-meson: |
1533 | 1820 | ||
1534 | ``meta.bbclass`` | 1821 | ``meson`` |
1535 | ================ | 1822 | ========= |
1536 | 1823 | ||
1537 | The ``meta`` class is inherited by recipes that do not build any output | 1824 | The :ref:`ref-classes-meson` class allows to create recipes that build software |
1538 | packages themselves, but act as a "meta" target for building other | 1825 | using the `Meson <https://mesonbuild.com/>`__ build system. You can use the |
1539 | recipes. | 1826 | :term:`MESON_BUILDTYPE`, :term:`MESON_TARGET` and :term:`EXTRA_OEMESON` |
1827 | variables to specify additional configuration options to be passed using the | ||
1828 | ``meson`` command line. | ||
1540 | 1829 | ||
1541 | .. _ref-classes-metadata_scm: | 1830 | .. _ref-classes-metadata_scm: |
1542 | 1831 | ||
1543 | ``metadata_scm.bbclass`` | 1832 | ``metadata_scm`` |
1544 | ======================== | 1833 | ================ |
1545 | 1834 | ||
1546 | The ``metadata_scm`` class provides functionality for querying the | 1835 | The :ref:`ref-classes-metadata_scm` class provides functionality for querying the |
1547 | branch and revision of a Source Code Manager (SCM) repository. | 1836 | branch and revision of a Source Code Manager (SCM) repository. |
1548 | 1837 | ||
1549 | The :ref:`base <ref-classes-base>` class uses this class to print the | 1838 | The :ref:`ref-classes-base` class uses this class to print the revisions of |
1550 | revisions of each layer before starting every build. The | 1839 | each layer before starting every build. The :ref:`ref-classes-metadata_scm` |
1551 | ``metadata_scm`` class is enabled by default because it is inherited by | 1840 | class is enabled by default because it is inherited by the |
1552 | the ``base`` class. | 1841 | :ref:`ref-classes-base` class. |
1553 | 1842 | ||
1554 | .. _ref-classes-migrate_localcount: | 1843 | .. _ref-classes-migrate_localcount: |
1555 | 1844 | ||
1556 | ``migrate_localcount.bbclass`` | 1845 | ``migrate_localcount`` |
1557 | ============================== | 1846 | ====================== |
1558 | 1847 | ||
1559 | The ``migrate_localcount`` class verifies a recipe's localcount data and | 1848 | The :ref:`ref-classes-migrate_localcount` class verifies a recipe's localcount data and |
1560 | increments it appropriately. | 1849 | increments it appropriately. |
1561 | 1850 | ||
1562 | .. _ref-classes-mime: | 1851 | .. _ref-classes-mime: |
1563 | 1852 | ||
1564 | ``mime.bbclass`` | 1853 | ``mime`` |
1565 | ================ | 1854 | ======== |
1566 | 1855 | ||
1567 | The ``mime`` class generates the proper post-install and post-remove | 1856 | The :ref:`ref-classes-mime` class generates the proper post-install and post-remove |
1568 | (postinst/postrm) scriptlets for packages that install MIME type files. | 1857 | (postinst/postrm) scriptlets for packages that install MIME type files. |
1569 | These scriptlets call ``update-mime-database`` to add the MIME types to | 1858 | These scriptlets call ``update-mime-database`` to add the MIME types to |
1570 | the shared database. | 1859 | the shared database. |
1571 | 1860 | ||
1861 | .. _ref-classes-mime-xdg: | ||
1862 | |||
1863 | ``mime-xdg`` | ||
1864 | ============ | ||
1865 | |||
1866 | The :ref:`ref-classes-mime-xdg` class generates the proper | ||
1867 | post-install and post-remove (postinst/postrm) scriptlets for packages | ||
1868 | that install ``.desktop`` files containing ``MimeType`` entries. | ||
1869 | These scriptlets call ``update-desktop-database`` to add the MIME types | ||
1870 | to the database of MIME types handled by desktop files. | ||
1871 | |||
1872 | Thanks to this class, when users open a file through a file browser | ||
1873 | on recently created images, they don't have to choose the application | ||
1874 | to open the file from the pool of all known applications, even the ones | ||
1875 | that cannot open the selected file. | ||
1876 | |||
1877 | If you have recipes installing their ``.desktop`` files as absolute | ||
1878 | symbolic links, the detection of such files cannot be done by the current | ||
1879 | implementation of this class. In this case, you have to add the corresponding | ||
1880 | package names to the :term:`MIME_XDG_PACKAGES` variable. | ||
1881 | |||
1572 | .. _ref-classes-mirrors: | 1882 | .. _ref-classes-mirrors: |
1573 | 1883 | ||
1574 | ``mirrors.bbclass`` | 1884 | ``mirrors`` |
1575 | =================== | 1885 | =========== |
1576 | 1886 | ||
1577 | The ``mirrors`` class sets up some standard | 1887 | The :ref:`ref-classes-mirrors` class sets up some standard |
1578 | :term:`MIRRORS` entries for source code mirrors. These | 1888 | :term:`MIRRORS` entries for source code mirrors. These |
1579 | mirrors provide a fall-back path in case the upstream source specified | 1889 | mirrors provide a fall-back path in case the upstream source specified |
1580 | in :term:`SRC_URI` within recipes is unavailable. | 1890 | in :term:`SRC_URI` within recipes is unavailable. |
1581 | 1891 | ||
1582 | This class is enabled by default since it is inherited by the | 1892 | This class is enabled by default since it is inherited by the |
1583 | :ref:`base <ref-classes-base>` class. | 1893 | :ref:`ref-classes-base` class. |
1584 | 1894 | ||
1585 | .. _ref-classes-module: | 1895 | .. _ref-classes-module: |
1586 | 1896 | ||
1587 | ``module.bbclass`` | 1897 | ``module`` |
1588 | ================== | 1898 | ========== |
1589 | 1899 | ||
1590 | The ``module`` class provides support for building out-of-tree Linux | 1900 | The :ref:`ref-classes-module` class provides support for building out-of-tree Linux |
1591 | kernel modules. The class inherits the | 1901 | kernel modules. The class inherits the :ref:`ref-classes-module-base` and |
1592 | :ref:`module-base <ref-classes-module-base>` and | 1902 | :ref:`ref-classes-kernel-module-split` classes, and implements the |
1593 | :ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, | 1903 | :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The class provides |
1594 | and implements the :ref:`ref-tasks-compile` and | ||
1595 | :ref:`ref-tasks-install` tasks. The class provides | ||
1596 | everything needed to build and package a kernel module. | 1904 | everything needed to build and package a kernel module. |
1597 | 1905 | ||
1598 | For general information on out-of-tree Linux kernel modules, see the | 1906 | For general information on out-of-tree Linux kernel modules, see the |
@@ -1601,50 +1909,49 @@ section in the Yocto Project Linux Kernel Development Manual. | |||
1601 | 1909 | ||
1602 | .. _ref-classes-module-base: | 1910 | .. _ref-classes-module-base: |
1603 | 1911 | ||
1604 | ``module-base.bbclass`` | 1912 | ``module-base`` |
1605 | ======================= | 1913 | =============== |
1606 | 1914 | ||
1607 | The ``module-base`` class provides the base functionality for building | 1915 | The :ref:`ref-classes-module-base` class provides the base functionality for |
1608 | Linux kernel modules. Typically, a recipe that builds software that | 1916 | building Linux kernel modules. Typically, a recipe that builds software that |
1609 | includes one or more kernel modules and has its own means of building | 1917 | includes one or more kernel modules and has its own means of building the module |
1610 | the module inherits this class as opposed to inheriting the | 1918 | inherits this class as opposed to inheriting the :ref:`ref-classes-module` |
1611 | :ref:`module <ref-classes-module>` class. | 1919 | class. |
1612 | 1920 | ||
1613 | .. _ref-classes-multilib*: | 1921 | .. _ref-classes-multilib*: |
1614 | 1922 | ||
1615 | ``multilib*.bbclass`` | 1923 | ``multilib*`` |
1616 | ===================== | 1924 | ============= |
1617 | 1925 | ||
1618 | The ``multilib*`` classes provide support for building libraries with | 1926 | The :ref:`ref-classes-multilib*` classes provide support for building libraries with |
1619 | different target optimizations or target architectures and installing | 1927 | different target optimizations or target architectures and installing |
1620 | them side-by-side in the same image. | 1928 | them side-by-side in the same image. |
1621 | 1929 | ||
1622 | For more information on using the Multilib feature, see the | 1930 | For more information on using the Multilib feature, see the |
1623 | ":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`" |
1624 | section in the Yocto Project Development Tasks Manual. | 1932 | section in the Yocto Project Development Tasks Manual. |
1625 | 1933 | ||
1626 | .. _ref-classes-native: | 1934 | .. _ref-classes-native: |
1627 | 1935 | ||
1628 | ``native.bbclass`` | 1936 | ``native`` |
1629 | ================== | 1937 | ========== |
1630 | 1938 | ||
1631 | The ``native`` class provides common functionality for recipes that | 1939 | The :ref:`ref-classes-native` class provides common functionality for recipes that |
1632 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler | 1940 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler |
1633 | or other tools from the build host). | 1941 | or other tools from the build host). |
1634 | 1942 | ||
1635 | You can create a recipe that builds tools that run natively on the host | 1943 | You can create a recipe that builds tools that run natively on the host |
1636 | a couple different ways: | 1944 | a couple different ways: |
1637 | 1945 | ||
1638 | - Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` | 1946 | - Create a ``myrecipe-native.bb`` recipe that inherits the :ref:`ref-classes-native` |
1639 | 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 |
1640 | in the recipe after all other inherit statements so that the | 1948 | in the recipe after all other inherit statements so that the |
1641 | ``native`` class is inherited last. | 1949 | :ref:`ref-classes-native` class is inherited last. |
1642 | 1950 | ||
1643 | .. note:: | 1951 | .. note:: |
1644 | 1952 | ||
1645 | 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 |
1646 | naming convention: | 1954 | naming convention:: |
1647 | :: | ||
1648 | 1955 | ||
1649 | myrecipe-native.bb | 1956 | myrecipe-native.bb |
1650 | 1957 | ||
@@ -1652,79 +1959,76 @@ a couple different ways: | |||
1652 | Not using this naming convention can lead to subtle problems | 1959 | Not using this naming convention can lead to subtle problems |
1653 | caused by existing code that depends on that naming convention. | 1960 | caused by existing code that depends on that naming convention. |
1654 | 1961 | ||
1655 | - Create or modify a target recipe that contains the following: | 1962 | - Create or modify a target recipe that contains the following:: |
1656 | :: | ||
1657 | 1963 | ||
1658 | BBCLASSEXTEND = "native" | 1964 | BBCLASSEXTEND = "native" |
1659 | 1965 | ||
1660 | Inside the | 1966 | Inside the |
1661 | recipe, use ``_class-native`` and ``_class-target`` overrides to | 1967 | recipe, use ``:class-native`` and ``:class-target`` overrides to |
1662 | specify any functionality specific to the respective native or target | 1968 | specify any functionality specific to the respective native or target |
1663 | case. | 1969 | case. |
1664 | 1970 | ||
1665 | Although applied differently, the ``native`` class is used with both | 1971 | Although applied differently, the :ref:`ref-classes-native` class is used with both |
1666 | methods. The advantage of the second method is that you do not need to | 1972 | methods. The advantage of the second method is that you do not need to |
1667 | have two separate recipes (assuming you need both) for native and | 1973 | have two separate recipes (assuming you need both) for native and |
1668 | target. All common parts of the recipe are automatically shared. | 1974 | target. All common parts of the recipe are automatically shared. |
1669 | 1975 | ||
1670 | .. _ref-classes-nativesdk: | 1976 | .. _ref-classes-nativesdk: |
1671 | 1977 | ||
1672 | ``nativesdk.bbclass`` | 1978 | ``nativesdk`` |
1673 | ===================== | 1979 | ============= |
1674 | 1980 | ||
1675 | The ``nativesdk`` class provides common functionality for recipes that | 1981 | The :ref:`ref-classes-nativesdk` class provides common functionality for recipes that |
1676 | wish to build tools to run as part of an SDK (i.e. tools that run on | 1982 | wish to build tools to run as part of an SDK (i.e. tools that run on |
1677 | :term:`SDKMACHINE`). | 1983 | :term:`SDKMACHINE`). |
1678 | 1984 | ||
1679 | You can create a recipe that builds tools that run on the SDK machine a | 1985 | You can create a recipe that builds tools that run on the SDK machine a |
1680 | couple different ways: | 1986 | couple different ways: |
1681 | 1987 | ||
1682 | - Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the | 1988 | - Create a ``nativesdk-myrecipe.bb`` recipe that inherits the |
1683 | ``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 |
1684 | inherit statement in the recipe after all other inherit statements so | 1990 | inherit statement in the recipe after all other inherit statements so |
1685 | that the ``nativesdk`` class is inherited last. | 1991 | that the :ref:`ref-classes-nativesdk` class is inherited last. |
1686 | 1992 | ||
1687 | - 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:: |
1688 | :: | ||
1689 | 1994 | ||
1690 | BBCLASSEXTEND = "nativesdk" | 1995 | BBCLASSEXTEND = "nativesdk" |
1691 | 1996 | ||
1692 | Inside the | 1997 | Inside the |
1693 | recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to | 1998 | recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to |
1694 | specify any functionality specific to the respective SDK machine or | 1999 | specify any functionality specific to the respective SDK machine or |
1695 | target case. | 2000 | target case. |
1696 | 2001 | ||
1697 | .. note:: | 2002 | .. note:: |
1698 | 2003 | ||
1699 | When creating a recipe, you must follow this naming convention: | 2004 | When creating a recipe, you must follow this naming convention:: |
1700 | :: | ||
1701 | 2005 | ||
1702 | nativesdk-myrecipe.bb | 2006 | nativesdk-myrecipe.bb |
1703 | 2007 | ||
1704 | 2008 | ||
1705 | 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 |
1706 | depends on the naming convention. | 2010 | depends on the naming convention. |
1707 | 2011 | ||
1708 | Although applied differently, the ``nativesdk`` class is used with both | 2012 | Although applied differently, the :ref:`ref-classes-nativesdk` class is used with both |
1709 | methods. The advantage of the second method is that you do not need to | 2013 | methods. The advantage of the second method is that you do not need to |
1710 | have two separate recipes (assuming you need both) for the SDK machine | 2014 | have two separate recipes (assuming you need both) for the SDK machine |
1711 | and the target. All common parts of the recipe are automatically shared. | 2015 | and the target. All common parts of the recipe are automatically shared. |
1712 | 2016 | ||
1713 | .. _ref-classes-nopackages: | 2017 | .. _ref-classes-nopackages: |
1714 | 2018 | ||
1715 | ``nopackages.bbclass`` | 2019 | ``nopackages`` |
1716 | ====================== | 2020 | ============== |
1717 | 2021 | ||
1718 | Disables packaging tasks for those recipes and classes where packaging | 2022 | Disables packaging tasks for those recipes and classes where packaging |
1719 | is not needed. | 2023 | is not needed. |
1720 | 2024 | ||
1721 | .. _ref-classes-npm: | 2025 | .. _ref-classes-npm: |
1722 | 2026 | ||
1723 | ``npm.bbclass`` | 2027 | ``npm`` |
1724 | =============== | 2028 | ======= |
1725 | 2029 | ||
1726 | Provides support for building Node.js software fetched using the `node | 2030 | Provides support for building Node.js software fetched using the |
1727 | package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | 2031 | :wikipedia:`node package manager (NPM) <Npm_(software)>`. |
1728 | 2032 | ||
1729 | .. note:: | 2033 | .. note:: |
1730 | 2034 | ||
@@ -1732,77 +2036,175 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | |||
1732 | fetcher to have dependencies fetched and packaged automatically. | 2036 | fetcher to have dependencies fetched and packaged automatically. |
1733 | 2037 | ||
1734 | For information on how to create NPM packages, see the | 2038 | For information on how to create NPM packages, see the |
1735 | ":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`" | 2039 | ":ref:`dev-manual/packages:creating node package manager (npm) packages`" |
1736 | section in the Yocto Project Development Tasks Manual. | 2040 | section in the Yocto Project Development Tasks Manual. |
1737 | 2041 | ||
1738 | .. _ref-classes-oelint: | 2042 | .. _ref-classes-oelint: |
1739 | 2043 | ||
1740 | ``oelint.bbclass`` | 2044 | ``oelint`` |
1741 | ================== | 2045 | ========== |
1742 | 2046 | ||
1743 | The ``oelint`` class is an obsolete lint checking tool that exists in | 2047 | The :ref:`ref-classes-oelint` class is an obsolete lint checking tool available in |
1744 | ``meta/classes`` in the :term:`Source Directory`. | 2048 | ``meta/classes`` in the :term:`Source Directory`. |
1745 | 2049 | ||
1746 | A number of classes exist that could be generally useful in OE-Core but | 2050 | There are some classes that could be generally useful in OE-Core but |
1747 | are never actually used within OE-Core itself. The ``oelint`` class is | 2051 | are never actually used within OE-Core itself. The :ref:`ref-classes-oelint` class is |
1748 | one such example. However, being aware of this class can reduce the | 2052 | one such example. However, being aware of this class can reduce the |
1749 | proliferation of different versions of similar classes across multiple | 2053 | proliferation of different versions of similar classes across multiple |
1750 | layers. | 2054 | layers. |
1751 | 2055 | ||
2056 | .. _ref-classes-overlayfs: | ||
2057 | |||
2058 | ``overlayfs`` | ||
2059 | ============= | ||
2060 | |||
2061 | It's often desired in Embedded System design to have a read-only root filesystem. | ||
2062 | But a lot of different applications might want to have read-write access to | ||
2063 | some parts of a filesystem. It can be especially useful when your update mechanism | ||
2064 | overwrites the whole root filesystem, but you may want your application data to be preserved | ||
2065 | between updates. The :ref:`ref-classes-overlayfs` class provides a way | ||
2066 | to achieve that by means of ``overlayfs`` and at the same time keeping the base | ||
2067 | root filesystem read-only. | ||
2068 | |||
2069 | To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper | ||
2070 | layer in your machine configuration. The underlying file system can be anything that | ||
2071 | is 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 | |||
2082 | The 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 | |||
2085 | Then 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 | |||
2089 | To support several mount points you can use a different variable flag. Assuming we | ||
2090 | want to have a writable location on the file system, but do not need that the data | ||
2091 | survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` | ||
2092 | file system. | ||
2093 | |||
2094 | In your machine configuration:: | ||
2095 | |||
2096 | OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" | ||
2097 | |||
2098 | and then in your recipe:: | ||
2099 | |||
2100 | OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" | ||
2101 | |||
2102 | On a practical note, your application recipe might require multiple | ||
2103 | overlays to be mounted before running to avoid writing to the underlying | ||
2104 | file system (which can be forbidden in case of read-only file system) | ||
2105 | To achieve that :ref:`ref-classes-overlayfs` provides a ``systemd`` | ||
2106 | helper 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 | ||
2109 | to 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 | |||
2125 | In order to have the ``/etc`` directory in overlayfs a special handling at early | ||
2126 | boot 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 | ||
2128 | requires ``/etc`` to be mounted. | ||
2129 | |||
2130 | Example 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 | |||
2138 | Your machine configuration should define at least the device, mount point, and file system type | ||
2139 | you 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 | |||
2145 | To control more mount options you should consider setting mount options | ||
2146 | (``defaults`` is used by default):: | ||
2147 | |||
2148 | OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync" | ||
2149 | |||
2150 | The 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 | |||
1752 | .. _ref-classes-own-mirrors: | 2165 | .. _ref-classes-own-mirrors: |
1753 | 2166 | ||
1754 | ``own-mirrors.bbclass`` | 2167 | ``own-mirrors`` |
1755 | ======================= | 2168 | =============== |
1756 | 2169 | ||
1757 | The ``own-mirrors`` class makes it easier to set up your own | 2170 | The :ref:`ref-classes-own-mirrors` class makes it easier to set up your own |
1758 | :term:`PREMIRRORS` from which to first fetch source | 2171 | :term:`PREMIRRORS` from which to first fetch source |
1759 | before attempting to fetch it from the upstream specified in | 2172 | before attempting to fetch it from the upstream specified in |
1760 | :term:`SRC_URI` within each recipe. | 2173 | :term:`SRC_URI` within each recipe. |
1761 | 2174 | ||
1762 | To use this class, inherit it globally and specify | 2175 | To use this class, inherit it globally and specify |
1763 | :term:`SOURCE_MIRROR_URL`. Here is an example: | 2176 | :term:`SOURCE_MIRROR_URL`. Here is an example:: |
1764 | :: | ||
1765 | 2177 | ||
1766 | INHERIT += "own-mirrors" | 2178 | INHERIT += "own-mirrors" |
1767 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" | 2179 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" |
1768 | 2180 | ||
1769 | You can specify only a single URL | 2181 | You can specify only a single URL |
1770 | in ``SOURCE_MIRROR_URL``. | 2182 | in :term:`SOURCE_MIRROR_URL`. |
1771 | 2183 | ||
1772 | .. _ref-classes-package: | 2184 | .. _ref-classes-package: |
1773 | 2185 | ||
1774 | ``package.bbclass`` | 2186 | ``package`` |
1775 | =================== | 2187 | =========== |
1776 | 2188 | ||
1777 | The ``package`` class supports generating packages from a build's | 2189 | The :ref:`ref-classes-package` class supports generating packages from a build's |
1778 | output. The core generic functionality is in ``package.bbclass``. The | 2190 | output. The core generic functionality is in ``package.bbclass``. The |
1779 | code specific to particular package types resides in these | 2191 | code specific to particular package types resides in these |
1780 | package-specific classes: | 2192 | package-specific classes: :ref:`ref-classes-package_deb`, |
1781 | :ref:`package_deb <ref-classes-package_deb>`, | 2193 | :ref:`ref-classes-package_rpm`, :ref:`ref-classes-package_ipk`. |
1782 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
1783 | :ref:`package_ipk <ref-classes-package_ipk>`, and | ||
1784 | :ref:`package_tar <ref-classes-package_tar>`. | ||
1785 | |||
1786 | .. note:: | ||
1787 | |||
1788 | The | ||
1789 | package_tar | ||
1790 | class is broken and not supported. It is recommended that you do not | ||
1791 | use this class. | ||
1792 | 2194 | ||
1793 | You can control the list of resulting package formats by using the | 2195 | You can control the list of resulting package formats by using the |
1794 | ``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` | 2196 | :term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` |
1795 | configuration file, which is located in the :term:`Build Directory`. | 2197 | configuration file, which is located in the :term:`Build Directory`. |
1796 | When defining the variable, you can | 2198 | When defining the variable, you can specify one or more package types. |
1797 | specify one or more package types. Since images are generated from | 2199 | Since images are generated from packages, a packaging class is needed |
1798 | packages, a packaging class is needed to enable image generation. The | 2200 | to enable image generation. The first class listed in this variable is |
1799 | first class listed in this variable is used for image generation. | 2201 | used for image generation. |
1800 | 2202 | ||
1801 | If you take the optional step to set up a repository (package feed) on | 2203 | If you take the optional step to set up a repository (package feed) on |
1802 | the development host that can be used by DNF, you can install packages | 2204 | the development host that can be used by DNF, you can install packages |
1803 | from the feed while you are running the image on the target (i.e. | 2205 | from the feed while you are running the image on the target (i.e. |
1804 | runtime installation of packages). For more information, see the | 2206 | runtime installation of packages). For more information, see the |
1805 | ":ref:`dev-manual/common-tasks:using runtime package management`" | 2207 | ":ref:`dev-manual/packages:using runtime package management`" |
1806 | section in the Yocto Project Development Tasks Manual. | 2208 | section in the Yocto Project Development Tasks Manual. |
1807 | 2209 | ||
1808 | The package-specific class you choose can affect build-time performance | 2210 | The package-specific class you choose can affect build-time performance |
@@ -1812,8 +2214,8 @@ the same or similar package. This comparison takes into account a | |||
1812 | complete build of the package with all dependencies previously built. | 2214 | complete build of the package with all dependencies previously built. |
1813 | The reason for this discrepancy is because the RPM package manager | 2215 | The reason for this discrepancy is because the RPM package manager |
1814 | creates and processes more :term:`Metadata` than the IPK package | 2216 | creates and processes more :term:`Metadata` than the IPK package |
1815 | manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to | 2217 | manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to |
1816 | "package_ipk" if you are building smaller systems. | 2218 | ":ref:`ref-classes-package_ipk`" if you are building smaller systems. |
1817 | 2219 | ||
1818 | Before making your package manager decision, however, you should | 2220 | Before making your package manager decision, however, you should |
1819 | consider some further things about using RPM: | 2221 | consider some further things about using RPM: |
@@ -1838,120 +2240,182 @@ at these two Yocto Project mailing list links: | |||
1838 | 2240 | ||
1839 | .. _ref-classes-package_deb: | 2241 | .. _ref-classes-package_deb: |
1840 | 2242 | ||
1841 | ``package_deb.bbclass`` | 2243 | ``package_deb`` |
1842 | ======================= | 2244 | =============== |
1843 | 2245 | ||
1844 | The ``package_deb`` class provides support for creating packages that | 2246 | The :ref:`ref-classes-package_deb` class provides support for creating packages that |
1845 | use the Debian (i.e. ``.deb``) file format. The class ensures the | 2247 | use the Debian (i.e. ``.deb``) file format. The class ensures the |
1846 | packages are written out in a ``.deb`` file format to the | 2248 | packages are written out in a ``.deb`` file format to the |
1847 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. | 2249 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. |
1848 | 2250 | ||
1849 | This class inherits the :ref:`package <ref-classes-package>` class and | 2251 | This class inherits the :ref:`ref-classes-package` class and |
1850 | is enabled through the :term:`PACKAGE_CLASSES` | 2252 | is enabled through the :term:`PACKAGE_CLASSES` |
1851 | variable in the ``local.conf`` file. | 2253 | variable in the ``local.conf`` file. |
1852 | 2254 | ||
1853 | .. _ref-classes-package_ipk: | 2255 | .. _ref-classes-package_ipk: |
1854 | 2256 | ||
1855 | ``package_ipk.bbclass`` | 2257 | ``package_ipk`` |
1856 | ======================= | 2258 | =============== |
1857 | 2259 | ||
1858 | The ``package_ipk`` class provides support for creating packages that | 2260 | The :ref:`ref-classes-package_ipk` class provides support for creating packages that |
1859 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages | 2261 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages |
1860 | are written out in a ``.ipk`` file format to the | 2262 | are written out in a ``.ipk`` file format to the |
1861 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. | 2263 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. |
1862 | 2264 | ||
1863 | This class inherits the :ref:`package <ref-classes-package>` class and | 2265 | This class inherits the :ref:`ref-classes-package` class and |
1864 | is enabled through the :term:`PACKAGE_CLASSES` | 2266 | is enabled through the :term:`PACKAGE_CLASSES` |
1865 | variable in the ``local.conf`` file. | 2267 | variable in the ``local.conf`` file. |
1866 | 2268 | ||
1867 | .. _ref-classes-package_rpm: | 2269 | .. _ref-classes-package_rpm: |
1868 | 2270 | ||
1869 | ``package_rpm.bbclass`` | 2271 | ``package_rpm`` |
1870 | ======================= | 2272 | =============== |
1871 | 2273 | ||
1872 | The ``package_rpm`` class provides support for creating packages that | 2274 | The :ref:`ref-classes-package_rpm` class provides support for creating packages that |
1873 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages | 2275 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages |
1874 | are written out in a ``.rpm`` file format to the | 2276 | are written out in a ``.rpm`` file format to the |
1875 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. | 2277 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. |
1876 | 2278 | ||
1877 | This class inherits the :ref:`package <ref-classes-package>` class and | 2279 | This class inherits the :ref:`ref-classes-package` class and |
1878 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1879 | variable in the ``local.conf`` file. | ||
1880 | |||
1881 | .. _ref-classes-package_tar: | ||
1882 | |||
1883 | ``package_tar.bbclass`` | ||
1884 | ======================= | ||
1885 | |||
1886 | The ``package_tar`` class provides support for creating tarballs. The | ||
1887 | class ensures the packages are written out in a tarball format to the | ||
1888 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. | ||
1889 | |||
1890 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1891 | is enabled through the :term:`PACKAGE_CLASSES` | 2280 | is enabled through the :term:`PACKAGE_CLASSES` |
1892 | variable in the ``local.conf`` file. | 2281 | variable in the ``local.conf`` file. |
1893 | 2282 | ||
1894 | .. note:: | ||
1895 | |||
1896 | You cannot specify the ``package_tar`` class first using the | ||
1897 | ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` | ||
1898 | file formats for your image or SDK. | ||
1899 | |||
1900 | .. _ref-classes-packagedata: | 2283 | .. _ref-classes-packagedata: |
1901 | 2284 | ||
1902 | ``packagedata.bbclass`` | 2285 | ``packagedata`` |
1903 | ======================= | 2286 | =============== |
1904 | 2287 | ||
1905 | The ``packagedata`` class provides common functionality for reading | 2288 | The :ref:`ref-classes-packagedata` class provides common functionality for reading |
1906 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These | 2289 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These |
1907 | files contain information about each output package produced by the | 2290 | files contain information about each output package produced by the |
1908 | OpenEmbedded build system. | 2291 | OpenEmbedded build system. |
1909 | 2292 | ||
1910 | This class is enabled by default because it is inherited by the | 2293 | This class is enabled by default because it is inherited by the |
1911 | :ref:`package <ref-classes-package>` class. | 2294 | :ref:`ref-classes-package` class. |
1912 | 2295 | ||
1913 | .. _ref-classes-packagegroup: | 2296 | .. _ref-classes-packagegroup: |
1914 | 2297 | ||
1915 | ``packagegroup.bbclass`` | 2298 | ``packagegroup`` |
1916 | ======================== | 2299 | ================ |
1917 | 2300 | ||
1918 | The ``packagegroup`` class sets default values appropriate for package | 2301 | The :ref:`ref-classes-packagegroup` class sets default values appropriate for package |
1919 | group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and | 2302 | group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and |
1920 | so forth). It is highly recommended that all package group recipes | 2303 | so forth). It is highly recommended that all package group recipes |
1921 | inherit this class. | 2304 | inherit this class. |
1922 | 2305 | ||
1923 | For information on how to use this class, see the | 2306 | For information on how to use this class, see the |
1924 | ":ref:`dev-manual/common-tasks:customizing images using custom package groups`" | 2307 | ":ref:`dev-manual/customizing-images:customizing images using custom package groups`" |
1925 | section in the Yocto Project Development Tasks Manual. | 2308 | section in the Yocto Project Development Tasks Manual. |
1926 | 2309 | ||
1927 | Previously, this class was called the ``task`` class. | 2310 | Previously, this class was called the ``task`` class. |
1928 | 2311 | ||
1929 | .. _ref-classes-patch: | 2312 | .. _ref-classes-patch: |
1930 | 2313 | ||
1931 | ``patch.bbclass`` | 2314 | ``patch`` |
1932 | ================= | 2315 | ========= |
1933 | 2316 | ||
1934 | The ``patch`` class provides all functionality for applying patches | 2317 | The :ref:`ref-classes-patch` class provides all functionality for applying patches |
1935 | during the :ref:`ref-tasks-patch` task. | 2318 | during the :ref:`ref-tasks-patch` task. |
1936 | 2319 | ||
1937 | This class is enabled by default because it is inherited by the | 2320 | This class is enabled by default because it is inherited by the |
1938 | :ref:`base <ref-classes-base>` class. | 2321 | :ref:`ref-classes-base` class. |
1939 | 2322 | ||
1940 | .. _ref-classes-perlnative: | 2323 | .. _ref-classes-perlnative: |
1941 | 2324 | ||
1942 | ``perlnative.bbclass`` | 2325 | ``perlnative`` |
1943 | ====================== | 2326 | ============== |
1944 | 2327 | ||
1945 | When inherited by a recipe, the ``perlnative`` class supports using the | 2328 | When inherited by a recipe, the :ref:`ref-classes-perlnative` class supports using the |
1946 | native version of Perl built by the build system rather than using the | 2329 | native version of Perl built by the build system rather than using the |
1947 | version provided by the build host. | 2330 | version provided by the build host. |
1948 | 2331 | ||
2332 | .. _ref-classes-pypi: | ||
2333 | |||
2334 | ``pypi`` | ||
2335 | ======== | ||
2336 | |||
2337 | The :ref:`ref-classes-pypi` class sets variables appropriately for recipes that build | ||
2338 | Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index. | ||
2339 | By default it determines the PyPI package name based upon :term:`BPN` | ||
2340 | (stripping the "python-" or "python3-" prefix off if present), however in | ||
2341 | some cases you may need to set it manually in the recipe by setting | ||
2342 | :term:`PYPI_PACKAGE`. | ||
2343 | |||
2344 | Variables 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` | ||
2346 | and :term:`CVE_PRODUCT`. | ||
2347 | |||
2348 | .. _ref-classes-python_flit_core: | ||
2349 | |||
2350 | ``python_flit_core`` | ||
2351 | ==================== | ||
2352 | |||
2353 | The :ref:`ref-classes-python_flit_core` class enables building Python modules which declare | ||
2354 | the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant | ||
2355 | ``flit_core.buildapi`` ``build-backend`` in the ``[build-system]`` | ||
2356 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). | ||
2357 | |||
2358 | Python modules built with ``flit_core.buildapi`` are pure Python (no | ||
2359 | ``C`` or ``Rust`` extensions). | ||
2360 | |||
2361 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2362 | |||
2363 | .. _ref-classes-python_pep517: | ||
2364 | |||
2365 | ``python_pep517`` | ||
2366 | ================= | ||
2367 | |||
2368 | The :ref:`ref-classes-python_pep517` class builds and installs a Python ``wheel`` binary | ||
2369 | archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__). | ||
2370 | |||
2371 | Recipes wouldn't inherit this directly, instead typically another class will | ||
2372 | inherit this and add the relevant native dependencies. | ||
2373 | |||
2374 | Examples 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 | |||
2383 | The :ref:`ref-classes-python_poetry_core` class enables building Python modules which use the | ||
2384 | `Poetry Core <https://python-poetry.org>`__ build system. | ||
2385 | |||
2386 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2387 | |||
2388 | .. _ref-classes-python_pyo3: | ||
2389 | |||
2390 | ``python_pyo3`` | ||
2391 | =============== | ||
2392 | |||
2393 | The :ref:`ref-classes-python_pyo3` class helps make sure that Python extensions | ||
2394 | written in Rust and built with `PyO3 <https://pyo3.rs/>`__, properly set up the | ||
2395 | environment for cross compilation. | ||
2396 | |||
2397 | This class is internal to the :ref:`ref-classes-python-setuptools3_rust` class | ||
2398 | and is not meant to be used directly in recipes. | ||
2399 | |||
2400 | .. _ref-classes-python-setuptools3_rust: | ||
2401 | |||
2402 | ``python-setuptools3_rust`` | ||
2403 | =========================== | ||
2404 | |||
2405 | The :ref:`ref-classes-python-setuptools3_rust` class enables building Python | ||
2406 | extensions implemented in Rust with `PyO3 <https://pyo3.rs/>`__, which allows | ||
2407 | to compile and distribute Python extensions written in Rust as easily | ||
2408 | as if they were written in C. | ||
2409 | |||
2410 | This class inherits the :ref:`ref-classes-setuptools3` and | ||
2411 | :ref:`ref-classes-python_pyo3` classes. | ||
2412 | |||
1949 | .. _ref-classes-pixbufcache: | 2413 | .. _ref-classes-pixbufcache: |
1950 | 2414 | ||
1951 | ``pixbufcache.bbclass`` | 2415 | ``pixbufcache`` |
1952 | ======================= | 2416 | =============== |
1953 | 2417 | ||
1954 | The ``pixbufcache`` class generates the proper post-install and | 2418 | The :ref:`ref-classes-pixbufcache` class generates the proper post-install and |
1955 | post-remove (postinst/postrm) scriptlets for packages that install | 2419 | post-remove (postinst/postrm) scriptlets for packages that install |
1956 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets | 2420 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets |
1957 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. | 2421 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. |
@@ -1966,24 +2430,24 @@ containing the loaders. | |||
1966 | 2430 | ||
1967 | .. _ref-classes-pkgconfig: | 2431 | .. _ref-classes-pkgconfig: |
1968 | 2432 | ||
1969 | ``pkgconfig.bbclass`` | 2433 | ``pkgconfig`` |
1970 | ===================== | 2434 | ============= |
1971 | 2435 | ||
1972 | The ``pkgconfig`` class provides a standard way to get header and | 2436 | The :ref:`ref-classes-pkgconfig` class provides a standard way to get header and |
1973 | library information by using ``pkg-config``. This class aims to smooth | 2437 | library information by using ``pkg-config``. This class aims to smooth |
1974 | integration of ``pkg-config`` into libraries that use it. | 2438 | integration of ``pkg-config`` into libraries that use it. |
1975 | 2439 | ||
1976 | During staging, BitBake installs ``pkg-config`` data into the | 2440 | During staging, BitBake installs ``pkg-config`` data into the |
1977 | ``sysroots/`` directory. By making use of sysroot functionality within | 2441 | ``sysroots/`` directory. By making use of sysroot functionality within |
1978 | ``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 |
1979 | files. | 2443 | files. |
1980 | 2444 | ||
1981 | .. _ref-classes-populate-sdk: | 2445 | .. _ref-classes-populate-sdk: |
1982 | 2446 | ||
1983 | ``populate_sdk.bbclass`` | 2447 | ``populate_sdk`` |
1984 | ======================== | 2448 | ================ |
1985 | 2449 | ||
1986 | The ``populate_sdk`` class provides support for SDK-only recipes. For | 2450 | The :ref:`ref-classes-populate-sdk` class provides support for SDK-only recipes. For |
1987 | information on advantages gained when building a cross-development | 2451 | information on advantages gained when building a cross-development |
1988 | toolchain using the :ref:`ref-tasks-populate_sdk` | 2452 | toolchain using the :ref:`ref-tasks-populate_sdk` |
1989 | task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" | 2453 | task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
@@ -1992,40 +2456,39 @@ Software Development Kit (eSDK) manual. | |||
1992 | 2456 | ||
1993 | .. _ref-classes-populate-sdk-*: | 2457 | .. _ref-classes-populate-sdk-*: |
1994 | 2458 | ||
1995 | ``populate_sdk_*.bbclass`` | 2459 | ``populate_sdk_*`` |
1996 | ========================== | 2460 | ================== |
1997 | 2461 | ||
1998 | The ``populate_sdk_*`` classes support SDK creation and consist of the | 2462 | The :ref:`ref-classes-populate-sdk-*` classes support SDK creation and consist of the |
1999 | following classes: | 2463 | following classes: |
2000 | 2464 | ||
2001 | - ``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 |
2002 | all package managers (i.e. DEB, RPM, and opkg). | 2466 | all package managers (i.e. DEB, RPM, and opkg). |
2003 | 2467 | ||
2004 | - ``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 |
2005 | package manager. | 2469 | package manager. |
2006 | 2470 | ||
2007 | - ``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 |
2008 | package manager. | 2472 | package manager. |
2009 | 2473 | ||
2010 | - ``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 |
2011 | (IPK format) package manager. | 2475 | (IPK format) package manager. |
2012 | 2476 | ||
2013 | - ``populate_sdk_ext``: Supports extensible SDK creation under all | 2477 | - :ref:`populate_sdk_ext <ref-classes-populate-sdk-*>`: Supports extensible SDK creation under all |
2014 | package managers. | 2478 | package managers. |
2015 | 2479 | ||
2016 | The ``populate_sdk_base`` class inherits the appropriate | 2480 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class inherits the appropriate |
2017 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on | 2481 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on |
2018 | :term:`IMAGE_PKGTYPE`. | 2482 | :term:`IMAGE_PKGTYPE`. |
2019 | 2483 | ||
2020 | The base class ensures all source and destination directories are | 2484 | The base class ensures all source and destination directories are |
2021 | established and then populates the SDK. After populating the SDK, the | 2485 | established and then populates the SDK. After populating the SDK, the |
2022 | ``populate_sdk_base`` class constructs two sysroots: | 2486 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class constructs two sysroots: |
2023 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which | 2487 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which |
2024 | contains the cross-compiler and associated tooling, and the target, | 2488 | contains the cross-compiler and associated tooling, and the target, |
2025 | which contains a target root filesystem that is configured for the SDK | 2489 | which contains a target root filesystem that is configured for the SDK |
2026 | usage. These two images reside in :term:`SDK_OUTPUT`, | 2490 | usage. These two images reside in :term:`SDK_OUTPUT`, |
2027 | which consists of the following: | 2491 | which consists of the following:: |
2028 | :: | ||
2029 | 2492 | ||
2030 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs | 2493 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs |
2031 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs | 2494 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs |
@@ -2033,9 +2496,9 @@ which consists of the following: | |||
2033 | Finally, the base populate SDK class creates the toolchain environment | 2496 | Finally, the base populate SDK class creates the toolchain environment |
2034 | setup script, the tarball of the SDK, and the installer. | 2497 | setup script, the tarball of the SDK, and the installer. |
2035 | 2498 | ||
2036 | The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and | 2499 | The respective :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`, :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`, and |
2037 | ``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. |
2038 | These classes are inherited by and used with the ``populate_sdk_base`` | 2501 | These classes are inherited by and used with the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
2039 | class. | 2502 | class. |
2040 | 2503 | ||
2041 | For more information on the cross-development toolchain generation, see | 2504 | For more information on the cross-development toolchain generation, see |
@@ -2050,10 +2513,10 @@ Software Development Kit (eSDK) manual. | |||
2050 | 2513 | ||
2051 | .. _ref-classes-prexport: | 2514 | .. _ref-classes-prexport: |
2052 | 2515 | ||
2053 | ``prexport.bbclass`` | 2516 | ``prexport`` |
2054 | ==================== | 2517 | ============ |
2055 | 2518 | ||
2056 | The ``prexport`` class provides functionality for exporting | 2519 | The :ref:`ref-classes-prexport` class provides functionality for exporting |
2057 | :term:`PR` values. | 2520 | :term:`PR` values. |
2058 | 2521 | ||
2059 | .. note:: | 2522 | .. note:: |
@@ -2063,10 +2526,10 @@ The ``prexport`` class provides functionality for exporting | |||
2063 | 2526 | ||
2064 | .. _ref-classes-primport: | 2527 | .. _ref-classes-primport: |
2065 | 2528 | ||
2066 | ``primport.bbclass`` | 2529 | ``primport`` |
2067 | ==================== | 2530 | ============ |
2068 | 2531 | ||
2069 | The ``primport`` class provides functionality for importing | 2532 | The :ref:`ref-classes-primport` class provides functionality for importing |
2070 | :term:`PR` values. | 2533 | :term:`PR` values. |
2071 | 2534 | ||
2072 | .. note:: | 2535 | .. note:: |
@@ -2076,130 +2539,142 @@ The ``primport`` class provides functionality for importing | |||
2076 | 2539 | ||
2077 | .. _ref-classes-prserv: | 2540 | .. _ref-classes-prserv: |
2078 | 2541 | ||
2079 | ``prserv.bbclass`` | 2542 | ``prserv`` |
2080 | ================== | 2543 | ========== |
2081 | 2544 | ||
2082 | The ``prserv`` class provides functionality for using a :ref:`PR | 2545 | The :ref:`ref-classes-prserv` class provides functionality for using a :ref:`PR |
2083 | service <dev-manual/common-tasks:working with a pr service>` in order to | 2546 | service <dev-manual/packages:working with a pr service>` in order to |
2084 | automatically manage the incrementing of the :term:`PR` | 2547 | automatically manage the incrementing of the :term:`PR` |
2085 | variable for each recipe. | 2548 | variable for each recipe. |
2086 | 2549 | ||
2087 | This class is enabled by default because it is inherited by the | 2550 | This class is enabled by default because it is inherited by the |
2088 | :ref:`package <ref-classes-package>` class. However, the OpenEmbedded | 2551 | :ref:`ref-classes-package` class. However, the OpenEmbedded |
2089 | build system will not enable the functionality of this class unless | 2552 | build system will not enable the functionality of this class unless |
2090 | :term:`PRSERV_HOST` has been set. | 2553 | :term:`PRSERV_HOST` has been set. |
2091 | 2554 | ||
2092 | .. _ref-classes-ptest: | 2555 | .. _ref-classes-ptest: |
2093 | 2556 | ||
2094 | ``ptest.bbclass`` | 2557 | ``ptest`` |
2095 | ================= | 2558 | ========= |
2096 | 2559 | ||
2097 | The ``ptest`` class provides functionality for packaging and installing | 2560 | The :ref:`ref-classes-ptest` class provides functionality for packaging and installing |
2098 | runtime tests for recipes that build software that provides these tests. | 2561 | runtime tests for recipes that build software that provides these tests. |
2099 | 2562 | ||
2100 | This class is intended to be inherited by individual recipes. However, | 2563 | This class is intended to be inherited by individual recipes. However, |
2101 | the class' functionality is largely disabled unless "ptest" appears in | 2564 | the class' functionality is largely disabled unless "ptest" appears in |
2102 | :term:`DISTRO_FEATURES`. See the | 2565 | :term:`DISTRO_FEATURES`. See the |
2103 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | 2566 | ":ref:`dev-manual/packages:testing packages with ptest`" |
2104 | section in the Yocto Project Development Tasks Manual for more information | 2567 | section in the Yocto Project Development Tasks Manual for more information |
2105 | on ptest. | 2568 | on ptest. |
2106 | 2569 | ||
2570 | .. _ref-classes-ptest-cargo: | ||
2571 | |||
2572 | ``ptest-cargo`` | ||
2573 | =============== | ||
2574 | |||
2575 | The :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 | ||
2578 | test suites defined in the ``Cargo.toml`` file, into a dedicated | ||
2579 | ``-ptest`` package. | ||
2580 | |||
2107 | .. _ref-classes-ptest-gnome: | 2581 | .. _ref-classes-ptest-gnome: |
2108 | 2582 | ||
2109 | ``ptest-gnome.bbclass`` | 2583 | ``ptest-gnome`` |
2110 | ======================= | 2584 | =============== |
2111 | 2585 | ||
2112 | Enables package tests (ptests) specifically for GNOME packages, which | 2586 | Enables package tests (ptests) specifically for GNOME packages, which |
2113 | have tests intended to be executed with ``gnome-desktop-testing``. | 2587 | have tests intended to be executed with ``gnome-desktop-testing``. |
2114 | 2588 | ||
2115 | For information on setting up and running ptests, see the | 2589 | For information on setting up and running ptests, see the |
2116 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | 2590 | ":ref:`dev-manual/packages:testing packages with ptest`" |
2117 | section in the Yocto Project Development Tasks Manual. | 2591 | section in the Yocto Project Development Tasks Manual. |
2118 | 2592 | ||
2119 | .. _ref-classes-python-dir: | 2593 | .. _ref-classes-python3-dir: |
2120 | 2594 | ||
2121 | ``python-dir.bbclass`` | 2595 | ``python3-dir`` |
2122 | ====================== | 2596 | =============== |
2123 | 2597 | ||
2124 | The ``python-dir`` class provides the base version, location, and site | 2598 | The :ref:`ref-classes-python3-dir` class provides the base version, location, and site |
2125 | package location for Python. | 2599 | package location for Python 3. |
2126 | 2600 | ||
2127 | .. _ref-classes-python3native: | 2601 | .. _ref-classes-python3native: |
2128 | 2602 | ||
2129 | ``python3native.bbclass`` | 2603 | ``python3native`` |
2130 | ========================= | 2604 | ================= |
2131 | 2605 | ||
2132 | The ``python3native`` class supports using the native version of Python | 2606 | The :ref:`ref-classes-python3native` class supports using the native version of Python |
2133 | 3 built by the build system rather than support of the version provided | 2607 | 3 built by the build system rather than support of the version provided |
2134 | by the build host. | 2608 | by the build host. |
2135 | 2609 | ||
2136 | .. _ref-classes-pythonnative: | 2610 | .. _ref-classes-python3targetconfig: |
2137 | 2611 | ||
2138 | ``pythonnative.bbclass`` | 2612 | ``python3targetconfig`` |
2139 | ======================== | 2613 | ======================= |
2140 | 2614 | ||
2141 | When inherited by a recipe, the ``pythonnative`` class supports using | 2615 | The :ref:`ref-classes-python3targetconfig` class supports using the native version of Python |
2142 | the native version of Python built by the build system rather than using | 2616 | 3 built by the build system rather than support of the version provided |
2143 | the version provided by the build host. | 2617 | by the build host, except that the configuration for the target machine |
2618 | is accessible (such as correct installation directories). This also adds a | ||
2619 | dependency on target ``python3``, so should only be used where appropriate | ||
2620 | in order to avoid unnecessarily lengthening builds. | ||
2144 | 2621 | ||
2145 | .. _ref-classes-qemu: | 2622 | .. _ref-classes-qemu: |
2146 | 2623 | ||
2147 | ``qemu.bbclass`` | 2624 | ``qemu`` |
2148 | ================ | 2625 | ======== |
2149 | 2626 | ||
2150 | The ``qemu`` class provides functionality for recipes that either need | 2627 | The :ref:`ref-classes-qemu` class provides functionality for recipes that either need |
2151 | QEMU or test for the existence of QEMU. Typically, this class is used to | 2628 | QEMU or test for the existence of QEMU. Typically, this class is used to |
2152 | run programs for a target system on the build host using QEMU's | 2629 | run programs for a target system on the build host using QEMU's |
2153 | application emulation mode. | 2630 | application emulation mode. |
2154 | 2631 | ||
2155 | .. _ref-classes-recipe_sanity: | 2632 | .. _ref-classes-recipe_sanity: |
2156 | 2633 | ||
2157 | ``recipe_sanity.bbclass`` | 2634 | ``recipe_sanity`` |
2158 | ========================= | 2635 | ================= |
2159 | 2636 | ||
2160 | The ``recipe_sanity`` class checks for the presence of any host system | 2637 | The :ref:`ref-classes-recipe_sanity` class checks for the presence of any host system |
2161 | recipe prerequisites that might affect the build (e.g. variables that | 2638 | recipe prerequisites that might affect the build (e.g. variables that |
2162 | are set or software that is present). | 2639 | are set or software that is present). |
2163 | 2640 | ||
2164 | .. _ref-classes-relocatable: | 2641 | .. _ref-classes-relocatable: |
2165 | 2642 | ||
2166 | ``relocatable.bbclass`` | 2643 | ``relocatable`` |
2167 | ======================= | 2644 | =============== |
2168 | 2645 | ||
2169 | The ``relocatable`` class enables relocation of binaries when they are | 2646 | The :ref:`ref-classes-relocatable` class enables relocation of binaries when they are |
2170 | installed into the sysroot. | 2647 | installed into the sysroot. |
2171 | 2648 | ||
2172 | This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class | 2649 | This class makes use of the :ref:`ref-classes-chrpath` class and is used by |
2173 | and is used by both the :ref:`cross <ref-classes-cross>` and | 2650 | both the :ref:`ref-classes-cross` and :ref:`ref-classes-native` classes. |
2174 | :ref:`native <ref-classes-native>` classes. | ||
2175 | 2651 | ||
2176 | .. _ref-classes-remove-libtool: | 2652 | .. _ref-classes-remove-libtool: |
2177 | 2653 | ||
2178 | ``remove-libtool.bbclass`` | 2654 | ``remove-libtool`` |
2179 | ========================== | 2655 | ================== |
2180 | 2656 | ||
2181 | The ``remove-libtool`` class adds a post function to the | 2657 | The :ref:`ref-classes-remove-libtool` class adds a post function to the |
2182 | :ref:`ref-tasks-install` task to remove all ``.la`` files | 2658 | :ref:`ref-tasks-install` task to remove all ``.la`` files |
2183 | installed by ``libtool``. Removing these files results in them being | 2659 | installed by ``libtool``. Removing these files results in them being |
2184 | absent from both the sysroot and target packages. | 2660 | absent from both the sysroot and target packages. |
2185 | 2661 | ||
2186 | If a recipe needs the ``.la`` files to be installed, then the recipe can | 2662 | If a recipe needs the ``.la`` files to be installed, then the recipe can |
2187 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: | 2663 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:: |
2188 | :: | ||
2189 | 2664 | ||
2190 | REMOVE_LIBTOOL_LA = "0" | 2665 | REMOVE_LIBTOOL_LA = "0" |
2191 | 2666 | ||
2192 | .. note:: | 2667 | .. note:: |
2193 | 2668 | ||
2194 | The ``remove-libtool`` class is not enabled by default. | 2669 | The :ref:`ref-classes-remove-libtool` class is not enabled by default. |
2195 | 2670 | ||
2196 | .. _ref-classes-report-error: | 2671 | .. _ref-classes-report-error: |
2197 | 2672 | ||
2198 | ``report-error.bbclass`` | 2673 | ``report-error`` |
2199 | ======================== | 2674 | ================ |
2200 | 2675 | ||
2201 | The ``report-error`` class supports enabling the :ref:`error reporting | 2676 | The :ref:`ref-classes-report-error` class supports enabling the :ref:`error reporting |
2202 | tool <dev-manual/common-tasks:using the error reporting tool>`", | 2677 | tool <dev-manual/error-reporting-tool:using the error reporting tool>`", |
2203 | which allows you to submit build error information to a central database. | 2678 | which allows you to submit build error information to a central database. |
2204 | 2679 | ||
2205 | The class collects debug information for recipe, recipe version, task, | 2680 | The class collects debug information for recipe, recipe version, task, |
@@ -2210,10 +2685,10 @@ are created and stored in | |||
2210 | 2685 | ||
2211 | .. _ref-classes-rm-work: | 2686 | .. _ref-classes-rm-work: |
2212 | 2687 | ||
2213 | ``rm_work.bbclass`` | 2688 | ``rm_work`` |
2214 | =================== | 2689 | =========== |
2215 | 2690 | ||
2216 | The ``rm_work`` class supports deletion of temporary workspace, which | 2691 | The :ref:`ref-classes-rm-work` class supports deletion of temporary workspace, which |
2217 | can ease your hard drive demands during builds. | 2692 | can ease your hard drive demands during builds. |
2218 | 2693 | ||
2219 | The OpenEmbedded build system can use a substantial amount of disk space | 2694 | The OpenEmbedded build system can use a substantial amount of disk space |
@@ -2222,61 +2697,76 @@ under the ``${TMPDIR}/work`` directory for each recipe. Once the build | |||
2222 | system generates the packages for a recipe, the work files for that | 2697 | system generates the packages for a recipe, the work files for that |
2223 | recipe are no longer needed. However, by default, the build system | 2698 | recipe are no longer needed. However, by default, the build system |
2224 | preserves these files for inspection and possible debugging purposes. If | 2699 | preserves these files for inspection and possible debugging purposes. If |
2225 | you would rather have these files deleted to save disk space as the | 2700 | you would rather have these files deleted to save disk space as the build |
2226 | build progresses, you can enable ``rm_work`` by adding the following to | 2701 | progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to |
2227 | your ``local.conf`` file, which is found in the :term:`Build Directory`. | 2702 | your ``local.conf`` file, which is found in the :term:`Build Directory`:: |
2228 | :: | ||
2229 | 2703 | ||
2230 | INHERIT += "rm_work" | 2704 | INHERIT += "rm_work" |
2231 | 2705 | ||
2232 | If you are | 2706 | If you are modifying and building source code out of the work directory for a |
2233 | modifying and building source code out of the work directory for a | 2707 | recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your |
2234 | recipe, enabling ``rm_work`` will potentially result in your changes to | 2708 | changes to the source being lost. To exclude some recipes from having their work |
2235 | the source being lost. To exclude some recipes from having their work | 2709 | directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the |
2236 | directories deleted by ``rm_work``, you can add the names of the recipe | 2710 | recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, |
2237 | or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which | 2711 | which can also be set in your ``local.conf`` file. Here is an example:: |
2238 | can also be set in your ``local.conf`` file. Here is an example: | ||
2239 | :: | ||
2240 | 2712 | ||
2241 | RM_WORK_EXCLUDE += "busybox glibc" | 2713 | RM_WORK_EXCLUDE += "busybox glibc" |
2242 | 2714 | ||
2243 | .. _ref-classes-rootfs*: | 2715 | .. _ref-classes-rootfs*: |
2244 | 2716 | ||
2245 | ``rootfs*.bbclass`` | 2717 | ``rootfs*`` |
2246 | =================== | 2718 | =========== |
2247 | 2719 | ||
2248 | The ``rootfs*`` classes support creating the root filesystem for an | 2720 | The :ref:`ref-classes-rootfs*` classes support creating the root filesystem for an |
2249 | image and consist of the following classes: | 2721 | image and consist of the following classes: |
2250 | 2722 | ||
2251 | - The ``rootfs-postcommands`` class, which defines filesystem | 2723 | - The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class, which defines filesystem |
2252 | post-processing functions for image recipes. | 2724 | post-processing functions for image recipes. |
2253 | 2725 | ||
2254 | - 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 |
2255 | for images built using ``.deb`` packages. | 2727 | for images built using ``.deb`` packages. |
2256 | 2728 | ||
2257 | - 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 |
2258 | for images built using ``.rpm`` packages. | 2730 | for images built using ``.rpm`` packages. |
2259 | 2731 | ||
2260 | - 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 |
2261 | for images built using ``.ipk`` packages. | 2733 | for images built using ``.ipk`` packages. |
2262 | 2734 | ||
2263 | - The ``rootfsdebugfiles`` class, which installs additional files found | 2735 | - The :ref:`rootfsdebugfiles <ref-classes-rootfs*>` class, which installs additional files found |
2264 | on the build host directly into the root filesystem. | 2736 | on the build host directly into the root filesystem. |
2265 | 2737 | ||
2266 | The root filesystem is created from packages using one of the | 2738 | The root filesystem is created from packages using one of the |
2267 | ``rootfs*.bbclass`` files as determined by the | 2739 | :ref:`ref-classes-rootfs*` files as determined by the :term:`PACKAGE_CLASSES` |
2268 | :term:`PACKAGE_CLASSES` variable. | 2740 | variable. |
2269 | 2741 | ||
2270 | For information on how root filesystem images are created, see the | 2742 | For information on how root filesystem images are created, see the |
2271 | ":ref:`overview-manual/concepts:image generation`" | 2743 | ":ref:`overview-manual/concepts:image generation`" |
2272 | section in the Yocto Project Overview and Concepts Manual. | 2744 | section in the Yocto Project Overview and Concepts Manual. |
2273 | 2745 | ||
2746 | .. _ref-classes-rust: | ||
2747 | |||
2748 | ``rust`` | ||
2749 | ======== | ||
2750 | |||
2751 | The :ref:`ref-classes-rust` class is an internal class which is just used | ||
2752 | in the "rust" recipe, to build the Rust compiler and runtime | ||
2753 | library. Except for this recipe, it is not intended to be used directly. | ||
2754 | |||
2755 | .. _ref-classes-rust-common: | ||
2756 | |||
2757 | ``rust-common`` | ||
2758 | =============== | ||
2759 | |||
2760 | The :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 | ||
2762 | intended to be used directly. | ||
2763 | |||
2274 | .. _ref-classes-sanity: | 2764 | .. _ref-classes-sanity: |
2275 | 2765 | ||
2276 | ``sanity.bbclass`` | 2766 | ``sanity`` |
2277 | ================== | 2767 | ========== |
2278 | 2768 | ||
2279 | The ``sanity`` class checks to see if prerequisite software is present | 2769 | The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present |
2280 | on the host system so that users can be notified of potential problems | 2770 | on the host system so that users can be notified of potential problems |
2281 | that might affect their build. The class also performs basic user | 2771 | that might affect their build. The class also performs basic user |
2282 | configuration checks from the ``local.conf`` configuration file to | 2772 | configuration checks from the ``local.conf`` configuration file to |
@@ -2285,72 +2775,117 @@ usually determines whether to include this class. | |||
2285 | 2775 | ||
2286 | .. _ref-classes-scons: | 2776 | .. _ref-classes-scons: |
2287 | 2777 | ||
2288 | ``scons.bbclass`` | 2778 | ``scons`` |
2289 | ================= | 2779 | ========= |
2290 | 2780 | ||
2291 | The ``scons`` class supports recipes that need to build software that | 2781 | The :ref:`ref-classes-scons` class supports recipes that need to build software |
2292 | uses the SCons build system. You can use the | 2782 | that uses the SCons build system. You can use the :term:`EXTRA_OESCONS` |
2293 | :term:`EXTRA_OESCONS` variable to specify | 2783 | variable to specify additional configuration options you want to pass SCons |
2294 | additional configuration options you want to pass SCons command line. | 2784 | command line. |
2295 | 2785 | ||
2296 | .. _ref-classes-sdl: | 2786 | .. _ref-classes-sdl: |
2297 | 2787 | ||
2298 | ``sdl.bbclass`` | 2788 | ``sdl`` |
2299 | =============== | 2789 | ======= |
2300 | 2790 | ||
2301 | The ``sdl`` class supports recipes that need to build software that uses | 2791 | The :ref:`ref-classes-sdl` class supports recipes that need to build software that uses |
2302 | the Simple DirectMedia Layer (SDL) library. | 2792 | the Simple DirectMedia Layer (SDL) library. |
2303 | 2793 | ||
2304 | .. _ref-classes-setuptools: | 2794 | .. _ref-classes-python_setuptools_build_meta: |
2305 | 2795 | ||
2306 | ``setuptools.bbclass`` | 2796 | ``python_setuptools_build_meta`` |
2307 | ====================== | 2797 | ================================ |
2798 | |||
2799 | The :ref:`ref-classes-python_setuptools_build_meta` class enables building | ||
2800 | Python 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]`` | ||
2803 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). | ||
2308 | 2804 | ||
2309 | The ``setuptools`` class supports Python version 2.x extensions that use | 2805 | Python modules built with ``setuptools.build_meta`` can be pure Python or |
2310 | build systems based on ``setuptools``. If your recipe uses these build | 2806 | include ``C`` or ``Rust`` extensions). |
2311 | systems, the recipe needs to inherit the ``setuptools`` class. | 2807 | |
2808 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2312 | 2809 | ||
2313 | .. _ref-classes-setuptools3: | 2810 | .. _ref-classes-setuptools3: |
2314 | 2811 | ||
2315 | ``setuptools3.bbclass`` | 2812 | ``setuptools3`` |
2316 | ======================= | 2813 | =============== |
2317 | 2814 | ||
2318 | The ``setuptools3`` class supports Python version 3.x extensions that | 2815 | The :ref:`ref-classes-setuptools3` class supports Python version 3.x extensions |
2319 | use build systems based on ``setuptools3``. If your recipe uses these | 2816 | that use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` |
2320 | build systems, the recipe needs to inherit the ``setuptools3`` class. | 2817 | and have not migrated to the official ``pyproject.toml`` format). If your recipe |
2818 | uses these build systems, the recipe needs to inherit the | ||
2819 | :ref:`ref-classes-setuptools3` class. | ||
2321 | 2820 | ||
2322 | .. _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. | ||
2323 | 2840 | ||
2324 | ``sign_rpm.bbclass`` | 2841 | .. _ref-classes-setuptools3_legacy: |
2842 | |||
2843 | ``setuptools3_legacy`` | ||
2844 | ====================== | ||
2845 | |||
2846 | The :ref:`ref-classes-setuptools3_legacy` class supports | ||
2847 | Python 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`, | ||
2850 | this uses the traditional ``setup.py`` ``build`` and ``install`` commands and | ||
2851 | not wheels. This use of ``setuptools`` like this is | ||
2852 | `deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__ | ||
2853 | but still relatively common. | ||
2854 | |||
2855 | .. _ref-classes-setuptools3-base: | ||
2856 | |||
2857 | ``setuptools3-base`` | ||
2325 | ==================== | 2858 | ==================== |
2326 | 2859 | ||
2327 | The ``sign_rpm`` class supports generating signed RPM packages. | 2860 | The :ref:`ref-classes-setuptools3-base` class provides a reusable base for |
2861 | other classes that support building Python version 3.x extensions. If you need | ||
2862 | functionality that is not provided by the :ref:`ref-classes-setuptools3` class, | ||
2863 | you may want to ``inherit setuptools3-base``. Some recipes do not need the tasks | ||
2864 | in the :ref:`ref-classes-setuptools3` class and inherit this class instead. | ||
2328 | 2865 | ||
2329 | .. _ref-classes-sip: | 2866 | .. _ref-classes-sign_rpm: |
2330 | 2867 | ||
2331 | ``sip.bbclass`` | 2868 | ``sign_rpm`` |
2332 | =============== | 2869 | ============ |
2333 | 2870 | ||
2334 | The ``sip`` class supports recipes that build or package SIP-based | 2871 | The :ref:`ref-classes-sign_rpm` class supports generating signed RPM packages. |
2335 | Python bindings. | ||
2336 | 2872 | ||
2337 | .. _ref-classes-siteconfig: | 2873 | .. _ref-classes-siteconfig: |
2338 | 2874 | ||
2339 | ``siteconfig.bbclass`` | 2875 | ``siteconfig`` |
2340 | ====================== | 2876 | ============== |
2341 | 2877 | ||
2342 | The ``siteconfig`` class provides functionality for handling site | 2878 | The :ref:`ref-classes-siteconfig` class provides functionality for handling site |
2343 | configuration. The class is used by the | 2879 | configuration. The class is used by the :ref:`ref-classes-autotools` class to |
2344 | :ref:`autotools <ref-classes-autotools>` class to accelerate the | 2880 | accelerate the :ref:`ref-tasks-configure` task. |
2345 | :ref:`ref-tasks-configure` task. | ||
2346 | 2881 | ||
2347 | .. _ref-classes-siteinfo: | 2882 | .. _ref-classes-siteinfo: |
2348 | 2883 | ||
2349 | ``siteinfo.bbclass`` | 2884 | ``siteinfo`` |
2350 | ==================== | 2885 | ============ |
2351 | 2886 | ||
2352 | The ``siteinfo`` class provides information about the targets that might | 2887 | The :ref:`ref-classes-siteinfo` class provides information about the targets |
2353 | be needed by other classes or recipes. | 2888 | that might be needed by other classes or recipes. |
2354 | 2889 | ||
2355 | As an example, consider Autotools, which can require tests that must | 2890 | As an example, consider Autotools, which can require tests that must |
2356 | execute on the target hardware. Since this is not possible in general | 2891 | execute on the target hardware. Since this is not possible in general |
@@ -2359,20 +2894,20 @@ results so these tests can be skipped over but still make the correct | |||
2359 | values available. The ``meta/site directory`` contains test results | 2894 | values available. The ``meta/site directory`` contains test results |
2360 | sorted into different categories such as architecture, endianness, and | 2895 | sorted into different categories such as architecture, endianness, and |
2361 | the ``libc`` used. Site information provides a list of files containing | 2896 | the ``libc`` used. Site information provides a list of files containing |
2362 | data relevant to the current build in the ``CONFIG_SITE`` variable that | 2897 | data relevant to the current build in the :term:`CONFIG_SITE` variable that |
2363 | Autotools automatically picks up. | 2898 | Autotools automatically picks up. |
2364 | 2899 | ||
2365 | The class also provides variables like ``SITEINFO_ENDIANNESS`` and | 2900 | The class also provides variables like :term:`SITEINFO_ENDIANNESS` and |
2366 | ``SITEINFO_BITS`` that can be used elsewhere in the metadata. | 2901 | :term:`SITEINFO_BITS` that can be used elsewhere in the metadata. |
2367 | 2902 | ||
2368 | .. _ref-classes-sstate: | 2903 | .. _ref-classes-sstate: |
2369 | 2904 | ||
2370 | ``sstate.bbclass`` | 2905 | ``sstate`` |
2371 | ================== | 2906 | ========== |
2372 | 2907 | ||
2373 | The ``sstate`` class provides support for Shared State (sstate). By | 2908 | The :ref:`ref-classes-sstate` class provides support for Shared State (sstate). |
2374 | default, the class is enabled through the | 2909 | By default, the class is enabled through the :term:`INHERIT_DISTRO` variable's |
2375 | :term:`INHERIT_DISTRO` variable's default value. | 2910 | default value. |
2376 | 2911 | ||
2377 | For more information on sstate, see the | 2912 | For more information on sstate, see the |
2378 | ":ref:`overview-manual/concepts:shared state cache`" | 2913 | ":ref:`overview-manual/concepts:shared state cache`" |
@@ -2380,10 +2915,10 @@ section in the Yocto Project Overview and Concepts Manual. | |||
2380 | 2915 | ||
2381 | .. _ref-classes-staging: | 2916 | .. _ref-classes-staging: |
2382 | 2917 | ||
2383 | ``staging.bbclass`` | 2918 | ``staging`` |
2384 | =================== | 2919 | =========== |
2385 | 2920 | ||
2386 | The ``staging`` class installs files into individual recipe work | 2921 | The :ref:`ref-classes-staging` class installs files into individual recipe work |
2387 | directories for sysroots. The class contains the following key tasks: | 2922 | directories for sysroots. The class contains the following key tasks: |
2388 | 2923 | ||
2389 | - The :ref:`ref-tasks-populate_sysroot` task, | 2924 | - The :ref:`ref-tasks-populate_sysroot` task, |
@@ -2396,25 +2931,25 @@ directories for sysroots. The class contains the following key tasks: | |||
2396 | installs the files into the individual recipe work directories (i.e. | 2931 | installs the files into the individual recipe work directories (i.e. |
2397 | :term:`WORKDIR`). | 2932 | :term:`WORKDIR`). |
2398 | 2933 | ||
2399 | The code in the ``staging`` class is complex and basically works in two | 2934 | The code in the :ref:`ref-classes-staging` class is complex and basically works |
2400 | stages: | 2935 | in two stages: |
2401 | 2936 | ||
2402 | - *Stage One:* The first stage addresses recipes that have files they | 2937 | - *Stage One:* The first stage addresses recipes that have files they |
2403 | want to share with other recipes that have dependencies on the | 2938 | want to share with other recipes that have dependencies on the |
2404 | originating recipe. Normally these dependencies are installed through | 2939 | originating recipe. Normally these dependencies are installed through |
2405 | the :ref:`ref-tasks-install` task into | 2940 | the :ref:`ref-tasks-install` task into |
2406 | ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task | 2941 | ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task |
2407 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This | 2942 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This |
2408 | subset of files is controlled by the | 2943 | subset of files is controlled by the |
2409 | :term:`SYSROOT_DIRS`, | 2944 | :term:`SYSROOT_DIRS`, |
2410 | :term:`SYSROOT_DIRS_NATIVE`, and | 2945 | :term:`SYSROOT_DIRS_NATIVE`, and |
2411 | :term:`SYSROOT_DIRS_BLACKLIST` | 2946 | :term:`SYSROOT_DIRS_IGNORE` |
2412 | variables. | 2947 | variables. |
2413 | 2948 | ||
2414 | .. note:: | 2949 | .. note:: |
2415 | 2950 | ||
2416 | Additionally, a recipe can customize the files further by | 2951 | Additionally, a recipe can customize the files further by |
2417 | declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` | 2952 | declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS` |
2418 | variable. | 2953 | variable. |
2419 | 2954 | ||
2420 | 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 |
@@ -2456,11 +2991,11 @@ stages: | |||
2456 | recommended for general use, the files do allow some issues such | 2991 | recommended for general use, the files do allow some issues such |
2457 | as user creation and module indexes to be addressed. | 2992 | as user creation and module indexes to be addressed. |
2458 | 2993 | ||
2459 | Because recipes can have other dependencies outside of ``DEPENDS`` | 2994 | Because recipes can have other dependencies outside of :term:`DEPENDS` |
2460 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), | 2995 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), |
2461 | the sysroot creation function ``extend_recipe_sysroot`` is also added | 2996 | the sysroot creation function ``extend_recipe_sysroot`` is also added |
2462 | 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 |
2463 | ``DEPENDS`` but operate similarly. | 2998 | :term:`DEPENDS` but operate similarly. |
2464 | 2999 | ||
2465 | When installing dependencies into the sysroot, the code traverses the | 3000 | When installing dependencies into the sysroot, the code traverses the |
2466 | dependency graph and processes dependencies in exactly the same way | 3001 | dependency graph and processes dependencies in exactly the same way |
@@ -2470,8 +3005,7 @@ stages: | |||
2470 | dependencies traversed or installed. The same sstate dependency code | 3005 | dependencies traversed or installed. The same sstate dependency code |
2471 | is used so that builds should be identical regardless of whether | 3006 | is used so that builds should be identical regardless of whether |
2472 | sstate was used or not. For a closer look, see the | 3007 | sstate was used or not. For a closer look, see the |
2473 | ``setscene_depvalid()`` function in the | 3008 | ``setscene_depvalid()`` function in the :ref:`ref-classes-sstate` class. |
2474 | :ref:`sstate <ref-classes-sstate>` class. | ||
2475 | 3009 | ||
2476 | 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 |
2477 | 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 |
@@ -2480,11 +3014,11 @@ stages: | |||
2480 | 3014 | ||
2481 | .. _ref-classes-syslinux: | 3015 | .. _ref-classes-syslinux: |
2482 | 3016 | ||
2483 | ``syslinux.bbclass`` | 3017 | ``syslinux`` |
2484 | ==================== | 3018 | ============ |
2485 | 3019 | ||
2486 | The ``syslinux`` class provides syslinux-specific functions for building | 3020 | The :ref:`ref-classes-syslinux` class provides syslinux-specific functions for |
2487 | bootable images. | 3021 | building bootable images. |
2488 | 3022 | ||
2489 | The class supports the following variables: | 3023 | The class supports the following variables: |
2490 | 3024 | ||
@@ -2523,11 +3057,11 @@ The class supports the following variables: | |||
2523 | 3057 | ||
2524 | .. _ref-classes-systemd: | 3058 | .. _ref-classes-systemd: |
2525 | 3059 | ||
2526 | ``systemd.bbclass`` | 3060 | ``systemd`` |
2527 | =================== | 3061 | =========== |
2528 | 3062 | ||
2529 | The ``systemd`` class provides support for recipes that install systemd | 3063 | The :ref:`ref-classes-systemd` class provides support for recipes that install |
2530 | unit files. | 3064 | systemd unit files. |
2531 | 3065 | ||
2532 | The functionality for this class is disabled unless you have "systemd" | 3066 | The functionality for this class is disabled unless you have "systemd" |
2533 | in :term:`DISTRO_FEATURES`. | 3067 | in :term:`DISTRO_FEATURES`. |
@@ -2544,36 +3078,35 @@ You should set :term:`SYSTEMD_SERVICE` to the | |||
2544 | name of the service file. You should also use a package name override to | 3078 | name of the service file. You should also use a package name override to |
2545 | indicate the package to which the value applies. If the value applies to | 3079 | indicate the package to which the value applies. If the value applies to |
2546 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here | 3080 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here |
2547 | is an example from the connman recipe: | 3081 | is an example from the connman recipe:: |
2548 | :: | ||
2549 | 3082 | ||
2550 | SYSTEMD_SERVICE_${PN} = "connman.service" | 3083 | SYSTEMD_SERVICE:${PN} = "connman.service" |
2551 | 3084 | ||
2552 | Services are set up to start on boot automatically | 3085 | Services are set up to start on boot automatically |
2553 | unless you have set | 3086 | unless you have set |
2554 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". | 3087 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". |
2555 | 3088 | ||
2556 | For more information on ``systemd``, see the | 3089 | For more information on :ref:`ref-classes-systemd`, see the |
2557 | ":ref:`dev-manual/common-tasks:selecting an initialization manager`" | 3090 | ":ref:`dev-manual/init-manager:selecting an initialization manager`" |
2558 | section in the Yocto Project Development Tasks Manual. | 3091 | section in the Yocto Project Development Tasks Manual. |
2559 | 3092 | ||
2560 | .. _ref-classes-systemd-boot: | 3093 | .. _ref-classes-systemd-boot: |
2561 | 3094 | ||
2562 | ``systemd-boot.bbclass`` | 3095 | ``systemd-boot`` |
2563 | ======================== | 3096 | ================ |
2564 | 3097 | ||
2565 | The ``systemd-boot`` class provides functions specific to the | 3098 | The :ref:`ref-classes-systemd-boot` class provides functions specific to the |
2566 | systemd-boot bootloader for building bootable images. This is an | 3099 | systemd-boot bootloader for building bootable images. This is an |
2567 | internal class and is not intended to be used directly. | 3100 | internal class and is not intended to be used directly. |
2568 | 3101 | ||
2569 | .. note:: | 3102 | .. note:: |
2570 | 3103 | ||
2571 | 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 |
2572 | used in previous Yocto Project releases with the ``systemd`` project. | 3105 | used in previous Yocto Project releases with the ``systemd`` project. |
2573 | 3106 | ||
2574 | Set the :term:`EFI_PROVIDER` variable to | 3107 | Set the :term:`EFI_PROVIDER` variable to ":ref:`ref-classes-systemd-boot`" to |
2575 | "systemd-boot" to use this class. Doing so creates a standalone EFI | 3108 | use this class. Doing so creates a standalone EFI bootloader that is not |
2576 | bootloader that is not dependent on systemd. | 3109 | dependent on systemd. |
2577 | 3110 | ||
2578 | For information on more variables used and supported in this class, see | 3111 | For information on more variables used and supported in this class, see |
2579 | the :term:`SYSTEMD_BOOT_CFG`, | 3112 | the :term:`SYSTEMD_BOOT_CFG`, |
@@ -2586,76 +3119,71 @@ for more information. | |||
2586 | 3119 | ||
2587 | .. _ref-classes-terminal: | 3120 | .. _ref-classes-terminal: |
2588 | 3121 | ||
2589 | ``terminal.bbclass`` | 3122 | ``terminal`` |
2590 | ==================== | 3123 | ============ |
2591 | 3124 | ||
2592 | The ``terminal`` class provides support for starting a terminal session. | 3125 | The :ref:`ref-classes-terminal` class provides support for starting a terminal |
2593 | The :term:`OE_TERMINAL` variable controls which | 3126 | session. The :term:`OE_TERMINAL` variable controls which terminal emulator is |
2594 | terminal emulator is used for the session. | 3127 | used for the session. |
2595 | 3128 | ||
2596 | Other classes use the ``terminal`` class anywhere a separate terminal | 3129 | Other classes use the :ref:`ref-classes-terminal` class anywhere a separate |
2597 | session needs to be started. For example, the | 3130 | terminal session needs to be started. For example, the :ref:`ref-classes-patch` |
2598 | :ref:`patch <ref-classes-patch>` class assuming | 3131 | class assuming :term:`PATCHRESOLVE` is set to "user", the |
2599 | :term:`PATCHRESOLVE` is set to "user", the | 3132 | :ref:`ref-classes-cml1` class, and the :ref:`ref-classes-devshell` class all |
2600 | :ref:`cml1 <ref-classes-cml1>` class, and the | 3133 | use the :ref:`ref-classes-terminal` class. |
2601 | :ref:`devshell <ref-classes-devshell>` class all use the ``terminal`` | ||
2602 | class. | ||
2603 | 3134 | ||
2604 | .. _ref-classes-testimage*: | 3135 | .. _ref-classes-testimage: |
2605 | 3136 | ||
2606 | ``testimage*.bbclass`` | 3137 | ``testimage`` |
2607 | ====================== | 3138 | ============= |
2608 | 3139 | ||
2609 | The ``testimage*`` classes support running automated tests against | 3140 | The :ref:`ref-classes-testimage` class supports running automated tests against |
2610 | images using QEMU and on actual hardware. The classes handle loading the | 3141 | images using QEMU and on actual hardware. The classes handle loading the |
2611 | tests and starting the image. To use the classes, you need to perform | 3142 | tests and starting the image. To use the classes, you need to perform |
2612 | steps to set up the environment. | 3143 | steps to set up the environment. |
2613 | 3144 | ||
2614 | .. note:: | 3145 | To enable this class, add the following to your configuration:: |
2615 | 3146 | ||
2616 | Best practices include using :term:`IMAGE_CLASSES` rather than | 3147 | IMAGE_CLASSES += "testimage" |
2617 | :term:`INHERIT` to inherit the ``testimage`` class for automated image | ||
2618 | testing. | ||
2619 | 3148 | ||
2620 | The tests are commands that run on the target system over ``ssh``. Each | 3149 | The tests are commands that run on the target system over ``ssh``. Each |
2621 | test is written in Python and makes use of the ``unittest`` module. | 3150 | test is written in Python and makes use of the ``unittest`` module. |
2622 | 3151 | ||
2623 | The ``testimage.bbclass`` runs tests on an image when called using the | 3152 | The :ref:`ref-classes-testimage` class runs tests on an image when called using the |
2624 | following: | 3153 | following:: |
2625 | :: | ||
2626 | 3154 | ||
2627 | $ bitbake -c testimage image | 3155 | $ bitbake -c testimage image |
2628 | 3156 | ||
2629 | The ``testimage-auto`` class | 3157 | Alternatively, if you wish to have tests automatically run for each image |
2630 | runs tests on an image after the image is constructed (i.e. | 3158 | after it is built, you can set :term:`TESTIMAGE_AUTO`:: |
2631 | :term:`TESTIMAGE_AUTO` must be set to "1"). | 3159 | |
3160 | TESTIMAGE_AUTO = "1" | ||
2632 | 3161 | ||
2633 | For information on how to enable, run, and create new tests, see the | 3162 | For information on how to enable, run, and create new tests, see the |
2634 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 3163 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
2635 | section in the Yocto Project Development Tasks Manual. | 3164 | section in the Yocto Project Development Tasks Manual. |
2636 | 3165 | ||
2637 | .. _ref-classes-testsdk: | 3166 | .. _ref-classes-testsdk: |
2638 | 3167 | ||
2639 | ``testsdk.bbclass`` | 3168 | ``testsdk`` |
2640 | =================== | 3169 | =========== |
2641 | 3170 | ||
2642 | This class supports running automated tests against software development | 3171 | This class supports running automated tests against software development |
2643 | kits (SDKs). The ``testsdk`` class runs tests on an SDK when called | 3172 | kits (SDKs). The :ref:`ref-classes-testsdk` class runs tests on an SDK when called |
2644 | using the following: | 3173 | using the following:: |
2645 | :: | ||
2646 | 3174 | ||
2647 | $ bitbake -c testsdk image | 3175 | $ bitbake -c testsdk image |
2648 | 3176 | ||
2649 | .. note:: | 3177 | .. note:: |
2650 | 3178 | ||
2651 | Best practices include using :term:`IMAGE_CLASSES` rather than | 3179 | Best practices include using :term:`IMAGE_CLASSES` rather than |
2652 | :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK | 3180 | :term:`INHERIT` to inherit the :ref:`ref-classes-testsdk` class for automated SDK |
2653 | testing. | 3181 | testing. |
2654 | 3182 | ||
2655 | .. _ref-classes-texinfo: | 3183 | .. _ref-classes-texinfo: |
2656 | 3184 | ||
2657 | ``texinfo.bbclass`` | 3185 | ``texinfo`` |
2658 | =================== | 3186 | =========== |
2659 | 3187 | ||
2660 | This class should be inherited by recipes whose upstream packages invoke | 3188 | This class should be inherited by recipes whose upstream packages invoke |
2661 | the ``texinfo`` utilities at build-time. Native and cross recipes are | 3189 | the ``texinfo`` utilities at build-time. Native and cross recipes are |
@@ -2672,10 +3200,10 @@ host system. | |||
2672 | 3200 | ||
2673 | .. _ref-classes-toaster: | 3201 | .. _ref-classes-toaster: |
2674 | 3202 | ||
2675 | ``toaster.bbclass`` | 3203 | ``toaster`` |
2676 | =================== | 3204 | =========== |
2677 | 3205 | ||
2678 | The ``toaster`` class collects information about packages and images and | 3206 | The :ref:`ref-classes-toaster` class collects information about packages and images and |
2679 | sends them as events that the BitBake user interface can receive. The | 3207 | sends them as events that the BitBake user interface can receive. The |
2680 | class is enabled when the Toaster user interface is running. | 3208 | class is enabled when the Toaster user interface is running. |
2681 | 3209 | ||
@@ -2683,49 +3211,84 @@ This class is not intended to be used directly. | |||
2683 | 3211 | ||
2684 | .. _ref-classes-toolchain-scripts: | 3212 | .. _ref-classes-toolchain-scripts: |
2685 | 3213 | ||
2686 | ``toolchain-scripts.bbclass`` | 3214 | ``toolchain-scripts`` |
2687 | ============================= | 3215 | ===================== |
2688 | 3216 | ||
2689 | The ``toolchain-scripts`` class provides the scripts used for setting up | 3217 | The :ref:`ref-classes-toolchain-scripts` class provides the scripts used for setting up |
2690 | the environment for installed SDKs. | 3218 | the environment for installed SDKs. |
2691 | 3219 | ||
2692 | .. _ref-classes-typecheck: | 3220 | .. _ref-classes-typecheck: |
2693 | 3221 | ||
2694 | ``typecheck.bbclass`` | 3222 | ``typecheck`` |
2695 | ===================== | 3223 | ============= |
2696 | 3224 | ||
2697 | The ``typecheck`` class provides support for validating the values of | 3225 | The :ref:`ref-classes-typecheck` class provides support for validating the values of |
2698 | variables set at the configuration level against their defined types. | 3226 | variables set at the configuration level against their defined types. |
2699 | The OpenEmbedded build system allows you to define the type of a | 3227 | The OpenEmbedded build system allows you to define the type of a |
2700 | variable using the "type" varflag. Here is an example: | 3228 | variable using the "type" varflag. Here is an example:: |
2701 | :: | ||
2702 | 3229 | ||
2703 | IMAGE_FEATURES[type] = "list" | 3230 | IMAGE_FEATURES[type] = "list" |
2704 | 3231 | ||
2705 | .. _ref-classes-uboot-config: | 3232 | .. _ref-classes-uboot-config: |
2706 | 3233 | ||
2707 | ``uboot-config.bbclass`` | 3234 | ``uboot-config`` |
2708 | ======================== | 3235 | ================ |
2709 | 3236 | ||
2710 | The ``uboot-config`` class provides support for U-Boot configuration for | 3237 | The :ref:`ref-classes-uboot-config` class provides support for U-Boot configuration for |
2711 | a machine. Specify the machine in your recipe as follows: | 3238 | a machine. Specify the machine in your recipe as follows:: |
2712 | :: | ||
2713 | 3239 | ||
2714 | UBOOT_CONFIG ??= <default> | 3240 | UBOOT_CONFIG ??= <default> |
2715 | UBOOT_CONFIG[foo] = "config,images" | 3241 | UBOOT_CONFIG[foo] = "config,images,binary" |
2716 | 3242 | ||
2717 | You can also specify the machine using this method: | 3243 | You can also specify the machine using this method:: |
2718 | :: | ||
2719 | 3244 | ||
2720 | UBOOT_MACHINE = "config" | 3245 | UBOOT_MACHINE = "config" |
2721 | 3246 | ||
2722 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional | 3247 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional |
2723 | information. | 3248 | information. |
2724 | 3249 | ||
3250 | .. _ref-classes-uboot-sign: | ||
3251 | |||
3252 | ``uboot-sign`` | ||
3253 | ============== | ||
3254 | |||
3255 | The :ref:`ref-classes-uboot-sign` class provides support for U-Boot verified boot. | ||
3256 | It is intended to be inherited from U-Boot recipes. | ||
3257 | |||
3258 | The 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 | |||
3280 | See 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>`__ | ||
3282 | and the `signature process | ||
3283 | <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/signature.txt>`__. | ||
3284 | |||
3285 | See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class | ||
3286 | imitates. | ||
3287 | |||
2725 | .. _ref-classes-uninative: | 3288 | .. _ref-classes-uninative: |
2726 | 3289 | ||
2727 | ``uninative.bbclass`` | 3290 | ``uninative`` |
2728 | ===================== | 3291 | ============= |
2729 | 3292 | ||
2730 | Attempts to isolate the build system from the host distribution's C | 3293 | Attempts to isolate the build system from the host distribution's C |
2731 | library in order to make re-use of native shared state artifacts across | 3294 | library in order to make re-use of native shared state artifacts across |
@@ -2740,21 +3303,21 @@ yourself, publish the resulting tarball (e.g. via HTTP) and set | |||
2740 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an | 3303 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an |
2741 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. | 3304 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. |
2742 | 3305 | ||
2743 | The ``uninative`` class is also used unconditionally by the extensible | 3306 | The :ref:`ref-classes-uninative` class is also used unconditionally by the extensible |
2744 | SDK. When building the extensible SDK, ``uninative-tarball`` is built | 3307 | SDK. When building the extensible SDK, ``uninative-tarball`` is built |
2745 | and the resulting tarball is included within the SDK. | 3308 | and the resulting tarball is included within the SDK. |
2746 | 3309 | ||
2747 | .. _ref-classes-update-alternatives: | 3310 | .. _ref-classes-update-alternatives: |
2748 | 3311 | ||
2749 | ``update-alternatives.bbclass`` | 3312 | ``update-alternatives`` |
2750 | =============================== | 3313 | ======================= |
2751 | 3314 | ||
2752 | The ``update-alternatives`` class helps the alternatives system when | 3315 | The :ref:`ref-classes-update-alternatives` class helps the alternatives system when |
2753 | multiple sources provide the same command. This situation occurs when | 3316 | multiple sources provide the same command. This situation occurs when |
2754 | several programs that have the same or similar function are installed | 3317 | several programs that have the same or similar function are installed |
2755 | with the same name. For example, the ``ar`` command is available from | 3318 | with the same name. For example, the ``ar`` command is available from |
2756 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The | 3319 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The |
2757 | ``update-alternatives`` class handles renaming the binaries so that | 3320 | :ref:`ref-classes-update-alternatives` class handles renaming the binaries so that |
2758 | multiple packages can be installed without conflicts. The ``ar`` command | 3321 | multiple packages can be installed without conflicts. The ``ar`` command |
2759 | still works regardless of which packages are installed or subsequently | 3322 | still works regardless of which packages are installed or subsequently |
2760 | removed. The class renames the conflicting binary in each package and | 3323 | removed. The class renames the conflicting binary in each package and |
@@ -2774,7 +3337,7 @@ To use this class, you need to define a number of variables: | |||
2774 | These variables list alternative commands needed by a package, provide | 3337 | These variables list alternative commands needed by a package, provide |
2775 | pathnames for links, default links for targets, and so forth. For | 3338 | pathnames for links, default links for targets, and so forth. For |
2776 | details on how to use this class, see the comments in the | 3339 | details on how to use this class, see the comments in the |
2777 | :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>` |
2778 | file. | 3341 | file. |
2779 | 3342 | ||
2780 | .. note:: | 3343 | .. note:: |
@@ -2784,43 +3347,42 @@ file. | |||
2784 | 3347 | ||
2785 | .. _ref-classes-update-rc.d: | 3348 | .. _ref-classes-update-rc.d: |
2786 | 3349 | ||
2787 | ``update-rc.d.bbclass`` | 3350 | ``update-rc.d`` |
2788 | ======================= | 3351 | =============== |
2789 | 3352 | ||
2790 | The ``update-rc.d`` class uses ``update-rc.d`` to safely install an | 3353 | The :ref:`ref-classes-update-rc.d` class uses ``update-rc.d`` to safely install an |
2791 | initialization script on behalf of the package. The OpenEmbedded build | 3354 | initialization script on behalf of the package. The OpenEmbedded build |
2792 | system takes care of details such as making sure the script is stopped | 3355 | system takes care of details such as making sure the script is stopped |
2793 | before a package is removed and started when the package is installed. | 3356 | before a package is removed and started when the package is installed. |
2794 | 3357 | ||
2795 | Three variables control this class: ``INITSCRIPT_PACKAGES``, | 3358 | Three variables control this class: :term:`INITSCRIPT_PACKAGES`, |
2796 | ``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links | 3359 | :term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links |
2797 | for details. | 3360 | for details. |
2798 | 3361 | ||
2799 | .. _ref-classes-useradd: | 3362 | .. _ref-classes-useradd: |
2800 | 3363 | ||
2801 | ``useradd*.bbclass`` | 3364 | ``useradd*`` |
2802 | ==================== | 3365 | ============ |
2803 | 3366 | ||
2804 | The ``useradd*`` classes support the addition of users or groups for | 3367 | The :ref:`useradd* <ref-classes-useradd>` classes support the addition of users or groups for |
2805 | usage by the package on the target. For example, if you have packages | 3368 | usage by the package on the target. For example, if you have packages |
2806 | that contain system services that should be run under their own user or | 3369 | that contain system services that should be run under their own user or |
2807 | group, you can use these classes to enable creation of the user or | 3370 | group, you can use these classes to enable creation of the user or |
2808 | group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` | 3371 | group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb |
3372 | </openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>` | ||
2809 | recipe in the :term:`Source Directory` provides a simple | 3373 | recipe in the :term:`Source Directory` provides a simple |
2810 | example that shows how to add three users and groups to two packages. | 3374 | example that shows how to add three users and groups to two packages. |
2811 | See the ``useradd-example.bb`` recipe for more information on how to use | ||
2812 | these classes. | ||
2813 | 3375 | ||
2814 | The ``useradd_base`` class provides basic functionality for user or | 3376 | The :ref:`useradd_base <ref-classes-useradd>` class provides basic functionality for user or |
2815 | groups settings. | 3377 | groups settings. |
2816 | 3378 | ||
2817 | The ``useradd*`` classes support the | 3379 | The :ref:`useradd* <ref-classes-useradd>` classes support the |
2818 | :term:`USERADD_PACKAGES`, | 3380 | :term:`USERADD_PACKAGES`, |
2819 | :term:`USERADD_PARAM`, | 3381 | :term:`USERADD_PARAM`, |
2820 | :term:`GROUPADD_PARAM`, and | 3382 | :term:`GROUPADD_PARAM`, and |
2821 | :term:`GROUPMEMS_PARAM` variables. | 3383 | :term:`GROUPMEMS_PARAM` variables. |
2822 | 3384 | ||
2823 | The ``useradd-staticids`` class supports the addition of users or groups | 3385 | The :ref:`useradd-staticids <ref-classes-useradd>` class supports the addition of users or groups |
2824 | that have static user identification (``uid``) and group identification | 3386 | that have static user identification (``uid``) and group identification |
2825 | (``gid``) values. | 3387 | (``gid``) values. |
2826 | 3388 | ||
@@ -2836,61 +3398,58 @@ set static values, the OpenEmbedded build system looks in | |||
2836 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` | 3398 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` |
2837 | files for the values. | 3399 | files for the values. |
2838 | 3400 | ||
2839 | To use static ``uid`` and ``gid`` values, you need to set some | 3401 | To use static ``uid`` and ``gid`` values, you need to set some variables. See |
2840 | variables. See the :term:`USERADDEXTENSION`, | 3402 | the :term:`USERADDEXTENSION`, :term:`USERADD_UID_TABLES`, |
2841 | :term:`USERADD_UID_TABLES`, | 3403 | :term:`USERADD_GID_TABLES`, and :term:`USERADD_ERROR_DYNAMIC` variables. |
2842 | :term:`USERADD_GID_TABLES`, and | 3404 | You can also see the :ref:`ref-classes-useradd` class for additional |
2843 | :term:`USERADD_ERROR_DYNAMIC` variables. | 3405 | information. |
2844 | You can also see the :ref:`useradd <ref-classes-useradd>` class for | ||
2845 | additional information. | ||
2846 | 3406 | ||
2847 | .. note:: | 3407 | .. note:: |
2848 | 3408 | ||
2849 | 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 |
2850 | or disable the class by setting the ``USERADDEXTENSION`` variable. If you | 3410 | or disable the class by setting the :term:`USERADDEXTENSION` variable. If you |
2851 | 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 |
2852 | contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` | 3412 | contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR` |
2853 | directory will correct this condition. | 3413 | directory will correct this condition. |
2854 | 3414 | ||
2855 | .. _ref-classes-utility-tasks: | 3415 | .. _ref-classes-utility-tasks: |
2856 | 3416 | ||
2857 | ``utility-tasks.bbclass`` | 3417 | ``utility-tasks`` |
2858 | ========================= | 3418 | ================= |
2859 | 3419 | ||
2860 | The ``utility-tasks`` class provides support for various "utility" type | 3420 | The :ref:`ref-classes-utility-tasks` class provides support for various |
2861 | tasks that are applicable to all recipes, such as | 3421 | "utility" type tasks that are applicable to all recipes, such as |
2862 | :ref:`ref-tasks-clean` and | 3422 | :ref:`ref-tasks-clean` and :ref:`ref-tasks-listtasks`. |
2863 | :ref:`ref-tasks-listtasks`. | ||
2864 | 3423 | ||
2865 | This class is enabled by default because it is inherited by the | 3424 | This class is enabled by default because it is inherited by the |
2866 | :ref:`base <ref-classes-base>` class. | 3425 | :ref:`ref-classes-base` class. |
2867 | 3426 | ||
2868 | .. _ref-classes-utils: | 3427 | .. _ref-classes-utils: |
2869 | 3428 | ||
2870 | ``utils.bbclass`` | 3429 | ``utils`` |
2871 | ================= | 3430 | ========= |
2872 | 3431 | ||
2873 | The ``utils`` class provides some useful Python functions that are | 3432 | The :ref:`ref-classes-utils` class provides some useful Python functions that are |
2874 | typically used in inline Python expressions (e.g. ``${@...}``). One | 3433 | typically used in inline Python expressions (e.g. ``${@...}``). One |
2875 | example use is for ``bb.utils.contains()``. | 3434 | example use is for ``bb.utils.contains()``. |
2876 | 3435 | ||
2877 | This class is enabled by default because it is inherited by the | 3436 | This class is enabled by default because it is inherited by the |
2878 | :ref:`base <ref-classes-base>` class. | 3437 | :ref:`ref-classes-base` class. |
2879 | 3438 | ||
2880 | .. _ref-classes-vala: | 3439 | .. _ref-classes-vala: |
2881 | 3440 | ||
2882 | ``vala.bbclass`` | 3441 | ``vala`` |
2883 | ================ | 3442 | ======== |
2884 | 3443 | ||
2885 | The ``vala`` class supports recipes that need to build software written | 3444 | The :ref:`ref-classes-vala` class supports recipes that need to build software written |
2886 | using the Vala programming language. | 3445 | using the Vala programming language. |
2887 | 3446 | ||
2888 | .. _ref-classes-waf: | 3447 | .. _ref-classes-waf: |
2889 | 3448 | ||
2890 | ``waf.bbclass`` | 3449 | ``waf`` |
2891 | =============== | 3450 | ======= |
2892 | 3451 | ||
2893 | The ``waf`` class supports recipes that need to build software that uses | 3452 | The :ref:`ref-classes-waf` class supports recipes that need to build software that uses |
2894 | the Waf build system. You can use the | 3453 | the Waf build system. You can use the |
2895 | :term:`EXTRA_OECONF` or | 3454 | :term:`EXTRA_OECONF` or |
2896 | :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 cc5848fd4d..9319addc3c 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst | |||
@@ -22,8 +22,7 @@ Getting Help | |||
22 | 22 | ||
23 | The ``devtool`` command line is organized similarly to Git in that it | 23 | The ``devtool`` command line is organized similarly to Git in that it |
24 | has a number of sub-commands for each function. You can run | 24 | has 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 | ||
80 | As directed in the general help output, you can | 79 | As directed in the general help output, you can |
81 | get more syntax on a specific command by providing the command name and | 80 | get more syntax on a specific command by providing the command name and |
82 | using "--help": | 81 | using ``--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. | |||
128 | The following figure shows the workspace structure: | 126 | The 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 | ||
169 | Use the ``devtool add`` command to add a new recipe to the workspace | 166 | Use the ``devtool add`` command to add a new recipe to the workspace |
170 | layer. The recipe you add should not exist - ``devtool`` creates it for | 167 | layer. The recipe you add should not exist --- ``devtool`` creates it for |
171 | you. The source files the recipe uses should exist in an external area. | 168 | you. The source files the recipe uses should exist in an external area. |
172 | 169 | ||
173 | The following example creates and adds a new recipe named ``jackson`` to | 170 | The following example creates and adds a new recipe named ``jackson`` to |
174 | a workspace layer the tool creates. The source code built by the recipes | 171 | a workspace layer the tool creates. The source code built by the recipes |
175 | resides in ``/home/user/sources/jackson``: | 172 | resides 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 | ||
180 | If you add a recipe and the workspace layer does not exist, the command | 176 | If you add a recipe and the workspace layer does not exist, the command |
181 | creates the layer and populates it as described in "`The Workspace Layer | 177 | creates the layer and populates it as described in |
182 | Structure <#devtool-the-workspace-layer-structure>`__" section. | 178 | ":ref:`devtool-the-workspace-layer-structure`" section. |
183 | 179 | ||
184 | Running ``devtool add`` when the workspace layer exists causes the tool | 180 | Running ``devtool add`` when the workspace layer exists causes the tool |
185 | to add the recipe, append files, and source files into the existing | 181 | to add the recipe, append files, and source files into the existing |
@@ -201,23 +197,21 @@ unpacking files from a remote URI. In some cases, you might want to | |||
201 | specify a source revision by branch, tag, or commit hash. You can | 197 | specify a source revision by branch, tag, or commit hash. You can |
202 | specify these options when using the ``devtool add`` command: | 198 | specify 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 | ||
209 | In the previous example, you are checking out the DISTRO_NAME_NO_CAP | 204 | In the previous example, you are checking out the &DISTRO_NAME_NO_CAP; |
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 |
218 | 212 | ||
219 | The previous examples check out the | 213 | The previous examples check out the |
220 | DISTRO_REL_TAG tag and the commit associated with the | 214 | &DISTRO_REL_TAG; tag and the commit associated with the |
221 | some_commit_hash hash. | 215 | some_commit_hash hash. |
222 | 216 | ||
223 | .. note:: | 217 | .. note:: |
@@ -269,8 +263,7 @@ The ``devtool modify`` command extracts the source for a recipe, sets it | |||
269 | up as a Git repository if the source had not already been fetched from | 263 | up as a Git repository if the source had not already been fetched from |
270 | Git, checks out a branch for development, and applies any patches from | 264 | Git, checks out a branch for development, and applies any patches from |
271 | the recipe as commits on top. You can use the following command to | 265 | the recipe as commits on top. You can use the following command to |
272 | checkout the source files: | 266 | checkout 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. | |||
290 | When you use the ``devtool edit-recipe`` command, you must supply the | 283 | When you use the ``devtool edit-recipe`` command, you must supply the |
291 | root name of the recipe (i.e. no version, paths, or extensions). Also, | 284 | root name of the recipe (i.e. no version, paths, or extensions). Also, |
292 | the recipe file itself must reside in the workspace as a result of the | 285 | the 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. |
294 | override that requirement by using the "-a" or "--any-recipe" option. | ||
295 | Using either of these options allows you to edit any recipe regardless | ||
296 | of 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 | ||
310 | When you are satisfied with the results and you have committed your | 300 | When you are satisfied with the results and you have committed your |
311 | changes to the Git repository, you can then run the | 301 | changes 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 | |||
321 | your own layer rather than apply them to the original recipe. If so, you | 310 | your own layer rather than apply them to the original recipe. If so, you |
322 | can use the ``-a`` or ``--append`` option with the | 311 | can 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 |
324 | the layer into which to write an append file: | 313 | the 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 | |||
339 | Upstream recipes change over time. Consequently, you might find that you | 327 | Upstream recipes change over time. Consequently, you might find that you |
340 | need to determine if you can upgrade a recipe to a newer version. | 328 | need to determine if you can upgrade a recipe to a newer version. |
341 | 329 | ||
342 | To check on the upgrade status of a recipe, use the | 330 | To 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 |
344 | of your current recipe versions, the latest upstream versions, the email | 332 | version and the latest version available upstream. To get a more global |
345 | address of the recipe's maintainer, and any additional information such | 333 | picture, use the ``devtool check-upgrade-status`` command, which takes a |
346 | as commit hash strings and reasons you might not be able to upgrade a | 334 | list of recipes as input, or no arguments, in which case it checks all |
347 | particular recipe. | 335 | available recipes. This command will only print the recipes for which |
336 | a new upstream version is available. Each such recipe will have its current | ||
337 | version and latest upstream version, as well as the email of the maintainer | ||
338 | and any additional information such as the commit hash or reason for not | ||
339 | being able to upgrade it, displayed in a table. | ||
340 | |||
341 | This 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` | ||
344 | variables 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 | ||
360 | As with all ``devtool`` commands, you can get help on the individual | 362 | As with all ``devtool`` commands, you can get help on the individual |
361 | command: | 363 | command:: |
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: | |||
377 | Unless you provide a specific recipe name on the command line, the | 378 | Unless you provide a specific recipe name on the command line, the |
378 | command checks all recipes in all configured layers. | 379 | command checks all recipes in all configured layers. |
379 | 380 | ||
380 | Following is a partial example table that reports on all the recipes. | 381 | Here 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 | |||
381 | Notice the reported reason for not upgrading the ``base-passwd`` recipe. | 392 | Notice the reported reason for not upgrading the ``base-passwd`` recipe. |
382 | In this example, while a new version is available upstream, you do not | 393 | In this example, while a new version is available upstream, you do not |
383 | want to use it because the dependency on ``cdebconf`` is not easily | 394 | want to use it because the dependency on ``cdebconf`` is not easily |
384 | satisfied. | 395 | satisfied. Maintainers can explicit the reason that is shown by adding |
396 | the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. | ||
397 | See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>` | ||
398 | for 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 | 402 | Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` |
397 | ... | 403 | in 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> | 404 | version. |
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 | ||
413 | As software matures, upstream recipes are upgraded to newer versions. As | 411 | As software matures, upstream recipes are upgraded to newer versions. As |
414 | a developer, you need to keep your local recipes up-to-date with the | 412 | a developer, you need to keep your local recipes up-to-date with the |
415 | upstream version releases. Several methods exist by which you can | 413 | upstream version releases. There are several ways of upgrading recipes. |
416 | upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" | 414 | You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`" |
417 | section of the Yocto Project Development Tasks Manual. This section | 415 | section of the Yocto Project Development Tasks Manual. This section |
418 | overviews the ``devtool upgrade`` command. | 416 | overviews 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`" |
442 | section in the Yocto Project Application Development and the Extensible | 440 | section in the Yocto Project Application Development and the Extensible |
443 | Software Development Kit (eSDK) manual. You can also see an example of | 441 | Software Development Kit (eSDK) manual. You can also see an example of |
444 | how to use ``devtool upgrade`` in the ":ref:`dev-manual/common-tasks:using \`\`devtool upgrade\`\``" | 442 | how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``" |
445 | section in the Yocto Project Development Tasks Manual. | 443 | section 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 | |||
462 | separate "attic" subdirectory under the workspace layer. | 460 | separate "attic" subdirectory under the workspace layer. |
463 | 461 | ||
464 | Here is an example that resets the workspace directory that contains the | 462 | Here 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 | ||
482 | When you use the ``devtool build`` command, you must supply the root | 479 | When you use the ``devtool build`` command, you must supply the root |
483 | name of the recipe (i.e. do not provide versions, paths, or extensions). | 480 | name of the recipe (i.e. do not provide versions, paths, or extensions). |
484 | You can use either the "-s" or the "--disable-parallel-make" options to | 481 | You can use either the ``-s`` or the ``--disable-parallel-make`` options to |
485 | disable parallel makes during the build. Here is an example: | 482 | disable 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 | |||
499 | to edit your custom image recipe appropriately. | 495 | to edit your custom image recipe appropriately. |
500 | 496 | ||
501 | When you use the ``devtool build-image`` command, you must supply the | 497 | When you use the ``devtool build-image`` command, you must supply the |
502 | name of the image. This command has no command line options: | 498 | name 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 | ||
512 | Use the ``devtool deploy-target`` command to deploy the recipe's build | 507 | Use the ``devtool deploy-target`` command to deploy the recipe's build |
513 | output to the live target machine: | 508 | output 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 | ||
532 | Some conditions exist that could prevent a deployed application from | 526 | Some conditions could prevent a deployed application from |
533 | behaving as expected. When both of the following conditions exist, your | 527 | behaving as expected. When both of the following conditions are met, your |
534 | application has the potential to not behave correctly when run on the | 528 | application has the potential to not behave correctly when run on the |
535 | target: | 529 | target: |
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 | ||
544 | If both of these conditions exist, your application will not behave as | 538 | If both of these conditions are met, your application will not behave as |
545 | expected. The reason for this misbehavior is because the | 539 | expected. 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. |
547 | libraries) on which your new application depends. The assumption is that | 541 | libraries) on which your new application depends. The assumption is that |
@@ -562,8 +556,7 @@ Use the ``devtool undeploy-target`` command to remove deployed build | |||
562 | output from the target machine. For the ``devtool undeploy-target`` | 556 | output from the target machine. For the ``devtool undeploy-target`` |
563 | command to work, you must have previously used the | 557 | command 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>`" |
565 | command. | 559 | command:: |
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 | ||
584 | The following example creates a new workspace layer in your current | 577 | The following example creates a new workspace layer in your current |
585 | working and by default names the workspace layer "workspace": | 578 | working and by default names the workspace layer "workspace":: |
586 | :: | ||
587 | 579 | ||
588 | $ devtool create-workspace | 580 | $ devtool create-workspace |
589 | 581 | ||
590 | You can create a workspace layer anywhere by supplying a pathname with | 582 | You can create a workspace layer anywhere by supplying a pathname with |
591 | the command. The following command creates a new workspace layer named | 583 | the 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 | |||
603 | workspace. Information includes the paths to their respective external | 594 | workspace. Information includes the paths to their respective external |
604 | source trees. | 595 | source trees. |
605 | 596 | ||
606 | The ``devtool status`` command has no command-line options: | 597 | The ``devtool status`` command has no command-line options:: |
607 | :: | ||
608 | 598 | ||
609 | $ devtool status | 599 | $ devtool status |
610 | 600 | ||
611 | Following is sample output after using | 601 | Here 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>` |
613 | to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory: | 603 | to 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 @@ | |||
1 | DESCRIPTION = "GNU Helloworld application" | ||
2 | SECTION = "examples" | ||
3 | LICENSE = "GPLv3" | ||
4 | LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504" | ||
5 | |||
6 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
7 | SRC_URI[sha256sum] = "31e066137a962676e89f69d1b65382de95a7ef7d914b8cb956f41ea72e0f516b" | ||
8 | |||
9 | inherit 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 | |||
3 | int 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 @@ | |||
1 | DESCRIPTION = "Simple helloworld application" | ||
2 | SECTION = "examples" | ||
3 | LICENSE = "MIT" | ||
4 | LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" | ||
5 | |||
6 | SRC_URI = "file://helloworld.c" | ||
7 | |||
8 | S = "${WORKDIR}" | ||
9 | |||
10 | do_compile() { | ||
11 | ${CC} ${LDFLAGS} helloworld.c -o helloworld | ||
12 | } | ||
13 | |||
14 | do_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 @@ | |||
1 | require recipes-graphics/xorg-lib/xorg-lib-common.inc | ||
2 | |||
3 | DESCRIPTION = "X11 Pixmap library" | ||
4 | LICENSE = "X-BSD" | ||
5 | LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" | ||
6 | DEPENDS += "libxext" | ||
7 | PR = "r2" | ||
8 | PE = "1" | ||
9 | |||
10 | XORG_PN = "libXpm" | ||
11 | |||
12 | PACKAGES =+ "sxpm cxpm" | ||
13 | FILES_cxpm = "${bindir}/cxpm" | ||
14 | FILES_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 @@ | |||
1 | DESCRIPTION = "Tools for managing memory technology devices." | ||
2 | SECTION = "base" | ||
3 | DEPENDS = "zlib" | ||
4 | HOMEPAGE = "http://www.linux-mtd.infradead.org/" | ||
5 | LICENSE = "GPLv2" | ||
6 | LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ | ||
7 | file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" | ||
8 | |||
9 | SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz" | ||
10 | |||
11 | CFLAGS_prepend = "-I ${S}/include " | ||
12 | |||
13 | do_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 @@ | |||
4 | FAQ | 4 | FAQ |
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 | 9 | General questions |
10 | ================= | ||
11 | |||
12 | How does Poky differ from OpenEmbedded? | ||
13 | --------------------------------------- | ||
14 | |||
15 | The term ``Poky`` refers to the specific reference build | ||
10 | system that the Yocto Project provides. Poky is based on | 16 | system 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 |
12 | generic term used here for the build system is the "OpenEmbedded build | 18 | generic 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 | |||
15 | first before being pulled back into Poky. This practice benefits both | 21 | first before being pulled back into Poky. This practice benefits both |
16 | projects immediately. | 22 | projects immediately. |
17 | 23 | ||
18 | **Q:** My development system does not meet the required Git, tar, and | 24 | How can you claim Poky / OpenEmbedded-Core is stable? |
19 | Python versions. In particular, I do not have Python 3.5.0 or greater. | 25 | ----------------------------------------------------- |
20 | Can I still use the Yocto Project? | ||
21 | |||
22 | **A:** You can get the required tools on your host development system a | ||
23 | couple different ways (i.e. building a tarball or downloading a | ||
24 | tarball). See the | ||
25 | ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" | ||
26 | section 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; | 27 | There 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? | 40 | Are 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 | 43 | See :yocto_wiki:`Products that use the Yocto Project |
46 | Support Package (BSP) layer for it. For more information on how to | 44 | </Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project |
47 | create a BSP layer, see the | 45 | Wiki. Don't hesitate to contribute to this page if you know other such |
48 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 46 | products. |
49 | section in the Yocto Project Development Tasks Manual and the | ||
50 | :doc:`/bsp-guide/index`. | ||
51 | 47 | ||
52 | Usually, if the board is not completely exotic, adding support in the | 48 | Building environment |
53 | Yocto Project is fairly straightforward. | 49 | ==================== |
54 | 50 | ||
55 | **Q:** Are there any products built using the OpenEmbedded build system? | 51 | Missing dependencies on the development system? |
52 | ----------------------------------------------- | ||
56 | 53 | ||
57 | **A:** The software running on the `Vernier | 54 | If your development system does not meet the required Git, tar, and |
58 | LabQuest <https://vernier.com/labquest/>`__ is built using the | 55 | Python versions, you can get the required tools on your host development |
59 | OpenEmbedded build system. See the `Vernier | 56 | system in different ways (i.e. building a tarball or downloading a |
60 | LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website | 57 | tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" |
61 | for more information. There are a number of pre-production devices using | 58 | section for steps on how to update your build tools. |
62 | the OpenEmbedded build system and the Yocto Project team announces them | ||
63 | as soon as they are released. | ||
64 | 59 | ||
65 | **Q:** What does the OpenEmbedded build system produce as output? | 60 | How 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 | 63 | The way the build system obtains source code is highly |
68 | various formats, the output of an OpenEmbedded build depends on how you | 64 | configurable. You can setup the build system to get source code in most |
69 | start it. Usually, the output is a flashable image ready for the target | 65 | environments if HTTP transport is available. |
70 | device. | ||
71 | 66 | ||
72 | **Q:** How do I add my package to the Yocto Project? | 67 | When the build system searches for source code, it first tries the local |
68 | download 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 | 72 | Assuming your distribution is "poky", the OpenEmbedded build system uses |
75 | information on how to create a BitBake recipe, see the | 73 | the Yocto Project source :term:`PREMIRRORS` by default for SCM-based |
76 | ":ref:`dev-manual/common-tasks:writing a new recipe`" | 74 | sources, upstreams for normal tarballs, and then falls back to a number |
77 | section in the Yocto Project Development Tasks Manual. | 75 | of other mirrors including the Yocto Project source mirror if those |
76 | fail. | ||
77 | |||
78 | As an example, you could add a specific server for the build system to | ||
79 | attempt 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 = "\ |
80 | image 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 | 88 | These changes cause the build system to intercept Git, FTP, HTTP, and |
83 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | 89 | HTTPS requests and direct them to the ``http://`` sources mirror. You |
84 | then upgrade the packages using the package tools on the device, much | 90 | can use ``file://`` URLs to point to local directories or network shares |
85 | like on a desktop distribution such as Ubuntu or Fedora. However, | 91 | as well. |
86 | package management on the target is entirely optional. | ||
87 | 92 | ||
88 | **Q:** I see the error | 93 | Another option is to set:: |
89 | '``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is | ||
90 | wrong? | ||
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 | 97 | This statement tells BitBake to issue an error |
96 | system is trying to download sources. Is something wrong? | 98 | instead of trying to access the Internet. This technique is useful if |
99 | you want to ensure code builds only from local sources. | ||
97 | 100 | ||
98 | **A:** Nothing is wrong. The OpenEmbedded build system checks any | 101 | Here is another technique:: |
99 | configured source mirrors before downloading from the upstream sources. | 102 | |
100 | The build system does this searching for both source archives and | 103 | BB_FETCH_PREMIRRORONLY = "1" |
101 | pre-checked out versions of SCM-managed software. These checks help in | ||
102 | large installations because it can reduce load on the SCM servers | ||
103 | themselves. The address above is one of the default mirrors configured | ||
104 | into the build system. Consequently, if an upstream source disappears, | ||
105 | the 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 | 105 | This statement limits the build system to pulling source from the |
108 | but the package is being marked as machine-specific in all cases, how do | 106 | :term:`PREMIRRORS` only. Again, this technique is useful for reproducing |
109 | I prevent this? | 107 | builds. |
110 | 108 | ||
111 | **A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file | 109 | Here is yet another technique:: |
112 | but make sure the package is manually marked as machine-specific for the | ||
113 | case 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" |
118 | that? | 112 | |
113 | This statement tells the build system to generate mirror tarballs. This | ||
114 | technique is useful if you want to create a mirror server. If not, | ||
115 | however, the technique can simply waste time during the build. | ||
119 | 116 | ||
120 | **A:** Most source fetching by the OpenEmbedded build system is done by | 117 | Finally, consider an example where you are behind an HTTP-only firewall. |
118 | You could make the following changes to the ``local.conf`` configuration | ||
119 | file 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 | |||
128 | These changes would cause the build system to successfully fetch source | ||
129 | over HTTP and any network accesses to anything other than the | ||
130 | :term:`PREMIRRORS` would fail. | ||
131 | |||
132 | Most 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 |
123 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user | 135 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user |
124 | file. | 136 | file. |
125 | 137 | ||
126 | Following is the applicable code for setting various proxy types in the | 138 | Here 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. |
128 | To use them, remove the comments: :: | 140 | To 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 | ||
151 | The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``, | ||
152 | and ``all_proxy`` set as to standard shell environment variables to redirect | ||
153 | requests through proxy servers. | ||
154 | |||
139 | The Yocto Project also includes a | 155 | The 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 |
141 | and Git proxy servers if needed. For more information on setting up | 157 | how to configure CVS and Git proxy servers if needed. |
142 | various proxy types and configuring proxy servers, see the | ||
143 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" | ||
144 | Wiki 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 |
149 | used 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>`" |
150 | the build in some way such as ``quilt-native``, which is used to apply | 163 | Wiki page. |
151 | patches. The non-native version is the one that runs on the target | 164 | |
152 | device. | 165 | Using the OpenEmbedded Build system |
166 | =================================== | ||
167 | |||
168 | How do I use an external toolchain? | ||
169 | ----------------------------------- | ||
170 | |||
171 | See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`" | ||
172 | section in the Development Task manual. | ||
173 | |||
174 | Why do I get chmod permission issues? | ||
175 | ------------------------------------- | ||
153 | 176 | ||
154 | **Q:** I'm seeing random build failures. Help?! | 177 | If you see the error |
178 | ``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``, | ||
179 | you are probably running the build on an NTFS filesystem. Instead, | ||
180 | run 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 | 183 | I see many 404 errors trying to download sources. Is anything wrong? |
184 | -------------------------------------------------------------------- | ||
185 | |||
186 | Nothing is wrong. The OpenEmbedded build system checks any | ||
187 | configured source mirrors before downloading from the upstream sources. | ||
188 | The build system does this searching for both source archives and | ||
189 | pre-checked out versions of SCM-managed software. These checks help in | ||
190 | large installations because it can reduce load on the SCM servers | ||
191 | themselves. This can also allow builds to continue to work if an | ||
192 | upstream source disappears. | ||
193 | |||
194 | Why do I get random build failures? | ||
195 | ----------------------------------- | ||
196 | |||
197 | If the same build is failing in totally different and random | ||
157 | ways, the most likely explanation is: | 198 | ways, 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 | |||
166 | single-bit failures in any of these areas. True random failures have | 207 | single-bit failures in any of these areas. True random failures have |
167 | always been traced back to hardware or virtualization issues. | 208 | always been traced back to hardware or virtualization issues. |
168 | 209 | ||
169 | **Q:** When I try to build a native recipe, the build fails with | 210 | Why 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 | 213 | When you try to build a native recipe, you may get an error message that |
173 | not in use but ``iconv.h`` has been included from ``libiconv``, you need | 214 | indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been |
174 | to check to see if you have a previously installed version of the header | 215 | included from ``libiconv``:: |
175 | file 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 | ||
180 | If you find a previously installed | 219 | When this happens, you need to check whether you have a previously |
181 | file, you should either uninstall it or temporarily rename it and try | 220 | installed version of the header file in ``/usr/local/include/``. |
182 | the build again. | 221 | If that's the case, you should either uninstall it or temporarily rename |
222 | it and try the build again. | ||
183 | 223 | ||
184 | This issue is just a single manifestation of "system leakage" issues | 224 | This issue is just a single manifestation of "system leakage" issues |
185 | caused when the OpenEmbedded build system finds and uses previously | 225 | caused when the OpenEmbedded build system finds and uses previously |
186 | installed files during a native build. This type of issue might not be | 226 | installed files during a native build. This type of issue might not be |
187 | limited to ``iconv.h``. Be sure that leakage cannot occur from | 227 | limited 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? | 230 | Why 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 | ||
193 | for the answer for your specific case. It is worth bearing in mind that | ||
194 | for GPL compliance, there needs to be enough information shipped to | ||
195 | allow someone else to rebuild and produce the same end result you are | ||
196 | shipping. This means sharing the source code, any patches applied to it, | ||
197 | and also any configuration information about how that package was | ||
198 | configured and built. | ||
199 | |||
200 | You can find more information on licensing in the | ||
201 | ":ref:`overview-manual/development-environment:licensing`" | ||
202 | section in the Yocto | ||
203 | Project Overview and Concepts Manual and also in the | ||
204 | ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
205 | section 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 | ||
211 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
212 | the ``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 | ||
218 | default? | ||
219 | |||
220 | **A:** The default interfaces file provided by the netbase recipe does | ||
221 | not automatically bring up network interfaces. Therefore, you will need | ||
222 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
223 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
224 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
225 | information on creating these types of miscellaneous recipe files. | ||
226 | |||
227 | For 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 | ||
235 | 1.3 times the size of the populated root filesystem. To affect the image | ||
236 | size, 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 | ||
259 | of the tools the OpenEmbedded build system depends on, such as | ||
260 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
261 | situation 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 | ||
266 | is primarily controlled with the ``TCMODE`` variable. This variable | ||
267 | controls which ``tcmode-*.inc`` file to include from the | ||
268 | ``meta/conf/distro/include`` directory within the :term:`Source Directory`. | ||
269 | |||
270 | The default value of ``TCMODE`` is "default", which tells the | ||
271 | OpenEmbedded build system to use its internally built toolchain (i.e. | ||
272 | ``tcmode-default.inc``). However, other patterns are accepted. In | ||
273 | particular, "external-\*" refers to external toolchains. One example is | ||
274 | the Sourcery G++ Toolchain. The support for this toolchain resides in | ||
275 | the separate ``meta-sourcery`` layer at | ||
276 | https://github.com/MentorEmbedded/meta-sourcery/. | ||
277 | |||
278 | In addition to the toolchain configuration, you also need a | ||
279 | corresponding toolchain recipe file. This recipe file needs to package | ||
280 | up 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 | ||
284 | will it work behind my firewall or proxy server? | ||
285 | 232 | ||
286 | **A:** The way the build system obtains source code is highly | 233 | Files provided by your native recipe could be missing from the native |
287 | configurable. You can setup the build system to get source code in most | 234 | sysroot, your recipe could also be installing to the wrong place, or you |
288 | environments if HTTP transport is available. | 235 | could be getting permission errors during the :ref:`ref-tasks-install` |
289 | 236 | task in your recipe. | |
290 | When the build system searches for source code, it first tries the local | ||
291 | download directory. If that location fails, Poky tries | ||
292 | :term:`PREMIRRORS`, the upstream source, and then | ||
293 | :term:`MIRRORS` in that order. | ||
294 | |||
295 | Assuming your distribution is "poky", the OpenEmbedded build system uses | ||
296 | the Yocto Project source ``PREMIRRORS`` by default for SCM-based | ||
297 | sources, upstreams for normal tarballs, and then falls back to a number | ||
298 | of other mirrors including the Yocto Project source mirror if those | ||
299 | fail. | ||
300 | 237 | ||
301 | As an example, you could add a specific server for the build system to | 238 | This situation happens when the build system used by a package does not |
302 | attempt before any others by adding something like the following to the | 239 | recognize the environment variables supplied to it by :term:`BitBake`. The |
303 | ``local.conf`` configuration file: :: | 240 | incident that prompted this FAQ entry involved a Makefile that used an |
241 | environment variable named ``BINDIR`` instead of the more standard | ||
242 | variable ``bindir``. The makefile's hardcoded default value of | ||
243 | "/usr/bin" worked most of the time, but not for the recipe's ``-native`` | ||
244 | variant. For another example, permission errors might be caused by a | ||
245 | Makefile that ignores ``DESTDIR`` or uses a different name for that | ||
246 | environment variable. Check the build system of the package to see if | ||
247 | these kinds of issues exist. | ||
304 | 248 | ||
305 | PREMIRRORS_prepend = "\ | 249 | Can 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 | ||
311 | These changes cause the build system to intercept Git, FTP, HTTP, and | 252 | Yes --- you can easily do this. When you use BitBake to build an |
312 | HTTPS requests and direct them to the ``http://`` sources mirror. You | 253 | image, all the build output goes into the directory created when you run |
313 | can use ``file://`` URLs to point to local directories or network shares | 254 | the build environment setup script (i.e. :ref:`structure-core-script`). |
314 | as well. | 255 | By default, this :term:`Build Directory` is named ``build`` but can be named |
256 | anything you want. | ||
315 | 257 | ||
316 | Aside from the previous technique, these options also exist: | 258 | Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the |
317 | :: | 259 | build output yet preserve any source code or downloaded files from |
260 | previous builds, simply remove the ``tmp`` directory. | ||
318 | 261 | ||
319 | BB_NO_NETWORK = "1" | 262 | Customizing generated images |
263 | ============================ | ||
320 | 264 | ||
321 | This statement tells BitBake to issue an error | 265 | What does the OpenEmbedded build system produce as output? |
322 | instead of trying to access the Internet. This technique is useful if | 266 | ---------------------------------------------------------- |
323 | you want to ensure code builds only from local sources. | ||
324 | 267 | ||
325 | Here is another technique: | 268 | Because you can use the same set of recipes to create output of |
326 | :: | 269 | various formats, the output of an OpenEmbedded build depends on how you |
270 | start it. Usually, the output is a flashable image ready for the target | ||
271 | device. | ||
327 | 272 | ||
328 | BB_FETCH_PREMIRRORONLY = "1" | 273 | How do I make the Yocto Project support my board? |
274 | ------------------------------------------------- | ||
329 | 275 | ||
330 | This statement | 276 | Support for an additional board is added by creating a Board |
331 | limits the build system to pulling source from the ``PREMIRRORS`` only. | 277 | Support Package (BSP) layer for it. For more information on how to |
332 | Again, this technique is useful for reproducing builds. | 278 | create a BSP layer, see the |
279 | ":ref:`dev-manual/layers:understanding and creating layers`" | ||
280 | section in the Yocto Project Development Tasks Manual and the | ||
281 | :doc:`/bsp-guide/index`. | ||
333 | 282 | ||
334 | Here is another technique: | 283 | Usually, if the board is not completely exotic, adding support in the |
335 | :: | 284 | Yocto Project is fairly straightforward. |
336 | 285 | ||
337 | BB_GENERATE_MIRROR_TARBALLS = "1" | 286 | How do I make the Yocto Project support my package? |
287 | --------------------------------------------------- | ||
338 | 288 | ||
339 | This | 289 | To add a package, you need to create a BitBake recipe. For |
340 | statement tells the build system to generate mirror tarballs. This | 290 | information on how to create a BitBake recipe, see the |
341 | technique is useful if you want to create a mirror server. If not, | 291 | ":ref:`dev-manual/new-recipe:writing a new recipe`" |
342 | however, the technique can simply waste time during the build. | 292 | section in the Yocto Project Development Tasks Manual. |
343 | 293 | ||
344 | Finally, consider an example where you are behind an HTTP-only firewall. | 294 | What do I need to ship for license compliance? |
345 | You could make the following changes to the ``local.conf`` configuration | 295 | ---------------------------------------------- |
346 | file as long as the ``PREMIRRORS`` server is current: :: | ||
347 | 296 | ||
348 | PREMIRRORS_prepend = "\ | 297 | This is a difficult question and you need to consult your lawyer |
349 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | 298 | for the answer for your specific case. It is worth bearing in mind that |
350 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | 299 | for GPL compliance, there needs to be enough information shipped to |
351 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | 300 | allow someone else to rebuild and produce the same end result you are |
352 | BB_FETCH_PREMIRRORONLY = "1" | 301 | shipping. This means sharing the source code, any patches applied to it, |
302 | and also any configuration information about how that package was | ||
303 | configured and built. | ||
353 | 304 | ||
354 | These changes would cause the build system to successfully fetch source | 305 | You can find more information on licensing in the |
355 | over HTTP and any network accesses to anything other than the | 306 | ":ref:`overview-manual/development-environment:licensing`" |
356 | ``PREMIRRORS`` would fail. | 307 | section 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`" | ||
309 | section in the Yocto Project Development Tasks Manual. | ||
357 | 310 | ||
358 | The build system also honors the standard shell environment variables | 311 | Do I have to make a full reflash after recompiling one package? |
359 | ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to | 312 | --------------------------------------------------------------- |
360 | redirect requests through proxy servers. | ||
361 | 313 | ||
362 | .. note:: | 314 | The OpenEmbedded build system can build packages in various |
315 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | ||
316 | then upgrade only the modified packages using the package tools on the device, | ||
317 | much like on a desktop distribution such as Ubuntu or Fedora. However, | ||
318 | package management on the target is entirely optional. | ||
363 | 319 | ||
364 | You can find more information on the | 320 | How 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? | 323 | If you have machine-specific data in a package for one machine only |
324 | but the package is being marked as machine-specific in all cases, | ||
325 | you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file. | ||
326 | However, but make sure the package is manually marked as machine-specific for the | ||
327 | case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` | ||
328 | is 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 | 330 | What's the difference between ``target`` and ``target-native``? |
371 | image, all the build output goes into the directory created when you run | 331 | --------------------------------------------------------------- |
372 | the build environment setup script (i.e. | ||
373 | :ref:`structure-core-script`). By default, this :term:`Build Directory` | ||
374 | is named ``build`` but can be named | ||
375 | anything you want. | ||
376 | 332 | ||
377 | Within the Build Directory, is the ``tmp`` directory. To remove all the | 333 | The ``*-native`` targets are designed to run on the system being |
378 | build output yet preserve any source code or downloaded files from | 334 | used for the build. These are usually tools that are needed to assist |
379 | previous builds, simply remove the ``tmp`` directory. | 335 | the build in some way such as ``quilt-native``, which is used to apply |
336 | patches. The non-native version is the one that runs on the target | ||
337 | device. | ||
380 | 338 | ||
381 | **Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for | 339 | Why 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 | 342 | Executables and libraries might need to be used from a directory |
385 | other than the directory into which they were initially installed. | 343 | other than the directory into which they were initially installed. |
386 | Complicating this situation is the fact that sometimes these executables | 344 | Complicating this situation is the fact that sometimes these executables |
387 | and libraries are compiled with the expectation of being run from that | 345 | and 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 | |||
408 | forth. | 366 | forth. |
409 | 367 | ||
410 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. | 368 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. |
411 | However, when the recipe builds a | 369 | However, when the recipe builds a native program (i.e. one that is |
412 | native program (i.e. one that is intended to run on the build machine), | 370 | intended to run on the build machine), that program is never installed |
413 | that program is never installed directly to the build machine's root | 371 | directly to the build machine's root file system. Consequently, the build |
414 | file system. Consequently, the build system uses paths within the Build | 372 | system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` |
415 | Directory for ``DESTDIR``, ``bindir`` and related variables. To better | 373 | and related variables. To better understand this, consider the following |
416 | understand this, consider the following two paths where the first is | 374 | two paths (artificially broken across lines for readability) where the |
417 | relatively normal and the second is not: | 375 | first 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 | ||
433 | Even if the paths look unusual, | 384 | Even if the paths look unusual, they both are correct --- the first for |
434 | they both are correct - the first for a target and the second for a | 385 | a target and the second for a native recipe. These paths are a consequence |
435 | native recipe. These paths are a consequence of the ``DESTDIR`` | 386 | of the ``DESTDIR`` mechanism and while they appear strange, they are correct |
436 | mechanism and while they appear strange, they are correct and in | 387 | and in practice very effective. |
437 | practice very effective. | ||
438 | 388 | ||
439 | **Q:** The files provided by my ``*-native`` recipe do not appear to be | 389 | How do I create images with more free space? |
440 | available to other recipes. Files are missing from the native sysroot, | 390 | -------------------------------------------- |
441 | my recipe is installing to the wrong place, or I am getting permissions | ||
442 | errors 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 | 392 | By default, the OpenEmbedded build system creates images that are |
445 | environment variables supplied to it by :term:`BitBake`. The | 393 | 1.3 times the size of the populated root filesystem. To affect the image |
446 | incident that prompted this FAQ entry involved a Makefile that used an | 394 | size, you need to set various configurations: |
447 | environment variable named ``BINDIR`` instead of the more standard | 395 | |
448 | variable ``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 |
450 | variant. For another example, permissions errors might be caused by a | 398 | the size of the image in Kbytes. The build system determines the size |
451 | Makefile that ignores ``DESTDIR`` or uses a different name for that | 399 | by taking into account the initial root filesystem size before any |
452 | environment variable. Check the the build system to see if these kinds | 400 | modifications such as requested size for the image and any requested |
453 | of 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 |
456 | changing 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. |
459 | it. 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 |
461 | file will ensure the binary is unchanged. The other less obvious thing that can | 409 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` |
462 | happen 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 |
464 | image will not be prelinked meaning the binaries would be unchanged. | 412 | :term:`IMAGE_ROOTFS_SIZE`. |
413 | |||
414 | Why aren't spaces in path names supported? | ||
415 | ------------------------------------------ | ||
416 | |||
417 | The Yocto Project team has tried to do this before but too many | ||
418 | of the tools the OpenEmbedded build system depends on, such as | ||
419 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
420 | situation changes, the team will not support spaces in pathnames. | ||
421 | |||
422 | I'm adding a binary in a recipe. Why is it different in the image? | ||
423 | ------------------------------------------------------------------ | ||
424 | |||
425 | The first most obvious change is the system stripping debug symbols from | ||
426 | it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being | ||
427 | stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols | ||
428 | being split into a separate file will ensure the binary is unchanged. | ||
429 | |||
430 | Issues on the running system | ||
431 | ============================ | ||
432 | |||
433 | How do I disable the cursor on my touchscreen device? | ||
434 | ----------------------------------------------------- | ||
435 | |||
436 | You need to create a form factor file as described in the | ||
437 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
438 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
439 | the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:: | ||
440 | |||
441 | HAVE_TOUCHSCREEN=1 | ||
442 | |||
443 | How to always bring up connected network interfaces? | ||
444 | ---------------------------------------------------- | ||
445 | |||
446 | The default interfaces file provided by the netbase recipe does | ||
447 | not automatically bring up network interfaces. Therefore, you will need | ||
448 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
449 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
450 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
451 | information on creating these types of miscellaneous recipe files. | ||
452 | |||
453 | For 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 | ||
7 | This chapter provides a reference of shipped machine and distro features | 7 | This chapter provides a reference of shipped machine and distro features |
8 | you can include as part of your image, a reference on image features you | 8 | you can include as part of your image, a reference on image features you |
9 | can select, and a reference on feature backfilling. | 9 | can select, and a reference on :ref:`ref-features-backfill`. |
10 | 10 | ||
11 | Features provide a mechanism for working out which packages should be | 11 | Features provide a mechanism for working out which packages should be |
12 | included in the generated images. Distributions can select which | 12 | included in the generated images. Distributions can select which |
13 | features they want to support through the ``DISTRO_FEATURES`` variable, | 13 | features they want to support through the :term:`DISTRO_FEATURES` variable, |
14 | which is set or appended to in a distribution's configuration file such | 14 | which is set or appended to in a distribution's configuration file such |
15 | as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. | 15 | as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. |
16 | Machine features are set in the ``MACHINE_FEATURES`` variable, which is | 16 | Machine features are set in the :term:`MACHINE_FEATURES` variable, which is |
17 | set in the machine configuration file and specifies the hardware | 17 | set in the machine configuration file and specifies the hardware |
18 | features for a given machine. | 18 | features for a given machine. |
19 | 19 | ||
@@ -26,8 +26,7 @@ One method you can use to determine which recipes are checking to see if | |||
26 | a particular feature is contained or not is to ``grep`` through the | 26 | a 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 |
28 | discovers the recipes whose build is potentially changed based on a | 28 | discovers the recipes whose build is potentially changed based on a |
29 | given feature: | 29 | given 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 | |||
101 | a package or packages. In most cases, the presence or absence of a | 102 | a package or packages. In most cases, the presence or absence of a |
102 | feature translates to the appropriate option supplied to the configure | 103 | feature translates to the appropriate option supplied to the configure |
103 | script during the :ref:`ref-tasks-configure` task for | 104 | script during the :ref:`ref-tasks-configure` task for |
104 | the recipes that optionally support the feature. | 105 | the recipes that optionally support the feature. Appropriate options |
106 | must be supplied, and enabling/disabling :term:`PACKAGECONFIG` for the | ||
107 | concerned packages is one way of supplying such options. | ||
105 | 108 | ||
106 | Some distro features are also machine features. These select features | 109 | Some distro features are also machine features. These select features |
107 | make sense to be controlled both at the machine and distribution | 110 | make 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 |
110 | information. | 113 | information. |
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 | |||
112 | This list only represents features as shipped with the Yocto Project | 122 | This list only represents features as shipped with the Yocto Project |
113 | metadata: | 123 | metadata, 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 | ||
189 | Image Features | 263 | Image Features |
@@ -197,19 +271,21 @@ you can add several different predefined packages such as development | |||
197 | utilities or packages with debug information needed to investigate | 271 | utilities or packages with debug information needed to investigate |
198 | application problems or profile applications. | 272 | application problems or profile applications. |
199 | 273 | ||
200 | The following image features are available for all images: | 274 | The 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 | ||
254 | Some image features are available only when you inherit the | 365 | Some 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 |
256 | these valid features is as follows: | 367 | these 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: | |||
293 | Feature Backfilling | 421 | Feature Backfilling |
294 | =================== | 422 | =================== |
295 | 423 | ||
296 | Sometimes it is necessary in the OpenEmbedded build system to extend | 424 | Sometimes it is necessary in the OpenEmbedded build system to |
297 | :term:`MACHINE_FEATURES` or | 425 | add 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 |
299 | that was previously enabled and not able to be disabled. For these | 427 | distributions or machine definitions to opt out of such new |
300 | cases, we need to add an additional feature item to appear in one of | 428 | features, to retain the same overall level of functionality. |
301 | these variables, but we do not want to force developers who have | 429 | |
302 | existing values of the variables in their configuration to add the new | 430 | To make this possible, the OpenEmbedded build system has a mechanism to |
303 | feature in order to retain the same overall level of functionality. | 431 | automatically "backfill" features into existing distro or machine |
304 | Thus, the OpenEmbedded build system has a mechanism to automatically | ||
305 | "backfill" these added features into existing distro or machine | ||
306 | configurations. You can see the list of features for which this is done | 432 | configurations. You can see the list of features for which this is done |
307 | by finding the | 433 | by 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. |
310 | variables in the ``meta/conf/bitbake.conf`` file. | 436 | |
311 | 437 | These two variables are paired with the | |
312 | Because such features are backfilled by default into all configurations | ||
313 | as described in the previous paragraph, developers who wish to disable | ||
314 | the new features need to be able to selectively prevent the backfilling | ||
315 | from occurring. They can do this by adding the undesired feature or | ||
316 | features to the | ||
317 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 438 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
318 | or | 439 | and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables |
319 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | 440 | which allow distro or machine configuration maintainers to `consider` any |
320 | variables for distro features and machine features respectively. | 441 | added feature, and decide when they wish to keep or exclude such feature, |
321 | 442 | thus preventing the backfilling from happening. | |
322 | Here are two examples to help illustrate feature backfilling: | 443 | |
323 | 444 | Here 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 | *********************** | ||
4 | Manual 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 | ||
28 | From within the ``poky`` Git repository, you can use the following | 29 | From within the ``poky`` Git repository, you can use the following |
29 | command to display the list of directories within the :term:`Source Directory` | 30 | command to display the list of directories within the :term:`Source Directory` |
30 | that contain image recipe files: :: | 31 | that contain image recipe files:: |
31 | 32 | ||
32 | $ ls meta*/recipes*/images/*.bb | 33 | $ ls meta*/recipes*/images/*.bb |
33 | 34 | ||
34 | Following is a list of supported recipes: | 35 | Here 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 | ||
32 | Either of these commands creates a partition on the system and uses the | 32 | Either of these commands creates a partition on the system and uses the |
33 | following syntax: | 33 | following syntax:: |
34 | :: | ||
35 | 34 | ||
36 | part [mntpoint] | 35 | part [mntpoint] |
37 | partition [mntpoint] | 36 | partition [mntpoint] |
38 | 37 | ||
39 | If you do not | 38 | If 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 | ||
61 | Here is an example that uses "/" as the mountpoint. The command uses | 61 | Here 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 | ||
67 | Here is a list that describes other supported options you can use with | 66 | Here is a list that describes other supported options you can use with |
68 | the ``part`` and ``partition`` commands: | 67 | the ``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 | |||
3 | Moving to the Yocto Project 1.3 Release | ||
4 | ======================================= | ||
5 | |||
6 | This section provides migration information for moving to the Yocto | ||
7 | Project 1.3 Release from the prior release. | ||
8 | |||
9 | .. _1.3-local-configuration: | ||
10 | |||
11 | Local Configuration | ||
12 | ------------------- | ||
13 | |||
14 | Differences include changes for | ||
15 | :term:`SSTATE_MIRRORS` and ``bblayers.conf``. | ||
16 | |||
17 | .. _migration-1.3-sstate-mirrors: | ||
18 | |||
19 | SSTATE_MIRRORS | ||
20 | ~~~~~~~~~~~~~~ | ||
21 | |||
22 | The shared state cache (sstate-cache), as pointed to by | ||
23 | :term:`SSTATE_DIR`, by default now has two-character | ||
24 | subdirectories to prevent issues arising from too many files in the same | ||
25 | directory. Also, native sstate-cache packages, which are built to run on | ||
26 | the host system, will go into a subdirectory named using the distro ID | ||
27 | string. If you copy the newly structured sstate-cache to a mirror | ||
28 | location (either local or remote) and then point to it in | ||
29 | :term:`SSTATE_MIRRORS`, you need to append "PATH" | ||
30 | to the end of the mirror URL so that the path used by BitBake before the | ||
31 | mirror substitution is appended to the path used to access the mirror. | ||
32 | Here is an example: :: | ||
33 | |||
34 | SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" | ||
35 | |||
36 | .. _migration-1.3-bblayers-conf: | ||
37 | |||
38 | bblayers.conf | ||
39 | ~~~~~~~~~~~~~ | ||
40 | |||
41 | The ``meta-yocto`` layer consists of two parts that correspond to the | ||
42 | Poky reference distribution and the reference hardware Board Support | ||
43 | Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``. | ||
44 | When running BitBake for the first time after upgrading, your | ||
45 | ``conf/bblayers.conf`` file will be updated to handle this change and | ||
46 | you will be asked to re-run or restart for the changes to take effect. | ||
47 | |||
48 | .. _1.3-recipes: | ||
49 | |||
50 | Recipes | ||
51 | ------- | ||
52 | |||
53 | Differences include changes for the following: | ||
54 | |||
55 | .. _migration-1.3-python-function-whitespace: | ||
56 | |||
57 | Python Function Whitespace | ||
58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
59 | |||
60 | All Python functions must now use four spaces for indentation. | ||
61 | Previously, an inconsistent mix of spaces and tabs existed, which made | ||
62 | extending these functions using ``_append`` or ``_prepend`` complicated | ||
63 | given that Python treats whitespace as syntactically significant. If you | ||
64 | are defining or extending any Python functions (e.g. | ||
65 | ``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in | ||
66 | custom recipes or classes, you need to ensure you are using consistent | ||
67 | four-space indentation. | ||
68 | |||
69 | .. _migration-1.3-proto=-in-src-uri: | ||
70 | |||
71 | proto= in SRC_URI | ||
72 | ~~~~~~~~~~~~~~~~~ | ||
73 | |||
74 | Any use of ``proto=`` in :term:`SRC_URI` needs to be | ||
75 | changed to ``protocol=``. In particular, this applies to the following | ||
76 | URIs: | ||
77 | |||
78 | - ``svn://`` | ||
79 | |||
80 | - ``bzr://`` | ||
81 | |||
82 | - ``hg://`` | ||
83 | |||
84 | - ``osc://`` | ||
85 | |||
86 | Other URIs were already using ``protocol=``. This change improves | ||
87 | consistency. | ||
88 | |||
89 | .. _migration-1.3-nativesdk: | ||
90 | |||
91 | nativesdk | ||
92 | ~~~~~~~~~ | ||
93 | |||
94 | The suffix ``nativesdk`` is now implemented as a prefix, which | ||
95 | simplifies a lot of the packaging code for ``nativesdk`` recipes. All | ||
96 | custom ``nativesdk`` recipes, which are relocatable packages that are | ||
97 | native to :term:`SDK_ARCH`, and any references need to | ||
98 | be updated to use ``nativesdk-*`` instead of ``*-nativesdk``. | ||
99 | |||
100 | .. _migration-1.3-task-recipes: | ||
101 | |||
102 | Task Recipes | ||
103 | ~~~~~~~~~~~~ | ||
104 | |||
105 | "Task" recipes are now known as "Package groups" and have been renamed | ||
106 | from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the | ||
107 | previous ``task-*`` names should work in most cases as there is an | ||
108 | automatic upgrade path for most packages. However, you should update | ||
109 | references in your own recipes and configurations as they could be | ||
110 | removed in future releases. You should also rename any custom ``task-*`` | ||
111 | recipes to ``packagegroup-*``, and change them to inherit | ||
112 | ``packagegroup`` instead of ``task``, as well as taking the opportunity | ||
113 | to remove anything now handled by ``packagegroup.bbclass``, such as | ||
114 | providing ``-dev`` and ``-dbg`` packages, setting | ||
115 | :term:`LIC_FILES_CHKSUM`, and so forth. See the | ||
116 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for | ||
117 | further details. | ||
118 | |||
119 | .. _migration-1.3-image-features: | ||
120 | |||
121 | IMAGE_FEATURES | ||
122 | ~~~~~~~~~~~~~~ | ||
123 | |||
124 | Image recipes that previously included ``apps-console-core`` in | ||
125 | :term:`IMAGE_FEATURES` should now include ``splash`` | ||
126 | instead to enable the boot-up splash screen. Retaining | ||
127 | ``apps-console-core`` will still include the splash screen but generates a | ||
128 | warning. The ``apps-x11-core`` and ``apps-x11-games`` ``IMAGE_FEATURES`` | ||
129 | features have been removed. | ||
130 | |||
131 | .. _migration-1.3-removed-recipes: | ||
132 | |||
133 | Removed Recipes | ||
134 | ~~~~~~~~~~~~~~~ | ||
135 | |||
136 | The following recipes have been removed. For most of them, it is | ||
137 | unlikely that you would have any references to them in your own | ||
138 | :term:`Metadata`. However, you should check your metadata | ||
139 | against 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 | |||
167 | In addition to the previously listed changes, the ``meta-demoapps`` | ||
168 | directory has also been removed because the recipes in it were not being | ||
169 | maintained and many had become obsolete or broken. Additionally, these | ||
170 | recipes were not parsed in the default configuration. Many of these | ||
171 | recipes are already provided in an updated and maintained form within | ||
172 | the 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 | |||
180 | Linux Kernel Naming | ||
181 | ------------------- | ||
182 | |||
183 | The naming scheme for kernel output binaries has been changed to now | ||
184 | include :term:`PE` as part of the filename: | ||
185 | :: | ||
186 | |||
187 | KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" | ||
188 | |||
189 | Because the ``PE`` variable is not set by default, these binary files | ||
190 | could result with names that include two dash characters. Here is an | ||
191 | example: :: | ||
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 @@ | |||
1 | Moving to the Yocto Project 1.4 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.4 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.4-bitbake: | ||
8 | |||
9 | BitBake | ||
10 | ------- | ||
11 | |||
12 | Differences 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 | |||
36 | Build Behavior | ||
37 | -------------- | ||
38 | |||
39 | Differences 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 | |||
68 | Proxies and Fetching Source | ||
69 | --------------------------- | ||
70 | |||
71 | A new ``oe-git-proxy`` script has been added to replace previous methods | ||
72 | of handling proxies and fetching source from Git. See the | ||
73 | ``meta-yocto/conf/site.conf.sample`` file for information on how to use | ||
74 | this script. | ||
75 | |||
76 | .. _migration-1.4-custom-interfaces-file-netbase-change: | ||
77 | |||
78 | Custom Interfaces File (netbase change) | ||
79 | --------------------------------------- | ||
80 | |||
81 | If you have created your own custom ``etc/network/interfaces`` file by | ||
82 | creating an append file for the ``netbase`` recipe, you now need to | ||
83 | create an append file for the ``init-ifupdown`` recipe instead, which | ||
84 | you can find in the :term:`Source Directory` at | ||
85 | ``meta/recipes-core/init-ifupdown``. For information on how to use | ||
86 | append files, see the | ||
87 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | ||
88 | section in the Yocto Project Development Tasks Manual. | ||
89 | |||
90 | .. _migration-1.4-remote-debugging: | ||
91 | |||
92 | Remote Debugging | ||
93 | ---------------- | ||
94 | |||
95 | Support for remote debugging with the Eclipse IDE is now separated into | ||
96 | an image feature (``eclipse-debug``) that corresponds to the | ||
97 | ``packagegroup-core-eclipse-debug`` package group. Previously, the | ||
98 | debugging feature was included through the ``tools-debug`` image | ||
99 | feature, which corresponds to the ``packagegroup-core-tools-debug`` | ||
100 | package group. | ||
101 | |||
102 | .. _migration-1.4-variables: | ||
103 | |||
104 | Variables | ||
105 | --------- | ||
106 | |||
107 | The 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 | |||
133 | Target Package Management with RPM | ||
134 | ---------------------------------- | ||
135 | |||
136 | If runtime package management is enabled and the RPM backend is | ||
137 | selected, Smart is now installed for package download, dependency | ||
138 | resolution, and upgrades instead of Zypper. For more information on how | ||
139 | to use Smart, run the following command on the target: | ||
140 | :: | ||
141 | |||
142 | smart --help | ||
143 | |||
144 | .. _migration-1.4-recipes-moved: | ||
145 | |||
146 | Recipes Moved | ||
147 | ------------- | ||
148 | |||
149 | The following recipes were moved from their previous locations because | ||
150 | they 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 | |||
178 | Removals and Renames | ||
179 | -------------------- | ||
180 | |||
181 | The 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 @@ | |||
1 | Moving to the Yocto Project 1.5 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.5 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.5-host-dependency-changes: | ||
8 | |||
9 | Host Dependency Changes | ||
10 | ----------------------- | ||
11 | |||
12 | The OpenEmbedded build system now has some additional requirements on | ||
13 | the 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 | |||
24 | If the Linux distribution you are using on your build host does not | ||
25 | provide packages for these, you can install and use the Buildtools | ||
26 | tarball, which provides an SDK-like environment containing them. | ||
27 | |||
28 | For more information on this requirement, see the | ||
29 | ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" | ||
30 | section. | ||
31 | |||
32 | .. _migration-1.5-atom-pc-bsp: | ||
33 | |||
34 | ``atom-pc`` Board Support Package (BSP) | ||
35 | --------------------------------------- | ||
36 | |||
37 | The ``atom-pc`` hardware reference BSP has been replaced by a | ||
38 | ``genericx86`` BSP. This BSP is not necessarily guaranteed to work on | ||
39 | all 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 | |||
49 | BitBake | ||
50 | ------- | ||
51 | |||
52 | The 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 | |||
78 | QA Warnings | ||
79 | ----------- | ||
80 | |||
81 | The 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 | |||
109 | Directory Layout Changes | ||
110 | ------------------------ | ||
111 | |||
112 | The 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 | |||
142 | Shortened Git ``SRCREV`` Values | ||
143 | ------------------------------- | ||
144 | |||
145 | BitBake will now shorten revisions from Git repositories from the normal | ||
146 | 40 characters down to 10 characters within :term:`SRCPV` | ||
147 | for improved usability in path and file names. This change should be | ||
148 | safe within contexts where these revisions are used because the chances | ||
149 | of spatially close collisions is very low. Distant collisions are not a | ||
150 | major issue in the way the values are used. | ||
151 | |||
152 | .. _migration-1.5-image-features: | ||
153 | |||
154 | ``IMAGE_FEATURES`` | ||
155 | ------------------ | ||
156 | |||
157 | The 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 | |||
182 | The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has | ||
183 | been introduced. You can find some of the implications for this change | ||
184 | :oe_git:`here </openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`. | ||
185 | The change also means that recipes that install files to ``/var/run`` | ||
186 | must 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 | |||
191 | Removal of Package Manager Database Within Image Recipes | ||
192 | -------------------------------------------------------- | ||
193 | |||
194 | The image ``core-image-minimal`` no longer adds | ||
195 | ``remove_packaging_data_files`` to | ||
196 | :term:`ROOTFS_POSTPROCESS_COMMAND`. | ||
197 | This addition is now handled automatically when "package-management" is | ||
198 | not in :term:`IMAGE_FEATURES`. If you have custom | ||
199 | image recipes that make this addition, you should remove the lines, as | ||
200 | they are not needed and might interfere with correct operation of | ||
201 | postinstall scripts. | ||
202 | |||
203 | .. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time: | ||
204 | |||
205 | Images Now Rebuild Only on Changes Instead of Every Time | ||
206 | -------------------------------------------------------- | ||
207 | |||
208 | The :ref:`ref-tasks-rootfs` and other related image | ||
209 | construction tasks are no longer marked as "nostamp". Consequently, they | ||
210 | will only be re-executed when their inputs have changed. Previous | ||
211 | versions of the OpenEmbedded build system always rebuilt the image when | ||
212 | requested rather when necessary. | ||
213 | |||
214 | .. _migration-1.5-task-recipes: | ||
215 | |||
216 | Task Recipes | ||
217 | ------------ | ||
218 | |||
219 | The previously deprecated ``task.bbclass`` has now been dropped. For | ||
220 | recipes that previously inherited from this class, you should rename | ||
221 | them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup | ||
222 | instead. | ||
223 | |||
224 | For more information, see the | ||
225 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section. | ||
226 | |||
227 | .. _migration-1.5-busybox: | ||
228 | |||
229 | BusyBox | ||
230 | ------- | ||
231 | |||
232 | By default, we now split BusyBox into two binaries: one that is suid | ||
233 | root for those components that need it, and another for the rest of the | ||
234 | components. Splitting BusyBox allows for optimization that eliminates | ||
235 | the ``tinylogin`` recipe as recommended by upstream. You can disable | ||
236 | this split by setting | ||
237 | :term:`BUSYBOX_SPLIT_SUID` to "0". | ||
238 | |||
239 | .. _migration-1.5-automated-image-testing: | ||
240 | |||
241 | Automated Image Testing | ||
242 | ----------------------- | ||
243 | |||
244 | A new automated image testing framework has been added through the | ||
245 | :ref:`testimage.bbclass <ref-classes-testimage*>` class. This | ||
246 | framework replaces the older ``imagetest-qemu`` framework. | ||
247 | |||
248 | You can learn more about performing automated image tests in the | ||
249 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | ||
250 | section in the Yocto Project Development Tasks Manual. | ||
251 | |||
252 | .. _migration-1.5-build-history: | ||
253 | |||
254 | Build History | ||
255 | ------------- | ||
256 | |||
257 | Following 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 | |||
271 | For more information on Build History, see the | ||
272 | ":ref:`dev-manual/common-tasks:maintaining build output quality`" | ||
273 | section in the Yocto Project Development Tasks Manual. | ||
274 | |||
275 | .. _migration-1.5-udev: | ||
276 | |||
277 | ``udev`` | ||
278 | -------- | ||
279 | |||
280 | Following 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 | |||
293 | Removed 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 | |||
321 | Other Changes | ||
322 | ------------- | ||
323 | |||
324 | Following 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 @@ | |||
1 | Moving to the Yocto Project 1.6 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.6 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.6-archiver-class: | ||
8 | |||
9 | ``archiver`` Class | ||
10 | ------------------ | ||
11 | |||
12 | The :ref:`archiver <ref-classes-archiver>` class has been rewritten | ||
13 | and its configuration has been simplified. For more details on the | ||
14 | source archiver, see the | ||
15 | ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
16 | section in the Yocto Project Development Tasks Manual. | ||
17 | |||
18 | .. _migration-1.6-packaging-changes: | ||
19 | |||
20 | Packaging Changes | ||
21 | ----------------- | ||
22 | |||
23 | The 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 | |||
43 | BitBake | ||
44 | ------- | ||
45 | |||
46 | The following changes have been made to :term:`BitBake`. | ||
47 | |||
48 | .. _migration-1.6-matching-branch-requirement-for-git-fetching: | ||
49 | |||
50 | Matching Branch Requirement for Git Fetching | ||
51 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
52 | |||
53 | When 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 | ||
56 | the branch using the following form: | ||
57 | :: | ||
58 | |||
59 | SRC_URI = "git://server.name/repository;branch=branchname" | ||
60 | |||
61 | If you do not specify a branch, BitBake looks in the default "master" branch. | ||
62 | |||
63 | Alternatively, if you need to bypass this check (e.g. if you are | ||
64 | fetching a revision corresponding to a tag that is not on any branch), | ||
65 | you can add ";nobranch=1" to the end of the URL within ``SRC_URI``. | ||
66 | |||
67 | .. _migration-1.6-bitbake-deps: | ||
68 | |||
69 | Python Definition substitutions | ||
70 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
71 | |||
72 | BitBake had some previously deprecated Python definitions within its | ||
73 | ``bb`` module removed. You should use their sub-module counterparts | ||
74 | instead: | ||
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 | |||
96 | SVK Fetcher | ||
97 | ~~~~~~~~~~~ | ||
98 | |||
99 | The SVK fetcher has been removed from BitBake. | ||
100 | |||
101 | .. _migration-1.6-bitbake-console-output: | ||
102 | |||
103 | Console Output Error Redirection | ||
104 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
105 | |||
106 | The 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 | ||
109 | will 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 | ||
118 | names contain underscores have the underscores replaced by hyphens for | ||
119 | the override so that they now function properly. For example, the task | ||
120 | override for :ref:`ref-tasks-populate_sdk` is | ||
121 | ``task-populate-sdk``. | ||
122 | |||
123 | .. _migration-1.6-variable-changes: | ||
124 | |||
125 | Changes to Variables | ||
126 | -------------------- | ||
127 | |||
128 | The following variables have changed. For information on the | ||
129 | OpenEmbedded 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 | ||
137 | not offer full POSIX locking and inode consistency and can cause | ||
138 | unexpected issues if used to store ``TMPDIR``. | ||
139 | |||
140 | The check for this occurs on startup. If ``TMPDIR`` is detected on an | ||
141 | NFS mount, an error occurs. | ||
142 | |||
143 | .. _migration-1.6-variable-changes-PRINC: | ||
144 | |||
145 | ``PRINC`` | ||
146 | ~~~~~~~~~ | ||
147 | |||
148 | The ``PRINC`` variable has been deprecated and triggers a warning if | ||
149 | detected during a build. For :term:`PR` increments on changes, | ||
150 | use the PR service instead. You can find out more about this service in | ||
151 | the ":ref:`dev-manual/common-tasks:working with a pr service`" | ||
152 | section in the Yocto Project Development Tasks Manual. | ||
153 | |||
154 | .. _migration-1.6-variable-changes-IMAGE_TYPES: | ||
155 | |||
156 | ``IMAGE_TYPES`` | ||
157 | ~~~~~~~~~~~~~~~ | ||
158 | |||
159 | The "sum.jffs2" option for :term:`IMAGE_TYPES` has | ||
160 | been replaced by the "jffs2.sum" option, which fits the processing | ||
161 | order. | ||
162 | |||
163 | .. _migration-1.6-variable-changes-COPY_LIC_MANIFEST: | ||
164 | |||
165 | ``COPY_LIC_MANIFEST`` | ||
166 | ~~~~~~~~~~~~~~~~~~~~~ | ||
167 | |||
168 | The :term:`COPY_LIC_MANIFEST` variable must now | ||
169 | be 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 | |||
176 | The :term:`COPY_LIC_DIRS` variable must now be set | ||
177 | to "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 | |||
184 | The ``PACKAGE_GROUP`` variable has been renamed to | ||
185 | :term:`FEATURE_PACKAGES` to more accurately | ||
186 | reflect its purpose. You can still use ``PACKAGE_GROUP`` but the | ||
187 | OpenEmbedded build system produces a warning message when it encounters | ||
188 | the variable. | ||
189 | |||
190 | .. _migration-1.6-variable-changes-variable-entry-behavior: | ||
191 | |||
192 | Preprocess and Post Process Command Variable Behavior | ||
193 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
194 | |||
195 | The following variables now expect a semicolon separated list of | ||
196 | functions 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 | |||
208 | For | ||
209 | migration purposes, you can simply wrap shell commands in a shell | ||
210 | function 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 | |||
219 | Package Test (ptest) | ||
220 | -------------------- | ||
221 | |||
222 | Package Tests (ptest) are built but not installed by default. For | ||
223 | information on using Package Tests, see the | ||
224 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | ||
225 | section in the Yocto Project Development Tasks Manual. For information on the | ||
226 | ``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`" | ||
227 | section. | ||
228 | |||
229 | .. _migration-1.6-build-changes: | ||
230 | |||
231 | Build Changes | ||
232 | ------------- | ||
233 | |||
234 | Separate build and source directories have been enabled by default for | ||
235 | selected recipes where it is known to work (a whitelist) and for all | ||
236 | recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In | ||
237 | future releases the :ref:`autotools <ref-classes-autotools>` class | ||
238 | will enable a separate build directory by default as well. Recipes | ||
239 | building Autotools-based software that fails to build with a separate | ||
240 | build directory should be changed to inherit from the | ||
241 | :ref:`autotools-brokensep <ref-classes-autotools>` class instead of | ||
242 | the ``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 | ||
250 | default. 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 | |||
270 | In 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 | |||
276 | Licensing | ||
277 | --------- | ||
278 | |||
279 | The top-level ``LICENSE`` file has been changed to better describe the | ||
280 | license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However, | ||
281 | the licensing itself remains unchanged. | ||
282 | |||
283 | Normally, this change would not cause any side-effects. However, some | ||
284 | recipes point to this file within | ||
285 | :term:`LIC_FILES_CHKSUM` (as | ||
286 | ``${COREBASE}/LICENSE``) and thus the accompanying checksum must be | ||
287 | changed from 3f40d7994397109285ec7b81fdeb3b58 to | ||
288 | 4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have | ||
289 | ``LIC_FILES_CHKSUM`` point to a file describing the license that is | ||
290 | distributed with the source that the recipe is building, if possible, | ||
291 | rather than pointing to ``${COREBASE}/LICENSE``. | ||
292 | |||
293 | .. _migration-1.6-cflags-options: | ||
294 | |||
295 | ``CFLAGS`` Options | ||
296 | ------------------ | ||
297 | |||
298 | The "-fpermissive" option has been removed from the default | ||
299 | :term:`CFLAGS` value. You need to take action on | ||
300 | individual recipes that fail when building with this option. You need to | ||
301 | either patch the recipes to fix the issues reported by the compiler, or | ||
302 | you need to add "-fpermissive" to ``CFLAGS`` in the recipes. | ||
303 | |||
304 | .. _migration-1.6-custom-images: | ||
305 | |||
306 | Custom Image Output Types | ||
307 | ------------------------- | ||
308 | |||
309 | Custom image output types, as selected using | ||
310 | :term:`IMAGE_FSTYPES`, must declare their | ||
311 | dependencies on other image types (if any) using a new | ||
312 | :term:`IMAGE_TYPEDEP` variable. | ||
313 | |||
314 | .. _migration-1.6-do-package-write-task: | ||
315 | |||
316 | Tasks | ||
317 | ----- | ||
318 | |||
319 | The ``do_package_write`` task has been removed. The task is no longer | ||
320 | needed. | ||
321 | |||
322 | .. _migration-1.6-update-alternatives-provider: | ||
323 | |||
324 | ``update-alternative`` Provider | ||
325 | ------------------------------- | ||
326 | |||
327 | The default ``update-alternatives`` provider has been changed from | ||
328 | ``opkg`` to ``opkg-utils``. This change resolves some troublesome | ||
329 | circular 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 | |||
337 | The ``virtclass`` overrides are now deprecated. Use the equivalent class | ||
338 | overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.) | ||
339 | |||
340 | .. _migration-1.6-removed-renamed-recipes: | ||
341 | |||
342 | Removed and Renamed Recipes | ||
343 | --------------------------- | ||
344 | |||
345 | The 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 | |||
384 | Removed Classes | ||
385 | --------------- | ||
386 | |||
387 | The 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 | |||
399 | Reference Board Support Packages (BSPs) | ||
400 | --------------------------------------- | ||
401 | |||
402 | The 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 | |||
410 | The 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 @@ | |||
1 | Moving to the Yocto Project 1.7 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.7 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.7-changes-to-setting-qemu-packageconfig-options: | ||
8 | |||
9 | Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf`` | ||
10 | ------------------------------------------------------------------- | ||
11 | |||
12 | The QEMU recipe now uses a number of | ||
13 | :term:`PACKAGECONFIG` options to enable various | ||
14 | optional features. The method used to set defaults for these options | ||
15 | means that existing ``local.conf`` files will need to be be modified to | ||
16 | append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu`` | ||
17 | instead of setting it. In other words, to enable graphical output for | ||
18 | QEMU, 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 | |||
26 | Minimum Git version | ||
27 | ------------------- | ||
28 | |||
29 | The minimum :ref:`overview-manual/development-environment:git` | ||
30 | version required on the | ||
31 | build host is now 1.7.8 because the ``--list`` option is now required by | ||
32 | BitBake's Git fetcher. As always, if your host distribution does not | ||
33 | provide 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`" | ||
36 | section for more information. | ||
37 | |||
38 | .. _migration-1.7-autotools-class-changes: | ||
39 | |||
40 | Autotools Class Changes | ||
41 | ----------------------- | ||
42 | |||
43 | The following :ref:`autotools <ref-classes-autotools>` class changes | ||
44 | occurred: | ||
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 | |||
75 | Binary Configuration Scripts Disabled | ||
76 | ------------------------------------- | ||
77 | |||
78 | Some of the core recipes that package binary configuration scripts now | ||
79 | disable the scripts due to the scripts previously requiring error-prone | ||
80 | path substitution. Software that links against these libraries using | ||
81 | these scripts should use the much more robust ``pkg-config`` instead. | ||
82 | The list of recipes changed in this version (and their configuration | ||
83 | scripts) 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 | |||
107 | Additionally, support for ``pkg-config`` has been added to some recipes in the | ||
108 | previous list in the rare cases where the upstream software package does | ||
109 | not already provide it. | ||
110 | |||
111 | .. _migration-1.7-glibc-replaces-eglibc: | ||
112 | |||
113 | ``eglibc 2.19`` Replaced with ``glibc 2.20`` | ||
114 | -------------------------------------------- | ||
115 | |||
116 | Because ``eglibc`` and ``glibc`` were already fairly close, this | ||
117 | replacement should not require any significant changes to other software | ||
118 | that links to ``eglibc``. However, there were a number of minor changes | ||
119 | in ``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. | ||
123 | Thus, older kernels will no longer be usable in conjunction with it. | ||
124 | |||
125 | For full details on the changes in ``glibc 2.20``, see the upstream | ||
126 | release notes | ||
127 | `here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__. | ||
128 | |||
129 | .. _migration-1.7-kernel-module-autoloading: | ||
130 | |||
131 | Kernel Module Autoloading | ||
132 | ------------------------- | ||
133 | |||
134 | The :term:`module_autoload_* <module_autoload>` variable is now | ||
135 | deprecated and a new | ||
136 | :term:`KERNEL_MODULE_AUTOLOAD` variable | ||
137 | should be used instead. Also, :term:`module_conf_* <module_conf>` | ||
138 | must now be used in conjunction with a new | ||
139 | :term:`KERNEL_MODULE_PROBECONF` variable. | ||
140 | The new variables no longer require you to specify the module name as | ||
141 | part of the variable name. This change not only simplifies usage but | ||
142 | also allows the values of these variables to be appropriately | ||
143 | incorporated into task signatures and thus trigger the appropriate tasks | ||
144 | to re-execute when changed. You should replace any references to | ||
145 | ``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any | ||
146 | modules for which ``module_conf_*`` is specified to | ||
147 | ``KERNEL_MODULE_PROBECONF``. | ||
148 | |||
149 | .. _migration-1.7-qa-check-changes: | ||
150 | |||
151 | QA Check Changes | ||
152 | ---------------- | ||
153 | |||
154 | The 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 | |||
188 | Removed Recipes | ||
189 | --------------- | ||
190 | |||
191 | The 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 | |||
209 | Miscellaneous Changes | ||
210 | --------------------- | ||
211 | |||
212 | The 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 @@ | |||
1 | Moving to the Yocto Project 1.8 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.8 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.8-removed-recipes: | ||
8 | |||
9 | Removed Recipes | ||
10 | --------------- | ||
11 | |||
12 | The 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 | |||
47 | BlueZ 4.x / 5.x Selection | ||
48 | ------------------------- | ||
49 | |||
50 | Proper built-in support for selecting BlueZ 5.x in preference to the | ||
51 | default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your | ||
52 | :term:`DISTRO_FEATURES` value. If you had | ||
53 | previously added append files (``*.bbappend``) to make this selection, | ||
54 | you can now remove them. | ||
55 | |||
56 | Additionally, a ``bluetooth`` class has been added to make selection of | ||
57 | the appropriate bluetooth support within a recipe a little easier. If | ||
58 | you wish to make use of this class in a recipe, add something such as | ||
59 | the 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 | |||
68 | Kernel Build Changes | ||
69 | -------------------- | ||
70 | |||
71 | The kernel build process was changed to place the source in a common | ||
72 | shared work area and to place build artifacts separately in the source | ||
73 | code tree. In theory, migration paths have been provided for most common | ||
74 | usages in kernel recipes but this might not work in all cases. In | ||
75 | particular, 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 | ||
79 | inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might | ||
80 | wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the | ||
81 | kinds 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>` | ||
83 | where the ``linux.inc`` file in ``meta-oe`` was updated. | ||
84 | |||
85 | Recipes that rely on the kernel source code and do not inherit the | ||
86 | module 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 | |||
93 | SSL 3.0 is Now Disabled in OpenSSL | ||
94 | ---------------------------------- | ||
95 | |||
96 | SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids | ||
97 | any lingering instances of the POODLE vulnerability. If you feel you | ||
98 | must re-enable SSL 3.0, then you can add an append file (``*.bbappend``) | ||
99 | for the ``openssl`` recipe to remove "-no-ssl3" from | ||
100 | :term:`EXTRA_OECONF`. | ||
101 | |||
102 | .. _migration-1.8-default-sysroot-poisoning: | ||
103 | |||
104 | Default Sysroot Poisoning | ||
105 | ------------------------- | ||
106 | |||
107 | ``gcc's`` default sysroot and include directories are now "poisoned". In | ||
108 | other words, the sysroot and include directories are being redirected to | ||
109 | a non-existent location in order to catch when host directories are | ||
110 | being used due to the correct options not being passed. This poisoning | ||
111 | applies both to the cross-compiler used within the build and to the | ||
112 | cross-compiler produced in the SDK. | ||
113 | |||
114 | If this change causes something in the build to fail, it almost | ||
115 | certainly means the various compiler flags and commands are not being | ||
116 | passed correctly to the underlying piece of software. In such cases, you | ||
117 | need to take corrective steps. | ||
118 | |||
119 | .. _migration-1.8-rebuild-improvements: | ||
120 | |||
121 | Rebuild Improvements | ||
122 | -------------------- | ||
123 | |||
124 | Changes 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 | ||
127 | when the :ref:`ref-tasks-configure` task needs to be | ||
128 | re-executed. | ||
129 | |||
130 | One of the improvements is to attempt to run "make clean" during the | ||
131 | ``do_configure`` task if a ``Makefile`` exists. Some software packages | ||
132 | do not provide a working clean target within their make files. If you | ||
133 | have 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 | |||
140 | QA Check and Validation Changes | ||
141 | ------------------------------- | ||
142 | |||
143 | The 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 | |||
168 | Miscellaneous Changes | ||
169 | --------------------- | ||
170 | |||
171 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.0 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.0 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.0-gcc-5: | ||
8 | |||
9 | GCC 5 | ||
10 | ----- | ||
11 | |||
12 | The default compiler is now GCC 5.2. This change has required fixes for | ||
13 | compilation errors in a number of other recipes. | ||
14 | |||
15 | One important example is a fix for when the Linux kernel freezes at boot | ||
16 | time on ARM when built with GCC 5. If you are using your own kernel | ||
17 | recipe or source tree and building for ARM, you will likely need to | ||
18 | apply this | ||
19 | `patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__. | ||
20 | The standard ``linux-yocto`` kernel source tree already has a workaround | ||
21 | for the same issue. | ||
22 | |||
23 | For further details, see https://gcc.gnu.org/gcc-5/changes.html | ||
24 | and the porting guide at | ||
25 | https://gcc.gnu.org/gcc-5/porting_to.html. | ||
26 | |||
27 | Alternatively, 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 | |||
35 | Gstreamer 0.10 Removed | ||
36 | ---------------------- | ||
37 | |||
38 | Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of | ||
39 | the change, recipes for Gstreamer 0.10 and related software are now | ||
40 | located in ``meta-multimedia``. This change results in Qt4 having Phonon | ||
41 | and Gstreamer support in QtWebkit disabled by default. | ||
42 | |||
43 | .. _migration-2.0-removed-recipes: | ||
44 | |||
45 | Removed Recipes | ||
46 | --------------- | ||
47 | |||
48 | The 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 | |||
83 | BitBake datastore improvements | ||
84 | ------------------------------ | ||
85 | |||
86 | The method by which BitBake's datastore handles overrides has changed. | ||
87 | Overrides are now applied dynamically and ``bb.data.update_data()`` is | ||
88 | now a no-op. Thus, ``bb.data.update_data()`` is no longer required in | ||
89 | order to apply the correct overrides. In practice, this change is | ||
90 | unlikely to require any changes to Metadata. However, these minor | ||
91 | changes 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 | |||
106 | Shell Message Function Changes | ||
107 | ------------------------------ | ||
108 | |||
109 | The shell versions of the BitBake message functions (i.e. ``bbdebug``, | ||
110 | ``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are | ||
111 | now 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 | ||
114 | would expect to be printed by the BitBake UI are now actually printed. | ||
115 | In 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 | |||
129 | Extra Development/Debug Package Cleanup | ||
130 | --------------------------------------- | ||
131 | |||
132 | The 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 | |||
172 | All of the above recipes now conform to the standard packaging scheme | ||
173 | where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per | ||
174 | recipe. | ||
175 | |||
176 | .. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core: | ||
177 | |||
178 | Recipe Maintenance Tracking Data Moved to OE-Core | ||
179 | ------------------------------------------------- | ||
180 | |||
181 | Maintenance tracking data for recipes that was previously part of | ||
182 | ``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change | ||
183 | includes ``package_regex.inc`` and ``distro_alias.inc``, which are | ||
184 | typically enabled when using the ``distrodata`` class. Additionally, the | ||
185 | contents of ``upstream_tracking.inc`` has now been split out to the | ||
186 | relevant recipes. | ||
187 | |||
188 | .. _migration-2.0-automatic-stale-sysroot-file-cleanup: | ||
189 | |||
190 | Automatic Stale Sysroot File Cleanup | ||
191 | ------------------------------------ | ||
192 | |||
193 | Stale files from recipes that no longer exist in the current | ||
194 | configuration are now automatically removed from sysroot as well as | ||
195 | removed from any other place managed by shared state. This automatic | ||
196 | cleanup means that the build system now properly handles situations such | ||
197 | as renaming the build system side of recipes, removal of layers from | ||
198 | ``bblayers.conf``, and :term:`DISTRO_FEATURES` | ||
199 | changes. | ||
200 | |||
201 | Additionally, work directories for old versions of recipes are now | ||
202 | pruned. If you wish to disable pruning old work directories, you can set | ||
203 | the 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 | |||
213 | The ``linux-yocto`` tree has up to now been a combined set of kernel | ||
214 | changes and configuration (meta) data carried in a single tree. While | ||
215 | this format is effective at keeping kernel configuration and source | ||
216 | modifications synchronized, it is not always obvious to developers how | ||
217 | to manipulate the Metadata as compared to the source. | ||
218 | |||
219 | Metadata processing has now been removed from the | ||
220 | :ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external | ||
221 | Metadata repository ``yocto-kernel-cache``, which has always been used | ||
222 | to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto`` | ||
223 | cache repository is now the primary location for this data. Due to this | ||
224 | change, ``linux-yocto`` is no longer able to process combined trees. | ||
225 | Thus, if you need to have your own combined kernel repository, you must | ||
226 | do 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 | |||
231 | Additional QA checks | ||
232 | -------------------- | ||
233 | |||
234 | The 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 | |||
254 | Miscellaneous Changes | ||
255 | --------------------- | ||
256 | |||
257 | These 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 @@ | |||
1 | Moving to the Yocto Project 2.1 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.1 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.1-variable-expansion-in-python-functions: | ||
8 | |||
9 | Variable Expansion in Python Functions | ||
10 | -------------------------------------- | ||
11 | |||
12 | Variable expressions, such as ``${VARNAME}`` no longer expand | ||
13 | automatically within Python functions. Suppressing expansion was done to | ||
14 | allow Python functions to construct shell scripts or other code for | ||
15 | situations in which you do not want such expressions expanded. For any | ||
16 | existing code that relies on these expansions, you need to change the | ||
17 | expansions 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 | |||
23 | Overrides Must Now be Lower-Case | ||
24 | -------------------------------- | ||
25 | |||
26 | The convention for overrides has always been for them to be lower-case | ||
27 | characters. This practice is now a requirement as BitBake's datastore | ||
28 | now assumes lower-case characters in order to give a slight performance | ||
29 | boost during parsing. In practical terms, this requirement means that | ||
30 | anything that ends up in :term:`OVERRIDES` must now | ||
31 | appear 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 | |||
37 | Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory | ||
38 | ---------------------------------------------------------------------- | ||
39 | |||
40 | The expand parameter to ``getVar()`` and ``getVarFlag()`` previously | ||
41 | defaulted to False if not specified. Now, however, no default exists so | ||
42 | one must be specified. You must change any ``getVar()`` calls that do | ||
43 | not specify the final expand parameter to calls that do specify the | ||
44 | parameter. You can run the following ``sed`` command at the base of a | ||
45 | layer 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 | |||
62 | Makefile Environment Changes | ||
63 | ---------------------------- | ||
64 | |||
65 | :term:`EXTRA_OEMAKE` now defaults to "" instead of | ||
66 | "-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default | ||
67 | was a historical accident that has required many classes (e.g. | ||
68 | ``autotools``, ``module``) and recipes to override this default in order | ||
69 | to work with sensible build systems. When upgrading to the release, you | ||
70 | must edit any recipe that relies upon this old default by either setting | ||
71 | ``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any | ||
72 | required variable value overrides using ``EXTRA_OEMAKE``, which is | ||
73 | typically only needed when a Makefile sets a default value for a | ||
74 | variable that is inappropriate for cross-compilation using the "=" | ||
75 | operator rather than the "?=" operator. | ||
76 | |||
77 | .. _migration-2.1-libexecdir-reverted-to-prefix-libexec: | ||
78 | |||
79 | ``libexecdir`` Reverted to ``${prefix}/libexec`` | ||
80 | ------------------------------------------------ | ||
81 | |||
82 | The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as | ||
83 | compared to all other mainstream distributions, which either uses | ||
84 | ``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the | ||
85 | GNU Coding Standards (i.e. | ||
86 | https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) | ||
87 | that suggest ``${prefix}/libexec`` and also notes that any | ||
88 | package-specific nesting should be done by the package itself. Finally, | ||
89 | having ``libexecdir`` change between recipes makes it very difficult for | ||
90 | different recipes to invoke binaries that have been installed into | ||
91 | ``libexecdir``. The Filesystem Hierarchy Standard (i.e. | ||
92 | https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now | ||
93 | recognizes the use of ``${prefix}/libexec/``, giving distributions the | ||
94 | choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without | ||
95 | breaking 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 | |||
102 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | ||
103 | class, ``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 | ||
106 | as was previously assumed. Rather, the value changes based on whether | ||
107 | large file support is enabled. For most software that uses ``autoconf``, | ||
108 | this change should not be a problem. However, if you have a recipe that | ||
109 | bypasses the standard :ref:`ref-tasks-configure` task | ||
110 | from the ``autotools`` class and the software the recipe is building | ||
111 | uses a very old version of ``autoconf``, the recipe might be incapable | ||
112 | of determining the correct size of ``off_t`` during ``do_configure``. | ||
113 | |||
114 | The best course of action is to patch the software as necessary to allow | ||
115 | the default implementation from the ``autotools`` class to work such | ||
116 | that ``autoreconf`` succeeds and produces a working configure script, | ||
117 | and to remove the overridden ``do_configure`` task such that the default | ||
118 | implementation does get used. | ||
119 | |||
120 | .. _migration-2.1-image-generation-split-out-from-filesystem-generation: | ||
121 | |||
122 | Image Generation is Now Split Out from Filesystem Generation | ||
123 | ------------------------------------------------------------ | ||
124 | |||
125 | Previously, for image recipes the :ref:`ref-tasks-rootfs` | ||
126 | task assembled the filesystem and then from that filesystem generated | ||
127 | images. With this Yocto Project release, image generation is split into | ||
128 | separate :ref:`ref-tasks-image` tasks for clarity both in | ||
129 | operation and in the code. | ||
130 | |||
131 | For most cases, this change does not present any problems. However, if | ||
132 | you have made customizations that directly modify the ``do_rootfs`` task | ||
133 | or that mention ``do_rootfs``, you might need to update those changes. | ||
134 | In particular, if you had added any tasks after ``do_rootfs``, you | ||
135 | should make edits so that those tasks are after the | ||
136 | :ref:`ref-tasks-image-complete` task rather than | ||
137 | after ``do_rootfs`` so that the your added tasks run at the correct | ||
138 | time. | ||
139 | |||
140 | A minor part of this restructuring is that the post-processing | ||
141 | definitions 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, | ||
144 | however, they remain unchanged. | ||
145 | |||
146 | .. _migration-2.1-removed-recipes: | ||
147 | |||
148 | Removed Recipes | ||
149 | --------------- | ||
150 | |||
151 | The 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 | |||
188 | Class Changes | ||
189 | ------------- | ||
190 | |||
191 | The 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 | |||
212 | Build System User Interface Changes | ||
213 | ----------------------------------- | ||
214 | |||
215 | The 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 | |||
229 | ADT Removed | ||
230 | ----------- | ||
231 | |||
232 | The Application Development Toolkit (ADT) has been removed because its | ||
233 | functionality almost completely overlapped with the :ref:`standard | ||
234 | SDK <sdk-manual/using:using the standard sdk>` and the | ||
235 | :ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For | ||
236 | information 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 | |||
246 | Poky Reference Distribution Changes | ||
247 | ----------------------------------- | ||
248 | |||
249 | The 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 | |||
305 | Packaging Changes | ||
306 | ----------------- | ||
307 | |||
308 | The 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 | |||
320 | Tuning File Changes | ||
321 | ------------------- | ||
322 | |||
323 | The 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 | |||
342 | Supporting GObject Introspection | ||
343 | -------------------------------- | ||
344 | |||
345 | This release supports generation of GLib Introspective Repository (GIR) | ||
346 | files through GObject introspection, which is the standard mechanism for | ||
347 | accessing GObject-based software from runtime environments. You can | ||
348 | enable, disable, and test the generation of this data. See the | ||
349 | ":ref:`dev-manual/common-tasks:enabling gobject introspection support`" | ||
350 | section in the Yocto Project Development Tasks Manual for more | ||
351 | information. | ||
352 | |||
353 | .. _migration-2.1-miscellaneous-changes: | ||
354 | |||
355 | Miscellaneous Changes | ||
356 | --------------------- | ||
357 | |||
358 | These 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 @@ | |||
1 | Moving to the Yocto Project 2.2 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.2 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.2-minimum-kernel-version: | ||
8 | |||
9 | Minimum Kernel Version | ||
10 | ---------------------- | ||
11 | |||
12 | The minimum kernel version for the target system and for SDK is now | ||
13 | 3.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for | ||
14 | AArch64-based targets the version is 3.14. For Nios II-based targets, | ||
15 | the 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 | |||
24 | Staging Directories in Sysroot Has Been Simplified | ||
25 | -------------------------------------------------- | ||
26 | |||
27 | The way directories are staged in sysroot has been simplified and | ||
28 | introduces 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>` | ||
33 | for additional information. | ||
34 | |||
35 | .. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled: | ||
36 | |||
37 | Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled | ||
38 | ------------------------------------------------------------------- | ||
39 | |||
40 | Removal of old images and other files in ``tmp/deploy/`` is now enabled | ||
41 | by default due to a new staging method used for those files. As a result | ||
42 | of this change, the ``RM_OLD_IMAGE`` variable is now redundant. | ||
43 | |||
44 | .. _migration-2.2-python-changes: | ||
45 | |||
46 | Python Changes | ||
47 | -------------- | ||
48 | |||
49 | The following changes for Python occurred: | ||
50 | |||
51 | .. _migration-2.2-bitbake-now-requires-python-3.4: | ||
52 | |||
53 | BitBake Now Requires Python 3.4+ | ||
54 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
55 | |||
56 | BitBake requires Python 3.4 or greater. | ||
57 | |||
58 | .. _migration-2.2-utf-8-locale-required-on-build-host: | ||
59 | |||
60 | UTF-8 Locale Required on Build Host | ||
61 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
62 | |||
63 | A UTF-8 locale is required on the build host due to Python 3. Since | ||
64 | C.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 | |||
68 | Metadata Must Now Use Python 3 Syntax | ||
69 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
70 | |||
71 | The metadata is now required to use Python 3 syntax. For help preparing | ||
72 | metadata, see any of the many Python 3 porting guides available. | ||
73 | Alternatively, you can reference the conversion commits for Bitbake and | ||
74 | you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are | ||
75 | particular 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 | |||
89 | Target Python Recipes Switched to Python 3 | ||
90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
91 | |||
92 | Most target Python recipes have now been switched to Python 3. | ||
93 | Unfortunately, systems using RPM as a package manager and providing | ||
94 | online 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 | |||
110 | uClibc Replaced by musl | ||
111 | ----------------------- | ||
112 | |||
113 | uClibc has been removed in favor of musl. Musl has matured, is better | ||
114 | maintained, and is compatible with a wider range of applications as | ||
115 | compared 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 | ||
123 | directory for tasks. Consequently, any custom tasks you define now need | ||
124 | to either have the | ||
125 | ``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag | ||
126 | set, or the task needs to change into the appropriate working directory | ||
127 | manually (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 | ||
141 | cases. Previous usage patterns continue to be supported. | ||
142 | |||
143 | The new ``runqemu`` is a Python script. Machine knowledge is no longer | ||
144 | hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` | ||
145 | configuration file to define the BSP's own arguments and to make it | ||
146 | bootable with ``runqemu``. If you use a configuration file, use the | ||
147 | following form: | ||
148 | :: | ||
149 | |||
150 | image-name-machine.qemuboot.conf | ||
151 | |||
152 | The configuration file | ||
153 | enables fine-grained tuning of options passed to QEMU without the | ||
154 | ``runqemu`` script hard-coding any knowledge about different machines. | ||
155 | Using a configuration file is particularly convenient when trying to use | ||
156 | QEMU 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 | ||
159 | rootfs). QEMU boot arguments can be set in BSP's configuration file and | ||
160 | the ``qemuboot`` class will save them to ``qemuboot.conf``. | ||
161 | |||
162 | If you want to use ``runqemu`` without a configuration file, use the | ||
163 | following command form: | ||
164 | :: | ||
165 | |||
166 | $ runqemu machine rootfs kernel [options] | ||
167 | |||
168 | Supported 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 | |||
180 | Consider the | ||
181 | following example, which uses the ``qemux86-64`` machine, provides a | ||
182 | root 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 | |||
186 | Following is a list of variables that can be set in configuration files | ||
187 | such 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 | |||
223 | To use ``runqemu``, set :term:`IMAGE_CLASSES` as | ||
224 | follows 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 | |||
236 | Default Linker Hash Style Changed | ||
237 | --------------------------------- | ||
238 | |||
239 | The default linker hash style for ``gcc-cross`` is now "sysv" in order | ||
240 | to catch recipes that are building software without using the | ||
241 | OpenEmbedded :term:`LDFLAGS`. This change could result in | ||
242 | seeing some "No GNU_HASH in the elf binary" QA issues when building such | ||
243 | recipes. You need to fix these recipes so that they use the expected | ||
244 | ``LDFLAGS``. Depending on how the software is built, the build system | ||
245 | used by the software (e.g. a Makefile) might need to be patched. | ||
246 | However, sometimes making this fix is as simple as adding the following | ||
247 | to 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 | |||
257 | The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the | ||
258 | :term:`KERNEL_IMAGETYPE` variable to create the | ||
259 | image's base name. Because the OpenEmbedded build system can now build | ||
260 | multiple kernel image types, this part of the kernel image base name as | ||
261 | been removed leaving only the following: | ||
262 | :: | ||
263 | |||
264 | KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" | ||
265 | |||
266 | If you have recipes or | ||
267 | classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to | ||
268 | update the references to ensure they continue to work. | ||
269 | |||
270 | .. _migration-2.2-bitbake-changes: | ||
271 | |||
272 | BitBake Changes | ||
273 | --------------- | ||
274 | |||
275 | The 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 | |||
312 | Swabber has Been Removed | ||
313 | ------------------------ | ||
314 | |||
315 | Swabber, a tool that was intended to detect host contamination in the | ||
316 | build process, has been removed, as it has been unmaintained and unused | ||
317 | for some time and was never particularly effective. The OpenEmbedded | ||
318 | build system has since incorporated a number of mechanisms including | ||
319 | enhanced QA checks that mean that there is less of a need for such a | ||
320 | tool. | ||
321 | |||
322 | .. _migration-2.2-removed-recipes: | ||
323 | |||
324 | Removed Recipes | ||
325 | --------------- | ||
326 | |||
327 | The 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 | |||
381 | Removed Classes | ||
382 | --------------- | ||
383 | |||
384 | The 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 | |||
401 | Minor Packaging Changes | ||
402 | ----------------------- | ||
403 | |||
404 | The 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 | |||
416 | Miscellaneous Changes | ||
417 | --------------------- | ||
418 | |||
419 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.3 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.3 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.3-recipe-specific-sysroots: | ||
8 | |||
9 | Recipe-specific Sysroots | ||
10 | ------------------------ | ||
11 | |||
12 | The OpenEmbedded build system now uses one sysroot per recipe to resolve | ||
13 | long-standing issues with configuration script auto-detection of | ||
14 | undeclared dependencies. Consequently, you might find that some of your | ||
15 | previously written custom recipes are missing declared dependencies, | ||
16 | particularly those dependencies that are incidentally built earlier in a | ||
17 | typical build process and thus are already likely to be present in the | ||
18 | shared sysroot in previous releases. | ||
19 | |||
20 | Consider 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 | |||
86 | Within 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 | ||
89 | directory containing symbolic links linking only to the binaries from | ||
90 | the host mentioned in the :term:`HOSTTOOLS` and | ||
91 | :term:`HOSTTOOLS_NONFATAL` variables is added | ||
92 | to ``PATH``. | ||
93 | |||
94 | Consequently, any native binaries provided by the host that you need to | ||
95 | call needs to be in one of these two variables at the configuration | ||
96 | level. | ||
97 | |||
98 | Alternatively, you can add a native recipe (i.e. ``-native``) that | ||
99 | provides the binary to the recipe's :term:`DEPENDS` | ||
100 | value. | ||
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 | |||
111 | Changes to Scripts | ||
112 | ------------------ | ||
113 | |||
114 | The 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 | |||
149 | Changes to Functions | ||
150 | -------------------- | ||
151 | |||
152 | The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``, | ||
153 | and related functions have been removed in favor of ``d.getVar()``, | ||
154 | ``d.setVar()``, and so forth. | ||
155 | |||
156 | You need to fix any references to these old functions. | ||
157 | |||
158 | .. _migration-2.3-bitbake-changes: | ||
159 | |||
160 | BitBake Changes | ||
161 | --------------- | ||
162 | |||
163 | The 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 | |||
213 | Absolute Symbolic Links | ||
214 | ----------------------- | ||
215 | |||
216 | Absolute symbolic links (symlinks) within staged files are no longer | ||
217 | permitted and now trigger an error. Any explicit creation of symlinks | ||
218 | can use the ``lnr`` script, which is a replacement for ``ln -r``. | ||
219 | |||
220 | If the build scripts in the software that the recipe is building are | ||
221 | creating a number of absolute symlinks that need to be corrected, you | ||
222 | can inherit ``relative_symlinks`` within the recipe to turn those | ||
223 | absolute symlinks into relative symlinks. | ||
224 | |||
225 | .. _migration-2.3-gplv2-and-gplv3-moves: | ||
226 | |||
227 | GPLv2 Versions of GPLv3 Recipes Moved | ||
228 | ------------------------------------- | ||
229 | |||
230 | Older GPLv2 versions of GPLv3 recipes have moved to a separate | ||
231 | ``meta-gplv2`` layer. | ||
232 | |||
233 | If you use :term:`INCOMPATIBLE_LICENSE` to | ||
234 | exclude GPLv3 or set :term:`PREFERRED_VERSION` | ||
235 | to 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 | |||
243 | These relocated GPLv2 recipes do not receive the same level of | ||
244 | maintenance as other core recipes. The recipes do not get security fixes | ||
245 | and upstream no longer maintains them. In fact, the upstream community | ||
246 | is actively hostile towards people that use the old versions of the | ||
247 | recipes. Moving these recipes into a separate layer both makes the | ||
248 | different needs of the recipes clearer and clearly identifies the number | ||
249 | of 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 | |||
260 | Package Management Changes | ||
261 | -------------------------- | ||
262 | |||
263 | The 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 | |||
330 | Removed Recipes | ||
331 | --------------- | ||
332 | |||
333 | The 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 | |||
361 | Wic Changes | ||
362 | ----------- | ||
363 | |||
364 | The 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 | |||
385 | QA Changes | ||
386 | ---------- | ||
387 | |||
388 | The 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 | |||
411 | Miscellaneous Changes | ||
412 | --------------------- | ||
413 | |||
414 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.4 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.4 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.4-memory-resident-mode: | ||
8 | |||
9 | Memory Resident Mode | ||
10 | -------------------- | ||
11 | |||
12 | A persistent mode is now available in BitBake's default operation, | ||
13 | replacing 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 | ||
16 | seconds) and BitBake's server stays resident for that amount of time | ||
17 | between invocations. The ``oe-init-build-env-memres`` script has been | ||
18 | removed since a separate environment setup script is no longer needed. | ||
19 | |||
20 | .. _migration-2.4-packaging-changes: | ||
21 | |||
22 | Packaging Changes | ||
23 | ----------------- | ||
24 | |||
25 | This section provides information about packaging changes that have | ||
26 | occurred: | ||
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 | |||
89 | Removed Recipes | ||
90 | --------------- | ||
91 | |||
92 | The 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 | |||
194 | Kernel Device Tree Move | ||
195 | ----------------------- | ||
196 | |||
197 | Kernel Device Tree support is now easier to enable in a kernel recipe. | ||
198 | The Device Tree code has moved to a | ||
199 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class. | ||
200 | Functionality 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 | ||
203 | previous mechanism for doing this, | ||
204 | ``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid | ||
205 | breakage, but triggers a deprecation warning. Future releases of the | ||
206 | Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``. | ||
207 | It is advisable to remove any ``require`` statements that request | ||
208 | ``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel | ||
209 | recipes you might have. This will avoid breakage in post 2.4 releases. | ||
210 | |||
211 | .. _migration-2.4-package-qa-changes: | ||
212 | |||
213 | Package QA Changes | ||
214 | ------------------ | ||
215 | |||
216 | The 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 | |||
232 | The 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 | |||
246 | Miscellaneous Changes | ||
247 | --------------------- | ||
248 | |||
249 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.5 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.5 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.5-packaging-changes: | ||
8 | |||
9 | Packaging Changes | ||
10 | ----------------- | ||
11 | |||
12 | This section provides information about packaging changes that have | ||
13 | occurred: | ||
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 | |||
40 | Removed Recipes | ||
41 | --------------- | ||
42 | |||
43 | The 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 | |||
85 | Scripts and Tools Changes | ||
86 | ------------------------- | ||
87 | |||
88 | The 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 | |||
117 | BitBake Changes | ||
118 | --------------- | ||
119 | |||
120 | The 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 | |||
153 | Python and Python 3 Changes | ||
154 | --------------------------- | ||
155 | |||
156 | The following are auto-packaging changes to Python and Python 3: | ||
157 | |||
158 | The script-managed ``python-*-manifest.inc`` files that were previously | ||
159 | used to generate Python and Python 3 packages have been replaced with a | ||
160 | JSON-based file that is easier to read and maintain. A new task is | ||
161 | available for maintainers of the Python recipes to update the JSON file | ||
162 | when upgrading to new Python versions. You can now edit the file | ||
163 | directly instead of having to edit a script and run it to update the | ||
164 | file. | ||
165 | |||
166 | One particular change to note is that the Python recipes no longer have | ||
167 | build-time provides for their packages. This assumes ``python-foo`` is | ||
168 | one 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``, | ||
171 | but doing either of the following causes the package to work as | ||
172 | expected: :: | ||
173 | |||
174 | IMAGE_INSTALL_append = " python-foo" | ||
175 | |||
176 | or :: | ||
177 | |||
178 | RDEPENDS_${PN} = "python-foo" | ||
179 | |||
180 | The earlier build-time provides behavior was a quirk of the | ||
181 | way the Python manifest file was created. For more information on this | ||
182 | change please see :yocto_git:`this commit | ||
183 | </poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`. | ||
184 | |||
185 | .. _migration-2.5-miscellaneous-changes: | ||
186 | |||
187 | Miscellaneous Changes | ||
188 | --------------------- | ||
189 | |||
190 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.6 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.6 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.6-gcc-changes: | ||
8 | |||
9 | GCC 8.2 is Now Used by Default | ||
10 | ------------------------------ | ||
11 | |||
12 | The GNU Compiler Collection version 8.2 is now used by default for | ||
13 | compilation. For more information on what has changed in the GCC 8.x | ||
14 | release, see https://gcc.gnu.org/gcc-8/changes.html. | ||
15 | |||
16 | If you still need to compile with version 7.x, GCC 7.3 is also provided. | ||
17 | You can select this version by setting the and can be selected by | ||
18 | setting the :term:`GCCVERSION` variable to "7.%" in | ||
19 | your configuration. | ||
20 | |||
21 | .. _migration-2.6-removed-recipes: | ||
22 | |||
23 | Removed Recipes | ||
24 | --------------- | ||
25 | |||
26 | The 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 | |||
78 | Packaging Changes | ||
79 | ----------------- | ||
80 | |||
81 | The 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 | |||
103 | XOrg Protocol dependencies | ||
104 | -------------------------- | ||
105 | |||
106 | The ``*proto`` upstream repositories have been combined into one | ||
107 | "xorgproto" repository. Thus, the corresponding recipes have also been | ||
108 | combined into a single ``xorgproto`` recipe. Any recipes that depend | ||
109 | upon the older ``*proto`` recipes need to be changed to depend on the | ||
110 | newer ``xorgproto`` recipe instead. | ||
111 | |||
112 | For 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 | |||
120 | Previously, 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 | ||
123 | during the :ref:`ref-tasks-configure` task to satisfy | ||
124 | dependencies mentioned in ``setup.py`` if those dependencies were not | ||
125 | provided in the sysroot (i.e. recipes providing the dependencies were | ||
126 | missing 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 | |||
135 | Fetching these types of dependencies that are not provided in the | ||
136 | sysroot negatively affects the ability to reproduce builds. This type of | ||
137 | fetching is now explicitly disabled. Consequently, any missing | ||
138 | dependencies in Python recipes that use these classes now result in an | ||
139 | error 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 | |||
146 | Due to a bug, the kernel configuration audit functionality was not | ||
147 | writing out any resulting warnings during the build. This issue is now | ||
148 | corrected. You might notice these warnings now if you have a custom | ||
149 | kernel configuration with a ``linux-yocto`` style kernel recipe. | ||
150 | |||
151 | .. _migration-2.6-image-kernel-artifact-naming-changes: | ||
152 | |||
153 | Image/Kernel Artifact Naming Changes | ||
154 | ------------------------------------ | ||
155 | |||
156 | The 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 | |||
214 | The :term:`SERIAL_CONSOLE` variable has been | ||
215 | functionally replaced by the | ||
216 | :term:`SERIAL_CONSOLES` variable for some time. | ||
217 | With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been | ||
218 | officially deprecated. | ||
219 | |||
220 | ``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release. | ||
221 | However, for the sake of future compatibility, it is recommended that | ||
222 | you 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 | |||
233 | Configure Script Reports Unknown Options as Errors | ||
234 | -------------------------------------------------- | ||
235 | |||
236 | If the configure script reports an unknown option, this now triggers a | ||
237 | QA error instead of a warning. Any recipes that previously got away with | ||
238 | specifying such unknown options now need to be fixed. | ||
239 | |||
240 | .. _migration-2.6-override-changes: | ||
241 | |||
242 | Override Changes | ||
243 | ---------------- | ||
244 | |||
245 | The 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 | |||
289 | The configuration for the ``systemd`` recipe has been moved into a | ||
290 | ``system-conf`` recipe. Moving this configuration to a separate recipe | ||
291 | avoids the ``systemd`` recipe from becoming machine-specific for cases | ||
292 | where machine-specific configurations need to be applied (e.g. for | ||
293 | ``qemu*`` machines). | ||
294 | |||
295 | Currently, 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 | |||
305 | If you previously used bbappend files to append the ``systemd`` recipe to | ||
306 | change any of the listed files, you must do so for the ``systemd-conf`` | ||
307 | recipe instead. | ||
308 | |||
309 | .. _migration-2.6-automatic-testing-changes: | ||
310 | |||
311 | Automatic Testing Changes | ||
312 | ------------------------- | ||
313 | |||
314 | This 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 | |||
332 | OpenSSL Changes | ||
333 | --------------- | ||
334 | |||
335 | `OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to | ||
336 | 1.1. By default, this upgrade could cause problems for recipes that have | ||
337 | both versions in their dependency chains. The problem is that both | ||
338 | versions 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 | |||
346 | BitBake Changes | ||
347 | --------------- | ||
348 | |||
349 | The server logfile ``bitbake-cookerdaemon.log`` is now always placed in | ||
350 | the :term:`Build Directory` instead of the current | ||
351 | directory. | ||
352 | |||
353 | .. _migration-2.6-security-changes: | ||
354 | |||
355 | Security Changes | ||
356 | ---------------- | ||
357 | |||
358 | The Poky distribution now uses security compiler flags by default. | ||
359 | Inclusion of these flags could cause new failures due to stricter | ||
360 | checking for various potential security issues in code. | ||
361 | |||
362 | .. _migration-2.6-post-installation-changes: | ||
363 | |||
364 | Post Installation Changes | ||
365 | ------------------------- | ||
366 | |||
367 | You must explicitly mark post installs to defer to the target. If you | ||
368 | want to explicitly defer a postinstall to first boot on the target | ||
369 | rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or | ||
370 | call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. | ||
371 | Any failure of a ``pkg_postinst()`` script (including exit 1) triggers | ||
372 | an error during the :ref:`ref-tasks-rootfs` task. | ||
373 | |||
374 | For more information on post-installation behavior, see the | ||
375 | ":ref:`dev-manual/common-tasks:post-installation scripts`" | ||
376 | section in the Yocto Project Development Tasks Manual. | ||
377 | |||
378 | .. _migration-2.6-python-3-profile-guided-optimizations: | ||
379 | |||
380 | Python 3 Profile-Guided Optimization | ||
381 | ------------------------------------ | ||
382 | |||
383 | The ``python3`` recipe now enables profile-guided optimization. Using | ||
384 | this optimization requires a little extra build time in exchange for | ||
385 | improved performance on the target at runtime. Additionally, the | ||
386 | optimization is only enabled if the current | ||
387 | :term:`MACHINE` has support for user-mode emulation in | ||
388 | QEMU (i.e. "qemu-usermode" is in | ||
389 | :term:`MACHINE_FEATURES`, which it is by | ||
390 | default). | ||
391 | |||
392 | If you wish to disable Python profile-guided optimization regardless of | ||
393 | the value of ``MACHINE_FEATURES``, then ensure that | ||
394 | :term:`PACKAGECONFIG` for the ``python3`` recipe | ||
395 | does not contain "pgo". You could accomplish the latter using the | ||
396 | following at the configuration level: | ||
397 | :: | ||
398 | |||
399 | PACKAGECONFIG_remove_pn-python3 = "pgo" | ||
400 | |||
401 | Alternatively, you can set ``PACKAGECONFIG`` using an append file | ||
402 | for the ``python3`` recipe. | ||
403 | |||
404 | .. _migration-2.6-miscellaneous-changes: | ||
405 | |||
406 | Miscellaneous Changes | ||
407 | --------------------- | ||
408 | |||
409 | The 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 @@ | |||
1 | Moving to the Yocto Project 2.7 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.7 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.7-bitbake-changes: | ||
8 | |||
9 | BitBake Changes | ||
10 | --------------- | ||
11 | |||
12 | The 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 | |||
24 | Eclipse Support Removed | ||
25 | ----------------------- | ||
26 | |||
27 | Support for the Eclipse IDE has been removed. Support continues for | ||
28 | those releases prior to 2.7 that did include support. The 2.7 release | ||
29 | does 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 | |||
36 | The 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 | ||
39 | recipes that depend on QEMU's system emulation functionality at build | ||
40 | time, they should now depend upon ``qemu-system-native`` instead of | ||
41 | ``qemu-native``. | ||
42 | |||
43 | .. _migration-2.7-upstream-tracking.inc-removed: | ||
44 | |||
45 | The ``upstream-tracking.inc`` File Has Been Removed | ||
46 | --------------------------------------------------- | ||
47 | |||
48 | The previously deprecated ``upstream-tracking.inc`` file is now removed. | ||
49 | Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding | ||
50 | recipes instead. | ||
51 | |||
52 | Remove any references you have to the ``upstream-tracking.inc`` file in | ||
53 | your configuration. | ||
54 | |||
55 | .. _migration-2.7-distro-features-libc-removed: | ||
56 | |||
57 | The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed | ||
58 | ------------------------------------------------------ | ||
59 | |||
60 | The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to | ||
61 | configure glibc using kconfig has been removed for quite some time | ||
62 | making the ``libc-*`` features set no longer effective. | ||
63 | |||
64 | Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own | ||
65 | layers. | ||
66 | |||
67 | .. _migration-2.7-license-values: | ||
68 | |||
69 | License Value Corrections | ||
70 | ------------------------- | ||
71 | |||
72 | The 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 | |||
81 | Packaging Changes | ||
82 | ----------------- | ||
83 | |||
84 | This 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 | |||
125 | Removed Recipes | ||
126 | --------------- | ||
127 | |||
128 | The 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 | |||
142 | Removed Classes | ||
143 | --------------- | ||
144 | |||
145 | The 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 | |||
153 | Miscellaneous Changes | ||
154 | --------------------- | ||
155 | |||
156 | The 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 @@ | |||
1 | Moving to the Yocto Project 3.0 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.0 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.0-init-system-selection: | ||
8 | |||
9 | Init System Selection | ||
10 | --------------------- | ||
11 | |||
12 | Changing the init system manager previously required setting a number of | ||
13 | different 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 | ||
16 | for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The | ||
17 | default value, "none", for ``INIT_MANAGER`` should allow your current | ||
18 | settings to continue working. However, it is advisable to explicitly set | ||
19 | ``INIT_MANAGER``. | ||
20 | |||
21 | .. _migration-3.0-lsb-support-removed: | ||
22 | |||
23 | LSB Support Removed | ||
24 | ------------------- | ||
25 | |||
26 | Linux Standard Base (LSB) as a standard is not current, and is not well | ||
27 | suited for embedded applications. Support can be continued in a separate | ||
28 | layer if needed. However, presently LSB support has been removed from | ||
29 | the core. | ||
30 | |||
31 | As a result of this change, the ``poky-lsb`` derivative distribution | ||
32 | configuration that was also used for testing alternative configurations | ||
33 | has been replaced with a ``poky-altcfg`` distribution that has LSB parts | ||
34 | removed. | ||
35 | |||
36 | .. _migration-3.0-removed-recipes: | ||
37 | |||
38 | Removed Recipes | ||
39 | --------------- | ||
40 | |||
41 | The 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 | |||
106 | Packaging Changes | ||
107 | ----------------- | ||
108 | |||
109 | The 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 | |||
141 | CVE 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`` | ||
146 | class. The result uses NVD JSON data feeds rather than the deprecated | ||
147 | XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring, | ||
148 | and makes other improvements. | ||
149 | |||
150 | Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced | ||
151 | by ``CVE_CHECK_WHITELIST``. | ||
152 | |||
153 | .. _migration-3.0-bitbake-changes: | ||
154 | |||
155 | Bitbake Changes | ||
156 | --------------- | ||
157 | |||
158 | The 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 | |||
212 | Sanity Checks | ||
213 | ------------- | ||
214 | |||
215 | The 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 | |||
256 | Miscellaneous Changes | ||
257 | --------------------- | ||
258 | |||
259 | The 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 @@ | |||
1 | Moving to the Yocto Project 3.1 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.1 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.1-minimum-system-requirements: | ||
8 | |||
9 | Minimum system requirements | ||
10 | --------------------------- | ||
11 | |||
12 | The following versions / requirements of build host components have been | ||
13 | updated: | ||
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 | |||
25 | Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer* | ||
26 | required on the host. | ||
27 | |||
28 | .. _migration-3.1-mpc8315e-rdb-removed: | ||
29 | |||
30 | mpc8315e-rdb machine removed | ||
31 | ---------------------------- | ||
32 | |||
33 | The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given | ||
34 | the maintenance burden the ``mpc8315e-rdb`` machine configuration that | ||
35 | supported it has been removed in this release. The removal does leave a | ||
36 | gap in official PowerPC reference hardware support; this may change in | ||
37 | future if a suitable machine with accompanying support resources is | ||
38 | found. | ||
39 | |||
40 | .. _migration-3.1-python-2-removed: | ||
41 | |||
42 | Python 2 removed | ||
43 | ---------------- | ||
44 | |||
45 | Due to the expiration of upstream support in January 2020, support for | ||
46 | Python 2 has now been removed; it is recommended that you use Python 3 | ||
47 | instead. If absolutely needed there is a meta-python2 community layer | ||
48 | containing Python 2, related classes and various Python 2-based modules, | ||
49 | however it should not be considered as supported. | ||
50 | |||
51 | .. _migration-3.1-reproducible-builds: | ||
52 | |||
53 | Reproducible builds now enabled by default | ||
54 | ------------------------------------------ | ||
55 | |||
56 | In order to avoid unnecessary differences in output files (aiding binary | ||
57 | reproducibility), the Poky distribution configuration | ||
58 | (``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by | ||
59 | default. | ||
60 | |||
61 | .. _migration-3.1-ptest-feature-impact: | ||
62 | |||
63 | Impact of ptest feature is now more significant | ||
64 | ----------------------------------------------- | ||
65 | |||
66 | The Poky distribution configuration (``DISTRO = "poky"``) enables ptests | ||
67 | by default to enable runtime testing of various components. In this | ||
68 | release, a dependency needed to be added that has resulted in a | ||
69 | significant increase in the number of components that will be built just | ||
70 | when building a simple image such as core-image-minimal. If you do not | ||
71 | need runtime tests enabled for core components, then it is recommended | ||
72 | that you remove "ptest" from | ||
73 | :term:`DISTRO_FEATURES` to save a significant | ||
74 | amount 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 | |||
81 | Removed recipes | ||
82 | --------------- | ||
83 | |||
84 | The 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 | |||
117 | features_check class replaces distro_features_check | ||
118 | --------------------------------------------------- | ||
119 | |||
120 | The ``distro_features_check`` class has had its functionality expanded, | ||
121 | now 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 | ||
125 | renamed to ``features_check``; the ``distro_features_check`` class still | ||
126 | exists but generates a warning and redirects to the new class. In | ||
127 | preparation for a future removal of the old class it is recommended that | ||
128 | you update recipes currently inheriting ``distro_features_check`` to | ||
129 | inherit ``features_check`` instead. | ||
130 | |||
131 | .. _migration-3.1-removed-classes: | ||
132 | |||
133 | Removed classes | ||
134 | --------------- | ||
135 | |||
136 | The 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 | |||
155 | SRC_URI checksum behaviour | ||
156 | -------------------------- | ||
157 | |||
158 | Previously, recipes by tradition included both SHA256 and MD5 checksums | ||
159 | for remotely fetched files in :term:`SRC_URI`, even | ||
160 | though only one is actually mandated. However, the MD5 checksum does not | ||
161 | add much given its inherent weakness; thus when a checksum fails only | ||
162 | the SHA256 sum will now be printed. The md5sum will still be verified if | ||
163 | it is specified. | ||
164 | |||
165 | .. _migration-3.1-npm: | ||
166 | |||
167 | npm fetcher changes | ||
168 | ------------------- | ||
169 | |||
170 | The npm fetcher has been completely reworked in this release. The npm | ||
171 | fetcher now only fetches the package source itself and no longer the | ||
172 | dependencies; there is now also an npmsw fetcher which explicitly | ||
173 | fetches the shrinkwrap file and the dependencies. This removes the | ||
174 | slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which | ||
175 | pointed to local files; the lockdown file is no longer needed at all. | ||
176 | Additionally, the package name in ``npm://`` entries in | ||
177 | :term:`SRC_URI` is now specified using a ``package`` | ||
178 | parameter instead of the earlier ``name`` which overlapped with the | ||
179 | generic ``name`` parameter. All recipes using the npm fetcher will need | ||
180 | to be changed as a result. | ||
181 | |||
182 | An 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 | |||
187 | Another 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 | |||
192 | devtool and recipetool have also been updated to match with the npm | ||
193 | fetcher changes. Other than producing working and more complete recipes | ||
194 | for npm sources, there is also a minor change to the command line for | ||
195 | devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as | ||
196 | it is npm-specific. | ||
197 | |||
198 | .. _migration-3.1-packaging-changes: | ||
199 | |||
200 | Packaging 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 | |||
235 | Additional warnings | ||
236 | ------------------- | ||
237 | |||
238 | Warnings will now be shown at ``do_package_qa`` time in the following | ||
239 | circumstances: | ||
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 | ||
253 | configurations) now specifies ``wic`` instead of ``live`` by default in | ||
254 | :term:`IMAGE_FSTYPES`. The ``live`` image type will | ||
255 | likely be removed in a future release so it is recommended that you use | ||
256 | ``wic`` instead. | ||
257 | |||
258 | .. _migration-3.1-misc: | ||
259 | |||
260 | Miscellaneous 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 @@ | |||
1 | Moving to the Yocto Project 3.2 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.2 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.2-minimum-system-requirements: | ||
8 | |||
9 | Minimum system requirements | ||
10 | --------------------------- | ||
11 | |||
12 | ``gcc`` version 6.0 is now required at minimum on the build host. For older | ||
13 | host 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 | |||
20 | Removed recipes | ||
21 | --------------- | ||
22 | |||
23 | The 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 | |||
35 | Removed classes | ||
36 | --------------- | ||
37 | |||
38 | The 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 | |||
45 | pseudo path filtering and mismatch behaviour | ||
46 | -------------------------------------------- | ||
47 | |||
48 | pseudo now operates on a filtered subset of files. This is a significant change | ||
49 | to the way pseudo operates within OpenEmbedded - by default, pseudo monitors and | ||
50 | logs (adds to its database) any file created or modified whilst in a ``fakeroot`` | ||
51 | environment. However, there are large numbers of files that we simply don't care | ||
52 | about 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 | |||
55 | As of this release, new functionality in pseudo is enabled to ignore these | ||
56 | directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable) | ||
57 | resulting in a cleaner database with less chance of "stray" mismatches if files | ||
58 | are modified outside pseudo context. It also should reduce some overhead from | ||
59 | pseudo as the interprocess round trip to the server is avoided. | ||
60 | |||
61 | There is a possible complication where some existing recipe may break, for | ||
62 | example, 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, | ||
64 | there were errors trying to ``chown root`` for files in this location. Another | ||
65 | example was the ``tcl`` recipe where the source directory ``S`` is set to a | ||
66 | subdirectory of the source tree but files were written out to the directory | ||
67 | structure above that subdirectory. For these types of cases in your own recipes, | ||
68 | extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not | ||
69 | be monitoring. | ||
70 | |||
71 | In addition, pseudo's behaviour on mismatches has now been changed - rather | ||
72 | than doing what turns out to be a rather dangerous "fixup" if it sees a file | ||
73 | with a different path but the same inode as another file it has previously seen, | ||
74 | pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </Pseudo_Abort>` | ||
75 | that 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 | |||
83 | In order to solve some previously intractable problems with runtime | ||
84 | dependencies and multilib, a change was made that now requires the :term:`MLPREFIX` | ||
85 | value to be explicitly prepended to package names being added as | ||
86 | dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values) | ||
87 | where the dependency is conditionally added. | ||
88 | |||
89 | If you have anonymous python or in-line python conditionally adding | ||
90 | dependencies in your custom recipes, and you intend for those recipes to | ||
91 | work with multilib, then you will need to ensure that ``${MLPREFIX}`` | ||
92 | is 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 | |||
97 | This also applies when conditionally adding packages to :term:`PACKAGES` where | ||
98 | those 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 | |||
111 | packagegroup-core-device-devel no longer included in images built for qemu* machines | ||
112 | ------------------------------------------------------------------------------------ | ||
113 | |||
114 | ``packagegroup-core-device-devel`` was previously added automatically to | ||
115 | images built for ``qemu*`` machines, however the purpose of the group and what | ||
116 | it should contain is no longer clear, and in general, adding userspace | ||
117 | development items to images is best done at the image/class level; thus this | ||
118 | packagegroup was removed. | ||
119 | |||
120 | This packagegroup previously pulled in the following: | ||
121 | |||
122 | - ``distcc-config`` | ||
123 | - ``nfs-export-root`` | ||
124 | - ``bash`` | ||
125 | - ``binutils-symlinks`` | ||
126 | |||
127 | If you still need any of these in your image built for a ``qemu*`` machine | ||
128 | then you will add them explicitly to :term:`IMAGE_INSTALL` or another | ||
129 | appropriate place in the dependency chain for your image (if you have not | ||
130 | already done so). | ||
131 | |||
132 | |||
133 | .. _migration-3.2-dhcp: | ||
134 | |||
135 | DHCP server/client replaced | ||
136 | --------------------------- | ||
137 | |||
138 | The ``dhcp`` software package has become unmaintained and thus has been | ||
139 | functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will | ||
140 | need to replace references to the recipe/package names as appropriate - most | ||
141 | commonly, at the package level ``dhcp-client`` should be replaced by | ||
142 | ``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any | ||
143 | custom configuration files for these they will need to be adapted - refer to | ||
144 | the upstream documentation for ``dhcpcd`` and ``kea`` for further details. | ||
145 | |||
146 | |||
147 | .. _migration-3.2-packaging-changes: | ||
148 | |||
149 | Packaging 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 | |||
159 | Package QA check changes | ||
160 | ------------------------ | ||
161 | |||
162 | Previously, the following package QA checks triggered warnings, however they can | ||
163 | be indicators of genuine underlying problems and are therefore now treated as | ||
164 | errors: | ||
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 | |||
176 | In 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 | |||
189 | Globbing no longer supported in ``file://`` entries in ``SRC_URI`` | ||
190 | ------------------------------------------------------------------ | ||
191 | |||
192 | Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI` | ||
193 | did not properly support file checksums, thus changes to the source files | ||
194 | would not always change the do_fetch task checksum, and consequently would | ||
195 | not ensure that the changed files would be incorporated in subsequent builds. | ||
196 | |||
197 | Unfortunately it is not practical to make globbing work generically here, so | ||
198 | the decision was taken to remove support for globs in ``file://`` URLs. | ||
199 | If you have any usage of these in your recipes, then you will now need to | ||
200 | either add each of the files that you expect to match explicitly, or | ||
201 | alternatively if you still need files to be pulled in dynamically, put the | ||
202 | files into a subdirectory and reference that instead. | ||
203 | |||
204 | |||
205 | .. _migration-3.2-deploydir-clean: | ||
206 | |||
207 | deploy 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 | |||
212 | Most 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 | |||
217 | Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy`` | ||
218 | ------------------------------------------------------------------------------- | ||
219 | |||
220 | All ``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 | |||
226 | There are cases where one doesn't want ``ldconfig`` on target (e.g. for | ||
227 | read-only root filesystems, it's rather pointless), yet one still | ||
228 | needs ``/etc/ld.so.conf`` to be present at image build time: | ||
229 | |||
230 | When some recipe installs libraries to a non-standard location, and | ||
231 | therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we | ||
232 | need ``/etc/ld.so.conf`` containing: :: | ||
233 | |||
234 | include /etc/ld.so.conf.d/*.conf | ||
235 | |||
236 | in order to get those other locations picked up. | ||
237 | |||
238 | Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that | ||
239 | there's always an ``ld.so.conf`` present when the build-time ``ldconfig`` | ||
240 | runs towards the end of image construction. | ||
241 | |||
242 | The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up | ||
243 | significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they | ||
244 | might be needed in case ``ldconfig`` is installable, so they are left | ||
245 | in place after the image is built. Technically it would be possible to | ||
246 | remove them if desired, though it would not be trivial if you still | ||
247 | wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND` | ||
248 | will not work as ``ldconfig`` is run after the functions referred to | ||
249 | by that variable). | ||
250 | |||
251 | |||
252 | .. _migration-3.2-virgl: | ||
253 | |||
254 | Host 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), | ||
259 | but instructs them to load DRI drivers from the host. Unfortunately this | ||
260 | may not work well with proprietary graphics drivers such as those from | ||
261 | Nvidia; if you are using such drivers then you may need to switch to an | ||
262 | alternative (such as Nouveau in the case of Nvidia hardware) or avoid | ||
263 | using the GL options. | ||
264 | |||
265 | |||
266 | .. _migration-3.2-initramfs-suffix: | ||
267 | |||
268 | initramfs images now use a blank suffix | ||
269 | --------------------------------------- | ||
270 | |||
271 | The reference initramfs images (``core-image-minimal-initramfs``, | ||
272 | ``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now | ||
273 | set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults | ||
274 | to ``".rootfs"``. These images aren't root filesystems and thus the rootfs | ||
275 | label didn't make sense. If you are looking for the output files generated | ||
276 | by these image recipes directly then you will need to adapt to the new | ||
277 | naming without the ``.rootfs`` part. | ||
278 | |||
279 | |||
280 | .. _migration-3.2-image-artifact-names: | ||
281 | |||
282 | Image artifact name variables now centralised in image-artifact-names class | ||
283 | --------------------------------------------------------------------------- | ||
284 | |||
285 | The defaults for the following image artifact name variables have been moved | ||
286 | from 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 | |||
294 | Image-related classes now inherit this class, and typically these variables | ||
295 | are only referenced within image recipes so those will be unaffected by this | ||
296 | change. However if you have references to these variables in either a recipe | ||
297 | that is not an image or a class that is enabled globally, then those will | ||
298 | now need to be changed to ``inherit image-artifact-names``. | ||
299 | |||
300 | |||
301 | .. _migration-3.2-misc: | ||
302 | |||
303 | Miscellaneous 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 @@ | |||
1 | General Migration Considerations | ||
2 | ================================ | ||
3 | |||
4 | Some considerations are not tied to a specific Yocto Project release. | ||
5 | This section presents information you should consider when migrating to | ||
6 | any 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 | ****************************************** | ||
4 | Migrating to a Newer Yocto Project Release | ||
5 | ****************************************** | ||
6 | |||
7 | This chapter provides information you can use to migrate work to a newer | ||
8 | Yocto Project release. You can find the same information in the release | ||
9 | notes 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 | ||
746 | Configuring and Disabling QA Checks | 804 | Configuring and Disabling QA Checks |
747 | =================================== | 805 | =================================== |
@@ -752,10 +810,10 @@ either raise a warning or an error message, using the | |||
752 | variables, respectively. You can also disable checks within a particular | 810 | variables, respectively. You can also disable checks within a particular |
753 | recipe using :term:`INSANE_SKIP`. For information on | 811 | recipe using :term:`INSANE_SKIP`. For information on |
754 | how to work with the QA checks, see the | 812 | how 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 d8d362282b..920794679d 100644 --- a/documentation/ref-manual/release-process.rst +++ b/documentation/ref-manual/release-process.rst | |||
@@ -12,16 +12,15 @@ stability. | |||
12 | Major and Minor Release Cadence | 12 | Major and Minor Release Cadence |
13 | =============================== | 13 | =============================== |
14 | 14 | ||
15 | The Yocto Project delivers major releases (e.g. DISTRO) using a six | 15 | The Yocto Project delivers major releases (e.g. &DISTRO;) using a six |
16 | month cadence roughly timed each April and October of the year. | 16 | month cadence roughly timed each April and October of the year. |
17 | Following are examples of some major YP releases with their codenames | 17 | Here are examples of some major YP releases with their codenames |
18 | also shown. See the "`Major Release | 18 | also shown. See the ":ref:`ref-manual/release-process:major release codenames`" |
19 | Codenames <#major-release-codenames>`__" section for information on | 19 | section for information on codenames used with major releases. |
20 | codenames 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 | ||
26 | While the cadence is never perfect, this timescale facilitates | 25 | While the cadence is never perfect, this timescale facilitates |
27 | regular releases that have strong QA cycles while not overwhelming users | 26 | regular releases that have strong QA cycles while not overwhelming users |
@@ -30,12 +29,12 @@ major holidays in various geographies. | |||
30 | 29 | ||
31 | The Yocto project delivers minor (point) releases on an unscheduled | 30 | The Yocto project delivers minor (point) releases on an unscheduled |
32 | basis and are usually driven by the accumulation of enough significant | 31 | basis and are usually driven by the accumulation of enough significant |
33 | fixes or enhancements to the associated major release. Following are | 32 | fixes or enhancements to the associated major release. |
34 | some example past point releases: | 33 | Some 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 | ||
40 | The point release | 39 | The point release |
41 | indicates a point in the major release branch where a full QA cycle and | 40 | indicates a point in the major release branch where a full QA cycle and |
@@ -57,14 +56,16 @@ codename are likely to be compatible and thus work together. | |||
57 | .. note:: | 56 | .. note:: |
58 | 57 | ||
59 | Codenames are associated with major releases because a Yocto Project | 58 | Codenames are associated with major releases because a Yocto Project |
60 | release number (e.g. DISTRO) could conflict with a given layer or | 59 | release number (e.g. &DISTRO;) could conflict with a given layer or |
61 | company versioning scheme. Codenames are unique, interesting, and | 60 | company versioning scheme. Codenames are unique, interesting, and |
62 | easily identifiable. | 61 | easily identifiable. |
63 | 62 | ||
64 | Releases are given a nominal release version as well but the codename is | 63 | Releases are given a nominal release version as well but the codename is |
65 | used in repositories for this reason. You can find information on Yocto | 64 | used in repositories for this reason. You can find information on Yocto |
66 | Project releases and codenames at | 65 | Project releases and codenames at :yocto_wiki:`/Releases`. |
67 | :yocto_wiki:`/Releases`. | 66 | |
67 | Our :doc:`/migration-guides/index` detail how to migrate from one release of | ||
68 | the Yocto Project to the next. | ||
68 | 69 | ||
69 | Stable Release Process | 70 | Stable 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 | ||
89 | Stable release branches have strong maintenance for about a year after | 90 | .. _ref-long-term-support-releases: |
90 | their initial release. Should significant issues be found for any | 91 | |
91 | release regardless of its age, fixes could be backported to older | 92 | Long Term Support Releases |
92 | releases. For issues that are not backported given an older release, | 93 | ========================== |
93 | Community LTS trees and branches exist where community members share | 94 | |
94 | patches for older releases. However, these types of patches do not go | 95 | While stable releases are supported for a duration of seven months, |
95 | through the same release process as do point releases. You can find more | 96 | some specific ones are now supported for a longer period by the Yocto |
96 | information about stable branch maintenance at | 97 | Project, and are called Long Term Support (:term:`LTS`) releases. |
97 | :yocto_wiki:`/Stable_branch_maintenance`. | 98 | |
99 | When significant issues are found, :term:`LTS` releases allow to publish | ||
100 | fixes not only for the current stable release, but also to the | ||
101 | :term:`LTS` releases that are still supported. Older stable releases which | ||
102 | have reached their End of Life (EOL) won't receive such updates. | ||
103 | |||
104 | This started with version 3.1 ("Dunfell"), released in April 2020, which | ||
105 | the project initially committed to supporting for two years, but this duration | ||
106 | was later extended to four years. Similarly, the following :term:`LTS` release, | ||
107 | version 4.0 ("Kirkstone"), was released two years later in May 2022 and the | ||
108 | project committed to supporting it for four years too. | ||
109 | |||
110 | Therefore, a new :term:`LTS` release is made every two years and is supported | ||
111 | for four years. This offers more stability to project users and leaves more | ||
112 | time to upgrade to the following :term:`LTS` release. | ||
113 | |||
114 | See :yocto_wiki:`/Stable_Release_and_LTS` for details about the management | ||
115 | of 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 | ||
99 | Testing and Quality Assurance | 136 | Testing and Quality Assurance |
100 | ============================= | 137 | ============================= |
@@ -106,7 +143,7 @@ Additionally, because the test strategies are visible to you as a | |||
106 | developer, you can validate your projects. This section overviews the | 143 | developer, you can validate your projects. This section overviews the |
107 | available test infrastructure used in the Yocto Project. For information | 144 | available test infrastructure used in the Yocto Project. For information |
108 | on how to run available tests on your projects, see the | 145 | on 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`" |
110 | section in the Yocto Project Development Tasks Manual. | 147 | section in the Yocto Project Development Tasks Manual. |
111 | 148 | ||
112 | The QA/testing infrastructure is woven into the project to the point | 149 | The 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 | |||
152 | Originally, much of this testing was done manually. However, significant | 183 | Originally, much of this testing was done manually. However, significant |
153 | effort has been made to automate the tests so that more people can use | 184 | effort has been made to automate the tests so that more people can use |
154 | them and the Yocto Project development team can run them faster and more | 185 | them and the Yocto Project development team can run them faster and more |
155 | efficiently. | 186 | efficiently. |
156 | 187 | ||
157 | The Yocto Project's main Autobuilder (&YOCTO_AB_URL;) | 188 | The Yocto Project's main Autobuilder (&YOCTO_AB_URL;) publicly tests each Yocto |
158 | publicly tests each Yocto Project release's code in the | 189 | Project 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 |
160 | occurs for both the current state of the "master" branch and also for | 191 | testing occurs for both the current state of the "master" branch and also for |
161 | submitted patches. Testing for submitted patches usually occurs in the | 192 | submitted patches. Testing for submitted patches usually occurs in the |
162 | "ross/mut" branch in the ``poky-contrib`` repository (i.e. the | 193 | in the "master-next" branch in the :yocto_git:`poky </poky>` repository. |
163 | master-under-test branch) or in the "master-next" branch in the ``poky`` | ||
164 | repository. | ||
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 | ||
172 | Testing within these public branches ensures in a publicly visible way | 200 | Testing within these public branches ensures in a publicly visible way |
173 | that all of the main supposed architectures and recipes in OE-Core | 201 | that 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 | ||
12 | The Yocto Project team is happy for people to experiment with the Yocto | 12 | The Yocto Project team is happy for people to experiment with the Yocto |
13 | Project. A number of places exist to find help if you run into | 13 | Project. There is a number of places where you can find help if you run into |
14 | difficulties or find bugs. This presents information about contributing | 14 | difficulties or find bugs. This presents information about contributing |
15 | and participating in the Yocto Project. | 15 | and participating in the Yocto Project. |
16 | 16 | ||
@@ -23,8 +23,7 @@ The Yocto Project gladly accepts contributions. You can submit changes | |||
23 | to the project either by creating and sending pull requests, or by | 23 | to the project either by creating and sending pull requests, or by |
24 | submitting patches through email. For information on how to do both as | 24 | submitting patches through email. For information on how to do both as |
25 | well as information on how to identify the maintainer for each area of | 25 | well as information on how to identify the maintainer for each area of |
26 | code, see the ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" section in the | 26 | code, see the :doc:`../contributor-guide/index`. |
27 | Yocto 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 | |||
43 | component of the build system that acts contrary to the documentation or | 42 | component of the build system that acts contrary to the documentation or |
44 | your expectations). | 43 | your expectations). |
45 | 44 | ||
46 | A general procedure and guidelines exist for when you use Bugzilla to | 45 | For a general procedure and guidelines on how to use Bugzilla to submit a bug |
47 | submit a bug. For information on how to use Bugzilla to submit a bug | ||
48 | against the Yocto Project, see the following: | 46 | against 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/. | |||
59 | Mailing lists | 57 | Mailing lists |
60 | ============= | 58 | ============= |
61 | 59 | ||
62 | A number of mailing lists maintained by the Yocto Project exist as well | 60 | There are multiple mailing lists maintained by the Yocto Project as well |
63 | as related OpenEmbedded mailing lists for discussion, patch submission | 61 | as related OpenEmbedded mailing lists for discussion, patch submission |
64 | and announcements. To subscribe to one of the following mailing lists, | 62 | and announcements. To subscribe to one of the following mailing lists, |
65 | click on the appropriate URL in the following list and follow the | 63 | click on the appropriate URL in the following list and follow the |
66 | instructions: | 64 | instructions: |
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 | ||
86 | For 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 | |||
87 | See also :yocto_home:`the description of all mailing lists </community/mailing-lists/>`. | ||
88 | 88 | ||
89 | .. _resources-irc: | 89 | .. _resources-irc: |
90 | 90 | ||
91 | Internet Relay Chat (IRC) | 91 | Internet Relay Chat (IRC) |
92 | ========================= | 92 | ========================= |
93 | 93 | ||
94 | Two IRC channels on freenode are available for the Yocto Project and | 94 | Two IRC channels on `Libera Chat <https://libera.chat/>`__ |
95 | Poky discussions: | 95 | are 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 | ||
106 | Here is a list of resources you might find helpful: | 106 | Here 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 | |||
38 | project. BitBake, a :term:`Metadata` interpreter, reads the | 38 | project. BitBake, a :term:`Metadata` interpreter, reads the |
39 | Yocto Project Metadata and runs the tasks defined by that data. Failures | 39 | Yocto Project Metadata and runs the tasks defined by that data. Failures |
40 | are usually caused by errors in your Metadata and not from BitBake | 40 | are usually caused by errors in your Metadata and not from BitBake |
41 | itself; consequently, most users do not need to worry about BitBake. | 41 | itself. |
42 | 42 | ||
43 | When you run the ``bitbake`` command, the main BitBake executable (which | 43 | When you run the ``bitbake`` command, the main BitBake executable (which |
44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the | 44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the |
@@ -57,9 +57,8 @@ For more information on BitBake, see the :doc:`BitBake User Manual | |||
57 | This directory contains user configuration files and the output | 57 | This directory contains user configuration files and the output |
58 | generated by the OpenEmbedded build system in its standard configuration | 58 | generated by the OpenEmbedded build system in its standard configuration |
59 | where the source tree is combined with the output. The :term:`Build Directory` | 59 | where the source tree is combined with the output. The :term:`Build Directory` |
60 | is created initially when you ``source`` | 60 | is created initially when you ``source`` the OpenEmbedded build environment |
61 | the OpenEmbedded build environment setup script (i.e. | 61 | setup script (i.e. :ref:`structure-core-script`). |
62 | :ref:`structure-core-script`). | ||
63 | 62 | ||
64 | It is also possible to place output and configuration files in a | 63 | It is also possible to place output and configuration files in a |
65 | directory separate from the :term:`Source Directory` by | 64 | directory 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 | ||
70 | See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details | ||
71 | about 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`` | |||
150 | directory to do the bulk of the work. | 152 | directory to do the bulk of the work. |
151 | 153 | ||
152 | When you run this script, your Yocto Project environment is set up, a | 154 | When 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 |
154 | directory becomes the Build Directory, and you are presented with some | 156 | :term:`Build Directory`, and you are presented with some simple |
155 | simple suggestions as to what to do next, including a list of some | 157 | suggestions as to what to do next, including a list of some possible |
156 | possible targets to build. Here is an example: | 158 | targets 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 | ||
173 | The default output of the ``oe-init-build-env`` script is from the | 174 | The 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 |
175 | within the :term:`Source Directory`. If you design a | 176 | within the :term:`Source Directory`. If you design a |
176 | custom distribution, you can include your own version of this | 177 | custom distribution, you can include your own versions of these |
177 | configuration file to mention the targets defined by your distribution. | 178 | configuration files where you can provide a brief summary and detailed usage |
179 | notes, such as a list of the targets defined by your distribution. | ||
178 | See the | 180 | See 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`" |
180 | section in the Yocto Project Development Tasks Manual for more | 182 | section in the Yocto Project Development Tasks Manual for more |
181 | information. | 183 | information. |
182 | 184 | ||
183 | By default, running this script without a Build Directory argument | 185 | By default, running this script without a :term:`Build Directory` argument |
184 | creates the ``build/`` directory in your current working directory. If | 186 | creates the ``build/`` directory in your current working directory. If |
185 | you provide a Build Directory argument when you ``source`` the script, | 187 | you provide a :term:`Build Directory` argument when you ``source`` the script, |
186 | you direct the OpenEmbedded build system to create a Build Directory of | 188 | you direct the OpenEmbedded build system to create a :term:`Build Directory` of |
187 | your choice. For example, the following command creates a Build | 189 | your choice. For example, the following command creates a |
188 | Directory 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 | ||
193 | The OpenEmbedded build system uses the template configuration files, which | 195 | The OpenEmbedded build system uses the template configuration files, which |
194 | are found by default in the ``meta-poky/conf/`` directory in the Source | 196 | are found by default in the ``meta-poky/conf/templates/default`` directory in the Source |
195 | Directory. See the | 197 | Directory. 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`" |
197 | section in the Yocto Project Development Tasks Manual for more | 199 | section in the Yocto Project Development Tasks Manual for more |
198 | information. | 200 | information. |
199 | 201 | ||
@@ -215,14 +217,13 @@ These files are standard top-level files. | |||
215 | 217 | ||
216 | .. _structure-build: | 218 | .. _structure-build: |
217 | 219 | ||
218 | The Build Directory - ``build/`` | 220 | The Build Directory --- ``build/`` |
219 | ================================ | 221 | ================================== |
220 | 222 | ||
221 | The OpenEmbedded build system creates the :term:`Build Directory` | 223 | The OpenEmbedded build system creates the :term:`Build Directory` when you run |
222 | when you run the build environment setup | 224 | the build environment setup script :ref:`structure-core-script`. If you do not |
223 | script :ref:`structure-core-script`. If you do not give the Build | 225 | give the :term:`Build Directory` a specific name when you run the setup script, |
224 | Directory a specific name when you run the setup script, the name | 226 | the name defaults to ``build/``. |
225 | defaults to ``build/``. | ||
226 | 227 | ||
227 | For subsequent parsing and processing, the name of the Build directory | 228 | For subsequent parsing and processing, the name of the Build directory |
228 | is available via the :term:`TOPDIR` variable. | 229 | is available via the :term:`TOPDIR` variable. |
@@ -233,12 +234,24 @@ is available via the :term:`TOPDIR` variable. | |||
233 | ----------------------- | 234 | ----------------------- |
234 | 235 | ||
235 | The OpenEmbedded build system creates this directory when you enable | 236 | The OpenEmbedded build system creates this directory when you enable |
236 | build history via the ``buildhistory`` class file. The directory | 237 | build history via the :ref:`ref-classes-buildhistory` class file. The directory |
237 | organizes build information into image, packages, and SDK | 238 | organizes build information into image, packages, and SDK |
238 | subdirectories. For information on the build history feature, see the | 239 | subdirectories. 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`" |
240 | section in the Yocto Project Development Tasks Manual. | 241 | section in the Yocto Project Development Tasks Manual. |
241 | 242 | ||
243 | .. _structure-build-cache: | ||
244 | |||
245 | ``build/cache/`` | ||
246 | ---------------- | ||
247 | |||
248 | This directory contains several internal files used by the OpenEmbedded | ||
249 | build system. | ||
250 | |||
251 | It also contains ``sanity_info``, a text file keeping track of important | ||
252 | build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`, | ||
253 | as 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 | |||
253 | relatively rare. | 266 | relatively rare. |
254 | 267 | ||
255 | At a minimum, you would normally edit this file to select the target | 268 | At 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 |
258 | which you want to access downloaded files (``DL_DIR``). | 271 | which you want to access downloaded files (:term:`DL_DIR`). |
259 | 272 | ||
260 | If ``local.conf`` is not present when you start the build, the | 273 | If ``local.conf`` is not present when you start the build, the |
261 | OpenEmbedded build system creates it from ``local.conf.sample`` when you | 274 | OpenEmbedded 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 | ||
265 | The source ``local.conf.sample`` file used depends on the | 278 | The 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`` |
267 | when you are building from the Yocto Project development environment, | 280 | when you are building from the Yocto Project development environment, |
268 | and to ``meta/conf/`` when you are building from the OpenEmbedded-Core | 281 | and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core |
269 | environment. Because the script variable points to the source of the | 282 | environment. 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 |
271 | build environment from any layer by setting the variable in the | 284 | build environment from any layer by setting the variable in the |
272 | top-level build environment setup script as follows: | 285 | top-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 | ||
277 | Once the build process gets the sample | 289 | Once the build process gets the sample |
278 | file, it uses ``sed`` to substitute final | 290 | file, 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 | ||
294 | This configuration file defines | 306 | This configuration file defines |
295 | :ref:`layers <dev-manual/common-tasks:understanding and creating layers>`, | 307 | :ref:`layers <dev-manual/layers:understanding and creating layers>`, |
296 | which are directory trees, traversed (or walked) by BitBake. The | 308 | which 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` |
298 | variable to list the layers BitBake tries to find. | 310 | variable 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 | ||
305 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` | 317 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` |
306 | file used depends on the ``$TEMPLATECONF`` script variable, which | 318 | file used depends on the :term:`TEMPLATECONF` script variable, which |
307 | defaults to ``meta-poky/conf/`` when you are building from the Yocto | 319 | defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto |
308 | Project development environment, and to ``meta/conf/`` when you are | 320 | Project development environment, and to ``meta/conf/templates/default`` when you are |
309 | building from the OpenEmbedded-Core environment. Because the script | 321 | building from the OpenEmbedded-Core environment. Because the script |
310 | variable points to the source of the ``bblayers.conf.sample`` file, this | 322 | variable points to the source of the ``bblayers.conf.sample`` file, this |
311 | implies that you can base your build from any layer by setting the | 323 | implies that you can base your build from any layer by setting the |
312 | variable in the top-level build environment setup script as follows: | 324 | variable 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 | ||
317 | Once the build process gets the sample file, it uses ``sed`` to substitute final | 328 | Once 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 | |||
332 | This file indicates the state of the sanity checks and is created during | ||
333 | the build. | ||
334 | |||
335 | .. _structure-build-downloads: | 338 | .. _structure-build-downloads: |
336 | 339 | ||
337 | ``build/downloads/`` | 340 | ``build/downloads/`` |
@@ -340,7 +343,7 @@ the build. | |||
340 | This directory contains downloaded upstream source tarballs. You can | 343 | This directory contains downloaded upstream source tarballs. You can |
341 | reuse the directory for multiple builds or move the directory to another | 344 | reuse the directory for multiple builds or move the directory to another |
342 | location. You can control the location of this directory through the | 345 | location. 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 | |||
350 | This directory contains the shared state cache. You can reuse the | 353 | This directory contains the shared state cache. You can reuse the |
351 | directory for multiple builds or move the directory to another location. | 354 | directory for multiple builds or move the directory to another location. |
352 | You can control the location of this directory through the | 355 | You 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 | ||
375 | This directory stores the build statistics. | 378 | This 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 | ||
382 | When BitBake parses the metadata (recipes and configuration files), it | 386 | When BitBake parses the metadata (recipes and configuration files), it |
383 | caches the results in ``build/tmp/cache/`` to speed up future builds. | 387 | caches 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 | ||
398 | This directory contains any "end result" output from the OpenEmbedded | 402 | This directory contains any "end result" output from the OpenEmbedded |
399 | build process. The :term:`DEPLOY_DIR` variable points | 403 | build 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 | ||
411 | This directory receives any ``.deb`` packages produced by the build | 415 | This directory receives any ``.deb`` packages produced by the build |
412 | process. The packages are sorted into feeds for different architecture | 416 | process. 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 | ||
420 | This directory receives any ``.rpm`` packages produced by the build | 424 | This directory receives any ``.rpm`` packages produced by the build |
421 | process. The packages are sorted into feeds for different architecture | 425 | process. 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 | ||
429 | This directory receives ``.ipk`` packages produced by the build process. | 433 | This 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 | ||
436 | This directory receives package licensing information. For example, the | 440 | This directory receives package licensing information. For example, the |
437 | directory contains sub-directories for ``bash``, ``busybox``, and | 441 | directory 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`` |
439 | license files with other licensing information. For information on | 443 | license files with other licensing information. For information on |
440 | licensing, see the | 444 | licensing, 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`" |
442 | section in the Yocto Project Development Tasks Manual. | 446 | section 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 | ||
449 | This directory is populated with the basic output objects of the build | 453 | This 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. | |||
463 | If you do accidentally delete files here, you will need to force them to | 467 | If you do accidentally delete files here, you will need to force them to |
464 | be re-created. In order to do that, you will need to know the target | 468 | be re-created. In order to do that, you will need to know the target |
465 | that produced them. For example, these commands rebuild and re-create | 469 | that produced them. For example, these commands rebuild and re-create |
466 | the kernel files: | 470 | the 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 | ||
477 | The OpenEmbedded build system creates this directory to hold toolchain | 480 | The OpenEmbedded build system creates this directory to hold toolchain |
478 | installer scripts which, when executed, install the sysroot that matches | 481 | installer 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 | ||
489 | The OpenEmbedded build system uses this directory for the shared state | 492 | The OpenEmbedded build system uses this directory for the shared state |
490 | manifest files. The shared state code uses these files to record the | 493 | manifest 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 | ||
502 | This directory is the location of the sysroot contents that the task | 505 | This 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 | ||
517 | Previous versions of the OpenEmbedded build system used to create a | 520 | Previous versions of the OpenEmbedded build system used to create a |
518 | global shared sysroot per machine along with a native sysroot. Beginning | 521 | global shared sysroot per machine along with a native sysroot. Since |
519 | with the 2.3 version of the Yocto Project, sysroots exist in | 522 | the 2.3 version of the Yocto Project, there are sysroots in |
520 | recipe-specific :term:`WORKDIR` directories. Thus, the | 523 | recipe-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 | ||
535 | This directory holds information that BitBake uses for accounting | 538 | This directory holds information that BitBake uses for accounting |
536 | purposes to track what tasks have run and when they have run. The | 539 | purposes to track what tasks have run and when they have run. The |
537 | directory is sub-divided by architecture, package name, and version. | 540 | directory is sub-divided by architecture, package name, and version. |
538 | Following is an example: | 541 | Here 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 | ||
556 | This directory contains general logs that are not otherwise placed using | 558 | This directory contains general logs that are not otherwise placed using |
557 | the package's ``WORKDIR``. Examples of logs are the output from the | 559 | the 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 |
559 | necessarily mean this directory is created. | 561 | necessarily 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 | ||
566 | This directory contains architecture-specific work sub-directories for | 568 | This directory contains architecture-specific work sub-directories for |
567 | packages built by BitBake. All tasks execute from the appropriate work | 569 | packages 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 | |||
575 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` | 577 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` |
576 | built within the Yocto Project. For this package, a work directory of | 578 | built 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 |
578 | to as the ``WORKDIR``, is created. Within this directory, the source is | 580 | to as the :term:`WORKDIR`, is created. Within this directory, the source is |
579 | unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. | 581 | unpacked 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 |
581 | the Yocto Project Development Tasks Manual for more information.) Within | 583 | the Yocto Project Development Tasks Manual for more information.) Within |
582 | the ``linux-qemux86-standard-build`` directory, standard Quilt | 584 | the ``linux-qemux86-standard-build`` directory, standard Quilt |
583 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and | 585 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and |
584 | standard Quilt commands can be used. | 586 | standard Quilt commands can be used. |
585 | 587 | ||
586 | There are other directories generated within ``WORKDIR``. The most | 588 | There are other directories generated within :term:`WORKDIR`. The most |
587 | important directory is ``WORKDIR/temp/``, which has log files for each | 589 | important directory is ``WORKDIR/temp/``, which has log files for each |
588 | task (``log.do_*.pid``) and contains the scripts BitBake runs for each | 590 | task (``log.do_*.pid``) and contains the scripts BitBake runs for each |
589 | task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make | 591 | task (``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 | ||
598 | The recipe work directory - ``${WORKDIR}``. | 600 | The recipe work directory --- ``${WORKDIR}``. |
599 | 601 | ||
600 | As described earlier in the | 602 | As 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. | |||
607 | name, and the version of the recipe (i.e. | 609 | name, and the version of the recipe (i.e. |
608 | :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). | 610 | :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). |
609 | 611 | ||
610 | A number of key subdirectories exist within each recipe work directory: | 612 | Here 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 | ||
656 | For efficiency, the OpenEmbedded build system creates and uses this | 658 | For efficiency, the OpenEmbedded build system creates and uses this |
657 | directory to hold recipes that share a work directory with other | 659 | directory 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 | ||
663 | The Metadata - ``meta/`` | 665 | The Metadata --- ``meta/`` |
664 | ======================== | 666 | ========================== |
665 | 667 | ||
666 | As mentioned previously, :term:`Metadata` is the core of the | 668 | As mentioned previously, :term:`Metadata` is the core of the |
667 | Yocto Project. Metadata has several important subdivisions: | 669 | Yocto 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 | ||
674 | This directory contains the ``*.bbclass`` files. Class files are used to | 676 | These directories contain the ``*.bbclass`` files. Class files are used to |
675 | abstract common code so it can be reused by multiple packages. Every | 677 | abstract common code so it can be reused by multiple packages. Every |
676 | package inherits the ``base.bbclass`` file. Examples of other important | 678 | package inherits the :ref:`ref-classes-base` file. Examples of other important |
677 | classes are ``autotools.bbclass``, which in theory allows any | 679 | classes are :ref:`ref-classes-autotools`, which in theory allows any |
678 | Autotool-enabled package to work with the Yocto Project with minimal | 680 | Autotool-enabled package to work with the Yocto Project with minimal |
679 | effort. Another example is ``kernel.bbclass`` that contains common code | 681 | effort. Another example is :ref:`ref-classes-kernel` that contains common code |
680 | and functions for working with the Linux kernel. Functions like image | 682 | and functions for working with the Linux kernel. Functions like image |
681 | generation or packaging also have their specific class files such as | 683 | generation 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 | ||
684 | For reference information on classes, see the | 687 | For 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 | ||
705 | This directory contains all the machine configuration files. If you set | 708 | This 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 | ||
716 | The contents of this directory controls any distribution-specific | 719 | The contents of this directory controls any distribution-specific |
717 | configurations. For the Yocto Project, the ``defaultsetup.conf`` is the | 720 | configurations. For the Yocto Project, the ``defaultsetup.conf`` is the |
718 | main file here. This directory includes the versions and the ``SRCDATE`` | 721 | main file here. This directory includes the versions and the :term:`SRCDATE` |
719 | definitions for applications that are configured here. An example of an | 722 | definitions for applications that are configured here. An example of an |
720 | alternative configuration might be ``poky-bleeding.conf``. Although this | 723 | alternative configuration might be ``poky-bleeding.conf``. Although this |
721 | file mainly inherits its configuration from Poky. | 724 | file 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 | ||
728 | The OpenEmbedded build system searches this directory for configuration | 731 | The OpenEmbedded build system searches this directory for configuration |
729 | files that correspond to the value of | 732 | files that correspond to the value of |
@@ -748,7 +751,9 @@ and lists of files and directories with known permissions. | |||
748 | ------------- | 751 | ------------- |
749 | 752 | ||
750 | This directory contains OpenEmbedded Python library code used during the | 753 | This directory contains OpenEmbedded Python library code used during the |
751 | build process. | 754 | build 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 | ||
790 | This directory contains non-essential applications that add features | 795 | This directory contains non-essential applications that add features |
791 | compared to the alternatives in core. You might need this directory for | 796 | compared to the alternatives in core. You might need this directory for |
792 | full tool functionality or for Linux Standard Base (LSB) compliance. | 797 | full tool functionality. |
793 | 798 | ||
794 | .. _structure-meta-recipes-gnome: | 799 | .. _structure-meta-recipes-gnome: |
795 | 800 | ||
@@ -815,14 +820,6 @@ libraries. | |||
815 | This directory contains the kernel and generic applications and | 820 | This directory contains the kernel and generic applications and |
816 | libraries that have strong kernel dependencies. | 821 | libraries that have strong kernel dependencies. |
817 | 822 | ||
818 | .. _structure-meta-recipes-lsb4: | ||
819 | |||
820 | ``meta/recipes-lsb4/`` | ||
821 | ---------------------- | ||
822 | |||
823 | This directory contains recipes specifically added to support the Linux | ||
824 | Standard 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 66afb08102..0fc92550a5 100644 --- a/documentation/ref-manual/system-requirements.rst +++ b/documentation/ref-manual/system-requirements.rst | |||
@@ -4,7 +4,7 @@ | |||
4 | System Requirements | 4 | System Requirements |
5 | ******************* | 5 | ******************* |
6 | 6 | ||
7 | Welcome to the Yocto Project Reference Manual! This manual provides | 7 | Welcome to the Yocto Project Reference Manual. This manual provides |
8 | reference information for the current release of the Yocto Project, and | 8 | reference information for the current release of the Yocto Project, and |
9 | is most effectively used after you have an understanding of the basics | 9 | is most effectively used after you have an understanding of the basics |
10 | of the Yocto Project. The manual is neither meant to be read as a | 10 | of 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: | 32 | Minimum Free Disk Space |
33 | ======================= | ||
34 | |||
35 | To build an image such as ``core-image-sato`` for the ``qemux86-64`` machine, | ||
36 | you need a system with at least &MIN_DISK_SPACE; Gbytes of free disk space. | ||
37 | However, much more disk space will be necessary to build more complex images, | ||
38 | to run multiple builds and to cache build artifacts, improving build efficiency. | ||
39 | |||
40 | If you have a shortage of disk space, see the ":doc:`/dev-manual/disk-space`" | ||
41 | section of the Development Tasks Manual. | ||
42 | |||
43 | .. _system-requirements-minimum-ram: | ||
44 | |||
45 | Minimum System RAM | ||
46 | ================== | ||
47 | |||
48 | You 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 | ||
50 | system with 4 CPU cores, but your builds will be much faster on a system with | ||
51 | as much RAM and as many CPU cores as possible. | ||
52 | |||
53 | .. _system-requirements-supported-distros: | ||
33 | 54 | ||
34 | Supported Linux Distributions | 55 | Supported Linux Distributions |
35 | ============================= | 56 | ============================= |
36 | 57 | ||
37 | Currently, the Yocto Project is supported on the following | 58 | Currently, the &DISTRO; release ("&DISTRO_NAME;") of the Yocto Project is |
38 | distributions: | 59 | supported 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) | 81 | The following distribution versions are still tested, even though the |
82 | organizations 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 | |||
88 | Note that the Yocto Project doesn't have access to private updates | ||
89 | that some of these versions may have. Therefore, our testing has | ||
90 | limited value if you have access to such updates. | ||
91 | |||
92 | Finally, here are the distribution versions which were previously | ||
93 | tested on former revisions of "&DISTRO_NAME;", but no longer are: | ||
63 | 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 | ||
101 | Required Packages for the Build Host | 137 | Required Packages for the Build Host |
102 | ==================================== | 138 | ==================================== |
@@ -111,290 +147,240 @@ function. | |||
111 | Ubuntu and Debian | 147 | Ubuntu and Debian |
112 | ----------------- | 148 | ----------------- |
113 | 149 | ||
114 | The following list shows the required packages by function given a | 150 | Here are the packages needed to build an image on a headless system |
115 | supported Ubuntu or Debian Linux distribution: | 151 | with 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 | 161 | ||
126 | $ sudo apt-get build-dep qemu | 162 | $ sudo apt build-dep qemu |
127 | $ sudo apt-get remove oss4-dev | 163 | $ sudo apt remove oss4-dev |
128 | 164 | ||
129 | - For Debian-8, ``python3-git`` and ``pylint3`` are no longer | 165 | Here are the packages needed to build Project documentation manuals:: |
130 | available via ``apt-get``. | ||
131 | :: | ||
132 | 166 | ||
133 | $ sudo pip3 install GitPython pylint==1.9.5 | 167 | $ sudo apt install git make inkscape texlive-latex-extra |
134 | 168 | $ sudo apt install sphinx python3-saneyaml python3-sphinx-rtd-theme | |
135 | - *Essentials:* Packages needed to build an image on a headless system: | ||
136 | :: | ||
137 | |||
138 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; | ||
139 | |||
140 | - *Documentation:* Packages needed if you are going to build out the | ||
141 | Yocto Project documentation manuals: | ||
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 | ||
153 | Fedora Packages | 170 | Fedora Packages |
154 | --------------- | 171 | --------------- |
155 | 172 | ||
156 | The following list shows the required packages by function given a | 173 | Here are the packages needed to build an image on a headless system |
157 | supported Fedora Linux distribution: | 174 | with a supported Fedora Linux distribution:: |
158 | 175 | ||
159 | - *Essentials:* Packages needed to build an image for a headless | 176 | $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; |
160 | system: | ||
161 | :: | ||
162 | 177 | ||
163 | $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; | 178 | Here are the packages needed to build Project documentation manuals:: |
164 | 179 | ||
165 | - *Documentation:* Packages needed if you are going to build out the | 180 | $ sudo dnf install git make python3-pip which inkscape texlive-fncychap |
166 | Yocto Project documentation manuals: | 181 | &PIP3_HOST_PACKAGES_DOC; |
167 | :: | ||
168 | |||
169 | $ sudo dnf install make python3-pip which | ||
170 | &PIP3_HOST_PACKAGES_DOC; | ||
171 | 182 | ||
172 | openSUSE Packages | 183 | openSUSE Packages |
173 | ----------------- | 184 | ----------------- |
174 | 185 | ||
175 | The following list shows the required packages by function given a | 186 | Here are the packages needed to build an image on a headless system |
176 | supported openSUSE Linux distribution: | 187 | with 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 | |||
192 | CentOS-7 Packages | ||
193 | ----------------- | ||
194 | |||
195 | The following list shows the required packages by function given a | ||
196 | supported CentOS-7 Linux distribution: | ||
197 | |||
198 | - *Essentials:* Packages needed to build an image for a headless | ||
199 | system: | ||
200 | :: | ||
201 | |||
202 | $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; | ||
203 | |||
204 | .. note:: | ||
205 | 188 | ||
206 | - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is | 189 | $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; |
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 | 190 | ||
211 | - The ``makecache`` command consumes additional Metadata from | 191 | Here are the packages needed to build Project documentation manuals:: |
212 | ``epel-release``. | ||
213 | 192 | ||
214 | - *Documentation:* Packages needed if you are going to build out the | 193 | $ sudo zypper install git make python3-pip which inkscape texlive-fncychap |
215 | Yocto Project documentation manuals: | 194 | &PIP3_HOST_PACKAGES_DOC; |
216 | :: | ||
217 | 195 | ||
218 | $ sudo yum install make python3-pip which | ||
219 | &PIP3_HOST_PACKAGES_DOC; | ||
220 | 196 | ||
221 | CentOS-8 Packages | 197 | AlmaLinux Packages |
222 | ----------------- | 198 | ------------------ |
223 | 199 | ||
224 | The following list shows the required packages by function given a | 200 | Here are the packages needed to build an image on a headless system |
225 | supported CentOS-8 Linux distribution: | 201 | with a supported AlmaLinux distribution:: |
226 | 202 | ||
227 | - *Essentials:* Packages needed to build an image for a headless | 203 | $ sudo dnf install &ALMALINUX_HOST_PACKAGES_ESSENTIAL; |
228 | system: | ||
229 | :: | ||
230 | 204 | ||
231 | $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; | 205 | .. note:: |
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 | 218 | Here 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 | ||
253 | Required Git, tar, Python and gcc Versions | 225 | Required Git, tar, Python, make and gcc Versions |
254 | ========================================== | 226 | ================================================ |
255 | 227 | ||
256 | In order to use the build system, your host development system must meet | 228 | In order to use the build system, your host development system must meet |
257 | the following version requirements for Git, tar, and Python: | 229 | the 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 | ||
265 | If your host development system does not meet all these requirements, | 239 | If your host development system does not meet all these requirements, |
266 | you can resolve this by installing a ``buildtools`` tarball that | 240 | you can resolve this by installing a :term:`buildtools` tarball that |
267 | contains these tools. You can get the tarball one of two ways: download | 241 | contains these tools. You can either download a pre-built tarball or |
268 | a pre-built tarball or use BitBake to build the tarball. | 242 | use BitBake to build one. |
269 | 243 | ||
270 | In addition, your host development system must meet the following | 244 | In addition, your host development system must meet the following |
271 | version requirement for gcc: | 245 | version requirement for gcc: |
272 | 246 | ||
273 | - gcc 5.0 or greater | 247 | - gcc &MIN_GCC_VERSION; or greater |
274 | 248 | ||
275 | If your host development system does not meet this requirement, you can | 249 | If your host development system does not meet this requirement, you can |
276 | resolve this by installing a ``buildtools-extended`` tarball that | 250 | resolve this by installing a :term:`buildtools-extended` tarball that |
277 | contains additional tools, the equivalent of ``buildtools-essential``. | 251 | contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential`` |
252 | package. | ||
253 | |||
254 | For systems with a broken make version (e.g. make 4.2.1 without patches) but | ||
255 | where the rest of the host tools are usable, you can use the :term:`buildtools-make` | ||
256 | tarball instead. | ||
257 | |||
258 | In the sections that follow, three different methods will be described for | ||
259 | installing the :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make` | ||
260 | toolset. | ||
278 | 261 | ||
279 | Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script | 262 | Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script |
280 | -------------------------------------------------------------------------------- | 263 | -------------------------------------------------------------------------------- |
281 | 264 | ||
282 | The ``install-buildtools`` script is the easiest of the three methods by | 265 | The ``install-buildtools`` script is the easiest of the three methods by |
283 | which you can get these tools. It downloads a pre-built buildtools | 266 | which you can get these tools. It downloads a pre-built :term:`buildtools` |
284 | installer and automatically installs the tools for you: | 267 | installer and automatically installs the tools for you: |
285 | 268 | ||
286 | 1. 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 | ||
314 | 2. 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 | ||
301 | |||
302 | #. Source the tools environment setup script by using a command like the | ||
303 | following:: | ||
319 | 304 | ||
320 | Of course, you need to supply your installation directory and be sure to | 305 | $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux |
321 | use the right file (i.e. i586 or x86_64). | ||
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 | ||
331 | Downloading a Pre-Built ``buildtools`` Tarball | 315 | Downloading a Pre-Built ``buildtools`` Tarball |
332 | ---------------------------------------------- | 316 | ---------------------------------------------- |
333 | 317 | ||
334 | Downloading and running a pre-built buildtools installer is the easiest | 318 | If you would prefer not to use the ``install-buildtools`` script, you can instead |
335 | of the two methods by which you can get these tools: | 319 | download and run a pre-built :term:`buildtools` installer yourself with the following |
320 | steps: | ||
336 | 321 | ||
337 | 1. 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 | ||
339 | 2. 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 |
330 | |||
331 | Here is an example for the extended installer:: | ||
332 | |||
333 | $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh | ||
344 | 334 | ||
345 | Here is an example for the extended installer: | 335 | An example for the make-only installer:: |
346 | :: | ||
347 | 336 | ||
348 | $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh | 337 | $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh |
349 | 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 | ||
354 | 3. 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 | ||
372 | Building Your Own ``buildtools`` Tarball | 356 | Building Your Own ``buildtools`` Tarball |
373 | ---------------------------------------- | 357 | ---------------------------------------- |
374 | 358 | ||
375 | Building and running your own buildtools installer applies only when you | 359 | Building and running your own :term:`buildtools` installer applies only when you |
376 | have a build host that can already run BitBake. In this case, you use | 360 | have a build host that can already run BitBake. In this case, you use |
377 | that machine to build the ``.sh`` file and then take steps to transfer | 361 | that machine to build the ``.sh`` file and then take steps to transfer |
378 | and run it on a machine that does not meet the minimal Git, tar, and | 362 | and run it on a machine that does not meet the minimal Git, tar, and |
379 | Python (or gcc) requirements. | 363 | Python (or gcc) requirements. |
380 | 364 | ||
381 | Here are the steps to take to build and run your own buildtools | 365 | Here are the steps to take to build and run your own :term:`buildtools` |
382 | installer: | 366 | installer: |
383 | 367 | ||
384 | 1. 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 | ||
388 | 2. 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 | ||
408 | 3. 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 | ||
411 | 4. 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 | ||
427 | 5. 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 | ||
15 | The following sections describe normal tasks associated with building a | 15 | The following sections describe normal tasks associated with building a |
16 | recipe. For more information on tasks and dependencies, see the | 16 | recipe. 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 |
19 | BitBake User Manual. | 19 | BitBake User Manual. |
20 | 20 | ||
21 | .. _ref-tasks-build: | 21 | .. _ref-tasks-build: |
@@ -36,7 +36,7 @@ directory set to ``${``\ :term:`B`\ ``}``. | |||
36 | 36 | ||
37 | The default behavior of this task is to run the ``oe_runmake`` function | 37 | The default behavior of this task is to run the ``oe_runmake`` function |
38 | if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. | 38 | if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. |
39 | If no such file is found, the ``do_compile`` task does nothing. | 39 | If 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`\ ``}``. | |||
57 | The default behavior of this task is to run ``oe_runmake clean`` if a | 57 | The default behavior of this task is to run ``oe_runmake clean`` if a |
58 | makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and | 58 | makefile (``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 |
60 | file is found or the ``CLEANBROKEN`` variable is set to "1", the | 60 | file 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 | ||
80 | Recipes implementing this task should inherit the | 80 | Recipes 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 |
82 | to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be | 82 | to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be |
83 | confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up | 83 | confused 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 |
85 | through sstate use. The sstate mechanism takes care of copying the | 85 | through sstate use. The sstate mechanism takes care of copying the |
86 | output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. | 86 | output 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 | ||
93 | The ``do_deploy`` task is not added as a task by default and | 93 | The :ref:`ref-tasks-deploy` task is not added as a task by default and |
94 | consequently needs to be added manually. If you want the task to run | 94 | consequently needs to be added manually. If you want the task to run |
95 | after :ref:`ref-tasks-compile`, you can add it by doing | 95 | after :ref:`ref-tasks-compile`, you can add it by doing |
96 | the following: | 96 | the following:: |
97 | :: | ||
98 | 97 | ||
99 | addtask deploy after do_compile | 98 | addtask deploy after do_compile |
100 | 99 | ||
101 | Adding ``do_deploy`` after other tasks works the same way. | 100 | Adding :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 | ||
115 | If the ``do_deploy`` task re-executes, any previous output is removed | 113 | If 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 | ||
123 | Fetches the source code. This task uses the | 121 | Fetches the source code. This task uses the :term:`SRC_URI` variable and the |
124 | :term:`SRC_URI` variable and the argument's prefix to | 122 | argument's prefix to determine the correct |
125 | determine the correct :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` | 123 | :ref:`fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` |
126 | module. | 124 | module. |
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 | ||
133 | Starts the image generation process. The ``do_image`` task runs after | 131 | Starts the image generation process. The :ref:`ref-tasks-image` task runs after |
134 | the OpenEmbedded build system has run the | 132 | the 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 |
136 | identified for installation into the image and the root filesystem is | 134 | identified for installation into the image and the root filesystem is |
137 | created, complete with post-processing. | 135 | created, complete with post-processing. |
138 | 136 | ||
139 | The ``do_image`` task performs pre-processing on the image through the | 137 | The :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 |
141 | dynamically generates supporting ``do_image_*`` tasks as needed. | 139 | dynamically generates supporting :ref:`do_image_* <ref-tasks-image>` tasks as needed. |
142 | 140 | ||
143 | For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`" | 141 | For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`" |
144 | section in the Yocto Project Overview and Concepts Manual. | 142 | section 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 | ||
151 | Completes the image generation process. The ``do_image_complete`` task | 149 | Completes the image generation process. The :ref:`do_image_complete <ref-tasks-image-complete>` task |
152 | runs after the OpenEmbedded build system has run the | 150 | runs 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 |
154 | pre-processing occurs and through dynamically generated ``do_image_*`` | 152 | pre-processing occurs and through dynamically generated :ref:`do_image_* <ref-tasks-image>` |
155 | tasks the image is constructed. | 153 | tasks the image is constructed. |
156 | 154 | ||
157 | The ``do_image_complete`` task performs post-processing on the image | 155 | The :ref:`do_image_complete <ref-tasks-image-complete>` task performs post-processing on the image |
158 | through the | 156 | through 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. | |||
170 | Copies files that are to be packaged into the holding area | 168 | Copies 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 |
172 | working directory set to ``${``\ :term:`B`\ ``}``, which is the | 170 | working directory set to ``${``\ :term:`B`\ ``}``, which is the |
173 | compilation directory. The ``do_install`` task, as well as other tasks | 171 | compilation directory. The :ref:`ref-tasks-install` task, as well as other tasks |
174 | that either directly or indirectly depend on the installed files (e.g. | 172 | that 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` |
215 | variables. | 213 | variables. |
216 | 214 | ||
217 | The ``do_package`` task, in conjunction with the | 215 | The :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 |
219 | important package metadata. For additional information, see the | 217 | important 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 | ||
229 | Runs QA checks on packaged files. For more information on these checks, | 227 | Runs QA checks on packaged files. For more information on these checks, |
230 | see the :ref:`insane <ref-classes-insane>` class. | 228 | see 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 |
263 | the Yocto Project Overview and Concepts Manual. | 261 | the Yocto Project Overview and Concepts Manual. |
264 | 262 | ||
265 | .. _ref-tasks-package_write_tar: | ||
266 | |||
267 | ``do_package_write_tar`` | ||
268 | ------------------------ | ||
269 | |||
270 | Creates tarballs and places them in the | ||
271 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in | ||
272 | the package feeds area. For more information, see the | ||
273 | ":ref:`overview-manual/concepts:package feeds`" section in | ||
274 | the 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 | |||
302 | and kept in a subdirectory of the directory holding the recipe file. For | 289 | and kept in a subdirectory of the directory holding the recipe file. For |
303 | example, consider the | 290 | example, consider the |
304 | :yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>` | 291 | :yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>` |
305 | recipe from the OE-Core layer (i.e. ``poky/meta``): | 292 | recipe 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 | ||
310 | This recipe has two patch files located here: | 296 | This 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 | ||
315 | In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source | 300 | In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source |
316 | and patch files needed to build the package. | 301 | and 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 | ||
323 | As mentioned earlier, the build system treats files whose file types are | 308 | As 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 |
326 | file as a patch file: | 311 | file 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 | ||
334 | Conversely, if you have a directory full of patch files and you want to | 318 | Conversely, if you have a file whose file type is ``.patch`` or ``.diff`` |
335 | exclude some so that the ``do_patch`` task does not apply them during | 319 | and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply |
336 | the patch phase, you can use the "apply=no" parameter with the | 320 | it 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 | ||
346 | In the | 329 | In the previous example ``file1.patch`` would be applied as a patch by default |
347 | previous example, assuming all the files in the directory holding the | 330 | while ``file2.patch`` would not be applied. |
348 | patch files end with either ``.patch`` or ``.diff``, every file would be | ||
349 | applied as a patch by default except for the ``patch_file5`` patch. | ||
350 | 331 | ||
351 | You can find out more about the patching process in the | 332 | You 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 |
353 | the Yocto Project Overview and Concepts Manual and the | 334 | the 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 |
355 | Yocto Project Development Tasks Manual. | 336 | Yocto 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 | |||
400 | these variables inside your recipe if you need to make additional (or | 381 | these variables inside your recipe if you need to make additional (or |
401 | fewer) directories available to other recipes at build time. | 382 | fewer) directories available to other recipes at build time. |
402 | 383 | ||
403 | The ``do_populate_sysroot`` task is a shared state (sstate) task, which | 384 | The :ref:`ref-tasks-populate_sysroot` task is a shared state (sstate) task, which |
404 | means that the task can be accelerated through sstate use. Realize also | 385 | means that the task can be accelerated through sstate use. Realize also |
405 | that if the task is re-executed, any previous output is removed (i.e. | 386 | that 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 |
416 | dependencies specified by :term:`DEPENDS`). See the | 397 | dependencies 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 | ||
424 | Removes work files after the OpenEmbedded build system has finished with | 405 | Removes work files after the OpenEmbedded build system has finished with |
425 | them. You can learn more by looking at the | 406 | them. 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 | |||
436 | reside. For more information on how source files are unpacked, see the | 417 | reside. 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`" |
438 | section in the Yocto Project Overview and Concepts Manual and also see | 419 | section in the Yocto Project Overview and Concepts Manual and also see |
439 | the ``WORKDIR`` and ``S`` variable descriptions. | 420 | the :term:`WORKDIR` and :term:`S` variable descriptions. |
440 | 421 | ||
441 | Manually Called Tasks | 422 | Manually Called Tasks |
442 | ===================== | 423 | ===================== |
@@ -444,39 +425,6 @@ Manually Called Tasks | |||
444 | These tasks are typically manually triggered (e.g. by using the | 425 | These 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 | |||
452 | Provides information about the recipe including its upstream version and | ||
453 | status. The upstream version and status reveals whether or not a version | ||
454 | of the recipe exists upstream and a status of not updated, updated, or | ||
455 | unknown. | ||
456 | |||
457 | To check the upstream version and status of a recipe, use the following | ||
458 | devtool commands: | ||
459 | :: | ||
460 | |||
461 | $ devtool latest-version | ||
462 | $ devtool check-upgrade-status | ||
463 | |||
464 | See the ":ref:`ref-manual/devtool-reference:\`\`devtool\`\` quick reference`" | ||
465 | chapter for more information on | ||
466 | ``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" | ||
467 | section for information on checking the upgrade status of a recipe. | ||
468 | |||
469 | To 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 | |||
475 | By 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 | ||
490 | Removes all output files for a target from the | 438 | Removes 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 | ||
497 | You can run this task using BitBake as follows: | 445 | You 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 | |||
515 | Removes all output files, shared state | 462 | Removes 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 |
517 | downloaded source files for a target (i.e. the contents of | 464 | downloaded 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 |
519 | identical to the :ref:`ref-tasks-cleansstate` task | 466 | identical to the :ref:`ref-tasks-cleansstate` task |
520 | with the added removal of downloaded source files. | 467 | with the added removal of downloaded source files. |
521 | 468 | ||
522 | You can run this task using BitBake as follows: | 469 | You can run this task using BitBake as follows:: |
523 | :: | ||
524 | 470 | ||
525 | $ bitbake -c cleanall recipe | 471 | $ bitbake -c cleanall recipe |
526 | 472 | ||
527 | Typically, you would not normally use the ``cleanall`` task. Do so only | 473 | You should never use the :ref:`ref-tasks-cleanall` task in a normal |
528 | if you want to start fresh with the :ref:`ref-tasks-fetch` | 474 | scenario. If you want to start fresh with the :ref:`ref-tasks-fetch` task, |
529 | task. | 475 | use 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 | ||
536 | Removes all output files and shared state | 502 | Removes 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 |
538 | target. Essentially, the ``do_cleansstate`` task is identical to the | 504 | target. 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 |
540 | shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) | 506 | shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) |
541 | cache. | 507 | cache. |
542 | 508 | ||
543 | You can run this task using BitBake as follows: | 509 | You can run this task using BitBake as follows:: |
544 | :: | ||
545 | 510 | ||
546 | $ bitbake -c cleansstate recipe | 511 | $ bitbake -c cleansstate recipe |
547 | 512 | ||
548 | When you run the ``do_cleansstate`` task, the OpenEmbedded build system | 513 | When you run the :ref:`ref-tasks-cleansstate` task, the OpenEmbedded build system |
549 | no longer uses any sstate. Consequently, building the recipe from | 514 | no longer uses any sstate. Consequently, building the recipe from |
550 | scratch is guaranteed. | 515 | scratch 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 | ||
567 | Starts a shell in which an interactive Python interpreter allows you to | 543 | Starts a shell in which an interactive Python interpreter allows you to |
568 | interact with the BitBake build environment. From within this shell, you | 544 | interact with the BitBake build environment. From within this shell, you |
569 | can directly examine and set bits from the data store and execute | 545 | can directly examine and set bits from the data store and execute |
570 | functions as if within the BitBake environment. See the ":ref:`dev-manual/common-tasks:using a development python shell`" section in | 546 | functions as if within the BitBake environment. See the ":ref:`dev-manual/python-development-shell:using a Python development shell`" section in |
571 | the Yocto Project Development Tasks Manual for more information about | 547 | the Yocto Project Development Tasks Manual for more information about |
572 | using ``devpyshell``. | 548 | using ``pydevshell``. |
573 | 549 | ||
574 | .. _ref-tasks-devshell: | 550 | .. _ref-tasks-devshell: |
575 | 551 | ||
@@ -577,7 +553,7 @@ using ``devpyshell``. | |||
577 | --------------- | 553 | --------------- |
578 | 554 | ||
579 | Starts a shell whose environment is set up for development, debugging, | 555 | Starts a shell whose environment is set up for development, debugging, |
580 | or both. See the ":ref:`dev-manual/common-tasks:using a development shell`" section in the | 556 | or both. See the ":ref:`dev-manual/development-shell:using a development shell`" section in the |
581 | Yocto Project Development Tasks Manual for more information about using | 557 | Yocto 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 | ||
623 | Combines an initial RAM disk (initramfs) image and kernel together to | 599 | Combines an :term:`Initramfs` image and kernel together to |
624 | form a single image. The | 600 | form a single image. |
625 | :term:`CONFIG_INITRAMFS_SOURCE` variable | ||
626 | has 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 | ||
643 | Boots an image and performs runtime tests within the image. For | 617 | Boots an image and performs runtime tests within the image. For |
644 | information on automatically testing images, see the | 618 | information 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`" |
646 | section in the Yocto Project Development Tasks Manual. | 620 | section 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 | ||
657 | For information on automatically testing images, see the | 631 | For 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`" |
659 | section in the Yocto Project Development Tasks Manual. | 633 | section in the Yocto Project Development Tasks Manual. |
660 | 634 | ||
661 | Kernel-Related Tasks | 635 | Kernel-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 |
688 | file of differences is created, it can be used to create a config | 662 | file of differences is created, it can be used to create a config |
689 | fragment that only contains the differences. You can invoke this task | 663 | fragment that only contains the differences. You can invoke this task |
690 | from the command line as follows: | 664 | from 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 | ||
704 | Converts the newly unpacked kernel source into a form with which the | 677 | Converts the newly unpacked kernel source into a form with which the |
705 | OpenEmbedded build system can work. Because the kernel source can be | 678 | OpenEmbedded build system can work. Because the kernel source can be |
706 | fetched in several different ways, the ``do_kernel_checkout`` task makes | 679 | fetched in several different ways, the :ref:`ref-tasks-kernel_checkout` task makes |
707 | sure that subsequent tasks are given a clean working tree copy of the | 680 | sure that subsequent tasks are given a clean working tree copy of the |
708 | kernel with the correct branches checked out. | 681 | kernel with the correct branches checked out. |
709 | 682 | ||
@@ -714,12 +687,11 @@ kernel with the correct branches checked out. | |||
714 | 687 | ||
715 | Validates the configuration produced by the | 688 | Validates 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 |
718 | configuration does not appear in the final ``.config`` file or when you | 691 | configuration does not appear in the final ``.config`` file or when you |
719 | override a policy configuration in a hardware configuration fragment. | 692 | override a policy configuration in a hardware configuration fragment. |
720 | You can run this task explicitly and view the output by using the | 693 | You can run this task explicitly and view the output by using the |
721 | following command: | 694 | following 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 | ||
735 | After the kernel is patched by the :ref:`ref-tasks-patch` | 707 | After the kernel is patched by the :ref:`ref-tasks-patch` |
736 | task, the ``do_kernel_configme`` task assembles and merges all the | 708 | task, the :ref:`ref-tasks-kernel_configme` task assembles and merges all the |
737 | kernel config fragments into a merged configuration that can then be | 709 | kernel config fragments into a merged configuration that can then be |
738 | passed to the kernel configuration phase proper. This is also the time | 710 | passed to the kernel configuration phase proper. This is also the time |
739 | during which user-specified defconfigs are applied if present, and where | 711 | during 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 | ||
768 | Collects all the features required for a given kernel build, whether the | 739 | Collects all the features required for a given kernel build, whether the |
769 | features come from :term:`SRC_URI` or from Git | 740 | features come from :term:`SRC_URI` or from Git |
770 | repositories. After collection, the ``do_kernel_metadata`` task | 741 | repositories. After collection, the :ref:`ref-tasks-kernel_metadata` task |
771 | processes the features into a series of config fragments and patches, | 742 | processes the features into a series of config fragments and patches, |
772 | which can then be applied by subsequent tasks such as | 743 | which 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 | |||
793 | differences between the default defconfig and the changes made by the | 764 | differences between the default defconfig and the changes made by the |
794 | user using other methods (i.e. the | 765 | user using other methods (i.e. the |
795 | :ref:`ref-tasks-kernel_menuconfig` task. You | 766 | :ref:`ref-tasks-kernel_menuconfig` task. You |
796 | can invoke the task using the following command: | 767 | can 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. | |||
839 | After the kernel is unpacked but before it is patched, this task makes | 809 | After the kernel is unpacked but before it is patched, this task makes |
840 | sure that the machine and metadata branches as specified by the | 810 | sure 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 |
842 | branches. If these branches do not exist and | 812 | branches. 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 966962005b..ad9c46c339 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst | |||
@@ -4,7 +4,7 @@ | |||
4 | Yocto Project Terms | 4 | Yocto Project Terms |
5 | ******************* | 5 | ******************* |
6 | 6 | ||
7 | Following is a list of terms and definitions users new to the Yocto Project | 7 | Here is a list of terms and definitions users new to the Yocto Project |
8 | development environment might find helpful. While some of these terms are | 8 | development environment might find helpful. While some of these terms are |
9 | universal, the list includes them just in case: | 9 | universal, 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 4ce2648136..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 | 1506 | ||
1331 | .. note:: | 1507 | - Compressed version of the image |
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 | |||
1353 | :term:`COPYLEFT_PN_EXCLUDE` | ||
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 | 1513 | ||
1376 | The default value, which is "" indicating to not explicitly include | 1514 | CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}" |
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 | |||
1387 | The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` | ||
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" | ||
2661 | 3236 | ||
2662 | GROUPADD_PARAM_${PN} = "-r netdev" | 3237 | More than one group can be added by separating each set of different |
3238 | groups' parameters with a semicolon. | ||
3239 | |||
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}" | ||
3122 | 3712 | ||
3123 | IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}" | 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:: | ||
3124 | 3716 | ||
3717 | IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}" | ||
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 | |||
3440 | 4011 | ||
3441 | This will result in ``INCOMPATIBLE_LICENSE`` containing the names of | 4012 | INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only" |
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. | ||
4570 | |||
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". | ||
3884 | 4580 | ||
3885 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | 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" | ||
6179 | |||
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`:: | ||
6183 | |||
6184 | example.c | ||
6185 | example.service | ||
6186 | CMakeLists.txt | ||
6187 | |||
6188 | The ``CMakeLists.txt`` file contains:: | ||
5383 | 6189 | ||
5384 | PACKAGECONFIG_pn-recipename = "f4 f5" | 6190 | if(WITH_SYSTEMD) |
6191 | install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd) | ||
6192 | endif(WITH_SYSTEMD) | ||
5385 | 6193 | ||
5386 | Or, you can just amend the variable: | 6194 | In order to enable the installation of ``example.service`` we need to |
5387 | :: | 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:: | ||
5388 | 6202 | ||
5389 | PACKAGECONFIG_append_pn-recipename = " f4" | 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,42 +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 | Given that a recipe's own recipe name is already implicitly in its | 6732 | A recipe's own recipe name (:term:`PN`) is always implicitly prepended |
5926 | own PROVIDES list, it is unnecessary to add aliases with the "+=" operator; | 6733 | to :term:`PROVIDES`, so while using "+=" in the above example may not be |
5927 | using a simple assignment will be sufficient. In other words, | 6734 | strictly necessary it is recommended to avoid confusion. |
5928 | while you could write: | ||
5929 | :: | ||
5930 | |||
5931 | PROVIDES += "udev" | ||
5932 | |||
5933 | |||
5934 | in the above, the "+=" is overkill and unnecessary. | ||
5935 | 6735 | ||
5936 | In addition to providing recipes under alternate names, the | 6736 | In addition to providing recipes under alternate names, the |
5937 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | 6737 | :term:`PROVIDES` mechanism is also used to implement virtual targets. A |
5938 | virtual target is a name that corresponds to some particular | 6738 | virtual target is a name that corresponds to some particular |
5939 | functionality (e.g. a Linux kernel). Recipes that provide the | 6739 | functionality (e.g. a Linux kernel). Recipes that provide the |
5940 | functionality in question list the virtual target in ``PROVIDES``. | 6740 | functionality in question list the virtual target in :term:`PROVIDES`. |
5941 | Recipes that depend on the functionality in question can include the | 6741 | Recipes that depend on the functionality in question can include the |
5942 | virtual target in ``DEPENDS`` to leave the choice of provider open. | 6742 | virtual target in :term:`DEPENDS` to leave the choice of provider open. |
5943 | 6743 | ||
5944 | Conventionally, virtual targets have names on the form | 6744 | Conventionally, virtual targets have names on the form |
5945 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part | 6745 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part |
@@ -5950,15 +6750,14 @@ system and gives an overview of their function and contents. | |||
5950 | 6750 | ||
5951 | .. note:: | 6751 | .. note:: |
5952 | 6752 | ||
5953 | A corresponding mechanism for virtual runtime dependencies | 6753 | A corresponding mechanism for virtual runtime dependencies (packages) |
5954 | (packages) exists. However, the mechanism does not depend on any | 6754 | exists. However, the mechanism does not depend on any special |
5955 | special functionality beyond ordinary variable assignments. For | 6755 | functionality beyond ordinary variable assignments. For example, |
5956 | example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of | 6756 | :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the |
5957 | the component that manages the ``/dev`` directory. | 6757 | package of the component that manages the ``/dev`` directory. |
5958 | 6758 | ||
5959 | Setting the "preferred provider" for runtime dependencies is as | 6759 | Setting the "preferred provider" for runtime dependencies is as |
5960 | simple as using the following assignment in a configuration file: | 6760 | simple as using the following assignment in a configuration file:: |
5961 | :: | ||
5962 | 6761 | ||
5963 | VIRTUAL-RUNTIME_dev_manager = "udev" | 6762 | VIRTUAL-RUNTIME_dev_manager = "udev" |
5964 | 6763 | ||
@@ -5966,17 +6765,16 @@ system and gives an overview of their function and contents. | |||
5966 | :term:`PRSERV_HOST` | 6765 | :term:`PRSERV_HOST` |
5967 | The network based :term:`PR` service host and port. | 6766 | The network based :term:`PR` service host and port. |
5968 | 6767 | ||
5969 | The ``conf/local.conf.sample.extended`` configuration file in the | 6768 | The ``conf/templates/default/local.conf.sample.extended`` configuration |
5970 | :term:`Source Directory` shows how the | 6769 | file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` |
5971 | ``PRSERV_HOST`` variable is set: | 6770 | variable is set:: |
5972 | :: | ||
5973 | 6771 | ||
5974 | PRSERV_HOST = "localhost:0" | 6772 | PRSERV_HOST = "localhost:0" |
5975 | 6773 | ||
5976 | You must | 6774 | You must |
5977 | 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 |
5978 | service <dev-manual/common-tasks:working with a pr service>`. You can | 6776 | service <dev-manual/packages:working with a pr service>`. You can |
5979 | 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. |
5980 | 6778 | ||
5981 | 6779 | ||
5982 | :term:`PSEUDO_IGNORE_PATHS` | 6780 | :term:`PSEUDO_IGNORE_PATHS` |
@@ -5989,7 +6787,7 @@ system and gives an overview of their function and contents. | |||
5989 | 6787 | ||
5990 | :term:`PTEST_ENABLED` | 6788 | :term:`PTEST_ENABLED` |
5991 | Specifies whether or not :ref:`Package | 6789 | Specifies whether or not :ref:`Package |
5992 | Test <dev-manual/common-tasks:testing packages with ptest>` (ptest) | 6790 | Test <dev-manual/packages:testing packages with ptest>` (ptest) |
5993 | functionality is enabled when building a recipe. You should not set | 6791 | functionality is enabled when building a recipe. You should not set |
5994 | this variable directly. Enabling and disabling building Package Tests | 6792 | this variable directly. Enabling and disabling building Package Tests |
5995 | 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 |
@@ -5998,49 +6796,52 @@ system and gives an overview of their function and contents. | |||
5998 | :term:`PV` | 6796 | :term:`PV` |
5999 | 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 |
6000 | recipe filename. For example, if the recipe is named | 6798 | recipe filename. For example, if the recipe is named |
6001 | ``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". |
6002 | ``PV`` is generally not overridden within a recipe unless it is | 6800 | :term:`PV` is generally not overridden within a recipe unless it is |
6003 | building an unstable (i.e. development) version from a source code | 6801 | building an unstable (i.e. development) version from a source code |
6004 | repository (e.g. Git or Subversion). | 6802 | repository (e.g. Git or Subversion). |
6005 | 6803 | ||
6006 | ``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.) | ||
6007 | 6813 | ||
6008 | :term:`PYTHON_ABI` | 6814 | :term:`PYTHON_ABI` |
6009 | When used by recipes that inherit the | 6815 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` |
6010 | :ref:`distutils3 <ref-classes-distutils3>`, | 6816 | class, denotes the Application Binary Interface (ABI) currently in use |
6011 | :ref:`setuptools3 <ref-classes-setuptools3>`, | 6817 | for Python. By default, the ABI is "m". You do not have to set this |
6012 | :ref:`distutils <ref-classes-distutils>`, or | 6818 | variable as the OpenEmbedded build system sets it for you. |
6013 | :ref:`setuptools <ref-classes-setuptools>` classes, denotes the | ||
6014 | Application Binary Interface (ABI) currently in use for Python. By | ||
6015 | default, the ABI is "m". You do not have to set this variable as the | ||
6016 | OpenEmbedded build system sets it for you. | ||
6017 | 6819 | ||
6018 | The OpenEmbedded build system uses the ABI to construct directory | 6820 | The OpenEmbedded build system uses the ABI to construct directory |
6019 | names used when installing the Python headers and libraries in | 6821 | names used when installing the Python headers and libraries in |
6020 | sysroot (e.g. ``.../python3.3m/...``). | 6822 | sysroot (e.g. ``.../python3.3m/...``). |
6021 | 6823 | ||
6022 | Recipes that inherit the ``distutils`` class during cross-builds also | 6824 | :term:`QA_EMPTY_DIRS` |
6023 | use this variable to locate the headers and libraries of the | 6825 | Specifies a list of directories that are expected to be empty when |
6024 | 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>`. | ||
6025 | 6832 | ||
6026 | :term:`PYTHON_PN` | 6833 | :term:`QA_EMPTY_DIRS_RECOMMENDATION` |
6027 | When used by recipes that inherit the | 6834 | Specifies a recommendation for why a directory must be empty, |
6028 | `distutils3 <ref-classes-distutils3>`, | 6835 | which will be included in the error message if a specific directory |
6029 | :ref:`setuptools3 <ref-classes-setuptools3>`, | 6836 | is found to contain files. Must be overridden with the directory |
6030 | :ref:`distutils <ref-classes-distutils>`, or | 6837 | path to match on. |
6031 | :ref:`setuptools <ref-classes-setuptools>` classes, specifies the | ||
6032 | major Python version being built. For Python 3.x, ``PYTHON_PN`` would | ||
6033 | be "python3". You do not have to set this variable as the | ||
6034 | OpenEmbedded build system automatically sets it for you. | ||
6035 | 6838 | ||
6036 | The variable allows recipes to use common infrastructure such as the | 6839 | If no recommendation is specified for a directory, then the default |
6037 | following: | 6840 | "but it is expected to be empty" will be used. |
6038 | :: | ||
6039 | 6841 | ||
6040 | DEPENDS += "${PYTHON_PN}-native" | 6842 | An example message shows if files were present in '/dev':: |
6041 | 6843 | ||
6042 | In the previous example, | 6844 | QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime" |
6043 | the version of the dependency is ``PYTHON_PN``. | ||
6044 | 6845 | ||
6045 | :term:`RANLIB` | 6846 | :term:`RANLIB` |
6046 | The minimal command and arguments to run ``ranlib``. | 6847 | The minimal command and arguments to run ``ranlib``. |
@@ -6050,19 +6851,17 @@ system and gives an overview of their function and contents. | |||
6050 | will not be installed if conflicting packages are not first removed. | 6851 | will not be installed if conflicting packages are not first removed. |
6051 | 6852 | ||
6052 | Like all package-controlling variables, you must always use them in | 6853 | Like all package-controlling variables, you must always use them in |
6053 | conjunction with a package name override. Here is an example: | 6854 | conjunction with a package name override. Here is an example:: |
6054 | :: | ||
6055 | 6855 | ||
6056 | RCONFLICTS_${PN} = "another_conflicting_package_name" | 6856 | RCONFLICTS:${PN} = "another_conflicting_package_name" |
6057 | 6857 | ||
6058 | BitBake, which the OpenEmbedded build system uses, supports | 6858 | BitBake, which the OpenEmbedded build system uses, supports |
6059 | specifying versioned dependencies. Although the syntax varies | 6859 | specifying versioned dependencies. Although the syntax varies |
6060 | depending on the packaging format, BitBake hides these differences | 6860 | depending on the packaging format, BitBake hides these differences |
6061 | 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 |
6062 | ``RCONFLICTS`` variable: | 6862 | :term:`RCONFLICTS` variable:: |
6063 | :: | ||
6064 | 6863 | ||
6065 | RCONFLICTS_${PN} = "package (operator version)" | 6864 | RCONFLICTS:${PN} = "package (operator version)" |
6066 | 6865 | ||
6067 | For ``operator``, you can specify the following: | 6866 | For ``operator``, you can specify the following: |
6068 | 6867 | ||
@@ -6073,32 +6872,30 @@ system and gives an overview of their function and contents. | |||
6073 | - >= | 6872 | - >= |
6074 | 6873 | ||
6075 | 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 |
6076 | greater of the package ``foo``: | 6875 | greater of the package ``foo``:: |
6077 | :: | ||
6078 | 6876 | ||
6079 | RCONFLICTS_${PN} = "foo (>= 1.2)" | 6877 | RCONFLICTS:${PN} = "foo (>= 1.2)" |
6080 | 6878 | ||
6081 | :term:`RDEPENDS` | 6879 | :term:`RDEPENDS` |
6082 | Lists runtime dependencies of a package. These dependencies are other | 6880 | Lists runtime dependencies of a package. These dependencies are other |
6083 | 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 |
6084 | correctly. As an example, the following assignment declares that the | 6882 | correctly. As an example, the following assignment declares that the |
6085 | package ``foo`` needs the packages ``bar`` and ``baz`` to be | 6883 | package ``foo`` needs the packages ``bar`` and ``baz`` to be |
6086 | installed: | 6884 | installed:: |
6087 | :: | ||
6088 | 6885 | ||
6089 | RDEPENDS_foo = "bar baz" | 6886 | RDEPENDS:foo = "bar baz" |
6090 | 6887 | ||
6091 | The most common types of package | 6888 | The most common types of package |
6092 | runtime dependencies are automatically detected and added. Therefore, | 6889 | runtime dependencies are automatically detected and added. Therefore, |
6093 | most recipes do not need to set ``RDEPENDS``. For more information, | 6890 | most recipes do not need to set :term:`RDEPENDS`. For more information, |
6094 | see the | 6891 | see the |
6095 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | 6892 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" |
6096 | section in the Yocto Project Overview and Concepts Manual. | 6893 | section in the Yocto Project Overview and Concepts Manual. |
6097 | 6894 | ||
6098 | The practical effect of the above ``RDEPENDS`` assignment is that | 6895 | The practical effect of the above :term:`RDEPENDS` assignment is that |
6099 | ``bar`` and ``baz`` will be declared as dependencies inside the | 6896 | ``bar`` and ``baz`` will be declared as dependencies inside the |
6100 | package ``foo`` when it is written out by one of the | 6897 | package ``foo`` when it is written out by one of the |
6101 | :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks. | 6898 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. |
6102 | 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, |
6103 | which is determined by | 6900 | which is determined by |
6104 | :term:`PACKAGE_CLASSES`. When the | 6901 | :term:`PACKAGE_CLASSES`. When the |
@@ -6106,59 +6903,57 @@ system and gives an overview of their function and contents. | |||
6106 | also install the packages on which it depends. | 6903 | also install the packages on which it depends. |
6107 | 6904 | ||
6108 | To ensure that the packages ``bar`` and ``baz`` get built, the | 6905 | To ensure that the packages ``bar`` and ``baz`` get built, the |
6109 | previous ``RDEPENDS`` assignment also causes a task dependency to be | 6906 | previous :term:`RDEPENDS` assignment also causes a task dependency to be |
6110 | added. This dependency is from the recipe's | 6907 | added. This dependency is from the recipe's |
6111 | :ref:`ref-tasks-build` (not to be confused with | 6908 | :ref:`ref-tasks-build` (not to be confused with |
6112 | :ref:`ref-tasks-compile`) task to the | 6909 | :ref:`ref-tasks-compile`) task to the |
6113 | ``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 |
6114 | ``baz``. | 6911 | ``baz``. |
6115 | 6912 | ||
6116 | 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 |
6117 | names of other packages - they cannot be recipe names. Although | 6914 | names of other packages --- they cannot be recipe names. Although |
6118 | package names and recipe names usually match, the important point | 6915 | package names and recipe names usually match, the important point |
6119 | here is that you are providing package names within the ``RDEPENDS`` | 6916 | here is that you are providing package names within the :term:`RDEPENDS` |
6120 | 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 |
6121 | a recipe, see the :term:`PACKAGES` variable. | 6918 | a recipe, see the :term:`PACKAGES` variable. |
6122 | 6919 | ||
6123 | Because the ``RDEPENDS`` variable applies to packages being built, | 6920 | Because the :term:`RDEPENDS` variable applies to packages being built, |
6124 | 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 |
6125 | name (remember that a single recipe can build multiple packages). For | 6922 | name (remember that a single recipe can build multiple packages). For |
6126 | example, suppose you are building a development package that depends | 6923 | example, suppose you are building a development package that depends |
6127 | 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 |
6128 | ``RDEPENDS`` statement: | 6925 | :term:`RDEPENDS` statement:: |
6129 | :: | ||
6130 | 6926 | ||
6131 | RDEPENDS_${PN}-dev += "perl" | 6927 | RDEPENDS:${PN}-dev += "perl" |
6132 | 6928 | ||
6133 | In the example, | 6929 | In the example, |
6134 | the development package depends on the ``perl`` package. Thus, the | 6930 | the development package depends on the ``perl`` package. Thus, the |
6135 | ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of | 6931 | :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of |
6136 | the variable. | 6932 | the variable. |
6137 | 6933 | ||
6138 | .. note:: | 6934 | .. note:: |
6139 | 6935 | ||
6140 | ``RDEPENDS_${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` | 6936 | ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` |
6141 | by default. This default is set in the BitBake configuration file | 6937 | by default. This default is set in the BitBake configuration file |
6142 | (``meta/conf/bitbake.conf``). Be careful not to accidentally remove | 6938 | (``meta/conf/bitbake.conf``). Be careful not to accidentally remove |
6143 | ``${PN}`` when modifying ``RDEPENDS_${PN}-dev``. Use the "+=" operator | 6939 | ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator |
6144 | rather than the "=" operator. | 6940 | rather than the "=" operator. |
6145 | 6941 | ||
6146 | 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 |
6147 | in the ``PACKAGES`` variable. The :term:`PKG` variable | 6943 | in the :term:`PACKAGES` variable. The :term:`PKG` variable |
6148 | 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 |
6149 | :ref:`debian <ref-classes-debian>` class uses this to rename | 6945 | :ref:`ref-classes-debian` class uses this to rename |
6150 | packages), but this final package name cannot be used with | 6946 | packages), but this final package name cannot be used with |
6151 | ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be | 6947 | :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be |
6152 | independent of the package format used. | 6948 | independent of the package format used. |
6153 | 6949 | ||
6154 | BitBake, which the OpenEmbedded build system uses, supports | 6950 | BitBake, which the OpenEmbedded build system uses, supports |
6155 | specifying versioned dependencies. Although the syntax varies | 6951 | specifying versioned dependencies. Although the syntax varies |
6156 | depending on the packaging format, BitBake hides these differences | 6952 | depending on the packaging format, BitBake hides these differences |
6157 | 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 |
6158 | ``RDEPENDS`` variable: | 6954 | :term:`RDEPENDS` variable:: |
6159 | :: | ||
6160 | 6955 | ||
6161 | RDEPENDS_${PN} = "package (operator version)" | 6956 | RDEPENDS:${PN} = "package (operator version)" |
6162 | 6957 | ||
6163 | For ``operator``, you can specify the following: | 6958 | For ``operator``, you can specify the following: |
6164 | 6959 | ||
@@ -6172,43 +6967,105 @@ system and gives an overview of their function and contents. | |||
6172 | 6967 | ||
6173 | .. note:: | 6968 | .. note:: |
6174 | 6969 | ||
6175 | You can use ``EXTENDPKGV`` to provide a full package version | 6970 | You can use :term:`EXTENDPKGV` to provide a full package version |
6176 | specification. | 6971 | specification. |
6177 | 6972 | ||
6178 | 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 |
6179 | greater of the package ``foo``: | 6974 | greater of the package ``foo``:: |
6180 | :: | ||
6181 | 6975 | ||
6182 | RDEPENDS_${PN} = "foo (>= 1.2)" | 6976 | RDEPENDS:${PN} = "foo (>= 1.2)" |
6183 | 6977 | ||
6184 | For information on build-time dependencies, see the | 6978 | For information on build-time dependencies, see the :term:`DEPENDS` |
6185 | :term:`DEPENDS` variable. You can also see the | 6979 | variable. You can also see the |
6186 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | 6980 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and |
6187 | ":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 |
6188 | BitBake User Manual for additional information on tasks and | 6982 | BitBake User Manual for additional information on tasks and dependencies. |
6189 | 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. | ||
6190 | 7039 | ||
6191 | :term:`REQUIRED_DISTRO_FEATURES` | 7040 | :term:`REQUIRED_DISTRO_FEATURES` |
6192 | When inheriting the | 7041 | When inheriting the :ref:`ref-classes-features_check` |
6193 | :ref:`features_check <ref-classes-features_check>` | ||
6194 | class, this variable identifies distribution features that must exist | 7042 | class, this variable identifies distribution features that must exist |
6195 | in the current configuration in order for the OpenEmbedded build | 7043 | in the current configuration in order for the OpenEmbedded build |
6196 | system to build the recipe. In other words, if the | 7044 | system to build the recipe. In other words, if the |
6197 | ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not | 7045 | :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not |
6198 | appear in ``DISTRO_FEATURES`` within the current configuration, then | 7046 | appear in :term:`DISTRO_FEATURES` within the current configuration, then |
6199 | 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 |
6200 | the recipe then an error will be triggered. | 7048 | the recipe then an error will be triggered. |
6201 | 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 | |||
6202 | :term:`RM_WORK_EXCLUDE` | 7061 | :term:`RM_WORK_EXCLUDE` |
6203 | With ``rm_work`` enabled, this variable specifies a list of recipes | 7062 | With :ref:`ref-classes-rm-work` enabled, this variable |
6204 | whose work directories should not be removed. See the | 7063 | specifies a list of recipes whose work directories should not be removed. |
6205 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more | 7064 | See the ":ref:`ref-classes-rm-work`" section for more details. |
6206 | details. | ||
6207 | 7065 | ||
6208 | :term:`ROOT_HOME` | 7066 | :term:`ROOT_HOME` |
6209 | 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 |
6210 | follows in the BitBake configuration file: | 7068 | follows in the BitBake configuration file:: |
6211 | :: | ||
6212 | 7069 | ||
6213 | ROOT_HOME ??= "/home/root" | 7070 | ROOT_HOME ??= "/home/root" |
6214 | 7071 | ||
@@ -6221,8 +7078,7 @@ system and gives an overview of their function and contents. | |||
6221 | 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 |
6222 | 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" |
6223 | 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 |
6224 | define your override: | 7081 | define your override:: |
6225 | :: | ||
6226 | 7082 | ||
6227 | ROOT_HOME = "/root" | 7083 | ROOT_HOME = "/root" |
6228 | ROOT_HOME ?= "/root" | 7084 | ROOT_HOME ?= "/root" |
@@ -6234,16 +7090,15 @@ system and gives an overview of their function and contents. | |||
6234 | :term:`ROOTFS` | 7090 | :term:`ROOTFS` |
6235 | Indicates a filesystem image to include as the root filesystem. | 7091 | Indicates a filesystem image to include as the root filesystem. |
6236 | 7092 | ||
6237 | The ``ROOTFS`` variable is an optional variable used with the | 7093 | The :term:`ROOTFS` variable is an optional variable used with the |
6238 | :ref:`image-live <ref-classes-image-live>` class. | 7094 | :ref:`ref-classes-image-live` class. |
6239 | 7095 | ||
6240 | :term:`ROOTFS_POSTINSTALL_COMMAND` | 7096 | :term:`ROOTFS_POSTINSTALL_COMMAND` |
6241 | Specifies a list of functions to call after the OpenEmbedded build | 7097 | Specifies a list of functions to call after the OpenEmbedded build |
6242 | system has installed packages. You can specify functions separated by | 7098 | system has installed packages. You can specify functions separated by |
6243 | semicolons: | 7099 | spaces:: |
6244 | :: | ||
6245 | 7100 | ||
6246 | ROOTFS_POSTINSTALL_COMMAND += "function; ... " | 7101 | ROOTFS_POSTINSTALL_COMMAND += "function" |
6247 | 7102 | ||
6248 | 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 |
6249 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7104 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6254,10 +7109,9 @@ system and gives an overview of their function and contents. | |||
6254 | :term:`ROOTFS_POSTPROCESS_COMMAND` | 7109 | :term:`ROOTFS_POSTPROCESS_COMMAND` |
6255 | Specifies a list of functions to call once the OpenEmbedded build | 7110 | Specifies a list of functions to call once the OpenEmbedded build |
6256 | system has created the root filesystem. You can specify functions | 7111 | system has created the root filesystem. You can specify functions |
6257 | separated by semicolons: | 7112 | separated by spaces:: |
6258 | :: | ||
6259 | 7113 | ||
6260 | ROOTFS_POSTPROCESS_COMMAND += "function; ... " | 7114 | ROOTFS_POSTPROCESS_COMMAND += "function" |
6261 | 7115 | ||
6262 | 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 |
6263 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7117 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6270,10 +7124,9 @@ system and gives an overview of their function and contents. | |||
6270 | system has removed unnecessary packages. When runtime package | 7124 | system has removed unnecessary packages. When runtime package |
6271 | management is disabled in the image, several packages are removed | 7125 | management is disabled in the image, several packages are removed |
6272 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. | 7126 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. |
6273 | You can specify functions separated by semicolons: | 7127 | You can specify functions separated by spaces:: |
6274 | :: | ||
6275 | 7128 | ||
6276 | ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " | 7129 | ROOTFS_POSTUNINSTALL_COMMAND += "function" |
6277 | 7130 | ||
6278 | 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 |
6279 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7132 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6284,10 +7137,9 @@ system and gives an overview of their function and contents. | |||
6284 | :term:`ROOTFS_PREPROCESS_COMMAND` | 7137 | :term:`ROOTFS_PREPROCESS_COMMAND` |
6285 | Specifies a list of functions to call before the OpenEmbedded build | 7138 | Specifies a list of functions to call before the OpenEmbedded build |
6286 | system has created the root filesystem. You can specify functions | 7139 | system has created the root filesystem. You can specify functions |
6287 | separated by semicolons: | 7140 | separated by spaces:: |
6288 | :: | ||
6289 | 7141 | ||
6290 | ROOTFS_PREPROCESS_COMMAND += "function; ... " | 7142 | ROOTFS_PREPROCESS_COMMAND += "function" |
6291 | 7143 | ||
6292 | 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 |
6293 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7145 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6299,64 +7151,61 @@ system and gives an overview of their function and contents. | |||
6299 | 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 |
6300 | aliases are useful for satisfying runtime dependencies of other | 7152 | aliases are useful for satisfying runtime dependencies of other |
6301 | 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 |
6302 | ``RDEPENDS``). | 7154 | :term:`RDEPENDS`). |
6303 | 7155 | ||
6304 | .. note:: | 7156 | .. note:: |
6305 | 7157 | ||
6306 | 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. |
6307 | 7159 | ||
6308 | As with all package-controlling variables, you must always use the | 7160 | As with all package-controlling variables, you must always use the |
6309 | variable in conjunction with a package name override. Here is an | 7161 | variable in conjunction with a package name override. Here is an |
6310 | example: | 7162 | example:: |
6311 | :: | ||
6312 | 7163 | ||
6313 | RPROVIDES_${PN} = "widget-abi-2" | 7164 | RPROVIDES:${PN} = "widget-abi-2" |
6314 | 7165 | ||
6315 | :term:`RRECOMMENDS` | 7166 | :term:`RRECOMMENDS` |
6316 | 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 |
6317 | 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 |
6318 | packages in order to successfully build, but rather uses them for | 7169 | packages in order to successfully build, but rather uses them for |
6319 | extended usability. To specify runtime dependencies for packages, see | 7170 | extended usability. To specify runtime dependencies for packages, see |
6320 | the ``RDEPENDS`` variable. | 7171 | the :term:`RDEPENDS` variable. |
6321 | 7172 | ||
6322 | The package manager will automatically install the ``RRECOMMENDS`` | 7173 | The package manager will automatically install the :term:`RRECOMMENDS` |
6323 | list of packages when installing the built package. However, you can | 7174 | list of packages when installing the built package. However, you can |
6324 | prevent listed packages from being installed by using the | 7175 | prevent listed packages from being installed by using the |
6325 | :term:`BAD_RECOMMENDATIONS`, | 7176 | :term:`BAD_RECOMMENDATIONS`, |
6326 | :term:`NO_RECOMMENDATIONS`, and | 7177 | :term:`NO_RECOMMENDATIONS`, and |
6327 | :term:`PACKAGE_EXCLUDE` variables. | 7178 | :term:`PACKAGE_EXCLUDE` variables. |
6328 | 7179 | ||
6329 | Packages specified in ``RRECOMMENDS`` need not actually be produced. | 7180 | Packages specified in :term:`RRECOMMENDS` need not actually be produced. |
6330 | However, a recipe must exist that provides each package, either | 7181 | However, there must be a recipe providing each package, either |
6331 | through the :term:`PACKAGES` or | 7182 | through the :term:`PACKAGES` or |
6332 | :term:`PACKAGES_DYNAMIC` variables or the | 7183 | :term:`PACKAGES_DYNAMIC` variables or the |
6333 | :term:`RPROVIDES` variable, or an error will occur | 7184 | :term:`RPROVIDES` variable, or an error will occur |
6334 | 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 |
6335 | produced, the build continues without error. | 7186 | produced, the build continues without error. |
6336 | 7187 | ||
6337 | Because the ``RRECOMMENDS`` variable applies to packages being built, | 7188 | Because the :term:`RRECOMMENDS` variable applies to packages being built, |
6338 | 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 |
6339 | particular package whose usability is being extended. For example, | 7190 | particular package whose usability is being extended. For example, |
6340 | suppose you are building a development package that is extended to | 7191 | suppose you are building a development package that is extended to |
6341 | support wireless functionality. In this case, you would use the | 7192 | support wireless functionality. In this case, you would use the |
6342 | following: | 7193 | following:: |
6343 | :: | ||
6344 | 7194 | ||
6345 | RRECOMMENDS_${PN}-dev += "wireless_package_name" | 7195 | RRECOMMENDS:${PN}-dev += "wireless_package_name" |
6346 | 7196 | ||
6347 | In the | 7197 | In the |
6348 | 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 |
6349 | the ``PACKAGES`` namespace before any renaming of the output package | 7199 | the :term:`PACKAGES` namespace before any renaming of the output package |
6350 | by classes such as ``debian.bbclass``. | 7200 | by classes such as :ref:`ref-classes-debian`. |
6351 | 7201 | ||
6352 | BitBake, which the OpenEmbedded build system uses, supports | 7202 | BitBake, which the OpenEmbedded build system uses, supports |
6353 | specifying versioned recommends. Although the syntax varies depending | 7203 | specifying versioned recommends. Although the syntax varies depending |
6354 | on the packaging format, BitBake hides these differences from you. | 7204 | on the packaging format, BitBake hides these differences from you. |
6355 | Here is the general syntax to specify versions with the | 7205 | Here is the general syntax to specify versions with the |
6356 | ``RRECOMMENDS`` variable: | 7206 | :term:`RRECOMMENDS` variable:: |
6357 | :: | ||
6358 | 7207 | ||
6359 | RRECOMMENDS_${PN} = "package (operator version)" | 7208 | RRECOMMENDS:${PN} = "package (operator version)" |
6360 | 7209 | ||
6361 | For ``operator``, you can specify the following: | 7210 | For ``operator``, you can specify the following: |
6362 | 7211 | ||
@@ -6367,32 +7216,29 @@ system and gives an overview of their function and contents. | |||
6367 | - >= | 7216 | - >= |
6368 | 7217 | ||
6369 | 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 |
6370 | greater of the package ``foo``: | 7219 | greater of the package ``foo``:: |
6371 | :: | ||
6372 | 7220 | ||
6373 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | 7221 | RRECOMMENDS:${PN} = "foo (>= 1.2)" |
6374 | 7222 | ||
6375 | :term:`RREPLACES` | 7223 | :term:`RREPLACES` |
6376 | 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 |
6377 | this variable to determine which package should be installed to | 7225 | this variable to determine which package should be installed to |
6378 | 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 |
6379 | 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 |
6380 | the other package to the ``RCONFLICTS`` variable. | 7228 | the other package to the :term:`RCONFLICTS` variable. |
6381 | 7229 | ||
6382 | As with all package-controlling variables, you must use this variable | 7230 | As with all package-controlling variables, you must use this variable |
6383 | in conjunction with a package name override. Here is an example: | 7231 | in conjunction with a package name override. Here is an example:: |
6384 | :: | ||
6385 | 7232 | ||
6386 | RREPLACES_${PN} = "other_package_being_replaced" | 7233 | RREPLACES:${PN} = "other_package_being_replaced" |
6387 | 7234 | ||
6388 | BitBake, which the OpenEmbedded build system uses, supports | 7235 | BitBake, which the OpenEmbedded build system uses, supports |
6389 | specifying versioned replacements. Although the syntax varies | 7236 | specifying versioned replacements. Although the syntax varies |
6390 | depending on the packaging format, BitBake hides these differences | 7237 | depending on the packaging format, BitBake hides these differences |
6391 | 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 |
6392 | ``RREPLACES`` variable: | 7239 | :term:`RREPLACES` variable:: |
6393 | :: | ||
6394 | 7240 | ||
6395 | RREPLACES_${PN} = "package (operator version)" | 7241 | RREPLACES:${PN} = "package (operator version)" |
6396 | 7242 | ||
6397 | For ``operator``, you can specify the following: | 7243 | For ``operator``, you can specify the following: |
6398 | 7244 | ||
@@ -6403,10 +7249,9 @@ system and gives an overview of their function and contents. | |||
6403 | - >= | 7249 | - >= |
6404 | 7250 | ||
6405 | 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 |
6406 | or greater of the package ``foo``: | 7252 | or greater of the package ``foo``:: |
6407 | :: | ||
6408 | 7253 | ||
6409 | RREPLACES_${PN} = "foo (>= 1.2)" | 7254 | RREPLACES:${PN} = "foo (>= 1.2)" |
6410 | 7255 | ||
6411 | :term:`RSUGGESTS` | 7256 | :term:`RSUGGESTS` |
6412 | A list of additional packages that you can suggest for installation | 7257 | A list of additional packages that you can suggest for installation |
@@ -6415,10 +7260,14 @@ system and gives an overview of their function and contents. | |||
6415 | 7260 | ||
6416 | As with all package-controlling variables, you must always use this | 7261 | As with all package-controlling variables, you must always use this |
6417 | variable in conjunction with a package name override. Here is an | 7262 | variable in conjunction with a package name override. Here is an |
6418 | example: | 7263 | example:: |
6419 | :: | 7264 | |
7265 | RSUGGESTS:${PN} = "useful_package another_package" | ||
6420 | 7266 | ||
6421 | 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. | ||
6422 | 7271 | ||
6423 | :term:`S` | 7272 | :term:`S` |
6424 | The location in the :term:`Build Directory` where | 7273 | The location in the :term:`Build Directory` where |
@@ -6428,14 +7277,13 @@ system and gives an overview of their function and contents. | |||
6428 | 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 |
6429 | anything other than ``${BPN}-${PV}``, or if the source code is | 7278 | anything other than ``${BPN}-${PV}``, or if the source code is |
6430 | 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 |
6431 | ``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 |
6432 | to find the unpacked source. | 7281 | to find the unpacked source. |
6433 | 7282 | ||
6434 | As an example, assume a :term:`Source Directory` | 7283 | As an example, assume a :term:`Source Directory` |
6435 | top-level folder named ``poky`` and a default Build Directory at | 7284 | top-level folder named ``poky`` and a default :term:`Build Directory` at |
6436 | ``poky/build``. In this case, the work directory the build system | 7285 | ``poky/build``. In this case, the work directory the build system |
6437 | uses to keep the unpacked recipe for ``db`` is the following: | 7286 | uses to keep the unpacked recipe for ``db`` is the following:: |
6438 | :: | ||
6439 | 7287 | ||
6440 | 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 |
6441 | 7289 | ||
@@ -6444,11 +7292,10 @@ system and gives an overview of their function and contents. | |||
6444 | This next example assumes a Git repository. By default, Git | 7292 | This next example assumes a Git repository. By default, Git |
6445 | repositories are cloned to ``${WORKDIR}/git`` during | 7293 | repositories are cloned to ``${WORKDIR}/git`` during |
6446 | :ref:`ref-tasks-fetch`. Since this path is different | 7294 | :ref:`ref-tasks-fetch`. Since this path is different |
6447 | 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 |
6448 | source can be located: | 7296 | source can be located:: |
6449 | :: | ||
6450 | 7297 | ||
6451 | SRC_URI = "git://path/to/repo.git" | 7298 | SRC_URI = "git://path/to/repo.git;branch=main" |
6452 | S = "${WORKDIR}/git" | 7299 | S = "${WORKDIR}/git" |
6453 | 7300 | ||
6454 | :term:`SANITY_REQUIRED_UTILITIES` | 7301 | :term:`SANITY_REQUIRED_UTILITIES` |
@@ -6462,7 +7309,7 @@ system and gives an overview of their function and contents. | |||
6462 | been tested against. Identifiers consist of the host distributor ID | 7309 | been tested against. Identifiers consist of the host distributor ID |
6463 | 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 |
6464 | as read from ``/etc/lsb-release``. Separate the list items with | 7311 | as read from ``/etc/lsb-release``. Separate the list items with |
6465 | explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is | 7312 | explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is |
6466 | not empty and the current value of | 7313 | not empty and the current value of |
6467 | :term:`NATIVELSBSTRING` does not appear in the | 7314 | :term:`NATIVELSBSTRING` does not appear in the |
6468 | list, then the build system reports a warning that indicates the | 7315 | list, then the build system reports a warning that indicates the |
@@ -6472,12 +7319,29 @@ system and gives an overview of their function and contents. | |||
6472 | The target architecture for the SDK. Typically, you do not directly | 7319 | The target architecture for the SDK. Typically, you do not directly |
6473 | set this variable. Instead, use :term:`SDKMACHINE`. | 7320 | set this variable. Instead, use :term:`SDKMACHINE`. |
6474 | 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 | |||
6475 | :term:`SDK_DEPLOY` | 7340 | :term:`SDK_DEPLOY` |
6476 | The directory set up and used by the | 7341 | The directory set up and used by the |
6477 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which | 7342 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the |
6478 | the SDK is deployed. The ``populate_sdk_base`` class defines | 7343 | SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>` |
6479 | ``SDK_DEPLOY`` as follows: | 7344 | class defines :term:`SDK_DEPLOY` as follows:: |
6480 | :: | ||
6481 | 7345 | ||
6482 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" | 7346 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" |
6483 | 7347 | ||
@@ -6485,15 +7349,14 @@ system and gives an overview of their function and contents. | |||
6485 | The parent directory used by the OpenEmbedded build system when | 7349 | The parent directory used by the OpenEmbedded build system when |
6486 | creating SDK output. The | 7350 | creating SDK output. The |
6487 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines | 7351 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines |
6488 | the variable as follows: | 7352 | the variable as follows:: |
6489 | :: | ||
6490 | 7353 | ||
6491 | SDK_DIR = "${WORKDIR}/sdk" | 7354 | SDK_DIR = "${WORKDIR}/sdk" |
6492 | 7355 | ||
6493 | .. note:: | 7356 | .. note:: |
6494 | 7357 | ||
6495 | 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 |
6496 | ``WORKDIR``. The final output directory is :term:`SDK_DEPLOY`. | 7359 | :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. |
6497 | 7360 | ||
6498 | :term:`SDK_EXT_TYPE` | 7361 | :term:`SDK_EXT_TYPE` |
6499 | Controls whether or not shared state artifacts are copied into the | 7362 | Controls whether or not shared state artifacts are copied into the |
@@ -6511,14 +7374,12 @@ system and gives an overview of their function and contents. | |||
6511 | 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 |
6512 | 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 |
6513 | file contains package information on a line-per-package basis as | 7376 | file contains package information on a line-per-package basis as |
6514 | follows: | 7377 | follows:: |
6515 | :: | ||
6516 | 7378 | ||
6517 | packagename packagearch version | 7379 | packagename packagearch version |
6518 | 7380 | ||
6519 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | 7381 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class |
6520 | defines the manifest file as follows: | 7382 | defines the manifest file as follows:: |
6521 | :: | ||
6522 | 7383 | ||
6523 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" | 7384 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" |
6524 | 7385 | ||
@@ -6534,7 +7395,7 @@ system and gives an overview of their function and contents. | |||
6534 | 7395 | ||
6535 | .. note:: | 7396 | .. note:: |
6536 | 7397 | ||
6537 | Enabling the ``SDK_INCLUDE_PKGDATA`` | 7398 | Enabling the :term:`SDK_INCLUDE_PKGDATA` |
6538 | variable significantly increases build time because all of world | 7399 | variable significantly increases build time because all of world |
6539 | needs to be built. Enabling the variable also slightly increases | 7400 | needs to be built. Enabling the variable also slightly increases |
6540 | the size of the extensible SDK. | 7401 | the size of the extensible SDK. |
@@ -6548,82 +7409,21 @@ system and gives an overview of their function and contents. | |||
6548 | 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 |
6549 | steps to install the toolchain. | 7410 | steps to install the toolchain. |
6550 | 7411 | ||
6551 | The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if | 7412 | The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if |
6552 | ``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 |
6553 | ``SDK_EXT_TYPE`` is set to "full". | 7414 | :term:`SDK_EXT_TYPE` is set to "full". |
6554 | |||
6555 | :term:`SDK_INHERIT_BLACKLIST` | ||
6556 | A list of classes to remove from the :term:`INHERIT` | ||
6557 | value globally within the extensible SDK configuration. The | ||
6558 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the | ||
6559 | default value: | ||
6560 | :: | ||
6561 | |||
6562 | SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" | ||
6563 | |||
6564 | Some classes are not generally applicable within the extensible SDK | ||
6565 | context. You can use this variable to disable those classes. | ||
6566 | |||
6567 | For additional information on how to customize the extensible SDK's | ||
6568 | configuration, see the | ||
6569 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6570 | section in the Yocto Project Application Development and the | ||
6571 | Extensible Software Development Kit (eSDK) manual. | ||
6572 | |||
6573 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6574 | A list of variables not allowed through from the OpenEmbedded build | ||
6575 | system configuration into the extensible SDK configuration. Usually, | ||
6576 | these are variables that are specific to the machine on which the | ||
6577 | build system is running and thus would be potentially problematic | ||
6578 | within the extensible SDK. | ||
6579 | |||
6580 | By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the | ||
6581 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and | ||
6582 | excludes the following variables: | ||
6583 | |||
6584 | - :term:`CONF_VERSION` | ||
6585 | - :term:`BB_NUMBER_THREADS` | ||
6586 | - :term:`bitbake:BB_NUMBER_PARSE_THREADS` | ||
6587 | - :term:`PARALLEL_MAKE` | ||
6588 | - :term:`PRSERV_HOST` | ||
6589 | - :term:`SSTATE_MIRRORS` :term:`DL_DIR` | ||
6590 | - :term:`SSTATE_DIR` :term:`TMPDIR` | ||
6591 | - :term:`BB_SERVER_TIMEOUT` | ||
6592 | |||
6593 | For additional information on how to customize the extensible SDK's | ||
6594 | configuration, see the | ||
6595 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6596 | section in the Yocto Project Application Development and the | ||
6597 | Extensible Software Development Kit (eSDK) manual. | ||
6598 | |||
6599 | :term:`SDK_LOCAL_CONF_WHITELIST` | ||
6600 | A list of variables allowed through from the OpenEmbedded build | ||
6601 | system configuration into the extensible SDK configuration. By | ||
6602 | default, the list of variables is empty and is set in the | ||
6603 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. | ||
6604 | |||
6605 | This list overrides the variables specified using the | ||
6606 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6607 | variable as well as any variables identified by automatic | ||
6608 | blacklisting due to the "/" character being found at the start of the | ||
6609 | value, which is usually indicative of being a path and thus might not | ||
6610 | be valid on the system where the SDK is installed. | ||
6611 | |||
6612 | For additional information on how to customize the extensible SDK's | ||
6613 | configuration, see the | ||
6614 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6615 | section in the Yocto Project Application Development and the | ||
6616 | Extensible Software Development Kit (eSDK) manual. | ||
6617 | 7415 | ||
6618 | :term:`SDK_NAME` | 7416 | :term:`SDK_NAME` |
6619 | 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 |
6620 | :term:`DISTRO`, :term:`TCLIBC`, | 7418 | ``meta-poky/conf/distro/poky.conf``) is derived from the |
6621 | :term:`SDK_ARCH`, | 7419 | :term:`DISTRO`, |
6622 | :term:`IMAGE_BASENAME`, and | 7420 | :term:`TCLIBC`, |
6623 | :term:`TUNE_PKGARCH` variables: | 7421 | :term:`SDKMACHINE`, |
6624 | :: | 7422 | :term:`IMAGE_BASENAME`, |
7423 | :term:`TUNE_PKGARCH`, and | ||
7424 | :term:`MACHINE` variables:: | ||
6625 | 7425 | ||
6626 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" | 7426 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}" |
6627 | 7427 | ||
6628 | :term:`SDK_OS` | 7428 | :term:`SDK_OS` |
6629 | 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 |
@@ -6632,8 +7432,7 @@ system and gives an overview of their function and contents. | |||
6632 | :term:`SDK_OUTPUT` | 7432 | :term:`SDK_OUTPUT` |
6633 | The location used by the OpenEmbedded build system when creating SDK | 7433 | The location used by the OpenEmbedded build system when creating SDK |
6634 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | 7434 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
6635 | class defines the variable as follows: | 7435 | class defines the variable as follows:: |
6636 | :: | ||
6637 | 7436 | ||
6638 | SDK_DIR = "${WORKDIR}/sdk" | 7437 | SDK_DIR = "${WORKDIR}/sdk" |
6639 | SDK_OUTPUT = "${SDK_DIR}/image" | 7438 | SDK_OUTPUT = "${SDK_DIR}/image" |
@@ -6641,7 +7440,7 @@ system and gives an overview of their function and contents. | |||
6641 | 7440 | ||
6642 | .. note:: | 7441 | .. note:: |
6643 | 7442 | ||
6644 | 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 |
6645 | :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 |
6646 | :term:`SDK_DEPLOY`. | 7445 | :term:`SDK_DEPLOY`. |
6647 | 7446 | ||
@@ -6649,13 +7448,15 @@ system and gives an overview of their function and contents. | |||
6649 | Specifies a list of architectures compatible with the SDK machine. | 7448 | Specifies a list of architectures compatible with the SDK machine. |
6650 | This variable is set automatically and should not normally be | 7449 | This variable is set automatically and should not normally be |
6651 | hand-edited. Entries are separated using spaces and listed in order | 7450 | hand-edited. Entries are separated using spaces and listed in order |
6652 | 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 |
6653 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". | 7452 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". |
6654 | 7453 | ||
6655 | :term:`SDK_POSTPROCESS_COMMAND` | 7454 | :term:`SDK_POSTPROCESS_COMMAND` |
6656 | Specifies a list of functions to call once the OpenEmbedded build | 7455 | Specifies a list of functions to call once the OpenEmbedded build |
6657 | system creates the SDK. You can specify functions separated by | 7456 | system creates the SDK. You can specify functions separated by |
6658 | semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " | 7457 | spaces: |
7458 | |||
7459 | SDK_POSTPROCESS_COMMAND += "function" | ||
6659 | 7460 | ||
6660 | 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 |
6661 | 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 |
@@ -6663,8 +7464,9 @@ system and gives an overview of their function and contents. | |||
6663 | :term:`SDK_DIR` variable for more information. | 7464 | :term:`SDK_DIR` variable for more information. |
6664 | 7465 | ||
6665 | :term:`SDK_PREFIX` | 7466 | :term:`SDK_PREFIX` |
6666 | The toolchain binary prefix used for ``nativesdk`` recipes. The | 7467 | The toolchain binary prefix used for |
6667 | 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 | ||
6668 | :term:`TARGET_PREFIX` when building | 7470 | :term:`TARGET_PREFIX` when building |
6669 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". | 7471 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". |
6670 | 7472 | ||
@@ -6672,15 +7474,15 @@ system and gives an overview of their function and contents. | |||
6672 | 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, |
6673 | the following tasks are added: | 7475 | the following tasks are added: |
6674 | 7476 | ||
6675 | - do_populate_lic | 7477 | - :ref:`ref-tasks-populate_lic` |
6676 | - do_package_qa | 7478 | - :ref:`ref-tasks-package_qa` |
6677 | - do_populate_sysroot | 7479 | - :ref:`ref-tasks-populate_sysroot` |
6678 | - do_deploy | 7480 | - :ref:`ref-tasks-deploy` |
6679 | 7481 | ||
6680 | Despite the default value of "" for the | 7482 | Despite the default value of "" for the |
6681 | ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added | 7483 | :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added |
6682 | 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 |
6683 | ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional | 7485 | :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional |
6684 | tasks that are needed in order to build | 7486 | tasks that are needed in order to build |
6685 | :term:`SDK_TARGETS`). | 7487 | :term:`SDK_TARGETS`). |
6686 | 7488 | ||
@@ -6691,21 +7493,19 @@ system and gives an overview of their function and contents. | |||
6691 | The OpenEmbedded build system automatically sets this variable based | 7493 | The OpenEmbedded build system automatically sets this variable based |
6692 | on :term:`SDK_ARCH`, | 7494 | on :term:`SDK_ARCH`, |
6693 | :term:`SDK_VENDOR`, and | 7495 | :term:`SDK_VENDOR`, and |
6694 | :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` |
6695 | variable yourself. | 7497 | variable yourself. |
6696 | 7498 | ||
6697 | :term:`SDK_TARGET_MANIFEST` | 7499 | :term:`SDK_TARGET_MANIFEST` |
6698 | 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 |
6699 | 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 |
6700 | file contains package information on a line-per-package basis as | 7502 | file contains package information on a line-per-package basis as |
6701 | follows: | 7503 | follows:: |
6702 | :: | ||
6703 | 7504 | ||
6704 | packagename packagearch version | 7505 | packagename packagearch version |
6705 | 7506 | ||
6706 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | 7507 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class |
6707 | defines the manifest file as follows: | 7508 | defines the manifest file as follows:: |
6708 | :: | ||
6709 | 7509 | ||
6710 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" | 7510 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" |
6711 | 7511 | ||
@@ -6717,7 +7517,7 @@ system and gives an overview of their function and contents. | |||
6717 | standard or extensible SDK installation. The default value is "${PN}" | 7517 | standard or extensible SDK installation. The default value is "${PN}" |
6718 | (i.e. the image from which the SDK is built). | 7518 | (i.e. the image from which the SDK is built). |
6719 | 7519 | ||
6720 | The ``SDK_TARGETS`` variable is an internal variable and typically | 7520 | The :term:`SDK_TARGETS` variable is an internal variable and typically |
6721 | would not be changed. | 7521 | would not be changed. |
6722 | 7522 | ||
6723 | :term:`SDK_TITLE` | 7523 | :term:`SDK_TITLE` |
@@ -6725,19 +7525,22 @@ system and gives an overview of their function and contents. | |||
6725 | this title is based on the :term:`DISTRO_NAME` or | 7525 | this title is based on the :term:`DISTRO_NAME` or |
6726 | :term:`DISTRO` variable and is set in the | 7526 | :term:`DISTRO` variable and is set in the |
6727 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | 7527 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as |
6728 | follows: | 7528 | follows:: |
6729 | :: | ||
6730 | 7529 | ||
6731 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" | 7530 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" |
6732 | 7531 | ||
6733 | For the default distribution "poky", | 7532 | For the default distribution "poky", |
6734 | ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". | 7533 | :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". |
6735 | 7534 | ||
6736 | For information on how to change this default title, see the | 7535 | For information on how to change this default title, see the |
6737 | ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" | 7536 | ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" |
6738 | section in the Yocto Project Application Development and the | 7537 | section in the Yocto Project Application Development and the |
6739 | Extensible Software Development Kit (eSDK) manual. | 7538 | Extensible Software Development Kit (eSDK) manual. |
6740 | 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 | |||
6741 | :term:`SDK_UPDATE_URL` | 7544 | :term:`SDK_UPDATE_URL` |
6742 | 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, |
6743 | the value is used as the default update server when running | 7546 | the value is used as the default update server when running |
@@ -6747,29 +7550,32 @@ system and gives an overview of their function and contents. | |||
6747 | Specifies the name of the SDK vendor. | 7550 | Specifies the name of the SDK vendor. |
6748 | 7551 | ||
6749 | :term:`SDK_VERSION` | 7552 | :term:`SDK_VERSION` |
6750 | Specifies the version of the SDK. The distribution configuration file | 7553 | Specifies the version of the SDK. The Poky distribution configuration file |
6751 | (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the | 7554 | (``/meta-poky/conf/distro/poky.conf``) sets the default |
6752 | ``SDK_VERSION`` as follows: | 7555 | :term:`SDK_VERSION` as follows:: |
6753 | :: | ||
6754 | 7556 | ||
6755 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" | 7557 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" |
6756 | 7558 | ||
6757 | For additional information, see the | 7559 | For additional information, see the |
6758 | :term:`DISTRO_VERSION` and | 7560 | :term:`DISTRO_VERSION` and |
6759 | :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". | ||
6760 | 7567 | ||
6761 | :term:`SDKEXTPATH` | 7568 | :term:`SDKEXTPATH` |
6762 | The default installation directory for the Extensible SDK. By | 7569 | The default installation directory for the Extensible SDK. By |
6763 | default, this directory is based on the :term:`DISTRO` | 7570 | default, this directory is based on the :term:`DISTRO` |
6764 | variable and is set in the | 7571 | variable and is set in the |
6765 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | 7572 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as |
6766 | follows: | 7573 | follows:: |
6767 | :: | ||
6768 | 7574 | ||
6769 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" | 7575 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" |
6770 | 7576 | ||
6771 | For the | 7577 | For the |
6772 | default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". | 7578 | default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". |
6773 | 7579 | ||
6774 | For information on how to change this default directory, see the | 7580 | For information on how to change this default directory, see the |
6775 | ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" | 7581 | ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" |
@@ -6777,32 +7583,33 @@ system and gives an overview of their function and contents. | |||
6777 | Extensible Software Development Kit (eSDK) manual. | 7583 | Extensible Software Development Kit (eSDK) manual. |
6778 | 7584 | ||
6779 | :term:`SDKIMAGE_FEATURES` | 7585 | :term:`SDKIMAGE_FEATURES` |
6780 | Equivalent to ``IMAGE_FEATURES``. However, this variable applies to | 7586 | Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to |
6781 | the SDK generated from an image using the following command: | 7587 | the SDK generated from an image using the following command:: |
6782 | :: | ||
6783 | 7588 | ||
6784 | $ bitbake -c populate_sdk imagename | 7589 | $ bitbake -c populate_sdk imagename |
6785 | 7590 | ||
6786 | :term:`SDKMACHINE` | 7591 | :term:`SDKMACHINE` |
6787 | 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 |
6788 | 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` |
6789 | ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` | 7594 | value. The value points to a corresponding ``.conf`` file under |
6790 | 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>`. | ||
6791 | 7598 | ||
6792 | 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 |
6793 | The variable defaults to "i686" and is set in the local.conf file in | 7600 | architecture of the build machine. |
6794 | the Build Directory. | ||
6795 | :: | ||
6796 | |||
6797 | SDKMACHINE ?= "i686" | ||
6798 | 7601 | ||
6799 | .. note:: | 7602 | .. note:: |
6800 | 7603 | ||
6801 | You cannot set the ``SDKMACHINE`` | 7604 | You cannot set the :term:`SDKMACHINE` |
6802 | variable in your distribution configuration file. If you do, the | 7605 | variable in your distribution configuration file. If you do, the |
6803 | configuration will not take affect. | 7606 | configuration will not take effect. |
6804 | 7607 | ||
6805 | :term:`SDKPATH` | 7608 | :term:`SDKPATH` |
7609 | Defines the path used to collect the SDK components and build the | ||
7610 | installer. | ||
7611 | |||
7612 | :term:`SDKPATHINSTALL` | ||
6806 | 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 |
6807 | is generated by the OpenEmbedded build system. The path appears as | 7614 | is generated by the OpenEmbedded build system. The path appears as |
6808 | 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 |
@@ -6812,7 +7619,7 @@ system and gives an overview of their function and contents. | |||
6812 | :term:`SDKTARGETSYSROOT` | 7619 | :term:`SDKTARGETSYSROOT` |
6813 | 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 |
6814 | as it will be when installed into the default | 7621 | as it will be when installed into the default |
6815 | :term:`SDKPATH`. | 7622 | :term:`SDKPATHINSTALL`. |
6816 | 7623 | ||
6817 | :term:`SECTION` | 7624 | :term:`SECTION` |
6818 | The section in which packages should be categorized. Package | 7625 | The section in which packages should be categorized. Package |
@@ -6823,50 +7630,43 @@ system and gives an overview of their function and contents. | |||
6823 | building for the target. The flags are passed through the default | 7630 | building for the target. The flags are passed through the default |
6824 | value of the :term:`TARGET_CFLAGS` variable. | 7631 | value of the :term:`TARGET_CFLAGS` variable. |
6825 | 7632 | ||
6826 | The ``SELECTED_OPTIMIZATION`` variable takes the value of | 7633 | The :term:`SELECTED_OPTIMIZATION` variable takes the value of |
6827 | ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the | 7634 | :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which |
6828 | case, the value of ``DEBUG_OPTIMIZATION`` is used. | 7635 | case the value of :term:`DEBUG_OPTIMIZATION` is used. |
6829 | |||
6830 | :term:`SERIAL_CONSOLE` | ||
6831 | Defines a serial console (TTY) to enable using | ||
6832 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6833 | value that specifies the baud rate followed by the TTY device name | ||
6834 | separated by a space. You cannot specify more than one TTY device: | ||
6835 | :: | ||
6836 | |||
6837 | SERIAL_CONSOLE = "115200 ttyS0" | ||
6838 | |||
6839 | .. note:: | ||
6840 | |||
6841 | The ``SERIAL_CONSOLE`` variable is deprecated. Please use the | ||
6842 | :term:`SERIAL_CONSOLES` variable. | ||
6843 | 7636 | ||
6844 | :term:`SERIAL_CONSOLES` | 7637 | :term:`SERIAL_CONSOLES` |
6845 | Defines a serial console (TTY) to enable using | 7638 | Defines a serial console (TTY) to enable using |
6846 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | 7639 | :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the |
6847 | 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. |
6848 | separated by a semicolon. Use spaces to separate multiple devices: | 7641 | Use spaces to separate multiple devices:: |
6849 | :: | ||
6850 | 7642 | ||
6851 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" | 7643 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" |
6852 | 7644 | ||
6853 | :term:`SERIAL_CONSOLES_CHECK` | 7645 | :term:`SETUPTOOLS_BUILD_ARGS` |
6854 | Specifies serial consoles, which must be listed in | 7646 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` |
6855 | :term:`SERIAL_CONSOLES`, to check against | 7647 | class, this variable can be used to specify additional arguments to be |
6856 | ``/proc/console`` before enabling them using getty. This variable | 7648 | passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task. |
6857 | allows aliasing in the format: <device>:<alias>. If a device was | ||
6858 | listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in | ||
6859 | ``/proc/console``, you would do the following: :: | ||
6860 | 7649 | ||
6861 | 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. | ||
6862 | 7654 | ||
6863 | This variable is currently only supported with SysVinit (i.e. not | 7655 | :term:`SETUPTOOLS_SETUP_PATH` |
6864 | 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" | ||
6865 | 7665 | ||
6866 | :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` | 7666 | :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` |
6867 | 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 |
6868 | 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 |
6869 | another recipe. For example: :: | 7669 | another recipe. For example:: |
6870 | 7670 | ||
6871 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" | 7671 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" |
6872 | 7672 | ||
@@ -6874,7 +7674,7 @@ system and gives an overview of their function and contents. | |||
6874 | 7674 | ||
6875 | 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 |
6876 | 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 |
6877 | side. Here is an example: :: | 7677 | side. Here is an example:: |
6878 | 7678 | ||
6879 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" | 7679 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" |
6880 | 7680 | ||
@@ -6919,15 +7719,27 @@ system and gives an overview of their function and contents. | |||
6919 | 7719 | ||
6920 | To enable file removal, set the variable to "1" in your | 7720 | To enable file removal, set the variable to "1" in your |
6921 | ``conf/local.conf`` configuration file in your: | 7721 | ``conf/local.conf`` configuration file in your: |
6922 | :term:`Build Directory`. | 7722 | :term:`Build Directory`:: |
6923 | :: | ||
6924 | 7723 | ||
6925 | SKIP_FILEDEPS = "1" | 7724 | SKIP_FILEDEPS = "1" |
6926 | 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 | |||
6927 | :term:`SOC_FAMILY` | 7738 | :term:`SOC_FAMILY` |
6928 | Groups together machines based upon the same family of SOC (System On | 7739 | A colon-separated list grouping together machines based upon the same |
6929 | 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 |
6930 | 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. | ||
6931 | 7743 | ||
6932 | .. note:: | 7744 | .. note:: |
6933 | 7745 | ||
@@ -6940,7 +7752,7 @@ system and gives an overview of their function and contents. | |||
6940 | defined in the ``meta/conf/bitbake.conf`` configuration file. | 7752 | defined in the ``meta/conf/bitbake.conf`` configuration file. |
6941 | 7753 | ||
6942 | You will see this variable referenced in the default values of | 7754 | You will see this variable referenced in the default values of |
6943 | ``FILES_${PN}``. | 7755 | ``FILES:${PN}``. |
6944 | 7756 | ||
6945 | :term:`SOLIBSDEV` | 7757 | :term:`SOLIBSDEV` |
6946 | Defines the suffix for the development symbolic link (symlink) for | 7758 | Defines the suffix for the development symbolic link (symlink) for |
@@ -6949,11 +7761,28 @@ system and gives an overview of their function and contents. | |||
6949 | ``meta/conf/bitbake.conf`` configuration file. | 7761 | ``meta/conf/bitbake.conf`` configuration file. |
6950 | 7762 | ||
6951 | You will see this variable referenced in the default values of | 7763 | You will see this variable referenced in the default values of |
6952 | ``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" | ||
6953 | 7782 | ||
6954 | :term:`SOURCE_MIRROR_FETCH` | 7783 | :term:`SOURCE_MIRROR_FETCH` |
6955 | 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. |
6956 | creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in | 7785 | creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in |
6957 | your ``local.conf`` configuration file ensures the source for all | 7786 | your ``local.conf`` configuration file ensures the source for all |
6958 | recipes are fetched regardless of whether or not a recipe is | 7787 | recipes are fetched regardless of whether or not a recipe is |
6959 | compatible with the configuration. A recipe is considered | 7788 | compatible with the configuration. A recipe is considered |
@@ -6965,7 +7794,7 @@ system and gives an overview of their function and contents. | |||
6965 | 7794 | ||
6966 | .. note:: | 7795 | .. note:: |
6967 | 7796 | ||
6968 | Do not set the ``SOURCE_MIRROR_FETCH`` | 7797 | Do not set the :term:`SOURCE_MIRROR_FETCH` |
6969 | variable unless you are creating a source mirror. In other words, | 7798 | variable unless you are creating a source mirror. In other words, |
6970 | do not set the variable during a normal build. | 7799 | do not set the variable during a normal build. |
6971 | 7800 | ||
@@ -6975,20 +7804,132 @@ system and gives an overview of their function and contents. | |||
6975 | specified in :term:`SRC_URI`. | 7804 | specified in :term:`SRC_URI`. |
6976 | 7805 | ||
6977 | To use this variable, you must globally inherit the | 7806 | To use this variable, you must globally inherit the |
6978 | :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide | 7807 | :ref:`ref-classes-own-mirrors` class and then provide |
6979 | the URL to your mirrors. Here is the general syntax: | 7808 | the URL to your mirrors. Here is the general syntax:: |
6980 | :: | ||
6981 | 7809 | ||
6982 | INHERIT += "own-mirrors" | 7810 | INHERIT += "own-mirrors" |
6983 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" | 7811 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" |
6984 | 7812 | ||
6985 | .. note:: | 7813 | .. note:: |
6986 | 7814 | ||
6987 | 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. | ||
6988 | 7929 | ||
6989 | :term:`SPDXLICENSEMAP` | 7930 | :term:`SPDXLICENSEMAP` |
6990 | Maps commonly used license names to their SPDX counterparts found in | 7931 | Maps commonly used license names to their SPDX counterparts found in |
6991 | ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` | 7932 | ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` |
6992 | mappings, see the ``meta/conf/licenses.conf`` file. | 7933 | mappings, see the ``meta/conf/licenses.conf`` file. |
6993 | 7934 | ||
6994 | For additional information, see the :term:`LICENSE` | 7935 | For additional information, see the :term:`LICENSE` |
@@ -7008,8 +7949,7 @@ system and gives an overview of their function and contents. | |||
7008 | U-Boot recipe. | 7949 | U-Boot recipe. |
7009 | 7950 | ||
7010 | 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`` |
7011 | file as follows: | 7952 | file as follows:: |
7012 | :: | ||
7013 | 7953 | ||
7014 | # 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 |
7015 | # 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 |
@@ -7020,171 +7960,132 @@ system and gives an overview of their function and contents. | |||
7020 | SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" | 7960 | SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" |
7021 | SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" | 7961 | SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" |
7022 | 7962 | ||
7023 | The ``SPL_BINARY`` variable helps form | 7963 | The :term:`SPL_BINARY` variable helps form |
7024 | various ``SPL_*`` variables used by the OpenEmbedded build system. | 7964 | various ``SPL_*`` variables used by the OpenEmbedded build system. |
7025 | 7965 | ||
7026 | See the BeagleBone machine configuration example in the | 7966 | See the BeagleBone machine configuration example in the |
7027 | ":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`" |
7028 | section in the Yocto Project Board Support Package Developer's Guide | 7968 | section in the Yocto Project Board Support Package Developer's Guide |
7029 | for additional information. | 7969 | for additional information. |
7030 | 7970 | ||
7031 | :term:`SRC_URI` | 7971 | :term:`SPL_MKIMAGE_DTCOPTS` |
7032 | The list of source files - local or remote. This variable tells the | 7972 | Options for the device tree compiler passed to ``mkimage -D`` feature |
7033 | 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` |
7034 | 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 |
7035 | 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 |
7036 | a single ``SRC_URI`` entry. On the other hand, if the recipe or | 7976 | to ``mkimage``. |
7037 | append file needs to fetch a tarball, apply two patches, and include | ||
7038 | a custom file, the recipe or append file would include four instances | ||
7039 | of the variable. | ||
7040 | |||
7041 | The following list explains the available URI protocols. URI | ||
7042 | protocols are highly dependent on particular BitBake Fetcher | ||
7043 | submodules. Depending on the fetcher BitBake uses, various URL | ||
7044 | parameters are employed. For specifics on the supported Fetchers, see | ||
7045 | the ":ref:`Fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`" section in the | ||
7046 | BitBake User Manual. | ||
7047 | |||
7048 | - ``file://`` - Fetches files, which are usually files shipped | ||
7049 | with the :term:`Metadata`, from the local machine (e.g. | ||
7050 | :ref:`patch <overview-manual/concepts:patching>` files). | ||
7051 | The path is relative to the :term:`FILESPATH` | ||
7052 | variable. Thus, the build system searches, in order, from the | ||
7053 | following directories, which are assumed to be a subdirectories of | ||
7054 | the directory in which the recipe file (``.bb``) or append file | ||
7055 | (``.bbappend``) resides: | ||
7056 | |||
7057 | - ``${BPN}`` - The base recipe name without any special suffix | ||
7058 | or version numbers. | ||
7059 | |||
7060 | - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and | ||
7061 | version but without any special package name suffix. | ||
7062 | |||
7063 | - *files -* Files within a directory, which is named ``files`` | ||
7064 | and is also alongside the recipe or append file. | ||
7065 | 7977 | ||
7066 | .. 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. | ||
7067 | 7989 | ||
7068 | If you want the build system to pick up files specified through | 7990 | :term:`SPL_SIGN_KEYNAME` |
7069 | a | 7991 | The name of keys used by the :ref:`ref-classes-kernel-fitimage` class |
7070 | SRC_URI | 7992 | for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` |
7071 | 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`` |
7072 | the | 7994 | certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will |
7073 | FILESPATH | 7995 | have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. |
7074 | variable by also using the | ||
7075 | FILESEXTRAPATHS | ||
7076 | variable from within your append file. | ||
7077 | 7996 | ||
7078 | - ``bzr://`` - Fetches files from a Bazaar revision control | 7997 | :term:`SPLASH` |
7079 | 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``. | ||
7080 | 8002 | ||
7081 | - ``git://`` - Fetches files from a Git revision control | 8003 | :term:`SPLASH_IMAGES` |
7082 | repository. | 8004 | This variable, used by the ``psplash`` recipe, allows to customize |
8005 | the default splashscreen image. | ||
7083 | 8006 | ||
7084 | - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) | 8007 | Specified images in PNG format are converted to ``.h`` files by the recipe, |
7085 | revision control repository. | 8008 | and are included in the ``psplash`` binary, so you won't find them in |
8009 | the root filesystem. | ||
7086 | 8010 | ||
7087 | - ``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:: | ||
7088 | 8014 | ||
7089 | - ``ccrc://`` - Fetches files from a ClearCase repository. | 8015 | meta-acme/recipes-core/psplash |
8016 | ├── files | ||
8017 | │  └── logo-acme.png | ||
8018 | └── psplash_%.bbappend | ||
7090 | 8019 | ||
7091 | - ``http://`` - Fetches files from the Internet using ``http``. | 8020 | And here are the contents of the ``psplash_%.bbappend`` file in |
8021 | this example:: | ||
7092 | 8022 | ||
7093 | - ``https://`` - Fetches files from the Internet using ``https``. | 8023 | SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" |
8024 | FILESEXTRAPATHS:prepend := "${THISDIR}/files:" | ||
7094 | 8025 | ||
7095 | - ``ftp://`` - Fetches files from the Internet using ``ftp``. | 8026 | You could even add specific configuration options for ``psplash``, |
8027 | for example:: | ||
7096 | 8028 | ||
7097 | - ``cvs://`` - Fetches files from a CVS revision control | 8029 | EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" |
7098 | repository. | ||
7099 | 8030 | ||
7100 | - ``hg://`` - Fetches files from a Mercurial (``hg``) revision | 8031 | For information on append files, see the |
7101 | control repository. | 8032 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
8033 | section. | ||
7102 | 8034 | ||
7103 | - ``p4://`` - Fetches files from a Perforce (``p4``) revision | 8035 | :term:`SRCREV_FORMAT` |
7104 | control repository. | 8036 | See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. |
7105 | 8037 | ||
7106 | - ``ssh://`` - Fetches files from a secure shell. | 8038 | :term:`SRC_URI` |
7107 | 8039 | ||
7108 | - ``svn://`` - Fetches files from a Subversion (``svn``) revision | 8040 | See the BitBake manual for the initial description for this variable: |
7109 | control repository. | 8041 | :term:`bitbake:SRC_URI`. |
7110 | 8042 | ||
7111 | - ``npm://`` - Fetches JavaScript modules from a registry. | 8043 | The following features are added by OpenEmbedded and the Yocto Project. |
7112 | 8044 | ||
7113 | Standard and recipe-specific options for ``SRC_URI`` exist. Here are | 8045 | There are standard and recipe-specific options. Here are standard ones: |
7114 | standard options: | ||
7115 | 8046 | ||
7116 | - ``apply`` - Whether to apply the patch or not. The default | 8047 | - ``apply`` --- whether to apply the patch or not. The default |
7117 | action is to apply the patch. | 8048 | action is to apply the patch. |
7118 | 8049 | ||
7119 | - ``striplevel`` - Which striplevel to use when applying the | 8050 | - ``striplevel`` --- which striplevel to use when applying the |
7120 | patch. The default level is 1. | 8051 | patch. The default level is 1. |
7121 | 8052 | ||
7122 | - ``patchdir`` - Specifies the directory in which the patch should | 8053 | - ``patchdir`` --- specifies the directory in which the patch should |
7123 | be applied. The default is ``${``\ :term:`S`\ ``}``. | 8054 | be applied. The default is ``${``\ :term:`S`\ ``}``. |
7124 | 8055 | ||
7125 | Here are options specific to recipes building code from a revision | 8056 | Here are options specific to recipes building code from a revision |
7126 | control system: | 8057 | control system: |
7127 | 8058 | ||
7128 | - ``mindate`` - Apply the patch only if | 8059 | - ``mindate`` --- apply the patch only if |
7129 | :term:`SRCDATE` is equal to or greater than | 8060 | :term:`SRCDATE` is equal to or greater than |
7130 | ``mindate``. | 8061 | ``mindate``. |
7131 | 8062 | ||
7132 | - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later | 8063 | - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later |
7133 | than ``maxdate``. | 8064 | than ``maxdate``. |
7134 | 8065 | ||
7135 | - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or | 8066 | - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or |
7136 | greater than ``minrev``. | 8067 | greater than ``minrev``. |
7137 | 8068 | ||
7138 | - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later | 8069 | - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later |
7139 | than ``maxrev``. | 8070 | than ``maxrev``. |
7140 | 8071 | ||
7141 | - ``rev`` - Apply the patch only if ``SRCREV`` is equal to | 8072 | - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to |
7142 | ``rev``. | 8073 | ``rev``. |
7143 | 8074 | ||
7144 | - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to | 8075 | - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to |
7145 | ``rev``. | 8076 | ``rev``. |
7146 | 8077 | ||
7147 | Here are some additional options worth mentioning: | 8078 | .. note:: |
7148 | |||
7149 | - ``unpack`` - Controls whether or not to unpack the file if it is | ||
7150 | an archive. The default action is to unpack the file. | ||
7151 | |||
7152 | - ``destsuffix`` - Places the file (or extracts its contents) into | ||
7153 | the specified subdirectory of :term:`WORKDIR` when | ||
7154 | the Git fetcher is used. | ||
7155 | |||
7156 | - ``subdir`` - Places the file (or extracts its contents) into the | ||
7157 | specified subdirectory of ``WORKDIR`` when the local (``file://``) | ||
7158 | fetcher is used. | ||
7159 | |||
7160 | - ``localdir`` - Places the file (or extracts its contents) into | ||
7161 | the specified subdirectory of ``WORKDIR`` when the CVS fetcher is | ||
7162 | used. | ||
7163 | |||
7164 | - ``subpath`` - Limits the checkout to a specific subpath of the | ||
7165 | tree when using the Git fetcher is used. | ||
7166 | |||
7167 | - ``name`` - Specifies a name to be used for association with | ||
7168 | ``SRC_URI`` checksums or :term:`SRCREV` when you have more than one | ||
7169 | file or git repository specified in ``SRC_URI``. For example: | ||
7170 | :: | ||
7171 | |||
7172 | SRC_URI = "git://example.com/foo.git;name=first \ | ||
7173 | git://example.com/bar.git;name=second \ | ||
7174 | http://example.com/file.tar.gz;name=third" | ||
7175 | |||
7176 | SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" | ||
7177 | SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" | ||
7178 | SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" | ||
7179 | |||
7180 | 8079 | ||
7181 | - ``downloadfilename`` - Specifies the filename used when storing | 8080 | If you want the build system to pick up files specified through |
7182 | 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. | ||
7183 | 8084 | ||
7184 | :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` | 8085 | :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` |
7185 | By default, the OpenEmbedded build system automatically detects | 8086 | By default, the OpenEmbedded build system automatically detects |
7186 | whether ``SRC_URI`` contains files that are machine-specific. If so, | 8087 | whether :term:`SRC_URI` contains files that are machine-specific. If so, |
7187 | the build system automatically changes ``PACKAGE_ARCH``. Setting this | 8088 | the build system automatically changes :term:`PACKAGE_ARCH`. Setting this |
7188 | variable to "0" disables this behavior. | 8089 | variable to "0" disables this behavior. |
7189 | 8090 | ||
7190 | :term:`SRCDATE` | 8091 | :term:`SRCDATE` |
@@ -7196,18 +8097,16 @@ system and gives an overview of their function and contents. | |||
7196 | Returns the version string of the current package. This string is | 8097 | Returns the version string of the current package. This string is |
7197 | used to help define the value of :term:`PV`. | 8098 | used to help define the value of :term:`PV`. |
7198 | 8099 | ||
7199 | The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` | 8100 | The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf`` |
7200 | configuration file in the :term:`Source Directory` as | 8101 | configuration file in the :term:`Source Directory` as |
7201 | follows: | 8102 | follows:: |
7202 | :: | ||
7203 | 8103 | ||
7204 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" | 8104 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" |
7205 | 8105 | ||
7206 | 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 |
7207 | ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) | 8107 | :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``) |
7208 | located in ``meta/recipes-connectivity`` in the Source Directory | 8108 | located in ``meta/recipes-connectivity`` in the Source Directory |
7209 | defines ``PV`` as follows: | 8109 | defines :term:`PV` as follows:: |
7210 | :: | ||
7211 | 8110 | ||
7212 | PV = "0.12-git${SRCPV}" | 8111 | PV = "0.12-git${SRCPV}" |
7213 | 8112 | ||
@@ -7216,26 +8115,76 @@ system and gives an overview of their function and contents. | |||
7216 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note | 8115 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note |
7217 | 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 |
7218 | performing a query on the remote repository every time BitBake parses | 8117 | performing a query on the remote repository every time BitBake parses |
7219 | 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 |
7220 | identifier and not just a tag. | 8119 | identifier (e.g. the full SHA hash in git) and not just a tag. |
7221 | 8120 | ||
7222 | .. note:: | 8121 | .. note:: |
7223 | 8122 | ||
7224 | For information on limitations when inheriting the latest revision | 8123 | For information on limitations when inheriting the latest revision |
7225 | of software using ``SRCREV``, see the :term:`AUTOREV` variable | 8124 | of software using :term:`SRCREV`, see the :term:`AUTOREV` variable |
7226 | description and the | 8125 | description and the |
7227 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | 8126 | ":ref:`dev-manual/packages:automatically incrementing a package version number`" |
7228 | section, which is in the Yocto Project Development Tasks Manual. | 8127 | section, which is in the Yocto Project Development Tasks Manual. |
7229 | 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 | |||
7230 | :term:`SSTATE_DIR` | 8153 | :term:`SSTATE_DIR` |
7231 | The directory for the shared state cache. | 8154 | The directory for the shared state cache. |
7232 | 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 | |||
7233 | :term:`SSTATE_MIRROR_ALLOW_NETWORK` | 8182 | :term:`SSTATE_MIRROR_ALLOW_NETWORK` |
7234 | 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 |
7235 | :term:`SSTATE_MIRRORS` to work even when | 8184 | :term:`SSTATE_MIRRORS` to work even when |
7236 | 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 |
7237 | "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if | 8186 | "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if |
7238 | 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 |
7239 | 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 |
7240 | from the network. | 8189 | from the network. |
7241 | 8190 | ||
@@ -7253,26 +8202,33 @@ system and gives an overview of their function and contents. | |||
7253 | 8202 | ||
7254 | When pointing to sstate build artifacts on another machine that uses | 8203 | When pointing to sstate build artifacts on another machine that uses |
7255 | a different GCC version for native builds, you must configure | 8204 | a different GCC version for native builds, you must configure |
7256 | ``SSTATE_MIRRORS`` with a regular expression that maps local search | 8205 | :term:`SSTATE_MIRRORS` with a regular expression that maps local search |
7257 | paths to server paths. The paths need to take into account | 8206 | paths to server paths. The paths need to take into account |
7258 | :term:`NATIVELSBSTRING` set by the | 8207 | :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class. |
7259 | :ref:`uninative <ref-classes-uninative>` class. For example, the | 8208 | For example, the following maps the local search path ``universal-4.9`` |
7260 | following maps the local search path ``universal-4.9`` to the | 8209 | to the server-provided path server_url_sstate_path:: |
7261 | server-provided path server_url_sstate_path: | ||
7262 | :: | ||
7263 | 8210 | ||
7264 | 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" |
7265 | 8212 | ||
7266 | If a mirror uses the same structure as | 8213 | If a mirror uses the same structure as |
7267 | :term:`SSTATE_DIR`, you need to add "PATH" at the | 8214 | :term:`SSTATE_DIR`, you need to add "PATH" at the |
7268 | 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 |
7269 | correct path within the directory structure. | 8216 | correct path within the directory structure:: |
7270 | :: | ||
7271 | 8217 | ||
7272 | SSTATE_MIRRORS ?= "\ | 8218 | SSTATE_MIRRORS ?= "\ |
7273 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | 8219 | file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \ |
7274 | file://.* file:///some-local-dir/sstate/PATH" | 8220 | file://.* file:///some-local-dir/sstate/PATH" |
7275 | 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 | |||
7276 | :term:`SSTATE_SCAN_FILES` | 8232 | :term:`SSTATE_SCAN_FILES` |
7277 | Controls the list of files the OpenEmbedded build system scans for | 8233 | Controls the list of files the OpenEmbedded build system scans for |
7278 | hardcoded installation paths. The variable uses a space-separated | 8234 | hardcoded installation paths. The variable uses a space-separated |
@@ -7283,14 +8239,12 @@ system and gives an overview of their function and contents. | |||
7283 | (sstate) object during the first stage of preparing the sysroots. | 8239 | (sstate) object during the first stage of preparing the sysroots. |
7284 | That object is scanned for hardcoded paths for original installation | 8240 | That object is scanned for hardcoded paths for original installation |
7285 | 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 |
7286 | by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files | 8242 | by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files |
7287 | 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 |
7288 | than the variable being comprehensively set. The | 8244 | than the variable being comprehensively set. The |
7289 | :ref:`sstate <ref-classes-sstate>` class specifies the default list | 8245 | :ref:`ref-classes-sstate` class specifies the default list of files. |
7290 | of files. | ||
7291 | 8246 | ||
7292 | For details on the process, see the | 8247 | For details on the process, see the :ref:`ref-classes-staging` class. |
7293 | :ref:`staging <ref-classes-staging>` class. | ||
7294 | 8248 | ||
7295 | :term:`STAGING_BASE_LIBDIR_NATIVE` | 8249 | :term:`STAGING_BASE_LIBDIR_NATIVE` |
7296 | Specifies the path to the ``/lib`` subdirectory of the sysroot | 8250 | Specifies the path to the ``/lib`` subdirectory of the sysroot |
@@ -7346,7 +8300,7 @@ system and gives an overview of their function and contents. | |||
7346 | 8300 | ||
7347 | .. note:: | 8301 | .. note:: |
7348 | 8302 | ||
7349 | Recipes should never write files directly under the ``STAGING_DIR`` | 8303 | Recipes should never write files directly under the :term:`STAGING_DIR` |
7350 | directory because the OpenEmbedded build system manages the | 8304 | directory because the OpenEmbedded build system manages the |
7351 | directory automatically. Instead, files should be installed to | 8305 | directory automatically. Instead, files should be installed to |
7352 | ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` | 8306 | ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` |
@@ -7359,9 +8313,9 @@ system and gives an overview of their function and contents. | |||
7359 | 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 |
7360 | :ref:`ref-tasks-populate_sysroot` task copies | 8314 | :ref:`ref-tasks-populate_sysroot` task copies |
7361 | files. Exceptions include ``-native`` recipes, where the | 8315 | files. Exceptions include ``-native`` recipes, where the |
7362 | ``do_populate_sysroot`` task instead uses | 8316 | :ref:`ref-tasks-populate_sysroot` task instead uses |
7363 | :term:`STAGING_DIR_NATIVE`. Depending on | 8317 | :term:`STAGING_DIR_NATIVE`. Depending on |
7364 | 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 |
7365 | have the following values: | 8319 | have the following values: |
7366 | 8320 | ||
7367 | - For recipes building for the target machine, the value is | 8321 | - For recipes building for the target machine, the value is |
@@ -7375,11 +8329,11 @@ system and gives an overview of their function and contents. | |||
7375 | 8329 | ||
7376 | ``-native`` recipes are not installed into host paths like such | 8330 | ``-native`` recipes are not installed into host paths like such |
7377 | as ``/usr``. Rather, these recipes are installed into | 8331 | as ``/usr``. Rather, these recipes are installed into |
7378 | ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, | 8332 | :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, |
7379 | standard build environment variables such as | 8333 | standard build environment variables such as |
7380 | :term:`CPPFLAGS` and | 8334 | :term:`CPPFLAGS` and |
7381 | :term:`CFLAGS` are set up so that both host paths | 8335 | :term:`CFLAGS` are set up so that both host paths |
7382 | and ``STAGING_DIR_NATIVE`` are searched for libraries and | 8336 | and :term:`STAGING_DIR_NATIVE` are searched for libraries and |
7383 | headers using, for example, GCC's ``-isystem`` option. | 8337 | headers using, for example, GCC's ``-isystem`` option. |
7384 | 8338 | ||
7385 | Thus, the emphasis is that the ``STAGING_DIR*`` variables | 8339 | Thus, the emphasis is that the ``STAGING_DIR*`` variables |
@@ -7387,28 +8341,33 @@ system and gives an overview of their function and contents. | |||
7387 | :ref:`ref-tasks-configure`, | 8341 | :ref:`ref-tasks-configure`, |
7388 | :ref:`ref-tasks-compile`, and | 8342 | :ref:`ref-tasks-compile`, and |
7389 | :ref:`ref-tasks-install`. Having the real system | 8343 | :ref:`ref-tasks-install`. Having the real system |
7390 | root correspond to ``STAGING_DIR_HOST`` makes conceptual sense | 8344 | root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense |
7391 | for ``-native`` recipes, as they make use of host headers and | 8345 | for ``-native`` recipes, as they make use of host headers and |
7392 | libraries. | 8346 | libraries. |
7393 | 8347 | ||
8348 | Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`. | ||
8349 | |||
7394 | :term:`STAGING_DIR_NATIVE` | 8350 | :term:`STAGING_DIR_NATIVE` |
7395 | Specifies the path to the sysroot directory used when building | 8351 | Specifies the path to the sysroot directory used when building |
7396 | components that run on the build host itself. | 8352 | components that run on the build host itself. |
7397 | 8353 | ||
8354 | The default value is ``"${RECIPE_SYSROOT_NATIVE}"``, | ||
8355 | check :term:`RECIPE_SYSROOT_NATIVE`. | ||
8356 | |||
7398 | :term:`STAGING_DIR_TARGET` | 8357 | :term:`STAGING_DIR_TARGET` |
7399 | 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 |
7400 | component generates code. For components that do not generate code, | 8359 | component generates code. For components that do not generate code, |
7401 | which is the majority, ``STAGING_DIR_TARGET`` is set to match | 8360 | which is the majority, :term:`STAGING_DIR_TARGET` is set to match |
7402 | :term:`STAGING_DIR_HOST`. | 8361 | :term:`STAGING_DIR_HOST`. |
7403 | 8362 | ||
7404 | 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 |
7405 | those binaries in turn generate code for another different system | 8364 | binaries in turn generate code for another different system (e.g. |
7406 | (e.g. cross-canadian recipes). Using terminology from GNU, the | 8365 | :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU, |
7407 | 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 |
7408 | different, system is referred to as the "TARGET". Thus, the binaries | 8367 | different, system is referred to as the "TARGET". Thus, the binaries |
7409 | run on the "HOST" system and generate binaries for the "TARGET" | 8368 | run on the "HOST" system and generate binaries for the "TARGET" |
7410 | system. The ``STAGING_DIR_HOST`` variable points to the sysroot used | 8369 | system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used |
7411 | for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the | 8370 | for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the |
7412 | sysroot used for the "TARGET" system. | 8371 | sysroot used for the "TARGET" system. |
7413 | 8372 | ||
7414 | :term:`STAGING_ETCDIR_NATIVE` | 8373 | :term:`STAGING_ETCDIR_NATIVE` |
@@ -7433,7 +8392,7 @@ system and gives an overview of their function and contents. | |||
7433 | Points to the directory containing the kernel build artifacts. | 8392 | Points to the directory containing the kernel build artifacts. |
7434 | Recipes building software that needs to access kernel build artifacts | 8393 | Recipes building software that needs to access kernel build artifacts |
7435 | (e.g. ``systemtap-uprobes``) can look in the directory specified with | 8394 | (e.g. ``systemtap-uprobes``) can look in the directory specified with |
7436 | the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts | 8395 | the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts |
7437 | after the kernel has been built. | 8396 | after the kernel has been built. |
7438 | 8397 | ||
7439 | :term:`STAGING_KERNEL_DIR` | 8398 | :term:`STAGING_KERNEL_DIR` |
@@ -7453,9 +8412,8 @@ system and gives an overview of their function and contents. | |||
7453 | 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 |
7454 | 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 |
7455 | then appending additional information. Currently, the default | 8414 | then appending additional information. Currently, the default |
7456 | assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` | 8415 | assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` |
7457 | file is: | 8416 | file is:: |
7458 | :: | ||
7459 | 8417 | ||
7460 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" | 8418 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" |
7461 | 8419 | ||
@@ -7470,6 +8428,9 @@ system and gives an overview of their function and contents. | |||
7470 | :term:`PV`, and :term:`PR` for related variable | 8428 | :term:`PV`, and :term:`PR` for related variable |
7471 | information. | 8429 | information. |
7472 | 8430 | ||
8431 | :term:`STAMPCLEAN` | ||
8432 | See :term:`bitbake:STAMPCLEAN` in the BitBake manual. | ||
8433 | |||
7473 | :term:`STAMPS_DIR` | 8434 | :term:`STAMPS_DIR` |
7474 | Specifies the base directory in which the OpenEmbedded build system | 8435 | Specifies the base directory in which the OpenEmbedded build system |
7475 | places stamps. The default directory is ``${TMPDIR}/stamps``. | 8436 | places stamps. The default directory is ``${TMPDIR}/stamps``. |
@@ -7481,8 +8442,8 @@ system and gives an overview of their function and contents. | |||
7481 | :term:`SUMMARY` | 8442 | :term:`SUMMARY` |
7482 | 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 |
7483 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, | 8444 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, |
7484 | ``SUMMARY`` is used to define the | 8445 | :term:`SUMMARY` is used to define the |
7485 | :term:`DESCRIPTION` variable if ``DESCRIPTION`` is | 8446 | :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is |
7486 | not set in the recipe. | 8447 | not set in the recipe. |
7487 | 8448 | ||
7488 | :term:`SVNDIR` | 8449 | :term:`SVNDIR` |
@@ -7492,12 +8453,11 @@ system and gives an overview of their function and contents. | |||
7492 | :term:`SYSLINUX_DEFAULT_CONSOLE` | 8453 | :term:`SYSLINUX_DEFAULT_CONSOLE` |
7493 | 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 |
7494 | 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 |
7495 | follows where "X" is the console number you want to use: | 8456 | follows where "X" is the console number you want to use:: |
7496 | :: | ||
7497 | 8457 | ||
7498 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" | 8458 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" |
7499 | 8459 | ||
7500 | The :ref:`syslinux <ref-classes-syslinux>` class initially sets | 8460 | The :ref:`ref-classes-syslinux` class initially sets |
7501 | this variable to null but then checks for a value later. | 8461 | this variable to null but then checks for a value later. |
7502 | 8462 | ||
7503 | :term:`SYSLINUX_OPTS` | 8463 | :term:`SYSLINUX_OPTS` |
@@ -7505,15 +8465,14 @@ system and gives an overview of their function and contents. | |||
7505 | 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, |
7506 | separate the options with a semicolon character (``;``). | 8466 | separate the options with a semicolon character (``;``). |
7507 | 8467 | ||
7508 | The :ref:`syslinux <ref-classes-syslinux>` class uses this variable | 8468 | The :ref:`ref-classes-syslinux` class uses this variable |
7509 | to create a set of options. | 8469 | to create a set of options. |
7510 | 8470 | ||
7511 | :term:`SYSLINUX_SERIAL` | 8471 | :term:`SYSLINUX_SERIAL` |
7512 | 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 |
7513 | 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 |
7514 | variable's default value is set in the | 8474 | variable's default value is set in the |
7515 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | 8475 | :ref:`ref-classes-syslinux` class as follows:: |
7516 | :: | ||
7517 | 8476 | ||
7518 | SYSLINUX_SERIAL ?= "0 115200" | 8477 | SYSLINUX_SERIAL ?= "0 115200" |
7519 | 8478 | ||
@@ -7521,9 +8480,8 @@ system and gives an overview of their function and contents. | |||
7521 | 8480 | ||
7522 | :term:`SYSLINUX_SERIAL_TTY` | 8481 | :term:`SYSLINUX_SERIAL_TTY` |
7523 | Specifies the alternate console=tty... kernel boot argument. The | 8482 | Specifies the alternate console=tty... kernel boot argument. The |
7524 | variable's default value is set in the | 8483 | variable's default value is set in the :ref:`ref-classes-syslinux` |
7525 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | 8484 | class as follows:: |
7526 | :: | ||
7527 | 8485 | ||
7528 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" | 8486 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" |
7529 | 8487 | ||
@@ -7533,7 +8491,7 @@ system and gives an overview of their function and contents. | |||
7533 | 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 |
7534 | 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. |
7535 | 8493 | ||
7536 | The :ref:`syslinux <ref-classes-syslinux>` class checks for this | 8494 | The :ref:`ref-classes-syslinux` class checks for this |
7537 | variable and if found, the OpenEmbedded build system installs the | 8495 | variable and if found, the OpenEmbedded build system installs the |
7538 | splash screen. | 8496 | splash screen. |
7539 | 8497 | ||
@@ -7546,8 +8504,7 @@ system and gives an overview of their function and contents. | |||
7546 | :term:`SYSROOT_DIRS` | 8504 | :term:`SYSROOT_DIRS` |
7547 | Directories that are staged into the sysroot by the | 8505 | Directories that are staged into the sysroot by the |
7548 | :ref:`ref-tasks-populate_sysroot` task. By | 8506 | :ref:`ref-tasks-populate_sysroot` task. By |
7549 | default, the following directories are staged: | 8507 | default, the following directories are staged:: |
7550 | :: | ||
7551 | 8508 | ||
7552 | SYSROOT_DIRS = " \ | 8509 | SYSROOT_DIRS = " \ |
7553 | ${includedir} \ | 8510 | ${includedir} \ |
@@ -7555,33 +8512,67 @@ system and gives an overview of their function and contents. | |||
7555 | ${base_libdir} \ | 8512 | ${base_libdir} \ |
7556 | ${nonarch_base_libdir} \ | 8513 | ${nonarch_base_libdir} \ |
7557 | ${datadir} \ | 8514 | ${datadir} \ |
8515 | /sysroot-only \ | ||
7558 | " | 8516 | " |
7559 | 8517 | ||
7560 | :term:`SYSROOT_DIRS_BLACKLIST` | 8518 | :term:`SYSROOT_DIRS_IGNORE` |
7561 | Directories that are not staged into the sysroot by the | 8519 | Directories that are not staged into the sysroot by the |
7562 | :ref:`ref-tasks-populate_sysroot` task. You | 8520 | :ref:`ref-tasks-populate_sysroot` task. You |
7563 | can use this variable to exclude certain subdirectories of | 8521 | can use this variable to exclude certain subdirectories of |
7564 | directories listed in :term:`SYSROOT_DIRS` from | 8522 | directories listed in :term:`SYSROOT_DIRS` from |
7565 | staging. By default, the following directories are not staged: | 8523 | staging. By default, the following directories are not staged:: |
7566 | :: | ||
7567 | 8524 | ||
7568 | SYSROOT_DIRS_BLACKLIST = " \ | 8525 | SYSROOT_DIRS_IGNORE = " \ |
7569 | ${mandir} \ | 8526 | ${mandir} \ |
7570 | ${docdir} \ | 8527 | ${docdir} \ |
7571 | ${infodir} \ | 8528 | ${infodir} \ |
7572 | ${datadir}/locale \ | 8529 | ${datadir}/X11/locale \ |
7573 | ${datadir}/applications \ | 8530 | ${datadir}/applications \ |
8531 | ${datadir}/bash-completion \ | ||
7574 | ${datadir}/fonts \ | 8532 | ${datadir}/fonts \ |
8533 | ${datadir}/gtk-doc/html \ | ||
8534 | ${datadir}/installed-tests \ | ||
8535 | ${datadir}/locale \ | ||
7575 | ${datadir}/pixmaps \ | 8536 | ${datadir}/pixmaps \ |
8537 | ${datadir}/terminfo \ | ||
8538 | ${libdir}/${BPN}/ptest \ | ||
7576 | " | 8539 | " |
7577 | 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 | |||
7578 | :term:`SYSROOT_DIRS_NATIVE` | 8570 | :term:`SYSROOT_DIRS_NATIVE` |
7579 | Extra directories staged into the sysroot by the | 8571 | Extra directories staged into the sysroot by the |
7580 | :ref:`ref-tasks-populate_sysroot` task for | 8572 | :ref:`ref-tasks-populate_sysroot` task for |
7581 | ``-native`` recipes, in addition to those specified in | 8573 | ``-native`` recipes, in addition to those specified in |
7582 | :term:`SYSROOT_DIRS`. By default, the following | 8574 | :term:`SYSROOT_DIRS`. By default, the following |
7583 | extra directories are staged: | 8575 | extra directories are staged:: |
7584 | :: | ||
7585 | 8576 | ||
7586 | SYSROOT_DIRS_NATIVE = " \ | 8577 | SYSROOT_DIRS_NATIVE = " \ |
7587 | ${bindir} \ | 8578 | ${bindir} \ |
@@ -7605,13 +8596,12 @@ system and gives an overview of their function and contents. | |||
7605 | processing on the staged files, or to stage additional files. | 8596 | processing on the staged files, or to stage additional files. |
7606 | 8597 | ||
7607 | :term:`SYSTEMD_AUTO_ENABLE` | 8598 | :term:`SYSTEMD_AUTO_ENABLE` |
7608 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8599 | When inheriting the :ref:`ref-classes-systemd` class, |
7609 | this variable specifies whether the specified service in | 8600 | this variable specifies whether the specified service in |
7610 | :term:`SYSTEMD_SERVICE` should start | 8601 | :term:`SYSTEMD_SERVICE` should start |
7611 | automatically or not. By default, the service is enabled to | 8602 | automatically or not. By default, the service is enabled to |
7612 | automatically start at boot time. The default setting is in the | 8603 | automatically start at boot time. The default setting is in the |
7613 | :ref:`systemd <ref-classes-systemd>` class as follows: | 8604 | :ref:`ref-classes-systemd` class as follows:: |
7614 | :: | ||
7615 | 8605 | ||
7616 | SYSTEMD_AUTO_ENABLE ??= "enable" | 8606 | SYSTEMD_AUTO_ENABLE ??= "enable" |
7617 | 8607 | ||
@@ -7619,25 +8609,22 @@ system and gives an overview of their function and contents. | |||
7619 | 8609 | ||
7620 | :term:`SYSTEMD_BOOT_CFG` | 8610 | :term:`SYSTEMD_BOOT_CFG` |
7621 | When :term:`EFI_PROVIDER` is set to | 8611 | When :term:`EFI_PROVIDER` is set to |
7622 | "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the | 8612 | "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the |
7623 | configuration file that should be used. By default, the | 8613 | configuration file that should be used. By default, the |
7624 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8614 | :ref:`ref-classes-systemd-boot` class sets the |
7625 | ``SYSTEMD_BOOT_CFG`` as follows: | 8615 | :term:`SYSTEMD_BOOT_CFG` as follows:: |
7626 | :: | ||
7627 | 8616 | ||
7628 | SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" | 8617 | SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" |
7629 | 8618 | ||
7630 | For information on Systemd-boot, see the `Systemd-boot | 8619 | For information on Systemd-boot, see the `Systemd-boot |
7631 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | 8620 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. |
7632 | 8621 | ||
7633 | :term:`SYSTEMD_BOOT_ENTRIES` | 8622 | :term:`SYSTEMD_BOOT_ENTRIES` |
7634 | When :term:`EFI_PROVIDER` is set to | 8623 | When :term:`EFI_PROVIDER` is set to |
7635 | "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a | 8624 | "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a |
7636 | list of entry files (``*.conf``) to install that contain one boot | 8625 | list of entry files (``*.conf``) to install that contain one boot |
7637 | entry per file. By default, the | 8626 | entry per file. By default, the :ref:`ref-classes-systemd-boot` class |
7638 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8627 | sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: |
7639 | ``SYSTEMD_BOOT_ENTRIES`` as follows: | ||
7640 | :: | ||
7641 | 8628 | ||
7642 | SYSTEMD_BOOT_ENTRIES ?= "" | 8629 | SYSTEMD_BOOT_ENTRIES ?= "" |
7643 | 8630 | ||
@@ -7646,58 +8633,75 @@ system and gives an overview of their function and contents. | |||
7646 | 8633 | ||
7647 | :term:`SYSTEMD_BOOT_TIMEOUT` | 8634 | :term:`SYSTEMD_BOOT_TIMEOUT` |
7648 | When :term:`EFI_PROVIDER` is set to | 8635 | When :term:`EFI_PROVIDER` is set to |
7649 | "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the | 8636 | "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the |
7650 | boot menu timeout in seconds. By default, the | 8637 | boot menu timeout in seconds. By default, the |
7651 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8638 | :ref:`ref-classes-systemd-boot` class sets the |
7652 | ``SYSTEMD_BOOT_TIMEOUT`` as follows: | 8639 | :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: |
7653 | :: | ||
7654 | 8640 | ||
7655 | SYSTEMD_BOOT_TIMEOUT ?= "10" | 8641 | SYSTEMD_BOOT_TIMEOUT ?= "10" |
7656 | 8642 | ||
7657 | For information on Systemd-boot, see the `Systemd-boot | 8643 | For information on Systemd-boot, see the `Systemd-boot |
7658 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | 8644 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. |
7659 | 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 | |||
7660 | :term:`SYSTEMD_PACKAGES` | 8663 | :term:`SYSTEMD_PACKAGES` |
7661 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8664 | When inheriting the :ref:`ref-classes-systemd` class, |
7662 | 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 |
7663 | in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` | 8666 | in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` |
7664 | 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 |
7665 | reside in the recipes main package: | 8668 | reside in the recipes main package:: |
7666 | :: | ||
7667 | 8669 | ||
7668 | SYSTEMD_PACKAGES ?= "${PN}" | 8670 | SYSTEMD_PACKAGES ?= "${PN}" |
7669 | 8671 | ||
7670 | 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 |
7671 | 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 |
7672 | the build system can find the systemd unit files. | 8674 | the build system can find the systemd unit files. |
7673 | 8675 | ||
7674 | :term:`SYSTEMD_SERVICE` | 8676 | :term:`SYSTEMD_SERVICE` |
7675 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8677 | When inheriting the :ref:`ref-classes-systemd` class, |
7676 | this variable specifies the systemd service name for a package. | 8678 | this variable specifies the systemd service name for a package. |
7677 | 8679 | ||
8680 | Multiple services can be specified, each one separated by a space. | ||
8681 | |||
7678 | 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 |
7679 | 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 |
7680 | an example from the connman recipe: | 8684 | an example from the connman recipe:: |
7681 | :: | 8685 | |
8686 | SYSTEMD_SERVICE:${PN} = "connman.service" | ||
7682 | 8687 | ||
7683 | 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. | ||
7684 | 8691 | ||
7685 | :term:`SYSVINIT_ENABLED_GETTYS` | 8692 | :term:`SYSVINIT_ENABLED_GETTYS` |
7686 | When using | 8693 | When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, |
7687 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | ||
7688 | specifies a space-separated list of the virtual terminals that should | 8694 | specifies a space-separated list of the virtual terminals that should |
7689 | run a `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ | 8695 | run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming |
7690 | (allowing login), assuming :term:`USE_VT` is not set to | 8696 | :term:`USE_VT` is not set to "0". |
7691 | "0". | ||
7692 | 8697 | ||
7693 | 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 |
7694 | run a getty on the first virtual terminal). | 8699 | run a getty on the first virtual terminal). |
7695 | 8700 | ||
7696 | :term:`T` | 8701 | :term:`T` |
7697 | This variable points to a directory were BitBake places temporary | 8702 | This variable points to a directory were BitBake places temporary |
7698 | 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 |
7699 | particular recipe. The variable is typically set as follows: | 8704 | particular recipe. The variable is typically set as follows:: |
7700 | :: | ||
7701 | 8705 | ||
7702 | T = "${WORKDIR}/temp" | 8706 | T = "${WORKDIR}/temp" |
7703 | 8707 | ||
@@ -7705,7 +8709,7 @@ system and gives an overview of their function and contents. | |||
7705 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` | 8709 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` |
7706 | file sets this variable. | 8710 | file sets this variable. |
7707 | 8711 | ||
7708 | The ``T`` variable is not to be confused with the | 8712 | The :term:`T` variable is not to be confused with the |
7709 | :term:`TMPDIR` variable, which points to the root of | 8713 | :term:`TMPDIR` variable, which points to the root of |
7710 | the directory tree where BitBake places the output of an entire | 8714 | the directory tree where BitBake places the output of an entire |
7711 | build. | 8715 | build. |
@@ -7729,29 +8733,28 @@ system and gives an overview of their function and contents. | |||
7729 | 8733 | ||
7730 | :term:`TARGET_AS_ARCH` | 8734 | :term:`TARGET_AS_ARCH` |
7731 | Specifies architecture-specific assembler flags for the target | 8735 | Specifies architecture-specific assembler flags for the target |
7732 | system. ``TARGET_AS_ARCH`` is initialized from | 8736 | system. :term:`TARGET_AS_ARCH` is initialized from |
7733 | :term:`TUNE_ASARGS` by default in the BitBake | 8737 | :term:`TUNE_ASARGS` by default in the BitBake |
7734 | configuration file (``meta/conf/bitbake.conf``): | 8738 | configuration file (``meta/conf/bitbake.conf``):: |
7735 | :: | ||
7736 | 8739 | ||
7737 | TARGET_AS_ARCH = "${TUNE_ASARGS}" | 8740 | TARGET_AS_ARCH = "${TUNE_ASARGS}" |
7738 | 8741 | ||
7739 | :term:`TARGET_CC_ARCH` | 8742 | :term:`TARGET_CC_ARCH` |
7740 | Specifies architecture-specific C compiler flags for the target | 8743 | Specifies architecture-specific C compiler flags for the target |
7741 | system. ``TARGET_CC_ARCH`` is initialized from | 8744 | system. :term:`TARGET_CC_ARCH` is initialized from |
7742 | :term:`TUNE_CCARGS` by default. | 8745 | :term:`TUNE_CCARGS` by default. |
7743 | 8746 | ||
7744 | .. note:: | 8747 | .. note:: |
7745 | 8748 | ||
7746 | It is a common workaround to append :term:`LDFLAGS` to | 8749 | It is a common workaround to append :term:`LDFLAGS` to |
7747 | ``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 |
7748 | would not otherwise respect the exported ``LDFLAGS`` variable. | 8751 | would not otherwise respect the exported :term:`LDFLAGS` variable. |
7749 | 8752 | ||
7750 | :term:`TARGET_CC_KERNEL_ARCH` | 8753 | :term:`TARGET_CC_KERNEL_ARCH` |
7751 | 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 |
7752 | 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 |
7753 | cases where a userspace :term:`TUNE_CCARGS` is not | 8756 | cases where a userspace :term:`TUNE_CCARGS` is not |
7754 | compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` | 8757 | compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` |
7755 | variable allows the kernel (and associated modules) to use a | 8758 | variable allows the kernel (and associated modules) to use a |
7756 | different configuration. See the | 8759 | different configuration. See the |
7757 | ``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 |
@@ -7763,8 +8766,8 @@ system and gives an overview of their function and contents. | |||
7763 | :term:`CFLAGS` is set to the value of this variable by | 8766 | :term:`CFLAGS` is set to the value of this variable by |
7764 | default. | 8767 | default. |
7765 | 8768 | ||
7766 | Additionally, the SDK's environment setup script sets the ``CFLAGS`` | 8769 | Additionally, the SDK's environment setup script sets the :term:`CFLAGS` |
7767 | variable in the environment to the ``TARGET_CFLAGS`` value so that | 8770 | variable in the environment to the :term:`TARGET_CFLAGS` value so that |
7768 | executables built using the SDK also have the flags applied. | 8771 | executables built using the SDK also have the flags applied. |
7769 | 8772 | ||
7770 | :term:`TARGET_CPPFLAGS` | 8773 | :term:`TARGET_CPPFLAGS` |
@@ -7774,7 +8777,7 @@ system and gives an overview of their function and contents. | |||
7774 | value of this variable by default. | 8777 | value of this variable by default. |
7775 | 8778 | ||
7776 | Additionally, the SDK's environment setup script sets the | 8779 | Additionally, the SDK's environment setup script sets the |
7777 | ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` | 8780 | :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` |
7778 | 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 |
7779 | applied. | 8782 | applied. |
7780 | 8783 | ||
@@ -7785,7 +8788,7 @@ system and gives an overview of their function and contents. | |||
7785 | by default. | 8788 | by default. |
7786 | 8789 | ||
7787 | Additionally, the SDK's environment setup script sets the | 8790 | Additionally, the SDK's environment setup script sets the |
7788 | ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` | 8791 | :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` |
7789 | 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 |
7790 | applied. | 8793 | applied. |
7791 | 8794 | ||
@@ -7797,10 +8800,9 @@ system and gives an overview of their function and contents. | |||
7797 | 8800 | ||
7798 | :term:`TARGET_LD_ARCH` | 8801 | :term:`TARGET_LD_ARCH` |
7799 | Specifies architecture-specific linker flags for the target system. | 8802 | Specifies architecture-specific linker flags for the target system. |
7800 | ``TARGET_LD_ARCH`` is initialized from | 8803 | :term:`TARGET_LD_ARCH` is initialized from |
7801 | :term:`TUNE_LDARGS` by default in the BitBake | 8804 | :term:`TUNE_LDARGS` by default in the BitBake |
7802 | configuration file (``meta/conf/bitbake.conf``): | 8805 | configuration file (``meta/conf/bitbake.conf``):: |
7803 | :: | ||
7804 | 8806 | ||
7805 | TARGET_LD_ARCH = "${TUNE_LDARGS}" | 8807 | TARGET_LD_ARCH = "${TUNE_LDARGS}" |
7806 | 8808 | ||
@@ -7812,29 +8814,29 @@ system and gives an overview of their function and contents. | |||
7812 | 8814 | ||
7813 | Additionally, the SDK's environment setup script sets the | 8815 | Additionally, the SDK's environment setup script sets the |
7814 | :term:`LDFLAGS` variable in the environment to the | 8816 | :term:`LDFLAGS` variable in the environment to the |
7815 | ``TARGET_LDFLAGS`` value so that executables built using the SDK also | 8817 | :term:`TARGET_LDFLAGS` value so that executables built using the SDK also |
7816 | have the flags applied. | 8818 | have the flags applied. |
7817 | 8819 | ||
7818 | :term:`TARGET_OS` | 8820 | :term:`TARGET_OS` |
7819 | 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 |
7820 | "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" |
7821 | for musl libc. For ARM/EABI targets, "linux-gnueabi" and | 8823 | for musl libc. For ARM/EABI targets, the possible values are |
7822 | "linux-musleabi" possible values exist. | 8824 | "linux-gnueabi" and "linux-musleabi". |
7823 | 8825 | ||
7824 | :term:`TARGET_PREFIX` | 8826 | :term:`TARGET_PREFIX` |
7825 | Specifies the prefix used for the toolchain binary target tools. | 8827 | Specifies the prefix used for the toolchain binary target tools. |
7826 | 8828 | ||
7827 | Depending on the type of recipe and the build target, | 8829 | Depending on the type of recipe and the build target, |
7828 | ``TARGET_PREFIX`` is set as follows: | 8830 | :term:`TARGET_PREFIX` is set as follows: |
7829 | 8831 | ||
7830 | - For recipes building for the target machine, the value is | 8832 | - For recipes building for the target machine, the value is |
7831 | "${:term:`TARGET_SYS`}-". | 8833 | "${:term:`TARGET_SYS`}-". |
7832 | 8834 | ||
7833 | - For native recipes, the build system sets the variable to the | 8835 | - For native recipes, the build system sets the variable to the |
7834 | value of ``BUILD_PREFIX``. | 8836 | value of :term:`BUILD_PREFIX`. |
7835 | 8837 | ||
7836 | - For native SDK recipes (``nativesdk``), the build system sets the | 8838 | - For native SDK recipes (:ref:`ref-classes-nativesdk`), |
7837 | variable to the value of ``SDK_PREFIX``. | 8839 | the build system sets the variable to the value of :term:`SDK_PREFIX`. |
7838 | 8840 | ||
7839 | :term:`TARGET_SYS` | 8841 | :term:`TARGET_SYS` |
7840 | Specifies the system, including the architecture and the operating | 8842 | Specifies the system, including the architecture and the operating |
@@ -7848,7 +8850,7 @@ system and gives an overview of their function and contents. | |||
7848 | 8850 | ||
7849 | .. note:: | 8851 | .. note:: |
7850 | 8852 | ||
7851 | You do not need to set the ``TARGET_SYS`` variable yourself. | 8853 | You do not need to set the :term:`TARGET_SYS` variable yourself. |
7852 | 8854 | ||
7853 | Consider these two examples: | 8855 | Consider these two examples: |
7854 | 8856 | ||
@@ -7863,27 +8865,25 @@ system and gives an overview of their function and contents. | |||
7863 | 8865 | ||
7864 | :term:`TCLIBC` | 8866 | :term:`TCLIBC` |
7865 | Specifies the GNU standard C library (``libc``) variant to use during | 8867 | Specifies the GNU standard C library (``libc``) variant to use during |
7866 | the build process. This variable replaces ``POKYLIBC``, which is no | 8868 | the build process. |
7867 | longer supported. | ||
7868 | 8869 | ||
7869 | You can select "glibc", "musl", "newlib", or "baremetal" | 8870 | You can select "glibc", "musl", "newlib", or "baremetal". |
7870 | 8871 | ||
7871 | :term:`TCLIBCAPPEND` | 8872 | :term:`TCLIBCAPPEND` |
7872 | Specifies a suffix to be appended onto the | 8873 | Specifies a suffix to be appended onto the :term:`TMPDIR` value. The |
7873 | :term:`TMPDIR` value. The suffix identifies the | 8874 | suffix identifies the ``libc`` variant for building. When you are |
7874 | ``libc`` variant for building. When you are building for multiple | 8875 | building for multiple variants with the same :term:`Build Directory`, |
7875 | variants with the same :term:`Build Directory`, this | 8876 | this mechanism ensures that output for different ``libc`` variants is |
7876 | mechanism ensures that output for different ``libc`` variants is kept | 8877 | kept separate to avoid potential conflicts. |
7877 | separate to avoid potential conflicts. | ||
7878 | 8878 | ||
7879 | In the ``defaultsetup.conf`` file, the default value of | 8879 | In the ``defaultsetup.conf`` file, the default value of |
7880 | ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, | 8880 | :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, |
7881 | which normally only support one ``libc`` variant, set | 8881 | which normally only support one ``libc`` variant, set |
7882 | ``TCLIBCAPPEND`` to "" in their distro configuration file resulting | 8882 | :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting |
7883 | in no suffix being applied. | 8883 | in no suffix being applied. |
7884 | 8884 | ||
7885 | :term:`TCMODE` | 8885 | :term:`TCMODE` |
7886 | Specifies the toolchain selector. ``TCMODE`` controls the | 8886 | Specifies the toolchain selector. :term:`TCMODE` controls the |
7887 | characteristics of the generated packages and images by telling the | 8887 | characteristics of the generated packages and images by telling the |
7888 | OpenEmbedded build system which toolchain profile to use. By default, | 8888 | OpenEmbedded build system which toolchain profile to use. By default, |
7889 | the OpenEmbedded build system builds its own internal toolchain. The | 8889 | the OpenEmbedded build system builds its own internal toolchain. The |
@@ -7892,17 +8892,15 @@ system and gives an overview of their function and contents. | |||
7892 | 8892 | ||
7893 | .. note:: | 8893 | .. note:: |
7894 | 8894 | ||
7895 | 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 |
7896 | responsibility to ensure that the toolchain is compatible with the | 8896 | responsibility to ensure that the toolchain is compatible with the |
7897 | default toolchain. Using older or newer versions of these | 8897 | default toolchain. Using older or newer versions of these |
7898 | components might cause build problems. See the Release Notes for | 8898 | components might cause build problems. See |
7899 | the Yocto Project release for the specific components with which | 8899 | :doc:`Release Information </migration-guides/index>` for your |
7900 | the toolchain must be compatible. To access the Release Notes, go | 8900 | version of the Yocto Project, to find the specific components with |
7901 | to the :yocto_home:`Downloads </software-overview/downloads>` | 8901 | which the toolchain must be compatible. |
7902 | page on the Yocto Project website and click on the "RELEASE | 8902 | |
7903 | INFORMATION" link for the appropriate release. | 8903 | The :term:`TCMODE` variable is similar to :term:`TCLIBC`, |
7904 | |||
7905 | The ``TCMODE`` variable is similar to :term:`TCLIBC`, | ||
7906 | which controls the variant of the GNU standard C library (``libc``) | 8904 | which controls the variant of the GNU standard C library (``libc``) |
7907 | used during the build process: ``glibc`` or ``musl``. | 8905 | used during the build process: ``glibc`` or ``musl``. |
7908 | 8906 | ||
@@ -7913,22 +8911,47 @@ system and gives an overview of their function and contents. | |||
7913 | https://github.com/MentorEmbedded/meta-sourcery/. | 8911 | https://github.com/MentorEmbedded/meta-sourcery/. |
7914 | 8912 | ||
7915 | 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 |
7916 | Sourcery G++ Toolchain as an external toolchain. In summary, you must | 8914 | Sourcery G++ Toolchain as an external toolchain. You will have to |
7917 | 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 |
7918 | the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable | 8916 | :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to |
7919 | in your ``local.conf`` file to the location in which you installed | 8917 | the location of the toolchain. |
7920 | the toolchain. | ||
7921 | 8918 | ||
7922 | The fundamentals used for this example apply to any external | 8919 | The fundamentals used for this example apply to any external |
7923 | toolchain. You can use ``meta-sourcery`` as a template for adding | 8920 | toolchain. You can use ``meta-sourcery`` as a template for adding |
7924 | support for other external toolchains. | 8921 | support for other external toolchains. |
7925 | 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 | |||
7926 | :term:`TEST_EXPORT_DIR` | 8949 | :term:`TEST_EXPORT_DIR` |
7927 | The location the OpenEmbedded build system uses to export tests when | 8950 | The location the OpenEmbedded build system uses to export tests when |
7928 | the :term:`TEST_EXPORT_ONLY` variable is set | 8951 | the :term:`TEST_EXPORT_ONLY` variable is set |
7929 | to "1". | 8952 | to "1". |
7930 | 8953 | ||
7931 | The ``TEST_EXPORT_DIR`` variable defaults to | 8954 | The :term:`TEST_EXPORT_DIR` variable defaults to |
7932 | ``"${TMPDIR}/testimage/${PN}"``. | 8955 | ``"${TMPDIR}/testimage/${PN}"``. |
7933 | 8956 | ||
7934 | :term:`TEST_EXPORT_ONLY` | 8957 | :term:`TEST_EXPORT_ONLY` |
@@ -7938,7 +8961,7 @@ system and gives an overview of their function and contents. | |||
7938 | 8961 | ||
7939 | :term:`TEST_LOG_DIR` | 8962 | :term:`TEST_LOG_DIR` |
7940 | 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 |
7941 | ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. | 8964 | :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. |
7942 | 8965 | ||
7943 | .. note:: | 8966 | .. note:: |
7944 | 8967 | ||
@@ -7958,7 +8981,7 @@ system and gives an overview of their function and contents. | |||
7958 | For automated hardware testing, specifies additional arguments to | 8981 | For automated hardware testing, specifies additional arguments to |
7959 | pass through to the command specified in | 8982 | pass through to the command specified in |
7960 | :term:`TEST_POWERCONTROL_CMD`. Setting | 8983 | :term:`TEST_POWERCONTROL_CMD`. Setting |
7961 | ``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 |
7962 | wish, for example, to separate the machine-specific and | 8985 | wish, for example, to separate the machine-specific and |
7963 | non-machine-specific parts of the arguments. | 8986 | non-machine-specific parts of the arguments. |
7964 | 8987 | ||
@@ -7970,7 +8993,7 @@ system and gives an overview of their function and contents. | |||
7970 | file. | 8993 | file. |
7971 | 8994 | ||
7972 | For more information on testing images, see the | 8995 | For more information on testing images, see the |
7973 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 8996 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
7974 | section in the Yocto Project Development Tasks Manual. | 8997 | section in the Yocto Project Development Tasks Manual. |
7975 | 8998 | ||
7976 | :term:`TEST_SERIALCONTROL_CMD` | 8999 | :term:`TEST_SERIALCONTROL_CMD` |
@@ -7981,8 +9004,7 @@ system and gives an overview of their function and contents. | |||
7981 | program does. | 9004 | program does. |
7982 | 9005 | ||
7983 | For example, to use the Picocom terminal program on serial device | 9006 | For example, to use the Picocom terminal program on serial device |
7984 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: | 9007 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: |
7985 | :: | ||
7986 | 9008 | ||
7987 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | 9009 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" |
7988 | 9010 | ||
@@ -7990,7 +9012,7 @@ system and gives an overview of their function and contents. | |||
7990 | For automated hardware testing, specifies additional arguments to | 9012 | For automated hardware testing, specifies additional arguments to |
7991 | pass through to the command specified in | 9013 | pass through to the command specified in |
7992 | :term:`TEST_SERIALCONTROL_CMD`. Setting | 9014 | :term:`TEST_SERIALCONTROL_CMD`. Setting |
7993 | ``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 |
7994 | wish, for example, to separate the machine-specific and | 9016 | wish, for example, to separate the machine-specific and |
7995 | non-machine-specific parts of the command. | 9017 | non-machine-specific parts of the command. |
7996 | 9018 | ||
@@ -8002,7 +9024,7 @@ system and gives an overview of their function and contents. | |||
8002 | 9024 | ||
8003 | .. note:: | 9025 | .. note:: |
8004 | 9026 | ||
8005 | 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 |
8006 | 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 |
8007 | from ``WORKDIR/oe-rootfs-repo``. | 9029 | from ``WORKDIR/oe-rootfs-repo``. |
8008 | 9030 | ||
@@ -8019,18 +9041,16 @@ system and gives an overview of their function and contents. | |||
8019 | QEMU. | 9041 | QEMU. |
8020 | 9042 | ||
8021 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add | 9043 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add |
8022 | 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 |
8023 | follows: | 9045 | follows:: |
8024 | :: | ||
8025 | 9046 | ||
8026 | TEST_SUITES_append = " mytest" | 9047 | TEST_SUITES:append = " mytest" |
8027 | 9048 | ||
8028 | Alternatively, you can | 9049 | Alternatively, you can |
8029 | provide the "auto" option to have all applicable tests run against | 9050 | provide the "auto" option to have all applicable tests run against |
8030 | the image. | 9051 | the image:: |
8031 | :: | ||
8032 | 9052 | ||
8033 | TEST_SUITES_append = " auto" | 9053 | TEST_SUITES:append = " auto" |
8034 | 9054 | ||
8035 | Using this option causes the | 9055 | Using this option causes the |
8036 | build system to automatically run tests that are applicable to the | 9056 | build system to automatically run tests that are applicable to the |
@@ -8040,19 +9060,17 @@ system and gives an overview of their function and contents. | |||
8040 | 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 |
8041 | 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 |
8042 | 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 |
8043 | ``test_A``, then you must order the tests as follows: | 9063 | ``test_A``, then you must order the tests as follows:: |
8044 | :: | ||
8045 | 9064 | ||
8046 | TEST_SUITES = "test_A test_B" | 9065 | TEST_SUITES = "test_A test_B" |
8047 | 9066 | ||
8048 | For more information on testing images, see the | 9067 | For more information on testing images, see the |
8049 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 9068 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
8050 | section in the Yocto Project Development Tasks Manual. | 9069 | section in the Yocto Project Development Tasks Manual. |
8051 | 9070 | ||
8052 | :term:`TEST_TARGET` | 9071 | :term:`TEST_TARGET` |
8053 | Specifies the target controller to use when running tests against a | 9072 | Specifies the target controller to use when running tests against a |
8054 | test image. The default controller to use is "qemu": | 9073 | test image. The default controller to use is "qemu":: |
8055 | :: | ||
8056 | 9074 | ||
8057 | TEST_TARGET = "qemu" | 9075 | TEST_TARGET = "qemu" |
8058 | 9076 | ||
@@ -8061,12 +9079,12 @@ system and gives an overview of their function and contents. | |||
8061 | the controllers by adding a module in the layer's | 9079 | the controllers by adding a module in the layer's |
8062 | ``/lib/oeqa/controllers`` directory and by inheriting the | 9080 | ``/lib/oeqa/controllers`` directory and by inheriting the |
8063 | ``BaseTarget`` class, which is an abstract class that cannot be used | 9081 | ``BaseTarget`` class, which is an abstract class that cannot be used |
8064 | as a value of ``TEST_TARGET``. | 9082 | as a value of :term:`TEST_TARGET`. |
8065 | 9083 | ||
8066 | You can provide the following arguments with ``TEST_TARGET``: | 9084 | You can provide the following arguments with :term:`TEST_TARGET`: |
8067 | 9085 | ||
8068 | - *"qemu":* Boots a QEMU image and runs the tests. See the | 9086 | - *"qemu":* Boots a QEMU image and runs the tests. See the |
8069 | ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section | 9087 | ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section |
8070 | in the Yocto Project Development Tasks Manual for more | 9088 | in the Yocto Project Development Tasks Manual for more |
8071 | information. | 9089 | information. |
8072 | 9090 | ||
@@ -8082,17 +9100,16 @@ system and gives an overview of their function and contents. | |||
8082 | ``meta/lib/oeqa/controllers/simpleremote.py``. | 9100 | ``meta/lib/oeqa/controllers/simpleremote.py``. |
8083 | 9101 | ||
8084 | For information on running tests on hardware, see the | 9102 | For information on running tests on hardware, see the |
8085 | ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`" | 9103 | ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`" |
8086 | section in the Yocto Project Development Tasks Manual. | 9104 | section in the Yocto Project Development Tasks Manual. |
8087 | 9105 | ||
8088 | :term:`TEST_TARGET_IP` | 9106 | :term:`TEST_TARGET_IP` |
8089 | 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` |
8090 | variable has no effect when :term:`TEST_TARGET` is | 9108 | variable has no effect when :term:`TEST_TARGET` is |
8091 | set to "qemu". | 9109 | set to "qemu". |
8092 | 9110 | ||
8093 | 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 |
8094 | an example: | 9112 | an example:: |
8095 | :: | ||
8096 | 9113 | ||
8097 | TEST_TARGET_IP = "192.168.1.4:2201" | 9114 | TEST_TARGET_IP = "192.168.1.4:2201" |
8098 | 9115 | ||
@@ -8104,7 +9121,7 @@ system and gives an overview of their function and contents. | |||
8104 | 9121 | ||
8105 | :term:`TESTIMAGE_AUTO` | 9122 | :term:`TESTIMAGE_AUTO` |
8106 | Automatically runs the series of automated tests for images when an | 9123 | Automatically runs the series of automated tests for images when an |
8107 | image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes | 9124 | image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes |
8108 | any image that successfully builds to automatically boot under QEMU. | 9125 | any image that successfully builds to automatically boot under QEMU. |
8109 | 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 |
8110 | which testing is requested is automatically built first. | 9127 | which testing is requested is automatically built first. |
@@ -8120,9 +9137,9 @@ system and gives an overview of their function and contents. | |||
8120 | 9137 | ||
8121 | For more information | 9138 | For more information |
8122 | on enabling, running, and writing these tests, see the | 9139 | on enabling, running, and writing these tests, see the |
8123 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 9140 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
8124 | section in the Yocto Project Development Tasks Manual and the | 9141 | section in the Yocto Project Development Tasks Manual and the |
8125 | ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. | 9142 | ":ref:`ref-classes-testimage`" section. |
8126 | 9143 | ||
8127 | :term:`THISDIR` | 9144 | :term:`THISDIR` |
8128 | The directory in which the file BitBake is currently parsing is | 9145 | The directory in which the file BitBake is currently parsing is |
@@ -8136,24 +9153,23 @@ system and gives an overview of their function and contents. | |||
8136 | :term:`TMPDIR` | 9153 | :term:`TMPDIR` |
8137 | This variable is the base directory the OpenEmbedded build system | 9154 | This variable is the base directory the OpenEmbedded build system |
8138 | uses for all build output and intermediate files (other than the | 9155 | uses for all build output and intermediate files (other than the |
8139 | shared state cache). By default, the ``TMPDIR`` variable points to | 9156 | shared state cache). By default, the :term:`TMPDIR` variable points to |
8140 | ``tmp`` within the :term:`Build Directory`. | 9157 | ``tmp`` within the :term:`Build Directory`. |
8141 | 9158 | ||
8142 | 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 |
8143 | default, you can uncomment and edit the following statement in the | 9160 | default, you can uncomment and edit the following statement in the |
8144 | ``conf/local.conf`` file in the :term:`Source Directory`: | 9161 | ``conf/local.conf`` file in the :term:`Source Directory`:: |
8145 | :: | ||
8146 | 9162 | ||
8147 | #TMPDIR = "${TOPDIR}/tmp" | 9163 | #TMPDIR = "${TOPDIR}/tmp" |
8148 | 9164 | ||
8149 | 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, |
8150 | 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. |
8151 | 9167 | ||
8152 | The filesystem used by ``TMPDIR`` must have standard filesystem | 9168 | The filesystem used by :term:`TMPDIR` must have standard filesystem |
8153 | 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 |
8154 | 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 |
8155 | implementations, NFS does not meet this minimum requirement. | 9171 | implementations, NFS does not meet this minimum requirement. |
8156 | Consequently, ``TMPDIR`` cannot be on NFS. | 9172 | Consequently, :term:`TMPDIR` cannot be on NFS. |
8157 | 9173 | ||
8158 | :term:`TOOLCHAIN_HOST_TASK` | 9174 | :term:`TOOLCHAIN_HOST_TASK` |
8159 | This variable lists packages the OpenEmbedded build system uses when | 9175 | This variable lists packages the OpenEmbedded build system uses when |
@@ -8161,8 +9177,7 @@ system and gives an overview of their function and contents. | |||
8161 | packages specified by this variable are part of the toolchain set | 9177 | packages specified by this variable are part of the toolchain set |
8162 | that runs on the :term:`SDKMACHINE`, and each | 9178 | that runs on the :term:`SDKMACHINE`, and each |
8163 | package should usually have the prefix ``nativesdk-``. For example, | 9179 | package should usually have the prefix ``nativesdk-``. For example, |
8164 | consider the following command when building an SDK: | 9180 | consider the following command when building an SDK:: |
8165 | :: | ||
8166 | 9181 | ||
8167 | $ bitbake -c populate_sdk imagename | 9182 | $ bitbake -c populate_sdk imagename |
8168 | 9183 | ||
@@ -8180,11 +9195,29 @@ system and gives an overview of their function and contents. | |||
8180 | information on setting up a cross-development environment, see the | 9195 | information on setting up a cross-development environment, see the |
8181 | :doc:`/sdk-manual/index` manual. | 9196 | :doc:`/sdk-manual/index` manual. |
8182 | 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 | |||
8183 | :term:`TOOLCHAIN_OUTPUTNAME` | 9217 | :term:`TOOLCHAIN_OUTPUTNAME` |
8184 | This variable defines the name used for the toolchain output. The | 9218 | This variable defines the name used for the toolchain output. The |
8185 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets | 9219 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets |
8186 | the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: | 9220 | the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: |
8187 | :: | ||
8188 | 9221 | ||
8189 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" | 9222 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" |
8190 | 9223 | ||
@@ -8211,16 +9244,14 @@ system and gives an overview of their function and contents. | |||
8211 | :doc:`/sdk-manual/index` manual. | 9244 | :doc:`/sdk-manual/index` manual. |
8212 | 9245 | ||
8213 | :term:`TOPDIR` | 9246 | :term:`TOPDIR` |
8214 | The top-level :term:`Build Directory`. BitBake | 9247 | See :term:`bitbake:TOPDIR` in the BitBake manual. |
8215 | automatically sets this variable when you initialize your build | ||
8216 | environment using :ref:`structure-core-script`. | ||
8217 | 9248 | ||
8218 | :term:`TRANSLATED_TARGET_ARCH` | 9249 | :term:`TRANSLATED_TARGET_ARCH` |
8219 | A sanitized version of :term:`TARGET_ARCH`. This | 9250 | A sanitized version of :term:`TARGET_ARCH`. This |
8220 | 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 |
8221 | underscores are not allowed, for example within package filenames. In | 9252 | underscores are not allowed, for example within package filenames. In |
8222 | this case, dash characters replace any underscore characters used in | 9253 | this case, dash characters replace any underscore characters used in |
8223 | ``TARGET_ARCH``. | 9254 | :term:`TARGET_ARCH`. |
8224 | 9255 | ||
8225 | Do not edit this variable. | 9256 | Do not edit this variable. |
8226 | 9257 | ||
@@ -8229,19 +9260,18 @@ system and gives an overview of their function and contents. | |||
8229 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses | 9260 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses |
8230 | this value to setup configuration. | 9261 | this value to setup configuration. |
8231 | 9262 | ||
8232 | ``TUNE_ARCH`` definitions are specific to a given architecture. The | 9263 | :term:`TUNE_ARCH` definitions are specific to a given architecture. The |
8233 | definitions can be a single static definition, or can be dynamically | 9264 | definitions can be a single static definition, or can be dynamically |
8234 | 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 |
8235 | the architecture's ``README`` file. For example, the | 9266 | the architecture's ``README`` file. For example, the |
8236 | ``meta/conf/machine/include/mips/README`` file in the | 9267 | ``meta/conf/machine/include/mips/README`` file in the |
8237 | :term:`Source Directory` provides information for | 9268 | :term:`Source Directory` provides information for |
8238 | ``TUNE_ARCH`` specific to the ``mips`` architecture. | 9269 | :term:`TUNE_ARCH` specific to the ``mips`` architecture. |
8239 | 9270 | ||
8240 | ``TUNE_ARCH`` is tied closely to | 9271 | :term:`TUNE_ARCH` is tied closely to |
8241 | :term:`TARGET_ARCH`, which defines the target | 9272 | :term:`TARGET_ARCH`, which defines the target |
8242 | machine's architecture. The BitBake configuration file | 9273 | machine's architecture. The BitBake configuration file |
8243 | (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: | 9274 | (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: |
8244 | :: | ||
8245 | 9275 | ||
8246 | TARGET_ARCH = "${TUNE_ARCH}" | 9276 | TARGET_ARCH = "${TUNE_ARCH}" |
8247 | 9277 | ||
@@ -8259,12 +9289,11 @@ system and gives an overview of their function and contents. | |||
8259 | :term:`TUNE_ASARGS` | 9289 | :term:`TUNE_ASARGS` |
8260 | Specifies architecture-specific assembler flags for the target | 9290 | Specifies architecture-specific assembler flags for the target |
8261 | 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. |
8262 | ``TUNE_ASARGS`` is set using the tune include files, which are | 9292 | :term:`TUNE_ASARGS` is set using the tune include files, which are |
8263 | typically under ``meta/conf/machine/include/`` and are influenced | 9293 | typically under ``meta/conf/machine/include/`` and are influenced |
8264 | through :term:`TUNE_FEATURES`. For example, the | 9294 | through :term:`TUNE_FEATURES`. For example, the |
8265 | ``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 |
8266 | for the x86 architecture as follows: | 9296 | for the x86 architecture as follows:: |
8267 | :: | ||
8268 | 9297 | ||
8269 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" | 9298 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" |
8270 | 9299 | ||
@@ -8277,7 +9306,7 @@ system and gives an overview of their function and contents. | |||
8277 | :term:`TUNE_CCARGS` | 9306 | :term:`TUNE_CCARGS` |
8278 | Specifies architecture-specific C compiler flags for the target | 9307 | Specifies architecture-specific C compiler flags for the target |
8279 | 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. |
8280 | ``TUNE_CCARGS`` is set using the tune include files, which are | 9309 | :term:`TUNE_CCARGS` is set using the tune include files, which are |
8281 | typically under ``meta/conf/machine/include/`` and are influenced | 9310 | typically under ``meta/conf/machine/include/`` and are influenced |
8282 | through :term:`TUNE_FEATURES`. | 9311 | through :term:`TUNE_FEATURES`. |
8283 | 9312 | ||
@@ -8297,22 +9326,20 @@ system and gives an overview of their function and contents. | |||
8297 | are not conflicting and that they are supported. | 9326 | are not conflicting and that they are supported. |
8298 | 9327 | ||
8299 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines | 9328 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines |
8300 | ``TUNE_FEATURES`` as follows: | 9329 | :term:`TUNE_FEATURES` as follows:: |
8301 | :: | ||
8302 | 9330 | ||
8303 | TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" | 9331 | TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}" |
8304 | 9332 | ||
8305 | See the :term:`DEFAULTTUNE` variable for more information. | 9333 | See the :term:`DEFAULTTUNE` variable for more information. |
8306 | 9334 | ||
8307 | :term:`TUNE_LDARGS` | 9335 | :term:`TUNE_LDARGS` |
8308 | Specifies architecture-specific linker flags for the target system. | 9336 | Specifies architecture-specific linker flags for the target system. |
8309 | The set of flags is based on the selected tune features. | 9337 | The set of flags is based on the selected tune features. |
8310 | ``TUNE_LDARGS`` is set using the tune include files, which are | 9338 | :term:`TUNE_LDARGS` is set using the tune include files, which are |
8311 | typically under ``meta/conf/machine/include/`` and are influenced | 9339 | typically under ``meta/conf/machine/include/`` and are influenced |
8312 | through :term:`TUNE_FEATURES`. For example, the | 9340 | through :term:`TUNE_FEATURES`. For example, the |
8313 | ``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 |
8314 | for the x86 architecture as follows: | 9342 | for the x86 architecture as follows:: |
8315 | :: | ||
8316 | 9343 | ||
8317 | 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)}" |
8318 | 9345 | ||
@@ -8325,51 +9352,15 @@ system and gives an overview of their function and contents. | |||
8325 | :term:`TUNE_PKGARCH` | 9352 | :term:`TUNE_PKGARCH` |
8326 | The package architecture understood by the packaging system to define | 9353 | The package architecture understood by the packaging system to define |
8327 | the architecture, ABI, and tuning of output packages. The specific | 9354 | the architecture, ABI, and tuning of output packages. The specific |
8328 | tune is defined using the "_tune" override as follows: | 9355 | tune is defined using the "_tune" override as follows:: |
8329 | :: | ||
8330 | 9356 | ||
8331 | TUNE_PKGARCH_tune-tune = "tune" | 9357 | TUNE_PKGARCH:tune-tune = "tune" |
8332 | 9358 | ||
8333 | These tune-specific package architectures are defined in the machine | 9359 | These tune-specific package architectures are defined in the machine |
8334 | 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 |
8335 | the ``meta/conf/machine/include/tune-core2.inc`` file: | 9361 | the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: |
8336 | :: | 9362 | |
8337 | 9363 | TUNE_PKGARCH:tune-core2-32 = "core2-32" | |
8338 | TUNE_PKGARCH_tune-core2-32 = "core2-32" | ||
8339 | |||
8340 | :term:`TUNEABI` | ||
8341 | An underlying Application Binary Interface (ABI) used by a particular | ||
8342 | tuning in a given toolchain layer. Providers that use prebuilt | ||
8343 | libraries can use the ``TUNEABI``, | ||
8344 | :term:`TUNEABI_OVERRIDE`, and | ||
8345 | :term:`TUNEABI_WHITELIST` variables to check | ||
8346 | compatibility of tunings against their selection of libraries. | ||
8347 | |||
8348 | If ``TUNEABI`` is undefined, then every tuning is allowed. See the | ||
8349 | :ref:`sanity <ref-classes-sanity>` class to see how the variable is | ||
8350 | used. | ||
8351 | |||
8352 | :term:`TUNEABI_OVERRIDE` | ||
8353 | If set, the OpenEmbedded system ignores the | ||
8354 | :term:`TUNEABI_WHITELIST` variable. | ||
8355 | Providers that use prebuilt libraries can use the | ||
8356 | ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and | ||
8357 | :term:`TUNEABI` variables to check compatibility of a | ||
8358 | tuning against their selection of libraries. | ||
8359 | |||
8360 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8361 | variable is used. | ||
8362 | |||
8363 | :term:`TUNEABI_WHITELIST` | ||
8364 | A whitelist of permissible :term:`TUNEABI` values. If | ||
8365 | ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers | ||
8366 | that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, | ||
8367 | :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` | ||
8368 | variables to check compatibility of a tuning against their selection | ||
8369 | of libraries. | ||
8370 | |||
8371 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8372 | variable is used. | ||
8373 | 9364 | ||
8374 | :term:`TUNECONFLICTS[feature]` | 9365 | :term:`TUNECONFLICTS[feature]` |
8375 | Specifies CPU or Application Binary Interface (ABI) tuning features | 9366 | Specifies CPU or Application Binary Interface (ABI) tuning features |
@@ -8379,8 +9370,7 @@ system and gives an overview of their function and contents. | |||
8379 | the :term:`Source Directory`. Here is an example from | 9370 | the :term:`Source Directory`. Here is an example from |
8380 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file | 9371 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file |
8381 | 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" |
8382 | feature: | 9373 | feature:: |
8383 | :: | ||
8384 | 9374 | ||
8385 | TUNECONFLICTS[n32] = "o32 n64" | 9375 | TUNECONFLICTS[n32] = "o32 n64" |
8386 | 9376 | ||
@@ -8389,65 +9379,164 @@ system and gives an overview of their function and contents. | |||
8389 | feature. The specified feature is stored as a flag. Valid features | 9379 | feature. The specified feature is stored as a flag. Valid features |
8390 | are specified in the machine include files (e.g. | 9380 | are specified in the machine include files (e.g. |
8391 | ``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 |
8392 | from that file: | 9382 | from that file:: |
8393 | :: | ||
8394 | 9383 | ||
8395 | TUNEVALID[bigendian] = "Enable big-endian mode." | 9384 | TUNEVALID[bigendian] = "Enable big-endian mode." |
8396 | 9385 | ||
8397 | See the machine include files in the :term:`Source Directory` | 9386 | See the machine include files in the :term:`Source Directory` |
8398 | for these features. | 9387 | for these features. |
8399 | 9388 | ||
8400 | :term:`UBOOT_CONFIG` | 9389 | :term:`UBOOT_BINARY` |
8401 | Configures the :term:`UBOOT_MACHINE` and can | 9390 | Specifies the name of the binary build by U-Boot. |
8402 | also define :term:`IMAGE_FSTYPES` for individual | ||
8403 | cases. | ||
8404 | |||
8405 | Following is an example from the ``meta-fsl-arm`` layer. :: | ||
8406 | 9391 | ||
8407 | UBOOT_CONFIG ??= "sd" | 9392 | :term:`UBOOT_CONFIG` |
8408 | UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" | 9393 | Configures one or more U-Boot configurations to build. Each |
8409 | UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" | 9394 | configuration can define the :term:`UBOOT_MACHINE` and optionally the |
8410 | UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" | 9395 | :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`. |
8411 | UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" | 9396 | |
8412 | 9397 | Here is an example from the ``meta-freescale`` layer. :: | |
8413 | In this example, "sd" is selected as the configuration of the possible four for the | 9398 | |
8414 | ``UBOOT_MACHINE``. The "sd" configuration defines | 9399 | UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" |
8415 | "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the | 9400 | UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig" |
8416 | "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" |
8417 | 9402 | UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin" | |
8418 | For more information on how the ``UBOOT_CONFIG`` is handled, see the | 9403 | UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig" |
8419 | :ref:`uboot-config <ref-classes-uboot-config>` | 9404 | UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig" |
8420 | 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. | ||
8421 | 9416 | ||
8422 | :term:`UBOOT_DTB_LOADADDRESS` | 9417 | :term:`UBOOT_DTB_LOADADDRESS` |
8423 | 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 |
8424 | image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in | 9419 | image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in |
8425 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify | 9420 | :ref:`ref-classes-kernel-fitimage` class to specify the load address to be |
8426 | the load address to be used in | 9421 | used in creating the dtb sections of Image Tree Source for the FIT image. |
8427 | creating the dtb sections of Image Tree Source for the FIT image. | ||
8428 | 9422 | ||
8429 | :term:`UBOOT_DTBO_LOADADDRESS` | 9423 | :term:`UBOOT_DTBO_LOADADDRESS` |
8430 | 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 |
8431 | image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in | 9425 | image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in |
8432 | :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 |
8433 | 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. |
8434 | 9428 | ||
8435 | :term:`UBOOT_ENTRYPOINT` | 9429 | :term:`UBOOT_ENTRYPOINT` |
8436 | 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 |
8437 | creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a | 9431 | creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a |
8438 | command-line parameter to the ``uboot-mkimage`` utility. | 9432 | command-line parameter to the ``uboot-mkimage`` utility. |
8439 | 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 | |||
8440 | :term:`UBOOT_LOADADDRESS` | 9520 | :term:`UBOOT_LOADADDRESS` |
8441 | 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 |
8442 | creation, the ``UBOOT_LOADADDRESS`` variable is passed as a | 9522 | creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a |
8443 | command-line parameter to the ``uboot-mkimage`` utility. | 9523 | command-line parameter to the ``uboot-mkimage`` utility. |
8444 | 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 | |||
8445 | :term:`UBOOT_LOCALVERSION` | 9535 | :term:`UBOOT_LOCALVERSION` |
8446 | 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 |
8447 | 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 |
8448 | 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 |
8449 | "2013.10-yocto" given the following statement: | 9539 | "2013.10-yocto" given the following statement:: |
8450 | :: | ||
8451 | 9540 | ||
8452 | UBOOT_LOCALVERSION = "-yocto" | 9541 | UBOOT_LOCALVERSION = "-yocto" |
8453 | 9542 | ||
@@ -8466,56 +9555,65 @@ system and gives an overview of their function and contents. | |||
8466 | 9555 | ||
8467 | :term:`UBOOT_MKIMAGE` | 9556 | :term:`UBOOT_MKIMAGE` |
8468 | Specifies the name of the mkimage command as used by the | 9557 | Specifies the name of the mkimage command as used by the |
8469 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble | 9558 | :ref:`ref-classes-kernel-fitimage` class to assemble |
8470 | 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 |
8471 | script or function if desired. The default is "uboot-mkimage". | 9560 | script or function if desired. The default is "uboot-mkimage". |
8472 | 9561 | ||
8473 | :term:`UBOOT_MKIMAGE_DTCOPTS` | 9562 | :term:`UBOOT_MKIMAGE_DTCOPTS` |
8474 | Options for the device tree compiler passed to mkimage '-D' | 9563 | Options for the device tree compiler passed to ``mkimage -D`` feature |
8475 | 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` |
8476 | If ``UBOOT_MKIMAGE_DTCOPTS`` is not set then kernel-fitimage will not | 9565 | class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the |
8477 | 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". | ||
8478 | 9574 | ||
8479 | :term:`UBOOT_MKIMAGE_SIGN` | 9575 | :term:`UBOOT_MKIMAGE_SIGN` |
8480 | Specifies the name of the mkimage command as used by the | 9576 | Specifies the name of the mkimage command as used by the |
8481 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign | 9577 | :ref:`ref-classes-kernel-fitimage` class to sign |
8482 | 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 |
8483 | to substitute an alternative command, wrapper script or function if | 9579 | to substitute an alternative command, wrapper script or function if |
8484 | desired. The default is "${:term:`UBOOT_MKIMAGE`}". | 9580 | desired. The default is "${:term:`UBOOT_MKIMAGE`}". |
8485 | 9581 | ||
8486 | :term:`UBOOT_MKIMAGE_SIGN_ARGS` | 9582 | :term:`UBOOT_MKIMAGE_SIGN_ARGS` |
8487 | Optionally specifies additional arguments for the | 9583 | Optionally specifies additional arguments for the |
8488 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the | 9584 | :ref:`ref-classes-kernel-fitimage` class to pass to the |
8489 | mkimage command when signing the FIT image. | 9585 | mkimage command when signing the FIT image. |
8490 | 9586 | ||
8491 | :term:`UBOOT_RD_ENTRYPOINT` | 9587 | :term:`UBOOT_RD_ENTRYPOINT` |
8492 | Specifies the entrypoint for the RAM disk image. | 9588 | Specifies the entrypoint for the RAM disk image. During FIT image |
8493 | During FIT image creation, the | 9589 | creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in |
8494 | ``UBOOT_RD_ENTRYPOINT`` variable is used | 9590 | :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be |
8495 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | 9591 | used in creating the Image Tree Source for the FIT image. |
8496 | entrypoint to be used in creating the Image Tree Source for | ||
8497 | the FIT image. | ||
8498 | 9592 | ||
8499 | :term:`UBOOT_RD_LOADADDRESS` | 9593 | :term:`UBOOT_RD_LOADADDRESS` |
8500 | Specifies the load address for the RAM disk image. | 9594 | Specifies the load address for the RAM disk image. During FIT image |
8501 | During FIT image creation, the | 9595 | creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in |
8502 | ``UBOOT_RD_LOADADDRESS`` variable is used | 9596 | :ref:`ref-classes-kernel-fitimage` class to specify the load address to |
8503 | 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. |
8504 | load address to be used in creating the Image Tree Source for | ||
8505 | the FIT image. | ||
8506 | 9598 | ||
8507 | :term:`UBOOT_SIGN_ENABLE` | 9599 | :term:`UBOOT_SIGN_ENABLE` |
8508 | Enable signing of FIT image. The default value is "0". | 9600 | Enable signing of FIT image. The default value is "0". |
8509 | 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 | |||
8510 | :term:`UBOOT_SIGN_KEYDIR` | 9606 | :term:`UBOOT_SIGN_KEYDIR` |
8511 | Location of the directory containing the RSA key and | 9607 | Location of the directory containing the RSA key and certificate used for |
8512 | 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. | ||
8513 | 9610 | ||
8514 | :term:`UBOOT_SIGN_KEYNAME` | 9611 | :term:`UBOOT_SIGN_KEYNAME` |
8515 | 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 |
8516 | :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` |
8517 | 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`` |
8518 | :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``. | ||
8519 | 9617 | ||
8520 | :term:`UBOOT_SUFFIX` | 9618 | :term:`UBOOT_SUFFIX` |
8521 | 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`` |
@@ -8530,104 +9628,123 @@ system and gives an overview of their function and contents. | |||
8530 | 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 |
8531 | process. | 9629 | process. |
8532 | 9630 | ||
8533 | :term:`UNKNOWN_CONFIGURE_WHITELIST` | 9631 | :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` |
8534 | 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 |
8535 | as being invalid, should not generate a warning during the | 9633 | as being invalid, should not generate a warning during the |
8536 | :ref:`ref-tasks-configure` task. Normally, invalid | 9634 | :ref:`ref-tasks-configure` task. Normally, invalid |
8537 | 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. |
8538 | should be removed from :term:`EXTRA_OECONF` or | 9636 | should be removed from :term:`EXTRA_OECONF` or |
8539 | :term:`PACKAGECONFIG_CONFARGS`). | 9637 | :term:`PACKAGECONFIG_CONFARGS`). |
8540 | However, common options, for example, exist that are passed to all | 9638 | However, there are common options that are passed to all |
8541 | 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 |
8542 | configure scripts. It follows that no benefit exists in seeing a | 9640 | configure scripts. Therefore warnings about these options are useless. |
8543 | 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`. |
8544 | to ``UNKNOWN_CONFIGURE_WHITELIST``. | ||
8545 | 9642 | ||
8546 | The configure arguments check that uses | 9643 | The configure arguments check that uses |
8547 | ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the | 9644 | :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the |
8548 | :ref:`insane <ref-classes-insane>` class and is only enabled if the | 9645 | :ref:`ref-classes-insane` class and is only enabled if the |
8549 | recipe inherits the :ref:`autotools <ref-classes-autotools>` class. | 9646 | recipe inherits the :ref:`ref-classes-autotools` class. |
8550 | 9647 | ||
8551 | :term:`UPDATERCPN` | 9648 | :term:`UPDATERCPN` |
8552 | For recipes inheriting the | 9649 | For recipes inheriting the |
8553 | :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` | 9650 | :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN` |
8554 | specifies the package that contains the initscript that is enabled. | 9651 | specifies the package that contains the initscript that is enabled. |
8555 | 9652 | ||
8556 | The default value is "${PN}". Given that almost all recipes that | 9653 | The default value is "${PN}". Given that almost all recipes that |
8557 | install initscripts package them in the main package for the recipe, | 9654 | install initscripts package them in the main package for the recipe, |
8558 | you rarely need to set this variable in individual recipes. | 9655 | you rarely need to set this variable in individual recipes. |
8559 | 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 | |||
8560 | :term:`UPSTREAM_CHECK_GITTAGREGEX` | 9668 | :term:`UPSTREAM_CHECK_GITTAGREGEX` |
8561 | 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 |
8562 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | 9670 | source code version is by calling ``devtool latest-version recipe``. If |
8563 | the recipe source code is provided from Git repositories, the | 9671 | the recipe source code is provided from Git repositories, the |
8564 | OpenEmbedded build system determines the latest upstream version by | 9672 | OpenEmbedded build system determines the latest upstream version by |
8565 | picking the latest tag from the list of all repository tags. | 9673 | picking the latest tag from the list of all repository tags. |
8566 | 9674 | ||
8567 | You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a | 9675 | You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a |
8568 | regular expression to filter only the relevant tags should the | 9676 | regular expression to filter only the relevant tags should the |
8569 | default filter not work correctly. | 9677 | default filter not work correctly:: |
8570 | :: | ||
8571 | 9678 | ||
8572 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" | 9679 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" |
8573 | 9680 | ||
8574 | :term:`UPSTREAM_CHECK_REGEX` | 9681 | :term:`UPSTREAM_CHECK_REGEX` |
8575 | Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different | 9682 | Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different |
8576 | regular expression instead of the default one when the package | 9683 | regular expression instead of the default one when the package |
8577 | checking system is parsing the page found using | 9684 | checking system is parsing the page found using |
8578 | :term:`UPSTREAM_CHECK_URI`. | 9685 | :term:`UPSTREAM_CHECK_URI`:: |
8579 | :: | ||
8580 | 9686 | ||
8581 | UPSTREAM_CHECK_REGEX = "package_regex" | 9687 | UPSTREAM_CHECK_REGEX = "package_regex" |
8582 | 9688 | ||
8583 | :term:`UPSTREAM_CHECK_URI` | 9689 | :term:`UPSTREAM_CHECK_URI` |
8584 | 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 |
8585 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | 9691 | source code version is by calling ``devtool latest-version recipe``. If |
8586 | the source code is provided from tarballs, the latest version is | 9692 | the source code is provided from tarballs, the latest version is |
8587 | determined by fetching the directory listing where the tarball is and | 9693 | determined by fetching the directory listing where the tarball is and |
8588 | 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, |
8589 | 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 |
8590 | contains the link to the latest tarball. | 9696 | contains the link to the latest tarball:: |
8591 | :: | ||
8592 | 9697 | ||
8593 | UPSTREAM_CHECK_URI = "recipe_url" | 9698 | UPSTREAM_CHECK_URI = "recipe_url" |
8594 | 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 | |||
8595 | :term:`USE_DEVFS` | 9711 | :term:`USE_DEVFS` |
8596 | Determines if ``devtmpfs`` is used for ``/dev`` population. The | 9712 | Determines if ``devtmpfs`` is used for ``/dev`` population. The |
8597 | 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 |
8598 | 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 |
8599 | statically populated ``/dev`` directory. | 9715 | statically populated ``/dev`` directory. |
8600 | 9716 | ||
8601 | 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 |
8602 | the Yocto Project Development Tasks Manual for information on how to | 9718 | the Yocto Project Development Tasks Manual for information on how to |
8603 | use this variable. | 9719 | use this variable. |
8604 | 9720 | ||
8605 | :term:`USE_VT` | 9721 | :term:`USE_VT` |
8606 | When using | 9722 | When using |
8607 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | 9723 | :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, |
8608 | determines whether or not to run a | 9724 | determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>` |
8609 | `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any | 9725 | on any virtual terminals in order to enable logging in through those |
8610 | virtual terminals in order to enable logging in through those | ||
8611 | terminals. | 9726 | terminals. |
8612 | 9727 | ||
8613 | 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 |
8614 | 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 |
8615 | machine configuration file for machines that do not have a graphical | 9730 | machine configuration file for machines that do not have a graphical |
8616 | display attached and therefore do not need virtual terminal | 9731 | display attached and therefore do not need virtual terminal |
8617 | functionality. | 9732 | functionality. |
8618 | 9733 | ||
8619 | :term:`USER_CLASSES` | 9734 | :term:`USER_CLASSES` |
8620 | 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 |
8621 | OpenEmbedded build system to enable extra features (e.g. | 9736 | OpenEmbedded build system to enable extra features. |
8622 | ``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. | ||
8623 | 9740 | ||
8624 | The default list is set in your ``local.conf`` file: | 9741 | The default list is set in your ``local.conf`` file:: |
8625 | :: | ||
8626 | 9742 | ||
8627 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | 9743 | USER_CLASSES ?= "buildstats" |
8628 | 9744 | ||
8629 | For more information, see | 9745 | For more information, see |
8630 | ``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`. | ||
8631 | 9748 | ||
8632 | :term:`USERADD_ERROR_DYNAMIC` | 9749 | :term:`USERADD_ERROR_DYNAMIC` |
8633 | If set to ``error``, forces the OpenEmbedded build system to produce | 9750 | If set to ``error``, forces the OpenEmbedded build system to produce |
@@ -8639,11 +9756,10 @@ system and gives an overview of their function and contents. | |||
8639 | 9756 | ||
8640 | The default behavior for the build system is to dynamically apply | 9757 | The default behavior for the build system is to dynamically apply |
8641 | ``uid`` and ``gid`` values. Consequently, the | 9758 | ``uid`` and ``gid`` values. Consequently, the |
8642 | ``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 |
8643 | on using statically assigned ``gid`` and ``uid`` values, you should | 9760 | on using statically assigned ``gid`` and ``uid`` values, you should |
8644 | set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` | 9761 | set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` |
8645 | file as follows: | 9762 | file as follows:: |
8646 | :: | ||
8647 | 9763 | ||
8648 | USERADD_ERROR_DYNAMIC = "error" | 9764 | USERADD_ERROR_DYNAMIC = "error" |
8649 | 9765 | ||
@@ -8657,7 +9773,7 @@ system and gives an overview of their function and contents. | |||
8657 | .. note:: | 9773 | .. note:: |
8658 | 9774 | ||
8659 | There is a difference in behavior between setting | 9775 | There is a difference in behavior between setting |
8660 | ``USERADD_ERROR_DYNAMIC`` to ``error`` and setting it to ``warn``. | 9776 | :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. |
8661 | 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 |
8662 | 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 |
8663 | 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 |
@@ -8673,8 +9789,7 @@ system and gives an overview of their function and contents. | |||
8673 | When applying static group identification (``gid``) values, the | 9789 | When applying static group identification (``gid``) values, the |
8674 | OpenEmbedded build system looks in :term:`BBPATH` for a | 9790 | OpenEmbedded build system looks in :term:`BBPATH` for a |
8675 | ``files/group`` file and then applies those ``uid`` values. Set the | 9791 | ``files/group`` file and then applies those ``uid`` values. Set the |
8676 | variable as follows in your ``local.conf`` file: | 9792 | variable as follows in your ``local.conf`` file:: |
8677 | :: | ||
8678 | 9793 | ||
8679 | 9794 | ||
8680 | USERADD_GID_TABLES = "files/group" | 9795 | USERADD_GID_TABLES = "files/group" |
@@ -8685,33 +9800,31 @@ system and gives an overview of their function and contents. | |||
8685 | causes the build system to use static ``gid`` values. | 9800 | causes the build system to use static ``gid`` values. |
8686 | 9801 | ||
8687 | :term:`USERADD_PACKAGES` | 9802 | :term:`USERADD_PACKAGES` |
8688 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 9803 | When inheriting the :ref:`ref-classes-useradd` class, |
8689 | this variable specifies the individual packages within the recipe | 9804 | this variable specifies the individual packages within the recipe |
8690 | that require users and/or groups to be added. | 9805 | that require users and/or groups to be added. |
8691 | 9806 | ||
8692 | 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 |
8693 | 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 |
8694 | a recipe: | 9809 | a recipe:: |
8695 | :: | ||
8696 | 9810 | ||
8697 | USERADD_PACKAGES = "${PN}" | 9811 | USERADD_PACKAGES = "${PN}" |
8698 | 9812 | ||
8699 | .. note:: | 9813 | .. note:: |
8700 | 9814 | ||
8701 | 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` |
8702 | 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`, |
8703 | :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. | 9817 | :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. |
8704 | 9818 | ||
8705 | :term:`USERADD_PARAM` | 9819 | :term:`USERADD_PARAM` |
8706 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 9820 | When inheriting the :ref:`ref-classes-useradd` class, |
8707 | this variable specifies for a package what parameters should pass to | 9821 | this variable specifies for a package what parameters should pass to |
8708 | 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 |
8709 | package is installed. | 9823 | package is installed. |
8710 | 9824 | ||
8711 | Here is an example from the ``dbus`` recipe: | 9825 | Here is an example from the ``dbus`` recipe:: |
8712 | :: | ||
8713 | 9826 | ||
8714 | USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ | 9827 | USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ |
8715 | --no-create-home --shell /bin/false \ | 9828 | --no-create-home --shell /bin/false \ |
8716 | --user-group messagebus" | 9829 | --user-group messagebus" |
8717 | 9830 | ||
@@ -8727,8 +9840,7 @@ system and gives an overview of their function and contents. | |||
8727 | When applying static user identification (``uid``) values, the | 9840 | When applying static user identification (``uid``) values, the |
8728 | OpenEmbedded build system looks in :term:`BBPATH` for a | 9841 | OpenEmbedded build system looks in :term:`BBPATH` for a |
8729 | ``files/passwd`` file and then applies those ``uid`` values. Set the | 9842 | ``files/passwd`` file and then applies those ``uid`` values. Set the |
8730 | variable as follows in your ``local.conf`` file: | 9843 | variable as follows in your ``local.conf`` file:: |
8731 | :: | ||
8732 | 9844 | ||
8733 | USERADD_UID_TABLES = "files/passwd" | 9845 | USERADD_UID_TABLES = "files/passwd" |
8734 | 9846 | ||
@@ -8759,48 +9871,95 @@ system and gives an overview of their function and contents. | |||
8759 | Additionally, you should also set the | 9871 | Additionally, you should also set the |
8760 | :term:`USERADD_ERROR_DYNAMIC` variable. | 9872 | :term:`USERADD_ERROR_DYNAMIC` variable. |
8761 | 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 | |||
8762 | :term:`VOLATILE_LOG_DIR` | 9901 | :term:`VOLATILE_LOG_DIR` |
8763 | Specifies the persistence of the target's ``/var/log`` directory, | 9902 | Specifies the persistence of the target's ``/var/log`` directory, |
8764 | which is used to house postinstall target log files. | 9903 | which is used to house postinstall target log files. |
8765 | 9904 | ||
8766 | 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 |
8767 | 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 |
8768 | variable to "no" to make the log directory persistent. | 9907 | variable to "no" to make the log directory persistent. |
8769 | 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 | |||
8770 | :term:`WARN_QA` | 9921 | :term:`WARN_QA` |
8771 | Specifies the quality assurance checks whose failures are reported as | 9922 | Specifies the quality assurance checks whose failures are reported as |
8772 | warnings by the OpenEmbedded build system. You set this variable in | 9923 | warnings by the OpenEmbedded build system. You set this variable in |
8773 | your distribution configuration file. For a list of the checks you | 9924 | your distribution configuration file. For a list of the checks you |
8774 | can control with this variable, see the | 9925 | can control with this variable, see the |
8775 | ":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). | ||
8776 | 9936 | ||
8777 | :term:`WKS_FILE` | 9937 | :term:`WKS_FILE` |
8778 | 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 |
8779 | OpenEmbedded build system to create a partitioned image | 9939 | OpenEmbedded build system to create a partitioned image |
8780 | (image\ ``.wic``). For information on how to create a partitioned | 9940 | (``image.wic``). For information on how to create a partitioned |
8781 | image, see the | 9941 | image, see the |
8782 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | 9942 | ":ref:`dev-manual/wic:creating partitioned images using wic`" |
8783 | section in the Yocto Project Development Tasks Manual. For details on | 9943 | section in the Yocto Project Development Tasks Manual. For details on |
8784 | the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. | 9944 | the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. |
8785 | 9945 | ||
8786 | :term:`WKS_FILE_DEPENDS` | 9946 | :term:`WKS_FILE_DEPENDS` |
8787 | 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 |
8788 | build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only | 9948 | build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only |
8789 | applicable when Wic images are active (i.e. when | 9949 | applicable when Wic images are active (i.e. when |
8790 | :term:`IMAGE_FSTYPES` contains entries related | 9950 | :term:`IMAGE_FSTYPES` contains entries related |
8791 | 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 |
8792 | no effect. | 9952 | no effect. |
8793 | 9953 | ||
8794 | The ``WKS_FILE_DEPENDS`` variable is similar to the | 9954 | The :term:`WKS_FILE_DEPENDS` variable is similar to the |
8795 | :term:`DEPENDS` variable. When you use the variable in | 9955 | :term:`DEPENDS` variable. When you use the variable in |
8796 | 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 |
8797 | ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. | 9957 | :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. |
8798 | 9958 | ||
8799 | With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to | 9959 | With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to |
8800 | specify a list of additional dependencies (e.g. native tools, | 9960 | specify a list of additional dependencies (e.g. native tools, |
8801 | bootloaders, and so forth), that are required to build Wic images. | 9961 | bootloaders, and so forth), that are required to build Wic images. |
8802 | Following is an example: | 9962 | Here is an example:: |
8803 | :: | ||
8804 | 9963 | ||
8805 | WKS_FILE_DEPENDS = "some-native-tool" | 9964 | WKS_FILE_DEPENDS = "some-native-tool" |
8806 | 9965 | ||
@@ -8808,14 +9967,26 @@ system and gives an overview of their function and contents. | |||
8808 | previous example, some-native-tool would be replaced with an actual | 9967 | previous example, some-native-tool would be replaced with an actual |
8809 | native tool on which the build would depend. | 9968 | native tool on which the build would depend. |
8810 | 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 | |||
8811 | :term:`WORKDIR` | 9983 | :term:`WORKDIR` |
8812 | The pathname of the work directory in which the OpenEmbedded build | 9984 | The pathname of the work directory in which the OpenEmbedded build |
8813 | system builds a recipe. This directory is located within the | 9985 | system builds a recipe. This directory is located within the |
8814 | :term:`TMPDIR` directory structure and is specific to | 9986 | :term:`TMPDIR` directory structure and is specific to |
8815 | 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. |
8816 | 9988 | ||
8817 | The ``WORKDIR`` directory is defined as follows: | 9989 | The :term:`WORKDIR` directory is defined as follows:: |
8818 | :: | ||
8819 | 9990 | ||
8820 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | 9991 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} |
8821 | 9992 | ||
@@ -8824,18 +9995,17 @@ system and gives an overview of their function and contents. | |||
8824 | - :term:`TMPDIR`: The top-level build output directory | 9995 | - :term:`TMPDIR`: The top-level build output directory |
8825 | - :term:`MULTIMACH_TARGET_SYS`: The target system identifier | 9996 | - :term:`MULTIMACH_TARGET_SYS`: The target system identifier |
8826 | - :term:`PN`: The recipe name | 9997 | - :term:`PN`: The recipe name |
8827 | - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which | 9998 | - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which |
8828 | is usually the case for most recipes, then `EXTENDPE` is blank) | 9999 | is usually the case for most recipes, then :term:`EXTENDPE` is blank. |
8829 | - :term:`PV`: The recipe version | 10000 | - :term:`PV`: The recipe version |
8830 | - :term:`PR`: The recipe revision | 10001 | - :term:`PR`: The recipe revision |
8831 | 10002 | ||
8832 | As an example, assume a Source Directory top-level folder name | 10003 | As an example, assume a Source Directory top-level folder name |
8833 | ``poky``, a default Build Directory at ``poky/build``, and a | 10004 | ``poky``, a default :term:`Build Directory` at ``poky/build``, and a |
8834 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose | 10005 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose |
8835 | 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 |
8836 | 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 |
8837 | follows: | 10008 | follows:: |
8838 | :: | ||
8839 | 10009 | ||
8840 | 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 |
8841 | 10011 | ||
@@ -8846,6 +10016,37 @@ system and gives an overview of their function and contents. | |||
8846 | indirectly, includes "x11-base" in | 10016 | indirectly, includes "x11-base" in |
8847 | :term:`IMAGE_FEATURES`. | 10017 | :term:`IMAGE_FEATURES`. |
8848 | 10018 | ||
8849 | The default value of ``XSERVER``, if not specified in the machine | 10019 | The default value of :term:`XSERVER`, if not specified in the machine |
8850 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". | 10020 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". |
8851 | 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 | ||