diff options
Diffstat (limited to 'documentation/ref-manual/classes.rst')
-rw-r--r-- | documentation/ref-manual/classes.rst | 2518 |
1 files changed, 1550 insertions, 968 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index be112e0faf..9520d0bf7c 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: |
361 | |||
362 | ``cmake`` | ||
363 | ========= | ||
295 | 364 | ||
296 | ``clutter.bbclass`` | 365 | The :ref:`ref-classes-cmake` class allows recipes to build software using the |
297 | =================== | 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. | ||
298 | 369 | ||
299 | The ``clutter`` class consolidates the major and minor version naming | 370 | By default, the :ref:`ref-classes-cmake` class uses |
300 | and other common items used by Clutter and related recipes. | 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. | ||
301 | 375 | ||
302 | .. note:: | 376 | If you need to install custom CMake toolchain files supplied by the application |
377 | being built, you should install them (during :ref:`ref-tasks-install`) to the | ||
378 | preferred CMake Module directory: ``${D}${datadir}/cmake/modules/``. | ||
303 | 379 | ||
304 | Unlike some other classes related to specific libraries, recipes | 380 | .. _ref-classes-cmake-qemu: |
305 | building other software that uses Clutter do not need to inherit this | ||
306 | class unless they use the same recipe versioning scheme that the | ||
307 | Clutter and related recipes do. | ||
308 | 381 | ||
309 | .. _ref-classes-cmake: | 382 | ``cmake-qemu`` |
383 | ============== | ||
310 | 384 | ||
311 | ``cmake.bbclass`` | 385 | The :ref:`ref-classes-cmake-qemu` class might be used instead of the |
312 | ================= | 386 | :ref:`ref-classes-cmake` class. In addition to the features provided by the |
387 | :ref:`ref-classes-cmake` class, the :ref:`ref-classes-cmake-qemu` class passes | ||
388 | the ``CMAKE_CROSSCOMPILING_EMULATOR`` setting to ``cmake``. This allows to use | ||
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>`__. | ||
313 | 393 | ||
314 | The ``cmake`` class allows for recipes that need to build software using | 394 | Not all platforms are supported by QEMU. This class only works for machines with |
315 | the `CMake <https://cmake.org/overview/>`__ build system. You can use | 395 | ``qemu-usermode`` in the :ref:`ref-features-machine`. Using QEMU user-mode therefore |
316 | the :term:`EXTRA_OECMAKE` variable to specify | 396 | involves a certain risk, which is also the reason why this feature is not part of |
317 | additional configuration options to be passed using the ``cmake`` | 397 | the main :ref:`ref-classes-cmake` class by default. |
318 | command line. | 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:: | ||
319 | 401 | ||
320 | On the occasion that you would be installing custom CMake toolchain | 402 | cmake --build --target test |
321 | files supplied by the application being built, you should install them | 403 | |
322 | to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` | 404 | works transparently with QEMU user-mode. |
323 | Modules during | 405 | |
324 | :ref:`ref-tasks-install`. | 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,92 @@ 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 | .. note:: | ||
568 | |||
569 | Commit message metadata (``CVE: CVE-ID`` in a patch header) will not be scanned | ||
570 | in any patches that are remote, i.e. that are anything other than local files | ||
571 | referenced via ``file://`` in SRC_URI. However, a ``CVE-ID`` in a remote patch | ||
572 | file name itself will be registered. | ||
573 | |||
574 | If the recipe adds ``CVE-ID`` as flag of the :term:`CVE_STATUS` variable with status | ||
575 | mapped to ``Ignored``, then the CVE state is reported as ``Ignored``:: | ||
576 | |||
577 | CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows" | ||
578 | |||
579 | If CVE check reports that a recipe contains false positives or false negatives, these may be | ||
580 | fixed in recipes by adjusting the CVE product name using :term:`CVE_PRODUCT` and :term:`CVE_VERSION` variables. | ||
581 | :term:`CVE_PRODUCT` defaults to the plain recipe name :term:`BPN` which can be adjusted to one or more CVE | ||
582 | database vendor and product pairs using the syntax:: | ||
583 | |||
584 | CVE_PRODUCT = "flex_project:flex" | ||
585 | |||
586 | where ``flex_project`` is the CVE database vendor name and ``flex`` is the product name. Similarly | ||
587 | if the default recipe version :term:`PV` does not match the version numbers of the software component | ||
588 | in upstream releases or the CVE database, then the :term:`CVE_VERSION` variable can be used to set the | ||
589 | CVE database compatible version number, for example:: | ||
590 | |||
591 | CVE_VERSION = "2.39" | ||
592 | |||
593 | Any bugs or missing or incomplete information in the CVE database entries should be fixed in the CVE database | ||
594 | via the `NVD feedback form <https://nvd.nist.gov/info/contact-form>`__. | ||
595 | |||
596 | Users should note that security is a process, not a product, and thus also CVE checking, analyzing results, | ||
597 | patching and updating the software should be done as a regular process. The data and assumptions | ||
598 | required for CVE checker to reliably detect issues are frequently broken in various ways. | ||
599 | These can only be detected by reviewing the details of the issues and iterating over the generated reports, | ||
600 | and following what happens in other Linux distributions and in the greater open source community. | ||
601 | |||
602 | You will find some more details in the | ||
603 | ":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`" | ||
604 | section in the Development Tasks Manual. | ||
605 | |||
424 | .. _ref-classes-debian: | 606 | .. _ref-classes-debian: |
425 | 607 | ||
426 | ``debian.bbclass`` | 608 | ``debian`` |
427 | ================== | 609 | ========== |
428 | 610 | ||
429 | The ``debian`` class renames output packages so that they follow the | 611 | The :ref:`ref-classes-debian` class renames output packages so that they follow the |
430 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and | 612 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and |
431 | ``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library | 613 | ``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library |
432 | name and version as part of the package name. | 614 | name and version as part of the package name. |
@@ -438,10 +620,10 @@ naming scheme. | |||
438 | 620 | ||
439 | .. _ref-classes-deploy: | 621 | .. _ref-classes-deploy: |
440 | 622 | ||
441 | ``deploy.bbclass`` | 623 | ``deploy`` |
442 | ================== | 624 | ========== |
443 | 625 | ||
444 | The ``deploy`` class handles deploying files to the | 626 | The :ref:`ref-classes-deploy` class handles deploying files to the |
445 | :term:`DEPLOY_DIR_IMAGE` directory. The main | 627 | :term:`DEPLOY_DIR_IMAGE` directory. The main |
446 | function of this class is to allow the deploy step to be accelerated by | 628 | 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 | 629 | shared state. Recipes that inherit this class should define their own |
@@ -450,113 +632,109 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to | |||
450 | add the task at the appropriate place, which is usually after | 632 | add the task at the appropriate place, which is usually after |
451 | :ref:`ref-tasks-compile` or | 633 | :ref:`ref-tasks-compile` or |
452 | :ref:`ref-tasks-install`. The class then takes care of | 634 | :ref:`ref-tasks-install`. The class then takes care of |
453 | staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. | 635 | staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`. |
636 | |||
637 | .. _ref-classes-devicetree: | ||
638 | |||
639 | ``devicetree`` | ||
640 | ============== | ||
641 | |||
642 | The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles | ||
643 | device tree source files that are not in the kernel tree. | ||
644 | |||
645 | The compilation of out-of-tree device tree sources is the same as the kernel | ||
646 | in-tree device tree compilation process. This includes the ability to include | ||
647 | sources from the kernel such as SoC ``dtsi`` files as well as C header files, | ||
648 | such as ``gpio.h``. | ||
649 | |||
650 | The :ref:`ref-tasks-compile` task will compile two kinds of files: | ||
651 | |||
652 | - Regular device tree sources with a ``.dts`` extension. | ||
653 | |||
654 | - Device tree overlays, detected from the presence of the ``/plugin/;`` | ||
655 | string in the file contents. | ||
656 | |||
657 | This class deploys the generated device tree binaries into | ||
658 | ``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}/devicetree/``. This is similar to | ||
659 | what the :ref:`ref-classes-kernel-devicetree` class does, with the added | ||
660 | ``devicetree`` subdirectory to avoid name clashes. Additionally, the device | ||
661 | trees are populated into the sysroot for access via the sysroot from within | ||
662 | other recipes. | ||
663 | |||
664 | By default, all device tree sources located in :term:`DT_FILES_PATH` directory | ||
665 | are compiled. To select only particular sources, set :term:`DT_FILES` to | ||
666 | a space-separated list of files (relative to :term:`DT_FILES_PATH`). For | ||
667 | convenience, both ``.dts`` and ``.dtb`` extensions can be used. | ||
668 | |||
669 | An extra padding is appended to non-overlay device trees binaries. This | ||
670 | can typically be used as extra space for adding extra properties at boot time. | ||
671 | The padding size can be modified by setting :term:`DT_PADDING_SIZE` | ||
672 | to the desired size, in bytes. | ||
673 | |||
674 | See :oe_git:`devicetree.bbclass sources | ||
675 | </openembedded-core/tree/meta/classes-recipe/devicetree.bbclass>` | ||
676 | for further variables controlling this class. | ||
677 | |||
678 | Here is an excerpt of an example ``recipes-kernel/linux/devicetree-acme.bb`` | ||
679 | recipe inheriting this class:: | ||
680 | |||
681 | inherit devicetree | ||
682 | COMPATIBLE_MACHINE = "^mymachine$" | ||
683 | SRC_URI:mymachine = "file://mymachine.dts" | ||
454 | 684 | ||
455 | .. _ref-classes-devshell: | 685 | .. _ref-classes-devshell: |
456 | 686 | ||
457 | ``devshell.bbclass`` | 687 | ``devshell`` |
458 | ==================== | 688 | ============ |
459 | 689 | ||
460 | The ``devshell`` class adds the ``do_devshell`` task. Distribution | 690 | 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`" | 691 | 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 | 692 | section in the Yocto Project Development Tasks Manual for more |
463 | information about using ``devshell``. | 693 | information about using :ref:`ref-classes-devshell`. |
464 | 694 | ||
465 | .. _ref-classes-devupstream: | 695 | .. _ref-classes-devupstream: |
466 | 696 | ||
467 | ``devupstream.bbclass`` | 697 | ``devupstream`` |
468 | ======================= | 698 | =============== |
469 | 699 | ||
470 | The ``devupstream`` class uses | 700 | The :ref:`ref-classes-devupstream` class uses |
471 | :term:`BBCLASSEXTEND` to add a variant of the | 701 | :term:`BBCLASSEXTEND` to add a variant of the |
472 | recipe that fetches from an alternative URI (e.g. Git) instead of a | 702 | recipe that fetches from an alternative URI (e.g. Git) instead of a |
473 | tarball. Following is an example: | 703 | tarball. Here is an example:: |
474 | :: | ||
475 | 704 | ||
476 | BBCLASSEXTEND = "devupstream:target" | 705 | BBCLASSEXTEND = "devupstream:target" |
477 | SRC_URI_class-devupstream = "git://git.example.com/example" | 706 | SRC_URI:class-devupstream = "git://git.example.com/example;branch=main" |
478 | SRCREV_class-devupstream = "abcd1234" | 707 | SRCREV:class-devupstream = "abcd1234" |
479 | 708 | ||
480 | Adding the above statements to your recipe creates a variant that has | 709 | Adding the above statements to your recipe creates a variant that has |
481 | :term:`DEFAULT_PREFERENCE` set to "-1". | 710 | :term:`DEFAULT_PREFERENCE` set to "-1". |
482 | Consequently, you need to select the variant of the recipe to use it. | 711 | Consequently, you need to select the variant of the recipe to use it. |
483 | Any development-specific adjustments can be done by using the | 712 | Any development-specific adjustments can be done by using the |
484 | ``class-devupstream`` override. Here is an example: | 713 | ``class-devupstream`` override. Here is an example:: |
485 | :: | ||
486 | 714 | ||
487 | DEPENDS_append_class-devupstream = " gperf-native" | 715 | DEPENDS:append:class-devupstream = " gperf-native" |
488 | do_configure_prepend_class-devupstream() { | 716 | do_configure:prepend:class-devupstream() { |
489 | touch ${S}/README | 717 | touch ${S}/README |
490 | } | 718 | } |
491 | 719 | ||
492 | The class | 720 | The class |
493 | currently only supports creating a development variant of the target | 721 | currently only supports creating a development variant of the target |
494 | recipe, not ``native`` or ``nativesdk`` variants. | 722 | recipe, not :ref:`ref-classes-native` or :ref:`ref-classes-nativesdk` variants. |
495 | 723 | ||
496 | The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides | 724 | The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides |
497 | support for ``native`` and ``nativesdk`` variants. Consequently, this | 725 | support for :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk` variants. Consequently, this |
498 | functionality can be added in a future release. | 726 | functionality can be added in a future release. |
499 | 727 | ||
500 | Support for other version control systems such as Subversion is limited | 728 | Support for other version control systems such as Subversion is limited |
501 | due to BitBake's automatic fetch dependencies (e.g. | 729 | due to BitBake's automatic fetch dependencies (e.g. |
502 | ``subversion-native``). | 730 | ``subversion-native``). |
503 | 731 | ||
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: | 732 | .. _ref-classes-externalsrc: |
555 | 733 | ||
556 | ``externalsrc.bbclass`` | 734 | ``externalsrc`` |
557 | ======================= | 735 | =============== |
558 | 736 | ||
559 | The ``externalsrc`` class supports building software from source code | 737 | The :ref:`ref-classes-externalsrc` class supports building software from source code |
560 | that is external to the OpenEmbedded build system. Building software | 738 | that is external to the OpenEmbedded build system. Building software |
561 | from an external source tree means that the build system's normal fetch, | 739 | from an external source tree means that the build system's normal fetch, |
562 | unpack, and patch process is not used. | 740 | unpack, and patch process is not used. |
@@ -564,37 +742,34 @@ unpack, and patch process is not used. | |||
564 | By default, the OpenEmbedded build system uses the :term:`S` | 742 | By default, the OpenEmbedded build system uses the :term:`S` |
565 | and :term:`B` variables to locate unpacked recipe source code | 743 | and :term:`B` variables to locate unpacked recipe source code |
566 | and to build it, respectively. When your recipe inherits the | 744 | and to build it, respectively. When your recipe inherits the |
567 | ``externalsrc`` class, you use the | 745 | :ref:`ref-classes-externalsrc` class, you use the |
568 | :term:`EXTERNALSRC` and | 746 | :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` variables to |
569 | :term:`EXTERNALSRC_BUILD` variables to | 747 | ultimately define :term:`S` and :term:`B`. |
570 | ultimately define ``S`` and ``B``. | ||
571 | 748 | ||
572 | By default, this class expects the source code to support recipe builds | 749 | 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 | 750 | that use the :term:`B` variable to point to the directory in |
574 | which the OpenEmbedded build system places the generated objects built | 751 | which the OpenEmbedded build system places the generated objects built |
575 | from the recipes. By default, the ``B`` directory is set to the | 752 | from the recipes. By default, the :term:`B` directory is set to the |
576 | following, which is separate from the source directory (``S``): | 753 | following, which is separate from the source directory (:term:`S`):: |
577 | :: | ||
578 | 754 | ||
579 | ${WORKDIR}/${BPN}/{PV}/ | 755 | ${WORKDIR}/${BPN}-{PV}/ |
580 | 756 | ||
581 | See these variables for more information: | 757 | See these variables for more information: |
582 | :term:`WORKDIR`, :term:`BPN`, and | 758 | :term:`WORKDIR`, :term:`BPN`, and |
583 | :term:`PV`, | 759 | :term:`PV`, |
584 | 760 | ||
585 | For more information on the ``externalsrc`` class, see the comments in | 761 | For more information on the :ref:`ref-classes-externalsrc` class, see the comments in |
586 | ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. | 762 | ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. |
587 | For information on how to use the | 763 | For information on how to use the :ref:`ref-classes-externalsrc` class, see the |
588 | ``externalsrc`` class, see the | 764 | ":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. | 765 | section in the Yocto Project Development Tasks Manual. |
591 | 766 | ||
592 | .. _ref-classes-extrausers: | 767 | .. _ref-classes-extrausers: |
593 | 768 | ||
594 | ``extrausers.bbclass`` | 769 | ``extrausers`` |
595 | ====================== | 770 | ============== |
596 | 771 | ||
597 | The ``extrausers`` class allows additional user and group configuration | 772 | 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 | 773 | 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 | 774 | or from an image recipe allows additional user and group operations to |
600 | be performed using the | 775 | be performed using the |
@@ -602,16 +777,13 @@ be performed using the | |||
602 | 777 | ||
603 | .. note:: | 778 | .. note:: |
604 | 779 | ||
605 | The user and group operations added using the | 780 | 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 | 781 | 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 | 782 | image. Thus, the operations can be performed across the image as a |
609 | whole. Use the | 783 | whole. Use the :ref:`ref-classes-useradd` class to add user and group |
610 | useradd | 784 | configuration to a specific recipe. |
611 | class to add user and group configuration to a specific recipe. | ||
612 | 785 | ||
613 | Here is an example that uses this class in an image recipe: | 786 | Here is an example that uses this class in an image recipe:: |
614 | :: | ||
615 | 787 | ||
616 | inherit extrausers | 788 | inherit extrausers |
617 | EXTRA_USERS_PARAMS = "\ | 789 | EXTRA_USERS_PARAMS = "\ |
@@ -624,31 +796,42 @@ Here is an example that uses this class in an image recipe: | |||
624 | " | 796 | " |
625 | 797 | ||
626 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns | 798 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns |
627 | passwords: | 799 | passwords. First on host, create the (escaped) password hash:: |
628 | :: | 800 | |
801 | printf "%q" $(mkpasswd -m sha256crypt tester01) | ||
802 | |||
803 | The resulting hash is set to a variable and used in ``useradd`` command parameters:: | ||
629 | 804 | ||
630 | inherit extrausers | 805 | inherit extrausers |
806 | PASSWD = "\$X\$ABC123\$A-Long-Hash" | ||
631 | EXTRA_USERS_PARAMS = "\ | 807 | EXTRA_USERS_PARAMS = "\ |
632 | useradd -P tester01 tester-jim; \ | 808 | useradd -p '${PASSWD}' tester-jim; \ |
633 | useradd -P tester01 tester-sue; \ | 809 | useradd -p '${PASSWD}' tester-sue; \ |
634 | " | 810 | " |
635 | 811 | ||
636 | Finally, here is an example that sets the root password to "1876*18": | 812 | Finally, here is an example that sets the root password:: |
637 | :: | ||
638 | 813 | ||
639 | inherit extrausers | 814 | inherit extrausers |
640 | EXTRA_USERS_PARAMS = "\ | 815 | EXTRA_USERS_PARAMS = "\ |
641 | usermod -P 1876*18 root; \ | 816 | usermod -p '${PASSWD}' root; \ |
642 | " | 817 | " |
643 | 818 | ||
819 | .. note:: | ||
820 | |||
821 | From a security perspective, hardcoding a default password is not | ||
822 | generally a good idea or even legal in some jurisdictions. It is | ||
823 | recommended that you do not do this if you are building a production | ||
824 | image. | ||
825 | |||
826 | |||
644 | .. _ref-classes-features_check: | 827 | .. _ref-classes-features_check: |
645 | 828 | ||
646 | ``features_check.bbclass`` | 829 | ``features_check`` |
647 | ================================= | 830 | ================== |
648 | 831 | ||
649 | The ``features_check`` class allows individual recipes to check | 832 | The :ref:`ref-classes-features_check` class allows individual recipes to check |
650 | for required and conflicting | 833 | for required and conflicting :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` |
651 | :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`. | 834 | or :term:`COMBINED_FEATURES`. |
652 | 835 | ||
653 | This class provides support for the following variables: | 836 | This class provides support for the following variables: |
654 | 837 | ||
@@ -669,10 +852,10 @@ triggered. | |||
669 | 852 | ||
670 | .. _ref-classes-fontcache: | 853 | .. _ref-classes-fontcache: |
671 | 854 | ||
672 | ``fontcache.bbclass`` | 855 | ``fontcache`` |
673 | ===================== | 856 | ============= |
674 | 857 | ||
675 | The ``fontcache`` class generates the proper post-install and | 858 | The :ref:`ref-classes-fontcache` class generates the proper post-install and |
676 | post-remove (postinst and postrm) scriptlets for font packages. These | 859 | post-remove (postinst and postrm) scriptlets for font packages. These |
677 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts | 860 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts |
678 | to the font information cache. Since the cache files are | 861 | to the font information cache. Since the cache files are |
@@ -685,20 +868,20 @@ packages containing the fonts. | |||
685 | 868 | ||
686 | .. _ref-classes-fs-uuid: | 869 | .. _ref-classes-fs-uuid: |
687 | 870 | ||
688 | ``fs-uuid.bbclass`` | 871 | ``fs-uuid`` |
689 | =================== | 872 | =========== |
690 | 873 | ||
691 | The ``fs-uuid`` class extracts UUID from | 874 | The :ref:`ref-classes-fs-uuid` class extracts UUID from |
692 | ``${``\ :term:`ROOTFS`\ ``}``, which must have been built | 875 | ``${``\ :term:`ROOTFS`\ ``}``, which must have been built |
693 | by the time that this function gets called. The ``fs-uuid`` class only | 876 | 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``. | 877 | works on ``ext`` file systems and depends on ``tune2fs``. |
695 | 878 | ||
696 | .. _ref-classes-gconf: | 879 | .. _ref-classes-gconf: |
697 | 880 | ||
698 | ``gconf.bbclass`` | 881 | ``gconf`` |
699 | ================= | 882 | ========= |
700 | 883 | ||
701 | The ``gconf`` class provides common functionality for recipes that need | 884 | 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 | 885 | to install GConf schemas. The schemas will be put into a separate |
703 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created | 886 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created |
704 | automatically when this class is inherited. This package uses the | 887 | automatically when this class is inherited. This package uses the |
@@ -707,29 +890,80 @@ register and unregister the schemas in the target image. | |||
707 | 890 | ||
708 | .. _ref-classes-gettext: | 891 | .. _ref-classes-gettext: |
709 | 892 | ||
710 | ``gettext.bbclass`` | 893 | ``gettext`` |
711 | =================== | 894 | =========== |
712 | 895 | ||
713 | The ``gettext`` class provides support for building software that uses | 896 | The :ref:`ref-classes-gettext` class provides support for building |
714 | the GNU ``gettext`` internationalization and localization system. All | 897 | software that uses the GNU ``gettext`` internationalization and localization |
715 | recipes building software that use ``gettext`` should inherit this | 898 | system. All recipes building software that use ``gettext`` should inherit this |
716 | class. | 899 | class. |
717 | 900 | ||
901 | .. _ref-classes-github-releases: | ||
902 | |||
903 | ``github-releases`` | ||
904 | =================== | ||
905 | |||
906 | For recipes that fetch release tarballs from github, the :ref:`ref-classes-github-releases` | ||
907 | class sets up a standard way for checking available upstream versions | ||
908 | (to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)). | ||
909 | |||
910 | To use it, add ":ref:`ref-classes-github-releases`" to the inherit line in the recipe, | ||
911 | and if the default value of :term:`GITHUB_BASE_URI` is not suitable, | ||
912 | then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}`` | ||
913 | in the value you set for :term:`SRC_URI` within the recipe. | ||
914 | |||
718 | .. _ref-classes-gnomebase: | 915 | .. _ref-classes-gnomebase: |
719 | 916 | ||
720 | ``gnomebase.bbclass`` | 917 | ``gnomebase`` |
721 | ===================== | 918 | ============= |
722 | 919 | ||
723 | The ``gnomebase`` class is the base class for recipes that build | 920 | The :ref:`ref-classes-gnomebase` class is the base class for recipes that build |
724 | software from the GNOME stack. This class sets | 921 | software from the GNOME stack. This class sets |
725 | :term:`SRC_URI` to download the source from the GNOME | 922 | :term:`SRC_URI` to download the source from the GNOME |
726 | mirrors as well as extending :term:`FILES` with the typical | 923 | mirrors as well as extending :term:`FILES` with the typical |
727 | GNOME installation paths. | 924 | GNOME installation paths. |
728 | 925 | ||
926 | .. _ref-classes-go: | ||
927 | |||
928 | ``go`` | ||
929 | ====== | ||
930 | |||
931 | The :ref:`ref-classes-go` class supports building Go programs. The behavior of | ||
932 | this class is controlled by the mandatory :term:`GO_IMPORT` variable, and | ||
933 | by the optional :term:`GO_INSTALL` and :term:`GO_INSTALL_FILTEROUT` ones. | ||
934 | |||
935 | To build a Go program with the Yocto Project, you can use the | ||
936 | :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` | ||
937 | recipe as an example. | ||
938 | |||
939 | .. _ref-classes-go-mod: | ||
940 | |||
941 | ``go-mod`` | ||
942 | ========== | ||
943 | |||
944 | The :ref:`ref-classes-go-mod` class allows to use Go modules, and inherits the | ||
945 | :ref:`ref-classes-go` class. | ||
946 | |||
947 | See the associated :term:`GO_WORKDIR` variable. | ||
948 | |||
949 | .. _ref-classes-go-vendor: | ||
950 | |||
951 | ``go-vendor`` | ||
952 | ============= | ||
953 | |||
954 | The :ref:`ref-classes-go-vendor` class implements support for offline builds, | ||
955 | also known as Go vendoring. In such a scenario, the module dependencias are | ||
956 | downloaded during the :ref:`ref-tasks-fetch` task rather than when modules are | ||
957 | imported, thus being coherent with Yocto's concept of fetching every source | ||
958 | beforehand. | ||
959 | |||
960 | The dependencies are unpacked into the modules' ``vendor`` directory, where a | ||
961 | manifest file is generated. | ||
962 | |||
729 | .. _ref-classes-gobject-introspection: | 963 | .. _ref-classes-gobject-introspection: |
730 | 964 | ||
731 | ``gobject-introspection.bbclass`` | 965 | ``gobject-introspection`` |
732 | ================================= | 966 | ========================= |
733 | 967 | ||
734 | Provides support for recipes building software that supports GObject | 968 | Provides support for recipes building software that supports GObject |
735 | introspection. This functionality is only enabled if the | 969 | introspection. This functionality is only enabled if the |
@@ -740,16 +974,17 @@ introspection. This functionality is only enabled if the | |||
740 | 974 | ||
741 | .. note:: | 975 | .. note:: |
742 | 976 | ||
743 | This functionality is backfilled by default and, if not applicable, | 977 | This functionality is :ref:`backfilled <ref-features-backfill>` by default |
744 | should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or | 978 | and, if not applicable, should be disabled through |
745 | ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively. | 979 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or |
980 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. | ||
746 | 981 | ||
747 | .. _ref-classes-grub-efi: | 982 | .. _ref-classes-grub-efi: |
748 | 983 | ||
749 | ``grub-efi.bbclass`` | 984 | ``grub-efi`` |
750 | ==================== | 985 | ============ |
751 | 986 | ||
752 | The ``grub-efi`` class provides ``grub-efi``-specific functions for | 987 | The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for |
753 | building bootable images. | 988 | building bootable images. |
754 | 989 | ||
755 | This class supports several variables: | 990 | This class supports several variables: |
@@ -778,10 +1013,10 @@ This class supports several variables: | |||
778 | 1013 | ||
779 | .. _ref-classes-gsettings: | 1014 | .. _ref-classes-gsettings: |
780 | 1015 | ||
781 | ``gsettings.bbclass`` | 1016 | ``gsettings`` |
782 | ===================== | 1017 | ============= |
783 | 1018 | ||
784 | The ``gsettings`` class provides common functionality for recipes that | 1019 | 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 | 1020 | need to install GSettings (glib) schemas. The schemas are assumed to be |
786 | part of the main package. Appropriate post-install and post-remove | 1021 | part of the main package. Appropriate post-install and post-remove |
787 | (postinst/postrm) scriptlets are added to register and unregister the | 1022 | (postinst/postrm) scriptlets are added to register and unregister the |
@@ -789,18 +1024,18 @@ schemas in the target image. | |||
789 | 1024 | ||
790 | .. _ref-classes-gtk-doc: | 1025 | .. _ref-classes-gtk-doc: |
791 | 1026 | ||
792 | ``gtk-doc.bbclass`` | 1027 | ``gtk-doc`` |
793 | =================== | 1028 | =========== |
794 | 1029 | ||
795 | The ``gtk-doc`` class is a helper class to pull in the appropriate | 1030 | The :ref:`ref-classes-gtk-doc` class is a helper class to pull in the appropriate |
796 | ``gtk-doc`` dependencies and disable ``gtk-doc``. | 1031 | ``gtk-doc`` dependencies and disable ``gtk-doc``. |
797 | 1032 | ||
798 | .. _ref-classes-gtk-icon-cache: | 1033 | .. _ref-classes-gtk-icon-cache: |
799 | 1034 | ||
800 | ``gtk-icon-cache.bbclass`` | 1035 | ``gtk-icon-cache`` |
801 | ========================== | 1036 | ================== |
802 | 1037 | ||
803 | The ``gtk-icon-cache`` class generates the proper post-install and | 1038 | 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 | 1039 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and |
805 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add | 1040 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add |
806 | the fonts to GTK+'s icon cache. Since the cache files are | 1041 | the fonts to GTK+'s icon cache. Since the cache files are |
@@ -810,10 +1045,10 @@ creation. | |||
810 | 1045 | ||
811 | .. _ref-classes-gtk-immodules-cache: | 1046 | .. _ref-classes-gtk-immodules-cache: |
812 | 1047 | ||
813 | ``gtk-immodules-cache.bbclass`` | 1048 | ``gtk-immodules-cache`` |
814 | =============================== | 1049 | ======================= |
815 | 1050 | ||
816 | The ``gtk-immodules-cache`` class generates the proper post-install and | 1051 | 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+ | 1052 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ |
818 | input method modules for virtual keyboards. These scriptlets call | 1053 | input method modules for virtual keyboards. These scriptlets call |
819 | ``gtk-update-icon-cache`` to add the input method modules to the cache. | 1054 | ``gtk-update-icon-cache`` to add the input method modules to the cache. |
@@ -828,19 +1063,19 @@ the packages containing the modules. | |||
828 | 1063 | ||
829 | .. _ref-classes-gzipnative: | 1064 | .. _ref-classes-gzipnative: |
830 | 1065 | ||
831 | ``gzipnative.bbclass`` | 1066 | ``gzipnative`` |
832 | ====================== | 1067 | ============== |
833 | 1068 | ||
834 | The ``gzipnative`` class enables the use of different native versions of | 1069 | 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 | 1070 | ``gzip`` and ``pigz`` rather than the versions of these tools from the |
836 | build host. | 1071 | build host. |
837 | 1072 | ||
838 | .. _ref-classes-icecc: | 1073 | .. _ref-classes-icecc: |
839 | 1074 | ||
840 | ``icecc.bbclass`` | 1075 | ``icecc`` |
841 | ================= | 1076 | ========= |
842 | 1077 | ||
843 | The ``icecc`` class supports | 1078 | The :ref:`ref-classes-icecc` class supports |
844 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates | 1079 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates |
845 | taking compile jobs and distributing them among remote machines. | 1080 | taking compile jobs and distributing them among remote machines. |
846 | 1081 | ||
@@ -848,7 +1083,7 @@ The class stages directories with symlinks from ``gcc`` and ``g++`` to | |||
848 | ``icecc``, for both native and cross compilers. Depending on each | 1083 | ``icecc``, for both native and cross compilers. Depending on each |
849 | configure or compile, the OpenEmbedded build system adds the directories | 1084 | 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 | 1085 | 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`` | 1086 | ``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` |
852 | compilers, respectively. | 1087 | compilers, respectively. |
853 | 1088 | ||
854 | For the cross compiler, the class creates a ``tar.gz`` file that | 1089 | For the cross compiler, the class creates a ``tar.gz`` file that |
@@ -856,8 +1091,8 @@ contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which | |||
856 | is the version of the cross-compiler used in the cross-development | 1091 | is the version of the cross-compiler used in the cross-development |
857 | toolchain, accordingly. | 1092 | toolchain, accordingly. |
858 | 1093 | ||
859 | The class handles all three different compile stages (i.e native | 1094 | The class handles all three different compile stages (i.e native, |
860 | ,cross-kernel and target) and creates the necessary environment | 1095 | cross-kernel and target) and creates the necessary environment |
861 | ``tar.gz`` file to be used by the remote machines. The class also | 1096 | ``tar.gz`` file to be used by the remote machines. The class also |
862 | supports SDK generation. | 1097 | supports SDK generation. |
863 | 1098 | ||
@@ -867,67 +1102,66 @@ using ``which``. If :term:`ICECC_ENV_EXEC` is set | |||
867 | in your ``local.conf`` file, the variable should point to the | 1102 | 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 | 1103 | ``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 | 1104 | a user-provided script, the build system uses the default script |
870 | provided by the recipe ``icecc-create-env-native.bb``. | 1105 | provided by the recipe :oe_git:`icecc-create-env_0.1.bb |
1106 | </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`. | ||
871 | 1107 | ||
872 | .. note:: | 1108 | .. note:: |
873 | 1109 | ||
874 | This script is a modified version and not the one that comes with | 1110 | This script is a modified version and not the one that comes with |
875 | icecc. | 1111 | ``icecream``. |
876 | 1112 | ||
877 | If you do not want the Icecream distributed compile support to apply to | 1113 | If you do not want the Icecream distributed compile support to apply to |
878 | specific recipes or classes, you can effectively "blacklist" them by | 1114 | specific recipes or classes, you can ask them to be ignored by Icecream |
879 | listing the recipes and classes using the | 1115 | by listing the recipes and classes using the |
880 | :term:`ICECC_USER_PACKAGE_BL` and | 1116 | :term:`ICECC_RECIPE_DISABLE` and |
881 | :term:`ICECC_USER_CLASS_BL`, variables, | 1117 | :term:`ICECC_CLASS_DISABLE` variables, |
882 | respectively, in your ``local.conf`` file. Doing so causes the | 1118 | respectively, in your ``local.conf`` file. Doing so causes the |
883 | OpenEmbedded build system to handle these compilations locally. | 1119 | OpenEmbedded build system to handle these compilations locally. |
884 | 1120 | ||
885 | Additionally, you can list recipes using the | 1121 | Additionally, you can list recipes using the |
886 | :term:`ICECC_USER_PACKAGE_WL` variable in | 1122 | :term:`ICECC_RECIPE_ENABLE` variable in |
887 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes | 1123 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes |
888 | using an empty :term:`PARALLEL_MAKE` variable. | 1124 | using an empty :term:`PARALLEL_MAKE` variable. |
889 | 1125 | ||
890 | Inheriting the ``icecc`` class changes all sstate signatures. | 1126 | Inheriting the :ref:`ref-classes-icecc` class changes all sstate signatures. |
891 | Consequently, if a development team has a dedicated build system that | 1127 | Consequently, if a development team has a dedicated build system that |
892 | populates :term:`SSTATE_MIRRORS` and they want to | 1128 | populates :term:`SSTATE_MIRRORS` and they want to |
893 | reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build | 1129 | reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build |
894 | system need to either inherit the ``icecc`` class or nobody should. | 1130 | system need to either inherit the :ref:`ref-classes-icecc` class or nobody should. |
895 | 1131 | ||
896 | At the distribution level, you can inherit the ``icecc`` class to be | 1132 | 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 | 1133 | sure that all builders start with the same sstate signatures. After |
898 | inheriting the class, you can then disable the feature by setting the | 1134 | inheriting the class, you can then disable the feature by setting the |
899 | :term:`ICECC_DISABLED` variable to "1" as follows: | 1135 | :term:`ICECC_DISABLED` variable to "1" as follows:: |
900 | :: | ||
901 | 1136 | ||
902 | INHERIT_DISTRO_append = " icecc" | 1137 | INHERIT_DISTRO:append = " icecc" |
903 | ICECC_DISABLED ??= "1" | 1138 | ICECC_DISABLED ??= "1" |
904 | 1139 | ||
905 | This practice | 1140 | This practice |
906 | makes sure everyone is using the same signatures but also requires | 1141 | makes sure everyone is using the same signatures but also requires |
907 | individuals that do want to use Icecream to enable the feature | 1142 | individuals that do want to use Icecream to enable the feature |
908 | individually as follows in your ``local.conf`` file: | 1143 | individually as follows in your ``local.conf`` file:: |
909 | :: | ||
910 | 1144 | ||
911 | ICECC_DISABLED = "" | 1145 | ICECC_DISABLED = "" |
912 | 1146 | ||
913 | .. _ref-classes-image: | 1147 | .. _ref-classes-image: |
914 | 1148 | ||
915 | ``image.bbclass`` | 1149 | ``image`` |
916 | ================= | 1150 | ========= |
917 | 1151 | ||
918 | The ``image`` class helps support creating images in different formats. | 1152 | 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 | 1153 | First, the root filesystem is created from packages using one of the |
920 | ``rootfs*.bbclass`` files (depending on the package format used) and | 1154 | ``rootfs*.bbclass`` files (depending on the package format used) and |
921 | then one or more image files are created. | 1155 | then one or more image files are created. |
922 | 1156 | ||
923 | - The ``IMAGE_FSTYPES`` variable controls the types of images to | 1157 | - The :term:`IMAGE_FSTYPES` variable controls the types of images to |
924 | generate. | 1158 | generate. |
925 | 1159 | ||
926 | - The ``IMAGE_INSTALL`` variable controls the list of packages to | 1160 | - The :term:`IMAGE_INSTALL` variable controls the list of packages to |
927 | install into the image. | 1161 | install into the image. |
928 | 1162 | ||
929 | For information on customizing images, see the | 1163 | For information on customizing images, see the |
930 | ":ref:`dev-manual/common-tasks:customizing images`" section | 1164 | ":ref:`dev-manual/customizing-images:customizing images`" section |
931 | in the Yocto Project Development Tasks Manual. For information on how | 1165 | in the Yocto Project Development Tasks Manual. For information on how |
932 | images are created, see the | 1166 | images are created, see the |
933 | ":ref:`overview-manual/concepts:images`" section in the | 1167 | ":ref:`overview-manual/concepts:images`" section in the |
@@ -935,49 +1169,66 @@ Yocto Project Overview and Concepts Manual. | |||
935 | 1169 | ||
936 | .. _ref-classes-image-buildinfo: | 1170 | .. _ref-classes-image-buildinfo: |
937 | 1171 | ||
938 | ``image-buildinfo.bbclass`` | 1172 | ``image-buildinfo`` |
939 | =========================== | 1173 | =================== |
1174 | |||
1175 | The :ref:`ref-classes-image-buildinfo` class writes a plain text file containing | ||
1176 | build information to the target filesystem at ``${sysconfdir}/buildinfo`` | ||
1177 | by default (as specified by :term:`IMAGE_BUILDINFO_FILE`). | ||
1178 | This can be useful for manually determining the origin of any given | ||
1179 | image. It writes out two sections: | ||
1180 | |||
1181 | #. `Build Configuration`: a list of variables and their values (specified | ||
1182 | by :term:`IMAGE_BUILDINFO_VARS`, which defaults to :term:`DISTRO` and | ||
1183 | :term:`DISTRO_VERSION`) | ||
940 | 1184 | ||
941 | The ``image-buildinfo`` class writes information to the target | 1185 | #. `Layer Revisions`: the revisions of all of the layers used in the |
942 | filesystem on ``/etc/build``. | 1186 | build. |
1187 | |||
1188 | Additionally, when building an SDK it will write the same contents | ||
1189 | to ``/buildinfo`` by default (as specified by | ||
1190 | :term:`SDK_BUILDINFO_FILE`). | ||
943 | 1191 | ||
944 | .. _ref-classes-image_types: | 1192 | .. _ref-classes-image_types: |
945 | 1193 | ||
946 | ``image_types.bbclass`` | 1194 | ``image_types`` |
947 | ======================= | 1195 | =============== |
948 | 1196 | ||
949 | The ``image_types`` class defines all of the standard image output types | 1197 | The :ref:`ref-classes-image_types` class defines all of the standard image output types |
950 | that you can enable through the | 1198 | that you can enable through the |
951 | :term:`IMAGE_FSTYPES` variable. You can use this | 1199 | :term:`IMAGE_FSTYPES` variable. You can use this |
952 | class as a reference on how to add support for custom image output | 1200 | class as a reference on how to add support for custom image output |
953 | types. | 1201 | types. |
954 | 1202 | ||
955 | By default, the :ref:`image <ref-classes-image>` class automatically | 1203 | By default, the :ref:`ref-classes-image` class automatically |
956 | enables the ``image_types`` class. The ``image`` class uses the | 1204 | enables the :ref:`ref-classes-image_types` class. The :ref:`ref-classes-image` class uses the |
957 | ``IMGCLASSES`` variable as follows: | 1205 | ``IMGCLASSES`` variable as follows:: |
958 | :: | ||
959 | 1206 | ||
960 | IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" | 1207 | IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" |
961 | IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" | 1208 | # Only Linux SDKs support populate_sdk_ext, fall back to populate_sdk_base |
1209 | # in the non-Linux SDK_OS case, such as mingw32 | ||
1210 | inherit populate_sdk_base | ||
1211 | IMGCLASSES += "${@['', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" | ||
962 | IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" | 1212 | IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" |
963 | IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" | 1213 | IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" |
964 | IMGCLASSES += "image_types_wic" | 1214 | IMGCLASSES += "image_types_wic" |
965 | IMGCLASSES += "rootfs-postcommands" | 1215 | IMGCLASSES += "rootfs-postcommands" |
966 | IMGCLASSES += "image-postinst-intercepts" | 1216 | IMGCLASSES += "image-postinst-intercepts" |
967 | inherit ${IMGCLASSES} | 1217 | IMGCLASSES += "overlayfs-etc" |
1218 | inherit_defer ${IMGCLASSES} | ||
968 | 1219 | ||
969 | The ``image_types`` class also handles conversion and compression of images. | 1220 | The :ref:`ref-classes-image_types` class also handles conversion and compression of images. |
970 | 1221 | ||
971 | .. note:: | 1222 | .. note:: |
972 | 1223 | ||
973 | To build a VMware VMDK image, you need to add "wic.vmdk" to | 1224 | 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 | 1225 | :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. | 1226 | Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. |
976 | 1227 | ||
977 | .. _ref-classes-image-live: | 1228 | .. _ref-classes-image-live: |
978 | 1229 | ||
979 | ``image-live.bbclass`` | 1230 | ``image-live`` |
980 | ====================== | 1231 | ============== |
981 | 1232 | ||
982 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live | 1233 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live |
983 | images contain syslinux for legacy booting, as well as the bootloader | 1234 | images contain syslinux for legacy booting, as well as the bootloader |
@@ -987,43 +1238,12 @@ specified by :term:`EFI_PROVIDER` if | |||
987 | Normally, you do not use this class directly. Instead, you add "live" to | 1238 | Normally, you do not use this class directly. Instead, you add "live" to |
988 | :term:`IMAGE_FSTYPES`. | 1239 | :term:`IMAGE_FSTYPES`. |
989 | 1240 | ||
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: | 1241 | .. _ref-classes-insane: |
1022 | 1242 | ||
1023 | ``insane.bbclass`` | 1243 | ``insane`` |
1024 | ================== | 1244 | ========== |
1025 | 1245 | ||
1026 | The ``insane`` class adds a step to the package generation process so | 1246 | 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 | 1247 | that output quality assurance checks are generated by the OpenEmbedded |
1028 | build system. A range of checks are performed that check the build's | 1248 | build system. A range of checks are performed that check the build's |
1029 | output for common problems that show up during runtime. Distribution | 1249 | output for common problems that show up during runtime. Distribution |
@@ -1043,17 +1263,16 @@ configuration). However, to skip one or more checks in recipes, you | |||
1043 | should use :term:`INSANE_SKIP`. For example, to skip | 1263 | should use :term:`INSANE_SKIP`. For example, to skip |
1044 | the check for symbolic link ``.so`` files in the main package of a | 1264 | 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 | 1265 | recipe, add the following to the recipe. You need to realize that the |
1046 | package name override, in this example ``${PN}``, must be used: | 1266 | package name override, in this example ``${PN}``, must be used:: |
1047 | :: | ||
1048 | 1267 | ||
1049 | INSANE_SKIP_${PN} += "dev-so" | 1268 | INSANE_SKIP:${PN} += "dev-so" |
1050 | 1269 | ||
1051 | Please keep in mind that the QA checks | 1270 | Please keep in mind that the QA checks |
1052 | exist in order to detect real or potential problems in the packaged | 1271 | are meant to detect real or potential problems in the packaged |
1053 | output. So exercise caution when disabling these checks. | 1272 | output. So exercise caution when disabling these checks. |
1054 | 1273 | ||
1055 | The following list shows the tests you can list with the ``WARN_QA`` and | 1274 | The tests you can list with the :term:`WARN_QA` and |
1056 | ``ERROR_QA`` variables: | 1275 | :term:`ERROR_QA` variables are: |
1057 | 1276 | ||
1058 | - ``already-stripped:`` Checks that produced binaries have not | 1277 | - ``already-stripped:`` Checks that produced binaries have not |
1059 | already been stripped prior to the build system extracting debug | 1278 | already been stripped prior to the build system extracting debug |
@@ -1070,8 +1289,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. | 1289 | software, like bootloaders, might need to bypass this check. |
1071 | 1290 | ||
1072 | - ``buildpaths:`` Checks for paths to locations on the build host | 1291 | - ``buildpaths:`` Checks for paths to locations on the build host |
1073 | inside the output files. Currently, this test triggers too many false | 1292 | inside the output files. Not only can these leak information about |
1074 | positives and thus is not normally enabled. | 1293 | the build environment, they also hinder binary reproducibility. |
1075 | 1294 | ||
1076 | - ``build-deps:`` Determines if a build-time dependency that is | 1295 | - ``build-deps:`` Determines if a build-time dependency that is |
1077 | specified through :term:`DEPENDS`, explicit | 1296 | specified through :term:`DEPENDS`, explicit |
@@ -1084,20 +1303,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 | 1303 | the package is installed into the image during the |
1085 | :ref:`ref-tasks-rootfs` task because the auto-detected | 1304 | :ref:`ref-tasks-rootfs` task because the auto-detected |
1086 | dependency was not satisfied. An example of this would be where the | 1305 | dependency was not satisfied. An example of this would be where the |
1087 | :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically | 1306 | :ref:`ref-classes-update-rc.d` class automatically |
1088 | adds a dependency on the ``initscripts-functions`` package to | 1307 | adds a dependency on the ``initscripts-functions`` package to |
1089 | packages that install an initscript that refers to | 1308 | packages that install an initscript that refers to |
1090 | ``/etc/init.d/functions``. The recipe should really have an explicit | 1309 | ``/etc/init.d/functions``. The recipe should really have an explicit |
1091 | ``RDEPENDS`` for the package in question on ``initscripts-functions`` | 1310 | :term:`RDEPENDS` for the package in question on ``initscripts-functions`` |
1092 | so that the OpenEmbedded build system is able to ensure that the | 1311 | so that the OpenEmbedded build system is able to ensure that the |
1093 | ``initscripts`` recipe is actually built and thus the | 1312 | ``initscripts`` recipe is actually built and thus the |
1094 | ``initscripts-functions`` package is made available. | 1313 | ``initscripts-functions`` package is made available. |
1095 | 1314 | ||
1315 | - ``configure-gettext:`` Checks that if a recipe is building something | ||
1316 | that uses automake and the automake files contain an ``AM_GNU_GETTEXT`` | ||
1317 | directive, that the recipe also inherits the :ref:`ref-classes-gettext` | ||
1318 | class to ensure that gettext is available during the build. | ||
1319 | |||
1096 | - ``compile-host-path:`` Checks the | 1320 | - ``compile-host-path:`` Checks the |
1097 | :ref:`ref-tasks-compile` log for indications that | 1321 | :ref:`ref-tasks-compile` log for indications that |
1098 | paths to locations on the build host were used. Using such paths | 1322 | paths to locations on the build host were used. Using such paths |
1099 | might result in host contamination of the build output. | 1323 | might result in host contamination of the build output. |
1100 | 1324 | ||
1325 | - ``cve_status_not_in_db:`` Checks for each component if CVEs that are ignored | ||
1326 | via :term:`CVE_STATUS`, that those are (still) reported for this component | ||
1327 | in the NIST database. If not, a warning is printed. This check is disabled | ||
1328 | by default. | ||
1329 | |||
1101 | - ``debug-deps:`` Checks that all packages except ``-dbg`` packages | 1330 | - ``debug-deps:`` Checks that all packages except ``-dbg`` packages |
1102 | do not depend on ``-dbg`` packages, which would cause a packaging | 1331 | do not depend on ``-dbg`` packages, which would cause a packaging |
1103 | bug. | 1332 | bug. |
@@ -1128,10 +1357,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 | 1357 | - ``dev-so:`` Checks that the ``.so`` symbolic links are in the |
1129 | ``-dev`` package and not in any of the other packages. In general, | 1358 | ``-dev`` package and not in any of the other packages. In general, |
1130 | these symlinks are only useful for development purposes. Thus, the | 1359 | these symlinks are only useful for development purposes. Thus, the |
1131 | ``-dev`` package is the correct location for them. Some very rare | 1360 | ``-dev`` package is the correct location for them. In very rare |
1132 | cases do exist for dynamically loaded modules where these symlinks | 1361 | cases, such as dynamically loaded modules, these symlinks |
1133 | are needed instead in the main package. | 1362 | are needed instead in the main package. |
1134 | 1363 | ||
1364 | - ``empty-dirs:`` Checks that packages are not installing files to | ||
1365 | directories that are normally expected to be empty (such as ``/tmp``) | ||
1366 | The list of directories that are checked is specified by the | ||
1367 | :term:`QA_EMPTY_DIRS` variable. | ||
1368 | |||
1135 | - ``file-rdeps:`` Checks that file-level dependencies identified by | 1369 | - ``file-rdeps:`` Checks that file-level dependencies identified by |
1136 | the OpenEmbedded build system at packaging time are satisfied. For | 1370 | the OpenEmbedded build system at packaging time are satisfied. For |
1137 | example, a shell script might start with the line ``#!/bin/bash``. | 1371 | example, a shell script might start with the line ``#!/bin/bash``. |
@@ -1166,12 +1400,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. | 1400 | might result in host contamination of the build output. |
1167 | 1401 | ||
1168 | - ``installed-vs-shipped:`` Reports when files have been installed | 1402 | - ``installed-vs-shipped:`` Reports when files have been installed |
1169 | within ``do_install`` but have not been included in any package by | 1403 | 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 | 1404 | 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 | 1405 | 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 | 1406 | build process. Ideally, all installed files should be packaged or not |
1173 | installed at all. These files can be deleted at the end of | 1407 | installed at all. These files can be deleted at the end of |
1174 | ``do_install`` if the files are not needed in any package. | 1408 | :ref:`ref-tasks-install` if the files are not needed in any package. |
1175 | 1409 | ||
1176 | - ``invalid-chars:`` Checks that the recipe metadata variables | 1410 | - ``invalid-chars:`` Checks that the recipe metadata variables |
1177 | :term:`DESCRIPTION`, | 1411 | :term:`DESCRIPTION`, |
@@ -1181,18 +1415,17 @@ The following list shows the tests you can list with the ``WARN_QA`` and | |||
1181 | 1415 | ||
1182 | - ``invalid-packageconfig:`` Checks that no undefined features are | 1416 | - ``invalid-packageconfig:`` Checks that no undefined features are |
1183 | being added to :term:`PACKAGECONFIG`. For | 1417 | being added to :term:`PACKAGECONFIG`. For |
1184 | example, any name "foo" for which the following form does not exist: | 1418 | example, any name "foo" for which the following form does not exist:: |
1185 | :: | ||
1186 | 1419 | ||
1187 | PACKAGECONFIG[foo] = "..." | 1420 | PACKAGECONFIG[foo] = "..." |
1188 | 1421 | ||
1189 | - ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` | 1422 | - ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la`` |
1190 | file containing these paths is incorrect since ``libtool`` adds the | 1423 | file containing these paths is incorrect since ``libtool`` adds the |
1191 | correct sysroot prefix when using the files automatically itself. | 1424 | correct sysroot prefix when using the files automatically itself. |
1192 | 1425 | ||
1193 | - ``ldflags:`` Ensures that the binaries were linked with the | 1426 | - ``ldflags:`` Ensures that the binaries were linked with the |
1194 | :term:`LDFLAGS` options provided by the build system. | 1427 | :term:`LDFLAGS` options provided by the build system. |
1195 | If this test fails, check that the ``LDFLAGS`` variable is being | 1428 | If this test fails, check that the :term:`LDFLAGS` variable is being |
1196 | passed to the linker command. | 1429 | passed to the linker command. |
1197 | 1430 | ||
1198 | - ``libdir:`` Checks for libraries being installed into incorrect | 1431 | - ``libdir:`` Checks for libraries being installed into incorrect |
@@ -1205,11 +1438,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`` | 1438 | ``/usr/libexec``. This check is not performed if the ``libexecdir`` |
1206 | variable has been set explicitly to ``/usr/libexec``. | 1439 | variable has been set explicitly to ``/usr/libexec``. |
1207 | 1440 | ||
1441 | - ``mime:`` Check that if a package contains mime type files (``.xml`` | ||
1442 | files in ``${datadir}/mime/packages``) that the recipe also inherits | ||
1443 | the :ref:`ref-classes-mime` class in order to ensure that these get | ||
1444 | properly installed. | ||
1445 | |||
1446 | - ``mime-xdg:`` Checks that if a package contains a .desktop file with a | ||
1447 | 'MimeType' key present, that the recipe inherits the | ||
1448 | :ref:`ref-classes-mime-xdg` class that is required in order for that | ||
1449 | to be activated. | ||
1450 | |||
1451 | - ``missing-update-alternatives:`` Check that if a recipe sets the | ||
1452 | :term:`ALTERNATIVE` variable that the recipe also inherits | ||
1453 | :ref:`ref-classes-update-alternatives` such that the alternative will | ||
1454 | be correctly set up. | ||
1455 | |||
1208 | - ``packages-list:`` Checks for the same package being listed | 1456 | - ``packages-list:`` Checks for the same package being listed |
1209 | multiple times through the :term:`PACKAGES` variable | 1457 | multiple times through the :term:`PACKAGES` variable |
1210 | value. Installing the package in this manner can cause errors during | 1458 | value. Installing the package in this manner can cause errors during |
1211 | packaging. | 1459 | packaging. |
1212 | 1460 | ||
1461 | - ``patch-fuzz:`` Checks for fuzz in patch files that may allow | ||
1462 | them to apply incorrectly if the underlying code changes. | ||
1463 | |||
1464 | - ``patch-status-core:`` Checks that the Upstream-Status is specified | ||
1465 | and valid in the headers of patches for recipes in the OE-Core layer. | ||
1466 | |||
1467 | - ``patch-status-noncore:`` Checks that the Upstream-Status is specified | ||
1468 | and valid in the headers of patches for recipes in layers other than | ||
1469 | OE-Core. | ||
1470 | |||
1471 | - ``perllocalpod:`` Checks for ``perllocal.pod`` being erroneously | ||
1472 | installed and packaged by a recipe. | ||
1473 | |||
1213 | - ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an | 1474 | - ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an |
1214 | invalid format. | 1475 | invalid format. |
1215 | 1476 | ||
@@ -1232,7 +1493,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 | 1493 | invalid characters (i.e. characters other than 0-9, a-z, ., +, and |
1233 | -). | 1494 | -). |
1234 | 1495 | ||
1235 | - ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is | 1496 | - ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is |
1236 | undefined during :ref:`ref-tasks-package`. | 1497 | undefined during :ref:`ref-tasks-package`. |
1237 | 1498 | ||
1238 | - ``pkgvarcheck:`` Checks through the variables | 1499 | - ``pkgvarcheck:`` Checks through the variables |
@@ -1252,23 +1513,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 | 1513 | - ``pn-overrides:`` Checks that a recipe does not have a name |
1253 | (:term:`PN`) value that appears in | 1514 | (:term:`PN`) value that appears in |
1254 | :term:`OVERRIDES`. If a recipe is named such that | 1515 | :term:`OVERRIDES`. If a recipe is named such that |
1255 | its ``PN`` value matches something already in ``OVERRIDES`` (e.g. | 1516 | its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g. |
1256 | ``PN`` happens to be the same as :term:`MACHINE` or | 1517 | :term:`PN` happens to be the same as :term:`MACHINE` or |
1257 | :term:`DISTRO`), it can have unexpected consequences. | 1518 | :term:`DISTRO`), it can have unexpected consequences. |
1258 | For example, assignments such as ``FILES_${PN} = "xyz"`` effectively | 1519 | For example, assignments such as ``FILES:${PN} = "xyz"`` effectively |
1259 | turn into ``FILES = "xyz"``. | 1520 | turn into ``FILES = "xyz"``. |
1260 | 1521 | ||
1261 | - ``rpaths:`` Checks for rpaths in the binaries that contain build | 1522 | - ``rpaths:`` Checks for rpaths in the binaries that contain build |
1262 | system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` | 1523 | system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath`` |
1263 | options are being passed to the linker commands and your binaries | 1524 | options are being passed to the linker commands and your binaries |
1264 | have potential security issues. | 1525 | have potential security issues. |
1265 | 1526 | ||
1527 | - ``shebang-size:`` Check that the shebang line (``#!`` in the first line) | ||
1528 | in a packaged script is not longer than 128 characters, which can cause | ||
1529 | an error at runtime depending on the operating system. | ||
1530 | |||
1266 | - ``split-strip:`` Reports that splitting or stripping debug symbols | 1531 | - ``split-strip:`` Reports that splitting or stripping debug symbols |
1267 | from binaries has failed. | 1532 | from binaries has failed. |
1268 | 1533 | ||
1269 | - ``staticdev:`` Checks for static library files (``*.a``) in | 1534 | - ``staticdev:`` Checks for static library files (``*.a``) in |
1270 | non-``staticdev`` packages. | 1535 | non-``staticdev`` packages. |
1271 | 1536 | ||
1537 | - ``src-uri-bad:`` Checks that the :term:`SRC_URI` value set by a recipe | ||
1538 | does not contain a reference to ``${PN}`` (instead of the correct | ||
1539 | ``${BPN}``) nor refers to unstable Github archive tarballs. | ||
1540 | |||
1272 | - ``symlink-to-sysroot:`` Checks for symlinks in packages that point | 1541 | - ``symlink-to-sysroot:`` Checks for symlinks in packages that point |
1273 | into :term:`TMPDIR` on the host. Such symlinks will | 1542 | into :term:`TMPDIR` on the host. Such symlinks will |
1274 | work on the host, but are clearly invalid when running on the target. | 1543 | work on the host, but are clearly invalid when running on the target. |
@@ -1279,33 +1548,52 @@ 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 | 1548 | ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance |
1280 | issues. | 1549 | issues. |
1281 | 1550 | ||
1551 | - ``unhandled-features-check:`` check that if one of the variables that | ||
1552 | the :ref:`ref-classes-features_check` class supports (e.g. | ||
1553 | :term:`REQUIRED_DISTRO_FEATURES`) is set by a recipe, then the recipe | ||
1554 | also inherits :ref:`ref-classes-features_check` in order for the | ||
1555 | requirement to actually work. | ||
1556 | |||
1557 | - ``unimplemented-ptest:`` Checks that ptests are implemented for upstream | ||
1558 | tests. | ||
1559 | |||
1282 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying | 1560 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying |
1283 | for a package are also declared on the recipe level (i.e. any license | 1561 | for a package are also declared on the recipe level (i.e. any license |
1284 | in ``LICENSE_*`` should appear in :term:`LICENSE`). | 1562 | in ``LICENSE:*`` should appear in :term:`LICENSE`). |
1285 | 1563 | ||
1286 | - ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) | 1564 | - ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) |
1287 | in the binaries that by default on a standard system are searched by | 1565 | 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 | 1566 | the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will |
1289 | not cause any breakage, they do waste space and are unnecessary. | 1567 | not cause any breakage, they do waste space and are unnecessary. |
1290 | 1568 | ||
1569 | - ``usrmerge:`` If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this | ||
1570 | check will ensure that no package installs files to root (``/bin``, | ||
1571 | ``/sbin``, ``/lib``, ``/lib64``) directories. | ||
1572 | |||
1291 | - ``var-undefined:`` Reports when variables fundamental to packaging | 1573 | - ``var-undefined:`` Reports when variables fundamental to packaging |
1292 | (i.e. :term:`WORKDIR`, | 1574 | (i.e. :term:`WORKDIR`, |
1293 | :term:`DEPLOY_DIR`, :term:`D`, | 1575 | :term:`DEPLOY_DIR`, :term:`D`, |
1294 | :term:`PN`, and :term:`PKGD`) are undefined | 1576 | :term:`PN`, and :term:`PKGD`) are undefined |
1295 | during :ref:`ref-tasks-package`. | 1577 | during :ref:`ref-tasks-package`. |
1296 | 1578 | ||
1297 | - ``version-going-backwards:`` If Build History is enabled, reports | 1579 | - ``version-going-backwards:`` If the :ref:`ref-classes-buildhistory` |
1298 | when a package being written out has a lower version than the | 1580 | 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 | 1581 | version than the previously written package under the same name. If |
1300 | output packages into a feed and upgrading packages on a target system | 1582 | 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 | 1583 | 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 | 1584 | backwards can result in the target system not correctly upgrading to |
1303 | the package. | 1585 | the "new" version of the package. |
1304 | 1586 | ||
1305 | .. note:: | 1587 | .. note:: |
1306 | 1588 | ||
1307 | If you are not using runtime package management on your target | 1589 | This is only relevant when you are using runtime package management |
1308 | system, then you do not need to worry about this situation. | 1590 | on your target system. |
1591 | |||
1592 | - ``virtual-slash:`` Checks to see if ``virtual/`` is being used in | ||
1593 | :term:`RDEPENDS` or :term:`RPROVIDES`, which is not good practice --- | ||
1594 | ``virtual/`` is a convention intended for use in the build context | ||
1595 | (i.e. :term:`PROVIDES` and :term:`DEPENDS`) rather than the runtime | ||
1596 | context. | ||
1309 | 1597 | ||
1310 | - ``xorg-driver-abi:`` Checks that all packages containing Xorg | 1598 | - ``xorg-driver-abi:`` Checks that all packages containing Xorg |
1311 | drivers have ABI dependencies. The ``xserver-xorg`` recipe provides | 1599 | drivers have ABI dependencies. The ``xserver-xorg`` recipe provides |
@@ -1315,184 +1603,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 | 1603 | automatically get these versions. Consequently, you should only need |
1316 | to explicitly add dependencies to binary driver recipes. | 1604 | to explicitly add dependencies to binary driver recipes. |
1317 | 1605 | ||
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: | 1606 | .. _ref-classes-kernel: |
1329 | 1607 | ||
1330 | ``kernel.bbclass`` | 1608 | ``kernel`` |
1331 | ================== | 1609 | ========== |
1332 | 1610 | ||
1333 | The ``kernel`` class handles building Linux kernels. The class contains | 1611 | 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 | 1612 | 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 | 1613 | :term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds |
1336 | using the :ref:`module <ref-classes-module>` class. | 1614 | using the :ref:`ref-classes-module` class. |
1337 | 1615 | ||
1338 | This means that each built kernel module is packaged separately and | 1616 | 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. | 1617 | :ref:`ref-tasks-configure` copies it as ``.config`` in the build directory, |
1340 | If all modules are required, then installing the ``kernel-modules`` | 1618 | so it is automatically used as the kernel configuration for the build. This |
1341 | package installs all packages with modules and various other kernel | 1619 | copy is not performed in case ``.config`` already exists there: this allows |
1342 | packages such as ``kernel-vmlinux``. | 1620 | recipes to produce a configuration by other means in |
1343 | 1621 | ``do_configure:prepend``. | |
1344 | The ``kernel`` class contains logic that allows you to embed an initial | 1622 | |
1345 | RAM filesystem (initramfs) image when you build the kernel image. For | 1623 | Each built kernel module is packaged separately and inter-module |
1346 | information on how to build an initramfs, see the | 1624 | 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 | 1625 | are required, then installing the ``kernel-modules`` package installs all |
1626 | packages with modules and various other kernel packages such as | ||
1627 | ``kernel-vmlinux``. | ||
1628 | |||
1629 | The :ref:`ref-classes-kernel` class contains logic that allows you to embed an initial | ||
1630 | RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For | ||
1631 | information on how to build an :term:`Initramfs`, see the | ||
1632 | ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section in | ||
1348 | the Yocto Project Development Tasks Manual. | 1633 | the Yocto Project Development Tasks Manual. |
1349 | 1634 | ||
1350 | Various other classes are used by the ``kernel`` and ``module`` classes | 1635 | 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>`, | 1636 | internally including the :ref:`ref-classes-kernel-arch`, :ref:`ref-classes-module-base`, and |
1352 | :ref:`module-base <ref-classes-module-base>`, and | 1637 | :ref:`ref-classes-linux-kernel-base` classes. |
1353 | :ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes. | ||
1354 | 1638 | ||
1355 | .. _ref-classes-kernel-arch: | 1639 | .. _ref-classes-kernel-arch: |
1356 | 1640 | ||
1357 | ``kernel-arch.bbclass`` | 1641 | ``kernel-arch`` |
1358 | ======================= | 1642 | =============== |
1359 | 1643 | ||
1360 | The ``kernel-arch`` class sets the ``ARCH`` environment variable for | 1644 | The :ref:`ref-classes-kernel-arch` class sets the ``ARCH`` environment variable for |
1361 | Linux kernel compilation (including modules). | 1645 | Linux kernel compilation (including modules). |
1362 | 1646 | ||
1363 | .. _ref-classes-kernel-devicetree: | 1647 | .. _ref-classes-kernel-devicetree: |
1364 | 1648 | ||
1365 | ``kernel-devicetree.bbclass`` | 1649 | ``kernel-devicetree`` |
1366 | ============================= | 1650 | ===================== |
1367 | 1651 | ||
1368 | The ``kernel-devicetree`` class, which is inherited by the | 1652 | The :ref:`ref-classes-kernel-devicetree` class, which is inherited by the |
1369 | :ref:`kernel <ref-classes-kernel>` class, supports device tree | 1653 | :ref:`ref-classes-kernel` class, supports device tree generation. |
1370 | generation. | 1654 | |
1655 | Its behavior is mainly controlled by the following variables: | ||
1656 | |||
1657 | - :term:`KERNEL_DEVICETREE_BUNDLE`: whether to bundle the kernel and device tree | ||
1658 | - :term:`KERNEL_DTBDEST`: directory where to install DTB files | ||
1659 | - :term:`KERNEL_DTBVENDORED`: whether to keep vendor subdirectories | ||
1660 | - :term:`KERNEL_DTC_FLAGS`: flags for ``dtc``, the Device Tree Compiler | ||
1661 | - :term:`KERNEL_PACKAGE_NAME`: base name of the kernel packages | ||
1371 | 1662 | ||
1372 | .. _ref-classes-kernel-fitimage: | 1663 | .. _ref-classes-kernel-fitimage: |
1373 | 1664 | ||
1374 | ``kernel-fitimage.bbclass`` | 1665 | ``kernel-fitimage`` |
1375 | =========================== | 1666 | =================== |
1376 | 1667 | ||
1377 | The ``kernel-fitimage`` class provides support to pack a kernel image, | 1668 | The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image, |
1378 | device trees, a U-boot script, a Initramfs bundle and a RAM disk | 1669 | device trees, a U-boot script, an :term:`Initramfs` bundle and a RAM disk |
1379 | into a single FIT image. In theory, a FIT image can support any number | 1670 | into a single FIT image. In theory, a FIT image can support any number |
1380 | of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees. | 1671 | of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees. |
1381 | However, ``kernel-fitimage`` currently only supports | 1672 | However, :ref:`ref-classes-kernel-fitimage` currently only supports |
1382 | limited usescases: just one kernel image, an optional U-boot script, | 1673 | limited usecases: just one kernel image, an optional U-boot script, |
1383 | an optional Initramfs bundle, an optional RAM disk, and any number of | 1674 | an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of |
1384 | device tree. | 1675 | device trees. |
1385 | 1676 | ||
1386 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` | 1677 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` |
1387 | is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` | 1678 | is set to include ":ref:`ref-classes-kernel-fitimage`" and one of :term:`KERNEL_IMAGETYPE`, |
1388 | is set to "fitImage". | 1679 | :term:`KERNEL_ALT_IMAGETYPE` or :term:`KERNEL_IMAGETYPES` to include "fitImage". |
1389 | 1680 | ||
1390 | The options for the device tree compiler passed to ``mkimage -D`` | 1681 | The options for the device tree compiler passed to ``mkimage -D`` |
1391 | when creating the FIT image are specified using the | 1682 | when creating the FIT image are specified using the |
1392 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. | 1683 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. |
1393 | 1684 | ||
1394 | Only a single kernel can be added to the FIT image created by | 1685 | Only a single kernel can be added to the FIT image created by |
1395 | ``kernel-fitimage`` and the kernel image in FIT is mandatory. The | 1686 | :ref:`ref-classes-kernel-fitimage` and the kernel image in FIT is mandatory. The |
1396 | address where the kernel image is to be loaded by U-Boot is | 1687 | address where the kernel image is to be loaded by U-Boot is |
1397 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by | 1688 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by |
1398 | :term:`UBOOT_ENTRYPOINT`. | 1689 | :term:`UBOOT_ENTRYPOINT`. Setting :term:`FIT_ADDRESS_CELLS` to "2" |
1690 | is necessary if such addresses are 64 bit ones. | ||
1399 | 1691 | ||
1400 | Multiple device trees can be added to the FIT image created by | 1692 | Multiple device trees can be added to the FIT image created by |
1401 | ``kernel-fitimage`` and the device tree is optional. | 1693 | :ref:`ref-classes-kernel-fitimage` and the device tree is optional. |
1402 | The address where the device tree is to be loaded by U-Boot is | 1694 | The address where the device tree is to be loaded by U-Boot is |
1403 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays | 1695 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays |
1404 | and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. | 1696 | and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. |
1405 | 1697 | ||
1406 | Only a single RAM disk can be added to the FIT image created by | 1698 | Only a single RAM disk can be added to the FIT image created by |
1407 | ``kernel-fitimage`` and the RAM disk in FIT is optional. | 1699 | :ref:`ref-classes-kernel-fitimage` and the RAM disk in FIT is optional. |
1408 | The address where the RAM disk image is to be loaded by U-Boot | 1700 | The address where the RAM disk image is to be loaded by U-Boot |
1409 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by | 1701 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by |
1410 | :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when | 1702 | :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to the FIT image when |
1411 | :term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` | 1703 | :term:`INITRAMFS_IMAGE` is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE` |
1412 | is set to 0. | 1704 | is not set to 1. |
1413 | 1705 | ||
1414 | Only a single Initramfs bundle can be added to the FIT image created by | 1706 | Only a single :term:`Initramfs` bundle can be added to the FIT image created by |
1415 | ``kernel-fitimage`` and the Initramfs bundle in FIT is optional. | 1707 | :ref:`ref-classes-kernel-fitimage` and the :term:`Initramfs` bundle in FIT is optional. |
1416 | In case of Initramfs, the kernel is configured to be bundled with the rootfs | 1708 | In case of :term:`Initramfs`, the kernel is configured to be bundled with the root filesystem |
1417 | in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin). | 1709 | in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin). |
1418 | When the kernel is copied to RAM and executed, it unpacks the Initramfs rootfs. | 1710 | When the kernel is copied to RAM and executed, it unpacks the :term:`Initramfs` root filesystem. |
1419 | The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE` | 1711 | The :term:`Initramfs` bundle can be enabled when :term:`INITRAMFS_IMAGE` |
1420 | is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1. | 1712 | is specified and requires that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1. |
1421 | The address where the Initramfs bundle is to be loaded by U-boot is specified | 1713 | The address where the :term:`Initramfs` bundle is to be loaded by U-boot is specified |
1422 | by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`. | 1714 | by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`. |
1423 | 1715 | ||
1424 | Only a single U-boot boot script can be added to the FIT image created by | 1716 | Only a single U-boot boot script can be added to the FIT image created by |
1425 | ``kernel-fitimage`` and the boot script is optional. | 1717 | :ref:`ref-classes-kernel-fitimage` and the boot script is optional. |
1426 | The boot script is specified in the ITS file as a text file containing | 1718 | The boot script is specified in the ITS file as a text file containing |
1427 | U-boot commands. When using a boot script the user should configure the | 1719 | U-boot commands. When using a boot script the user should configure the |
1428 | U-boot ``do_install`` task to copy the script to sysroot. | 1720 | U-boot :ref:`ref-tasks-install` task to copy the script to sysroot. |
1429 | So the script can be included in the the FIT image by the ``kernel-fitimage`` | 1721 | So the script can be included in the FIT image by the :ref:`ref-classes-kernel-fitimage` |
1430 | class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to | 1722 | class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to |
1431 | load the boot script from the FIT image and executes it. | 1723 | load the boot script from the FIT image and execute it. |
1432 | 1724 | ||
1433 | The FIT image generated by ``kernel-fitimage`` class is signed when the | 1725 | The FIT image generated by the :ref:`ref-classes-kernel-fitimage` class is signed when the |
1434 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, | 1726 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, |
1435 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set | 1727 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set |
1436 | appropriately. The default values used for :term:`FIT_HASH_ALG` and | 1728 | appropriately. The default values used for :term:`FIT_HASH_ALG` and |
1437 | :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and | 1729 | :term:`FIT_SIGN_ALG` in :ref:`ref-classes-kernel-fitimage` are "sha256" and |
1438 | "rsa2048" respectively. The keys for signing fitImage can be generated using | 1730 | "rsa2048" respectively. The keys for signing the FIT image can be generated using |
1439 | the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and | 1731 | the :ref:`ref-classes-kernel-fitimage` class when both :term:`FIT_GENERATE_KEYS` and |
1440 | :term:`UBOOT_SIGN_ENABLE` are set to "1". | 1732 | :term:`UBOOT_SIGN_ENABLE` are set to "1". |
1441 | 1733 | ||
1442 | 1734 | ||
1443 | .. _ref-classes-kernel-grub: | 1735 | .. _ref-classes-kernel-grub: |
1444 | 1736 | ||
1445 | ``kernel-grub.bbclass`` | 1737 | ``kernel-grub`` |
1446 | ======================= | 1738 | =============== |
1447 | 1739 | ||
1448 | The ``kernel-grub`` class updates the boot area and the boot menu with | 1740 | The :ref:`ref-classes-kernel-grub` class updates the boot area and the boot menu with |
1449 | the kernel as the priority boot mechanism while installing a RPM to | 1741 | the kernel as the priority boot mechanism while installing a RPM to |
1450 | update the kernel on a deployed target. | 1742 | update the kernel on a deployed target. |
1451 | 1743 | ||
1452 | .. _ref-classes-kernel-module-split: | 1744 | .. _ref-classes-kernel-module-split: |
1453 | 1745 | ||
1454 | ``kernel-module-split.bbclass`` | 1746 | ``kernel-module-split`` |
1455 | =============================== | 1747 | ======================= |
1456 | 1748 | ||
1457 | The ``kernel-module-split`` class provides common functionality for | 1749 | The :ref:`ref-classes-kernel-module-split` class provides common functionality for |
1458 | splitting Linux kernel modules into separate packages. | 1750 | splitting Linux kernel modules into separate packages. |
1459 | 1751 | ||
1460 | .. _ref-classes-kernel-uboot: | 1752 | .. _ref-classes-kernel-uboot: |
1461 | 1753 | ||
1462 | ``kernel-uboot.bbclass`` | 1754 | ``kernel-uboot`` |
1463 | ======================== | 1755 | ================ |
1464 | 1756 | ||
1465 | The ``kernel-uboot`` class provides support for building from | 1757 | The :ref:`ref-classes-kernel-uboot` class provides support for building from |
1466 | vmlinux-style kernel sources. | 1758 | vmlinux-style kernel sources. |
1467 | 1759 | ||
1468 | .. _ref-classes-kernel-uimage: | 1760 | .. _ref-classes-kernel-uimage: |
1469 | 1761 | ||
1470 | ``kernel-uimage.bbclass`` | 1762 | ``kernel-uimage`` |
1471 | ========================= | 1763 | ================= |
1472 | 1764 | ||
1473 | The ``kernel-uimage`` class provides support to pack uImage. | 1765 | The :ref:`ref-classes-kernel-uimage` class provides support to pack uImage. |
1474 | 1766 | ||
1475 | .. _ref-classes-kernel-yocto: | 1767 | .. _ref-classes-kernel-yocto: |
1476 | 1768 | ||
1477 | ``kernel-yocto.bbclass`` | 1769 | ``kernel-yocto`` |
1478 | ======================== | 1770 | ================ |
1479 | 1771 | ||
1480 | The ``kernel-yocto`` class provides common functionality for building | 1772 | The :ref:`ref-classes-kernel-yocto` class provides common functionality for building |
1481 | from linux-yocto style kernel source repositories. | 1773 | from linux-yocto style kernel source repositories. |
1482 | 1774 | ||
1483 | .. _ref-classes-kernelsrc: | 1775 | .. _ref-classes-kernelsrc: |
1484 | 1776 | ||
1485 | ``kernelsrc.bbclass`` | 1777 | ``kernelsrc`` |
1486 | ===================== | 1778 | ============= |
1487 | 1779 | ||
1488 | The ``kernelsrc`` class sets the Linux kernel source and version. | 1780 | The :ref:`ref-classes-kernelsrc` class sets the Linux kernel source and version. |
1489 | 1781 | ||
1490 | .. _ref-classes-lib_package: | 1782 | .. _ref-classes-lib_package: |
1491 | 1783 | ||
1492 | ``lib_package.bbclass`` | 1784 | ``lib_package`` |
1493 | ======================= | 1785 | =============== |
1494 | 1786 | ||
1495 | The ``lib_package`` class supports recipes that build libraries and | 1787 | The :ref:`ref-classes-lib_package` class supports recipes that build libraries and |
1496 | produce executable binaries, where those binaries should not be | 1788 | produce executable binaries, where those binaries should not be |
1497 | installed by default along with the library. Instead, the binaries are | 1789 | installed by default along with the library. Instead, the binaries are |
1498 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to | 1790 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to |
@@ -1500,40 +1792,40 @@ make their installation optional. | |||
1500 | 1792 | ||
1501 | .. _ref-classes-libc*: | 1793 | .. _ref-classes-libc*: |
1502 | 1794 | ||
1503 | ``libc*.bbclass`` | 1795 | ``libc*`` |
1504 | ================= | 1796 | ========= |
1505 | 1797 | ||
1506 | The ``libc*`` classes support recipes that build packages with ``libc``: | 1798 | The :ref:`ref-classes-libc*` classes support recipes that build packages with ``libc``: |
1507 | 1799 | ||
1508 | - The ``libc-common`` class provides common support for building with | 1800 | - The :ref:`libc-common <ref-classes-libc*>` class provides common support for building with |
1509 | ``libc``. | 1801 | ``libc``. |
1510 | 1802 | ||
1511 | - The ``libc-package`` class supports packaging up ``glibc`` and | 1803 | - The :ref:`libc-package <ref-classes-libc*>` class supports packaging up ``glibc`` and |
1512 | ``eglibc``. | 1804 | ``eglibc``. |
1513 | 1805 | ||
1514 | .. _ref-classes-license: | 1806 | .. _ref-classes-license: |
1515 | 1807 | ||
1516 | ``license.bbclass`` | 1808 | ``license`` |
1517 | =================== | 1809 | =========== |
1518 | 1810 | ||
1519 | The ``license`` class provides license manifest creation and license | 1811 | The :ref:`ref-classes-license` class provides license manifest creation and license |
1520 | exclusion. This class is enabled by default using the default value for | 1812 | exclusion. This class is enabled by default using the default value for |
1521 | the :term:`INHERIT_DISTRO` variable. | 1813 | the :term:`INHERIT_DISTRO` variable. |
1522 | 1814 | ||
1523 | .. _ref-classes-linux-kernel-base: | 1815 | .. _ref-classes-linux-kernel-base: |
1524 | 1816 | ||
1525 | ``linux-kernel-base.bbclass`` | 1817 | ``linux-kernel-base`` |
1526 | ============================= | 1818 | ===================== |
1527 | 1819 | ||
1528 | The ``linux-kernel-base`` class provides common functionality for | 1820 | The :ref:`ref-classes-linux-kernel-base` class provides common functionality for |
1529 | recipes that build out of the Linux kernel source tree. These builds | 1821 | recipes that build out of the Linux kernel source tree. These builds |
1530 | goes beyond the kernel itself. For example, the Perf recipe also | 1822 | goes beyond the kernel itself. For example, the Perf recipe also |
1531 | inherits this class. | 1823 | inherits this class. |
1532 | 1824 | ||
1533 | .. _ref-classes-linuxloader: | 1825 | .. _ref-classes-linuxloader: |
1534 | 1826 | ||
1535 | ``linuxloader.bbclass`` | 1827 | ``linuxloader`` |
1536 | ======================= | 1828 | =============== |
1537 | 1829 | ||
1538 | Provides the function ``linuxloader()``, which gives the value of the | 1830 | Provides the function ``linuxloader()``, which gives the value of the |
1539 | dynamic loader/linker provided on the platform. This value is used by a | 1831 | dynamic loader/linker provided on the platform. This value is used by a |
@@ -1541,80 +1833,101 @@ number of other classes. | |||
1541 | 1833 | ||
1542 | .. _ref-classes-logging: | 1834 | .. _ref-classes-logging: |
1543 | 1835 | ||
1544 | ``logging.bbclass`` | 1836 | ``logging`` |
1545 | =================== | 1837 | =========== |
1546 | 1838 | ||
1547 | The ``logging`` class provides the standard shell functions used to log | 1839 | The :ref:`ref-classes-logging` class provides the standard shell functions used to log |
1548 | messages for various BitBake severity levels (i.e. ``bbplain``, | 1840 | messages for various BitBake severity levels (i.e. ``bbplain``, |
1549 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). | 1841 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). |
1550 | 1842 | ||
1551 | This class is enabled by default since it is inherited by the ``base`` | 1843 | This class is enabled by default since it is inherited by the :ref:`ref-classes-base` |
1552 | class. | 1844 | class. |
1553 | 1845 | ||
1554 | .. _ref-classes-meta: | 1846 | .. _ref-classes-meson: |
1555 | 1847 | ||
1556 | ``meta.bbclass`` | 1848 | ``meson`` |
1557 | ================ | 1849 | ========= |
1558 | 1850 | ||
1559 | The ``meta`` class is inherited by recipes that do not build any output | 1851 | The :ref:`ref-classes-meson` class allows to create recipes that build software |
1560 | packages themselves, but act as a "meta" target for building other | 1852 | using the `Meson <https://mesonbuild.com/>`__ build system. You can use the |
1561 | recipes. | 1853 | :term:`MESON_BUILDTYPE`, :term:`MESON_TARGET` and :term:`EXTRA_OEMESON` |
1854 | variables to specify additional configuration options to be passed using the | ||
1855 | ``meson`` command line. | ||
1562 | 1856 | ||
1563 | .. _ref-classes-metadata_scm: | 1857 | .. _ref-classes-metadata_scm: |
1564 | 1858 | ||
1565 | ``metadata_scm.bbclass`` | 1859 | ``metadata_scm`` |
1566 | ======================== | 1860 | ================ |
1567 | 1861 | ||
1568 | The ``metadata_scm`` class provides functionality for querying the | 1862 | The :ref:`ref-classes-metadata_scm` class provides functionality for querying the |
1569 | branch and revision of a Source Code Manager (SCM) repository. | 1863 | branch and revision of a Source Code Manager (SCM) repository. |
1570 | 1864 | ||
1571 | The :ref:`base <ref-classes-base>` class uses this class to print the | 1865 | The :ref:`ref-classes-base` class uses this class to print the revisions of |
1572 | revisions of each layer before starting every build. The | 1866 | each layer before starting every build. The :ref:`ref-classes-metadata_scm` |
1573 | ``metadata_scm`` class is enabled by default because it is inherited by | 1867 | class is enabled by default because it is inherited by the |
1574 | the ``base`` class. | 1868 | :ref:`ref-classes-base` class. |
1575 | 1869 | ||
1576 | .. _ref-classes-migrate_localcount: | 1870 | .. _ref-classes-migrate_localcount: |
1577 | 1871 | ||
1578 | ``migrate_localcount.bbclass`` | 1872 | ``migrate_localcount`` |
1579 | ============================== | 1873 | ====================== |
1580 | 1874 | ||
1581 | The ``migrate_localcount`` class verifies a recipe's localcount data and | 1875 | The :ref:`ref-classes-migrate_localcount` class verifies a recipe's localcount data and |
1582 | increments it appropriately. | 1876 | increments it appropriately. |
1583 | 1877 | ||
1584 | .. _ref-classes-mime: | 1878 | .. _ref-classes-mime: |
1585 | 1879 | ||
1586 | ``mime.bbclass`` | 1880 | ``mime`` |
1587 | ================ | 1881 | ======== |
1588 | 1882 | ||
1589 | The ``mime`` class generates the proper post-install and post-remove | 1883 | The :ref:`ref-classes-mime` class generates the proper post-install and post-remove |
1590 | (postinst/postrm) scriptlets for packages that install MIME type files. | 1884 | (postinst/postrm) scriptlets for packages that install MIME type files. |
1591 | These scriptlets call ``update-mime-database`` to add the MIME types to | 1885 | These scriptlets call ``update-mime-database`` to add the MIME types to |
1592 | the shared database. | 1886 | the shared database. |
1593 | 1887 | ||
1888 | .. _ref-classes-mime-xdg: | ||
1889 | |||
1890 | ``mime-xdg`` | ||
1891 | ============ | ||
1892 | |||
1893 | The :ref:`ref-classes-mime-xdg` class generates the proper | ||
1894 | post-install and post-remove (postinst/postrm) scriptlets for packages | ||
1895 | that install ``.desktop`` files containing ``MimeType`` entries. | ||
1896 | These scriptlets call ``update-desktop-database`` to add the MIME types | ||
1897 | to the database of MIME types handled by desktop files. | ||
1898 | |||
1899 | Thanks to this class, when users open a file through a file browser | ||
1900 | on recently created images, they don't have to choose the application | ||
1901 | to open the file from the pool of all known applications, even the ones | ||
1902 | that cannot open the selected file. | ||
1903 | |||
1904 | If you have recipes installing their ``.desktop`` files as absolute | ||
1905 | symbolic links, the detection of such files cannot be done by the current | ||
1906 | implementation of this class. In this case, you have to add the corresponding | ||
1907 | package names to the :term:`MIME_XDG_PACKAGES` variable. | ||
1908 | |||
1594 | .. _ref-classes-mirrors: | 1909 | .. _ref-classes-mirrors: |
1595 | 1910 | ||
1596 | ``mirrors.bbclass`` | 1911 | ``mirrors`` |
1597 | =================== | 1912 | =========== |
1598 | 1913 | ||
1599 | The ``mirrors`` class sets up some standard | 1914 | The :ref:`ref-classes-mirrors` class sets up some standard |
1600 | :term:`MIRRORS` entries for source code mirrors. These | 1915 | :term:`MIRRORS` entries for source code mirrors. These |
1601 | mirrors provide a fall-back path in case the upstream source specified | 1916 | mirrors provide a fall-back path in case the upstream source specified |
1602 | in :term:`SRC_URI` within recipes is unavailable. | 1917 | in :term:`SRC_URI` within recipes is unavailable. |
1603 | 1918 | ||
1604 | This class is enabled by default since it is inherited by the | 1919 | This class is enabled by default since it is inherited by the |
1605 | :ref:`base <ref-classes-base>` class. | 1920 | :ref:`ref-classes-base` class. |
1606 | 1921 | ||
1607 | .. _ref-classes-module: | 1922 | .. _ref-classes-module: |
1608 | 1923 | ||
1609 | ``module.bbclass`` | 1924 | ``module`` |
1610 | ================== | 1925 | ========== |
1611 | 1926 | ||
1612 | The ``module`` class provides support for building out-of-tree Linux | 1927 | The :ref:`ref-classes-module` class provides support for building out-of-tree Linux |
1613 | kernel modules. The class inherits the | 1928 | kernel modules. The class inherits the :ref:`ref-classes-module-base` and |
1614 | :ref:`module-base <ref-classes-module-base>` and | 1929 | :ref:`ref-classes-kernel-module-split` classes, and implements the |
1615 | :ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, | 1930 | :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The class provides |
1616 | and implements the :ref:`ref-tasks-compile` and | ||
1617 | :ref:`ref-tasks-install` tasks. The class provides | ||
1618 | everything needed to build and package a kernel module. | 1931 | everything needed to build and package a kernel module. |
1619 | 1932 | ||
1620 | For general information on out-of-tree Linux kernel modules, see the | 1933 | For general information on out-of-tree Linux kernel modules, see the |
@@ -1623,50 +1936,49 @@ section in the Yocto Project Linux Kernel Development Manual. | |||
1623 | 1936 | ||
1624 | .. _ref-classes-module-base: | 1937 | .. _ref-classes-module-base: |
1625 | 1938 | ||
1626 | ``module-base.bbclass`` | 1939 | ``module-base`` |
1627 | ======================= | 1940 | =============== |
1628 | 1941 | ||
1629 | The ``module-base`` class provides the base functionality for building | 1942 | The :ref:`ref-classes-module-base` class provides the base functionality for |
1630 | Linux kernel modules. Typically, a recipe that builds software that | 1943 | building Linux kernel modules. Typically, a recipe that builds software that |
1631 | includes one or more kernel modules and has its own means of building | 1944 | includes one or more kernel modules and has its own means of building the module |
1632 | the module inherits this class as opposed to inheriting the | 1945 | inherits this class as opposed to inheriting the :ref:`ref-classes-module` |
1633 | :ref:`module <ref-classes-module>` class. | 1946 | class. |
1634 | 1947 | ||
1635 | .. _ref-classes-multilib*: | 1948 | .. _ref-classes-multilib*: |
1636 | 1949 | ||
1637 | ``multilib*.bbclass`` | 1950 | ``multilib*`` |
1638 | ===================== | 1951 | ============= |
1639 | 1952 | ||
1640 | The ``multilib*`` classes provide support for building libraries with | 1953 | The :ref:`ref-classes-multilib*` classes provide support for building libraries with |
1641 | different target optimizations or target architectures and installing | 1954 | different target optimizations or target architectures and installing |
1642 | them side-by-side in the same image. | 1955 | them side-by-side in the same image. |
1643 | 1956 | ||
1644 | For more information on using the Multilib feature, see the | 1957 | For more information on using the Multilib feature, see the |
1645 | ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`" | 1958 | ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" |
1646 | section in the Yocto Project Development Tasks Manual. | 1959 | section in the Yocto Project Development Tasks Manual. |
1647 | 1960 | ||
1648 | .. _ref-classes-native: | 1961 | .. _ref-classes-native: |
1649 | 1962 | ||
1650 | ``native.bbclass`` | 1963 | ``native`` |
1651 | ================== | 1964 | ========== |
1652 | 1965 | ||
1653 | The ``native`` class provides common functionality for recipes that | 1966 | The :ref:`ref-classes-native` class provides common functionality for recipes that |
1654 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler | 1967 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler |
1655 | or other tools from the build host). | 1968 | or other tools from the build host). |
1656 | 1969 | ||
1657 | You can create a recipe that builds tools that run natively on the host | 1970 | You can create a recipe that builds tools that run natively on the host |
1658 | a couple different ways: | 1971 | a couple different ways: |
1659 | 1972 | ||
1660 | - Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` | 1973 | - Create a ``myrecipe-native.bb`` recipe that inherits the :ref:`ref-classes-native` |
1661 | class. If you use this method, you must order the inherit statement | 1974 | class. If you use this method, you must order the inherit statement |
1662 | in the recipe after all other inherit statements so that the | 1975 | in the recipe after all other inherit statements so that the |
1663 | ``native`` class is inherited last. | 1976 | :ref:`ref-classes-native` class is inherited last. |
1664 | 1977 | ||
1665 | .. note:: | 1978 | .. note:: |
1666 | 1979 | ||
1667 | When creating a recipe this way, the recipe name must follow this | 1980 | When creating a recipe this way, the recipe name must follow this |
1668 | naming convention: | 1981 | naming convention:: |
1669 | :: | ||
1670 | 1982 | ||
1671 | myrecipe-native.bb | 1983 | myrecipe-native.bb |
1672 | 1984 | ||
@@ -1674,79 +1986,76 @@ a couple different ways: | |||
1674 | Not using this naming convention can lead to subtle problems | 1986 | Not using this naming convention can lead to subtle problems |
1675 | caused by existing code that depends on that naming convention. | 1987 | caused by existing code that depends on that naming convention. |
1676 | 1988 | ||
1677 | - Create or modify a target recipe that contains the following: | 1989 | - Create or modify a target recipe that contains the following:: |
1678 | :: | ||
1679 | 1990 | ||
1680 | BBCLASSEXTEND = "native" | 1991 | BBCLASSEXTEND = "native" |
1681 | 1992 | ||
1682 | Inside the | 1993 | Inside the |
1683 | recipe, use ``_class-native`` and ``_class-target`` overrides to | 1994 | recipe, use ``:class-native`` and ``:class-target`` overrides to |
1684 | specify any functionality specific to the respective native or target | 1995 | specify any functionality specific to the respective native or target |
1685 | case. | 1996 | case. |
1686 | 1997 | ||
1687 | Although applied differently, the ``native`` class is used with both | 1998 | Although applied differently, the :ref:`ref-classes-native` class is used with both |
1688 | methods. The advantage of the second method is that you do not need to | 1999 | methods. The advantage of the second method is that you do not need to |
1689 | have two separate recipes (assuming you need both) for native and | 2000 | have two separate recipes (assuming you need both) for native and |
1690 | target. All common parts of the recipe are automatically shared. | 2001 | target. All common parts of the recipe are automatically shared. |
1691 | 2002 | ||
1692 | .. _ref-classes-nativesdk: | 2003 | .. _ref-classes-nativesdk: |
1693 | 2004 | ||
1694 | ``nativesdk.bbclass`` | 2005 | ``nativesdk`` |
1695 | ===================== | 2006 | ============= |
1696 | 2007 | ||
1697 | The ``nativesdk`` class provides common functionality for recipes that | 2008 | The :ref:`ref-classes-nativesdk` class provides common functionality for recipes that |
1698 | wish to build tools to run as part of an SDK (i.e. tools that run on | 2009 | wish to build tools to run as part of an SDK (i.e. tools that run on |
1699 | :term:`SDKMACHINE`). | 2010 | :term:`SDKMACHINE`). |
1700 | 2011 | ||
1701 | You can create a recipe that builds tools that run on the SDK machine a | 2012 | You can create a recipe that builds tools that run on the SDK machine a |
1702 | couple different ways: | 2013 | couple different ways: |
1703 | 2014 | ||
1704 | - Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the | 2015 | - Create a ``nativesdk-myrecipe.bb`` recipe that inherits the |
1705 | ``nativesdk`` class. If you use this method, you must order the | 2016 | :ref:`ref-classes-nativesdk` class. If you use this method, you must order the |
1706 | inherit statement in the recipe after all other inherit statements so | 2017 | inherit statement in the recipe after all other inherit statements so |
1707 | that the ``nativesdk`` class is inherited last. | 2018 | that the :ref:`ref-classes-nativesdk` class is inherited last. |
1708 | 2019 | ||
1709 | - Create a ``nativesdk`` variant of any recipe by adding the following: | 2020 | - Create a :ref:`ref-classes-nativesdk` variant of any recipe by adding the following:: |
1710 | :: | ||
1711 | 2021 | ||
1712 | BBCLASSEXTEND = "nativesdk" | 2022 | BBCLASSEXTEND = "nativesdk" |
1713 | 2023 | ||
1714 | Inside the | 2024 | Inside the |
1715 | recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to | 2025 | recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to |
1716 | specify any functionality specific to the respective SDK machine or | 2026 | specify any functionality specific to the respective SDK machine or |
1717 | target case. | 2027 | target case. |
1718 | 2028 | ||
1719 | .. note:: | 2029 | .. note:: |
1720 | 2030 | ||
1721 | When creating a recipe, you must follow this naming convention: | 2031 | When creating a recipe, you must follow this naming convention:: |
1722 | :: | ||
1723 | 2032 | ||
1724 | nativesdk-myrecipe.bb | 2033 | nativesdk-myrecipe.bb |
1725 | 2034 | ||
1726 | 2035 | ||
1727 | Not doing so can lead to subtle problems because code exists that | 2036 | Not doing so can lead to subtle problems because there is code that |
1728 | depends on the naming convention. | 2037 | depends on the naming convention. |
1729 | 2038 | ||
1730 | Although applied differently, the ``nativesdk`` class is used with both | 2039 | Although applied differently, the :ref:`ref-classes-nativesdk` class is used with both |
1731 | methods. The advantage of the second method is that you do not need to | 2040 | methods. The advantage of the second method is that you do not need to |
1732 | have two separate recipes (assuming you need both) for the SDK machine | 2041 | have two separate recipes (assuming you need both) for the SDK machine |
1733 | and the target. All common parts of the recipe are automatically shared. | 2042 | and the target. All common parts of the recipe are automatically shared. |
1734 | 2043 | ||
1735 | .. _ref-classes-nopackages: | 2044 | .. _ref-classes-nopackages: |
1736 | 2045 | ||
1737 | ``nopackages.bbclass`` | 2046 | ``nopackages`` |
1738 | ====================== | 2047 | ============== |
1739 | 2048 | ||
1740 | Disables packaging tasks for those recipes and classes where packaging | 2049 | Disables packaging tasks for those recipes and classes where packaging |
1741 | is not needed. | 2050 | is not needed. |
1742 | 2051 | ||
1743 | .. _ref-classes-npm: | 2052 | .. _ref-classes-npm: |
1744 | 2053 | ||
1745 | ``npm.bbclass`` | 2054 | ``npm`` |
1746 | =============== | 2055 | ======= |
1747 | 2056 | ||
1748 | Provides support for building Node.js software fetched using the `node | 2057 | Provides support for building Node.js software fetched using the |
1749 | package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | 2058 | :wikipedia:`node package manager (NPM) <Npm_(software)>`. |
1750 | 2059 | ||
1751 | .. note:: | 2060 | .. note:: |
1752 | 2061 | ||
@@ -1754,77 +2063,175 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | |||
1754 | fetcher to have dependencies fetched and packaged automatically. | 2063 | fetcher to have dependencies fetched and packaged automatically. |
1755 | 2064 | ||
1756 | For information on how to create NPM packages, see the | 2065 | For information on how to create NPM packages, see the |
1757 | ":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`" | 2066 | ":ref:`dev-manual/packages:creating node package manager (npm) packages`" |
1758 | section in the Yocto Project Development Tasks Manual. | 2067 | section in the Yocto Project Development Tasks Manual. |
1759 | 2068 | ||
1760 | .. _ref-classes-oelint: | 2069 | .. _ref-classes-oelint: |
1761 | 2070 | ||
1762 | ``oelint.bbclass`` | 2071 | ``oelint`` |
1763 | ================== | 2072 | ========== |
1764 | 2073 | ||
1765 | The ``oelint`` class is an obsolete lint checking tool that exists in | 2074 | The :ref:`ref-classes-oelint` class is an obsolete lint checking tool available in |
1766 | ``meta/classes`` in the :term:`Source Directory`. | 2075 | ``meta/classes`` in the :term:`Source Directory`. |
1767 | 2076 | ||
1768 | A number of classes exist that could be generally useful in OE-Core but | 2077 | There are some classes that could be generally useful in OE-Core but |
1769 | are never actually used within OE-Core itself. The ``oelint`` class is | 2078 | are never actually used within OE-Core itself. The :ref:`ref-classes-oelint` class is |
1770 | one such example. However, being aware of this class can reduce the | 2079 | one such example. However, being aware of this class can reduce the |
1771 | proliferation of different versions of similar classes across multiple | 2080 | proliferation of different versions of similar classes across multiple |
1772 | layers. | 2081 | layers. |
1773 | 2082 | ||
2083 | .. _ref-classes-overlayfs: | ||
2084 | |||
2085 | ``overlayfs`` | ||
2086 | ============= | ||
2087 | |||
2088 | It's often desired in Embedded System design to have a read-only root filesystem. | ||
2089 | But a lot of different applications might want to have read-write access to | ||
2090 | some parts of a filesystem. It can be especially useful when your update mechanism | ||
2091 | overwrites the whole root filesystem, but you may want your application data to be preserved | ||
2092 | between updates. The :ref:`ref-classes-overlayfs` class provides a way | ||
2093 | to achieve that by means of ``overlayfs`` and at the same time keeping the base | ||
2094 | root filesystem read-only. | ||
2095 | |||
2096 | To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper | ||
2097 | layer in your machine configuration. The underlying file system can be anything that | ||
2098 | is supported by ``overlayfs``. This has to be done in your machine configuration:: | ||
2099 | |||
2100 | OVERLAYFS_MOUNT_POINT[data] = "/data" | ||
2101 | |||
2102 | .. note:: | ||
2103 | |||
2104 | * QA checks fail to catch file existence if you redefine this variable in your recipe! | ||
2105 | * Only the existence of the systemd mount unit file is checked, not its contents. | ||
2106 | * To get more details on ``overlayfs``, its internals and supported operations, please refer | ||
2107 | to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`__. | ||
2108 | |||
2109 | The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP | ||
2110 | (e.g. in ``systemd-machine-units`` recipe) and it's installed into the image. | ||
2111 | |||
2112 | Then you can specify writable directories on a recipe basis (e.g. in my-application.bb):: | ||
2113 | |||
2114 | OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" | ||
2115 | |||
2116 | To support several mount points you can use a different variable flag. Assuming we | ||
2117 | want to have a writable location on the file system, but do not need that the data | ||
2118 | survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` | ||
2119 | file system. | ||
2120 | |||
2121 | In your machine configuration:: | ||
2122 | |||
2123 | OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" | ||
2124 | |||
2125 | and then in your recipe:: | ||
2126 | |||
2127 | OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" | ||
2128 | |||
2129 | On a practical note, your application recipe might require multiple | ||
2130 | overlays to be mounted before running to avoid writing to the underlying | ||
2131 | file system (which can be forbidden in case of read-only file system) | ||
2132 | To achieve that :ref:`ref-classes-overlayfs` provides a ``systemd`` | ||
2133 | helper service for mounting overlays. This helper service is named | ||
2134 | ``${PN}-overlays.service`` and can be depended on in your application recipe | ||
2135 | (named ``application`` in the following example) ``systemd`` unit by adding | ||
2136 | to the unit the following:: | ||
2137 | |||
2138 | [Unit] | ||
2139 | After=application-overlays.service | ||
2140 | Requires=application-overlays.service | ||
2141 | |||
2142 | .. note:: | ||
2143 | |||
2144 | The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it. | ||
2145 | In order to get ``/etc`` in overlayfs, see :ref:`ref-classes-overlayfs-etc`. | ||
2146 | |||
2147 | .. _ref-classes-overlayfs-etc: | ||
2148 | |||
2149 | ``overlayfs-etc`` | ||
2150 | ================= | ||
2151 | |||
2152 | In order to have the ``/etc`` directory in overlayfs a special handling at early | ||
2153 | boot stage is required. The idea is to supply a custom init script that mounts | ||
2154 | ``/etc`` before launching the actual init program, because the latter already | ||
2155 | requires ``/etc`` to be mounted. | ||
2156 | |||
2157 | Example usage in image recipe:: | ||
2158 | |||
2159 | IMAGE_FEATURES += "overlayfs-etc" | ||
2160 | |||
2161 | .. note:: | ||
2162 | |||
2163 | This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES` | ||
2164 | |||
2165 | Your machine configuration should define at least the device, mount point, and file system type | ||
2166 | you are going to use for ``overlayfs``:: | ||
2167 | |||
2168 | OVERLAYFS_ETC_MOUNT_POINT = "/data" | ||
2169 | OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" | ||
2170 | OVERLAYFS_ETC_FSTYPE ?= "ext4" | ||
2171 | |||
2172 | To control more mount options you should consider setting mount options | ||
2173 | (``defaults`` is used by default):: | ||
2174 | |||
2175 | OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync" | ||
2176 | |||
2177 | The class provides two options for ``/sbin/init`` generation: | ||
2178 | |||
2179 | - The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig`` | ||
2180 | and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage | ||
2181 | that you won't need to change any kernel parameters in order to make it work, | ||
2182 | but it poses a restriction that package-management can't be used, because updating | ||
2183 | the init manager would remove the generated script. | ||
2184 | |||
2185 | - If you wish to keep original init as is, you can set:: | ||
2186 | |||
2187 | OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0" | ||
2188 | |||
2189 | Then the generated init will be named ``/sbin/preinit`` and you would need to extend your | ||
2190 | kernel parameters manually in your bootloader configuration. | ||
2191 | |||
1774 | .. _ref-classes-own-mirrors: | 2192 | .. _ref-classes-own-mirrors: |
1775 | 2193 | ||
1776 | ``own-mirrors.bbclass`` | 2194 | ``own-mirrors`` |
1777 | ======================= | 2195 | =============== |
1778 | 2196 | ||
1779 | The ``own-mirrors`` class makes it easier to set up your own | 2197 | The :ref:`ref-classes-own-mirrors` class makes it easier to set up your own |
1780 | :term:`PREMIRRORS` from which to first fetch source | 2198 | :term:`PREMIRRORS` from which to first fetch source |
1781 | before attempting to fetch it from the upstream specified in | 2199 | before attempting to fetch it from the upstream specified in |
1782 | :term:`SRC_URI` within each recipe. | 2200 | :term:`SRC_URI` within each recipe. |
1783 | 2201 | ||
1784 | To use this class, inherit it globally and specify | 2202 | To use this class, inherit it globally and specify |
1785 | :term:`SOURCE_MIRROR_URL`. Here is an example: | 2203 | :term:`SOURCE_MIRROR_URL`. Here is an example:: |
1786 | :: | ||
1787 | 2204 | ||
1788 | INHERIT += "own-mirrors" | 2205 | INHERIT += "own-mirrors" |
1789 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" | 2206 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" |
1790 | 2207 | ||
1791 | You can specify only a single URL | 2208 | You can specify only a single URL |
1792 | in ``SOURCE_MIRROR_URL``. | 2209 | in :term:`SOURCE_MIRROR_URL`. |
1793 | 2210 | ||
1794 | .. _ref-classes-package: | 2211 | .. _ref-classes-package: |
1795 | 2212 | ||
1796 | ``package.bbclass`` | 2213 | ``package`` |
1797 | =================== | 2214 | =========== |
1798 | 2215 | ||
1799 | The ``package`` class supports generating packages from a build's | 2216 | The :ref:`ref-classes-package` class supports generating packages from a build's |
1800 | output. The core generic functionality is in ``package.bbclass``. The | 2217 | output. The core generic functionality is in ``package.bbclass``. The |
1801 | code specific to particular package types resides in these | 2218 | code specific to particular package types resides in these |
1802 | package-specific classes: | 2219 | package-specific classes: :ref:`ref-classes-package_deb`, |
1803 | :ref:`package_deb <ref-classes-package_deb>`, | 2220 | :ref:`ref-classes-package_rpm`, :ref:`ref-classes-package_ipk`. |
1804 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
1805 | :ref:`package_ipk <ref-classes-package_ipk>`, and | ||
1806 | :ref:`package_tar <ref-classes-package_tar>`. | ||
1807 | |||
1808 | .. note:: | ||
1809 | |||
1810 | The | ||
1811 | package_tar | ||
1812 | class is broken and not supported. It is recommended that you do not | ||
1813 | use this class. | ||
1814 | 2221 | ||
1815 | You can control the list of resulting package formats by using the | 2222 | You can control the list of resulting package formats by using the |
1816 | ``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` | 2223 | :term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` |
1817 | configuration file, which is located in the :term:`Build Directory`. | 2224 | configuration file, which is located in the :term:`Build Directory`. |
1818 | When defining the variable, you can | 2225 | When defining the variable, you can specify one or more package types. |
1819 | specify one or more package types. Since images are generated from | 2226 | Since images are generated from packages, a packaging class is needed |
1820 | packages, a packaging class is needed to enable image generation. The | 2227 | to enable image generation. The first class listed in this variable is |
1821 | first class listed in this variable is used for image generation. | 2228 | used for image generation. |
1822 | 2229 | ||
1823 | If you take the optional step to set up a repository (package feed) on | 2230 | If you take the optional step to set up a repository (package feed) on |
1824 | the development host that can be used by DNF, you can install packages | 2231 | the development host that can be used by DNF, you can install packages |
1825 | from the feed while you are running the image on the target (i.e. | 2232 | from the feed while you are running the image on the target (i.e. |
1826 | runtime installation of packages). For more information, see the | 2233 | runtime installation of packages). For more information, see the |
1827 | ":ref:`dev-manual/common-tasks:using runtime package management`" | 2234 | ":ref:`dev-manual/packages:using runtime package management`" |
1828 | section in the Yocto Project Development Tasks Manual. | 2235 | section in the Yocto Project Development Tasks Manual. |
1829 | 2236 | ||
1830 | The package-specific class you choose can affect build-time performance | 2237 | The package-specific class you choose can affect build-time performance |
@@ -1834,8 +2241,8 @@ the same or similar package. This comparison takes into account a | |||
1834 | complete build of the package with all dependencies previously built. | 2241 | complete build of the package with all dependencies previously built. |
1835 | The reason for this discrepancy is because the RPM package manager | 2242 | The reason for this discrepancy is because the RPM package manager |
1836 | creates and processes more :term:`Metadata` than the IPK package | 2243 | creates and processes more :term:`Metadata` than the IPK package |
1837 | manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to | 2244 | manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to |
1838 | "package_ipk" if you are building smaller systems. | 2245 | ":ref:`ref-classes-package_ipk`" if you are building smaller systems. |
1839 | 2246 | ||
1840 | Before making your package manager decision, however, you should | 2247 | Before making your package manager decision, however, you should |
1841 | consider some further things about using RPM: | 2248 | consider some further things about using RPM: |
@@ -1860,120 +2267,200 @@ at these two Yocto Project mailing list links: | |||
1860 | 2267 | ||
1861 | .. _ref-classes-package_deb: | 2268 | .. _ref-classes-package_deb: |
1862 | 2269 | ||
1863 | ``package_deb.bbclass`` | 2270 | ``package_deb`` |
1864 | ======================= | 2271 | =============== |
1865 | 2272 | ||
1866 | The ``package_deb`` class provides support for creating packages that | 2273 | The :ref:`ref-classes-package_deb` class provides support for creating packages that |
1867 | use the Debian (i.e. ``.deb``) file format. The class ensures the | 2274 | use the Debian (i.e. ``.deb``) file format. The class ensures the |
1868 | packages are written out in a ``.deb`` file format to the | 2275 | packages are written out in a ``.deb`` file format to the |
1869 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. | 2276 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. |
1870 | 2277 | ||
1871 | This class inherits the :ref:`package <ref-classes-package>` class and | 2278 | This class inherits the :ref:`ref-classes-package` class and |
1872 | is enabled through the :term:`PACKAGE_CLASSES` | 2279 | is enabled through the :term:`PACKAGE_CLASSES` |
1873 | variable in the ``local.conf`` file. | 2280 | variable in the ``local.conf`` file. |
1874 | 2281 | ||
1875 | .. _ref-classes-package_ipk: | 2282 | .. _ref-classes-package_ipk: |
1876 | 2283 | ||
1877 | ``package_ipk.bbclass`` | 2284 | ``package_ipk`` |
1878 | ======================= | 2285 | =============== |
1879 | 2286 | ||
1880 | The ``package_ipk`` class provides support for creating packages that | 2287 | The :ref:`ref-classes-package_ipk` class provides support for creating packages that |
1881 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages | 2288 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages |
1882 | are written out in a ``.ipk`` file format to the | 2289 | are written out in a ``.ipk`` file format to the |
1883 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. | 2290 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. |
1884 | 2291 | ||
1885 | This class inherits the :ref:`package <ref-classes-package>` class and | 2292 | This class inherits the :ref:`ref-classes-package` class and |
1886 | is enabled through the :term:`PACKAGE_CLASSES` | 2293 | is enabled through the :term:`PACKAGE_CLASSES` |
1887 | variable in the ``local.conf`` file. | 2294 | variable in the ``local.conf`` file. |
1888 | 2295 | ||
1889 | .. _ref-classes-package_rpm: | 2296 | .. _ref-classes-package_rpm: |
1890 | 2297 | ||
1891 | ``package_rpm.bbclass`` | 2298 | ``package_rpm`` |
1892 | ======================= | 2299 | =============== |
1893 | 2300 | ||
1894 | The ``package_rpm`` class provides support for creating packages that | 2301 | The :ref:`ref-classes-package_rpm` class provides support for creating packages that |
1895 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages | 2302 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages |
1896 | are written out in a ``.rpm`` file format to the | 2303 | are written out in a ``.rpm`` file format to the |
1897 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. | 2304 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. |
1898 | 2305 | ||
1899 | This class inherits the :ref:`package <ref-classes-package>` class and | 2306 | This class inherits the :ref:`ref-classes-package` class and |
1900 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1901 | variable in the ``local.conf`` file. | ||
1902 | |||
1903 | .. _ref-classes-package_tar: | ||
1904 | |||
1905 | ``package_tar.bbclass`` | ||
1906 | ======================= | ||
1907 | |||
1908 | The ``package_tar`` class provides support for creating tarballs. The | ||
1909 | class ensures the packages are written out in a tarball format to the | ||
1910 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. | ||
1911 | |||
1912 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1913 | is enabled through the :term:`PACKAGE_CLASSES` | 2307 | is enabled through the :term:`PACKAGE_CLASSES` |
1914 | variable in the ``local.conf`` file. | 2308 | variable in the ``local.conf`` file. |
1915 | 2309 | ||
1916 | .. note:: | ||
1917 | |||
1918 | You cannot specify the ``package_tar`` class first using the | ||
1919 | ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` | ||
1920 | file formats for your image or SDK. | ||
1921 | |||
1922 | .. _ref-classes-packagedata: | 2310 | .. _ref-classes-packagedata: |
1923 | 2311 | ||
1924 | ``packagedata.bbclass`` | 2312 | ``packagedata`` |
1925 | ======================= | 2313 | =============== |
1926 | 2314 | ||
1927 | The ``packagedata`` class provides common functionality for reading | 2315 | The :ref:`ref-classes-packagedata` class provides common functionality for reading |
1928 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These | 2316 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These |
1929 | files contain information about each output package produced by the | 2317 | files contain information about each output package produced by the |
1930 | OpenEmbedded build system. | 2318 | OpenEmbedded build system. |
1931 | 2319 | ||
1932 | 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 |
1933 | :ref:`package <ref-classes-package>` class. | 2321 | :ref:`ref-classes-package` class. |
1934 | 2322 | ||
1935 | .. _ref-classes-packagegroup: | 2323 | .. _ref-classes-packagegroup: |
1936 | 2324 | ||
1937 | ``packagegroup.bbclass`` | 2325 | ``packagegroup`` |
1938 | ======================== | 2326 | ================ |
1939 | 2327 | ||
1940 | The ``packagegroup`` class sets default values appropriate for package | 2328 | The :ref:`ref-classes-packagegroup` class sets default values appropriate for package |
1941 | group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and | 2329 | group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and |
1942 | so forth). It is highly recommended that all package group recipes | 2330 | so forth). It is highly recommended that all package group recipes |
1943 | inherit this class. | 2331 | inherit this class. |
1944 | 2332 | ||
1945 | For information on how to use this class, see the | 2333 | For information on how to use this class, see the |
1946 | ":ref:`dev-manual/common-tasks:customizing images using custom package groups`" | 2334 | ":ref:`dev-manual/customizing-images:customizing images using custom package groups`" |
1947 | section in the Yocto Project Development Tasks Manual. | 2335 | section in the Yocto Project Development Tasks Manual. |
1948 | 2336 | ||
1949 | Previously, this class was called the ``task`` class. | 2337 | Previously, this class was called the ``task`` class. |
1950 | 2338 | ||
1951 | .. _ref-classes-patch: | 2339 | .. _ref-classes-patch: |
1952 | 2340 | ||
1953 | ``patch.bbclass`` | 2341 | ``patch`` |
1954 | ================= | 2342 | ========= |
1955 | 2343 | ||
1956 | The ``patch`` class provides all functionality for applying patches | 2344 | The :ref:`ref-classes-patch` class provides all functionality for applying patches |
1957 | during the :ref:`ref-tasks-patch` task. | 2345 | during the :ref:`ref-tasks-patch` task. |
1958 | 2346 | ||
1959 | This class is enabled by default because it is inherited by the | 2347 | This class is enabled by default because it is inherited by the |
1960 | :ref:`base <ref-classes-base>` class. | 2348 | :ref:`ref-classes-base` class. |
1961 | 2349 | ||
1962 | .. _ref-classes-perlnative: | 2350 | .. _ref-classes-perlnative: |
1963 | 2351 | ||
1964 | ``perlnative.bbclass`` | 2352 | ``perlnative`` |
1965 | ====================== | 2353 | ============== |
1966 | 2354 | ||
1967 | When inherited by a recipe, the ``perlnative`` class supports using the | 2355 | When inherited by a recipe, the :ref:`ref-classes-perlnative` class supports using the |
1968 | native version of Perl built by the build system rather than using the | 2356 | native version of Perl built by the build system rather than using the |
1969 | version provided by the build host. | 2357 | version provided by the build host. |
1970 | 2358 | ||
2359 | .. _ref-classes-pypi: | ||
2360 | |||
2361 | ``pypi`` | ||
2362 | ======== | ||
2363 | |||
2364 | The :ref:`ref-classes-pypi` class sets variables appropriately for recipes that build | ||
2365 | Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index. | ||
2366 | By default it determines the PyPI package name based upon :term:`BPN` | ||
2367 | (stripping the "python-" or "python3-" prefix off if present), however in | ||
2368 | some cases you may need to set it manually in the recipe by setting | ||
2369 | :term:`PYPI_PACKAGE`. | ||
2370 | |||
2371 | Variables set by the :ref:`ref-classes-pypi` class include :term:`SRC_URI`, :term:`SECTION`, | ||
2372 | :term:`HOMEPAGE`, :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX` | ||
2373 | and :term:`CVE_PRODUCT`. | ||
2374 | |||
2375 | .. _ref-classes-python_flit_core: | ||
2376 | |||
2377 | ``python_flit_core`` | ||
2378 | ==================== | ||
2379 | |||
2380 | The :ref:`ref-classes-python_flit_core` class enables building Python modules which declare | ||
2381 | the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant | ||
2382 | ``flit_core.buildapi`` ``build-backend`` in the ``[build-system]`` | ||
2383 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). | ||
2384 | |||
2385 | Python modules built with ``flit_core.buildapi`` are pure Python (no | ||
2386 | ``C`` or ``Rust`` extensions). | ||
2387 | |||
2388 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2389 | |||
2390 | .. _ref-classes-python_maturin: | ||
2391 | |||
2392 | ``python_maturin`` | ||
2393 | ================== | ||
2394 | |||
2395 | The :ref:`ref-classes-python_maturin` class provides support for python-maturin, a replacement | ||
2396 | for setuptools_rust and another "backend" for building Python Wheels. | ||
2397 | |||
2398 | .. _ref-classes-python_mesonpy: | ||
2399 | |||
2400 | ``python_mesonpy`` | ||
2401 | ================== | ||
2402 | |||
2403 | The :ref:`ref-classes-python_mesonpy` class enables building Python modules which use the | ||
2404 | meson-python build system. | ||
2405 | |||
2406 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2407 | |||
2408 | .. _ref-classes-python_pep517: | ||
2409 | |||
2410 | ``python_pep517`` | ||
2411 | ================= | ||
2412 | |||
2413 | The :ref:`ref-classes-python_pep517` class builds and installs a Python ``wheel`` binary | ||
2414 | archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__). | ||
2415 | |||
2416 | Recipes wouldn't inherit this directly, instead typically another class will | ||
2417 | inherit this and add the relevant native dependencies. | ||
2418 | |||
2419 | Examples of classes which do this are :ref:`ref-classes-python_flit_core`, | ||
2420 | :ref:`ref-classes-python_setuptools_build_meta`, and | ||
2421 | :ref:`ref-classes-python_poetry_core`. | ||
2422 | |||
2423 | .. _ref-classes-python_poetry_core: | ||
2424 | |||
2425 | ``python_poetry_core`` | ||
2426 | ====================== | ||
2427 | |||
2428 | The :ref:`ref-classes-python_poetry_core` class enables building Python modules which use the | ||
2429 | `Poetry Core <https://python-poetry.org>`__ build system. | ||
2430 | |||
2431 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2432 | |||
2433 | .. _ref-classes-python_pyo3: | ||
2434 | |||
2435 | ``python_pyo3`` | ||
2436 | =============== | ||
2437 | |||
2438 | The :ref:`ref-classes-python_pyo3` class helps make sure that Python extensions | ||
2439 | written in Rust and built with `PyO3 <https://pyo3.rs/>`__, properly set up the | ||
2440 | environment for cross compilation. | ||
2441 | |||
2442 | This class is internal to the :ref:`ref-classes-python-setuptools3_rust` class | ||
2443 | and is not meant to be used directly in recipes. | ||
2444 | |||
2445 | .. _ref-classes-python-setuptools3_rust: | ||
2446 | |||
2447 | ``python-setuptools3_rust`` | ||
2448 | =========================== | ||
2449 | |||
2450 | The :ref:`ref-classes-python-setuptools3_rust` class enables building Python | ||
2451 | extensions implemented in Rust with `PyO3 <https://pyo3.rs/>`__, which allows | ||
2452 | to compile and distribute Python extensions written in Rust as easily | ||
2453 | as if they were written in C. | ||
2454 | |||
2455 | This class inherits the :ref:`ref-classes-setuptools3` and | ||
2456 | :ref:`ref-classes-python_pyo3` classes. | ||
2457 | |||
1971 | .. _ref-classes-pixbufcache: | 2458 | .. _ref-classes-pixbufcache: |
1972 | 2459 | ||
1973 | ``pixbufcache.bbclass`` | 2460 | ``pixbufcache`` |
1974 | ======================= | 2461 | =============== |
1975 | 2462 | ||
1976 | The ``pixbufcache`` class generates the proper post-install and | 2463 | The :ref:`ref-classes-pixbufcache` class generates the proper post-install and |
1977 | post-remove (postinst/postrm) scriptlets for packages that install | 2464 | post-remove (postinst/postrm) scriptlets for packages that install |
1978 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets | 2465 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets |
1979 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. | 2466 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. |
@@ -1988,24 +2475,24 @@ containing the loaders. | |||
1988 | 2475 | ||
1989 | .. _ref-classes-pkgconfig: | 2476 | .. _ref-classes-pkgconfig: |
1990 | 2477 | ||
1991 | ``pkgconfig.bbclass`` | 2478 | ``pkgconfig`` |
1992 | ===================== | 2479 | ============= |
1993 | 2480 | ||
1994 | The ``pkgconfig`` class provides a standard way to get header and | 2481 | The :ref:`ref-classes-pkgconfig` class provides a standard way to get header and |
1995 | library information by using ``pkg-config``. This class aims to smooth | 2482 | library information by using ``pkg-config``. This class aims to smooth |
1996 | integration of ``pkg-config`` into libraries that use it. | 2483 | integration of ``pkg-config`` into libraries that use it. |
1997 | 2484 | ||
1998 | During staging, BitBake installs ``pkg-config`` data into the | 2485 | During staging, BitBake installs ``pkg-config`` data into the |
1999 | ``sysroots/`` directory. By making use of sysroot functionality within | 2486 | ``sysroots/`` directory. By making use of sysroot functionality within |
2000 | ``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the | 2487 | ``pkg-config``, the :ref:`ref-classes-pkgconfig` class no longer has to manipulate the |
2001 | files. | 2488 | files. |
2002 | 2489 | ||
2003 | .. _ref-classes-populate-sdk: | 2490 | .. _ref-classes-populate-sdk: |
2004 | 2491 | ||
2005 | ``populate_sdk.bbclass`` | 2492 | ``populate_sdk`` |
2006 | ======================== | 2493 | ================ |
2007 | 2494 | ||
2008 | The ``populate_sdk`` class provides support for SDK-only recipes. For | 2495 | The :ref:`ref-classes-populate-sdk` class provides support for SDK-only recipes. For |
2009 | information on advantages gained when building a cross-development | 2496 | information on advantages gained when building a cross-development |
2010 | toolchain using the :ref:`ref-tasks-populate_sdk` | 2497 | toolchain using the :ref:`ref-tasks-populate_sdk` |
2011 | task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" | 2498 | task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
@@ -2014,40 +2501,39 @@ Software Development Kit (eSDK) manual. | |||
2014 | 2501 | ||
2015 | .. _ref-classes-populate-sdk-*: | 2502 | .. _ref-classes-populate-sdk-*: |
2016 | 2503 | ||
2017 | ``populate_sdk_*.bbclass`` | 2504 | ``populate_sdk_*`` |
2018 | ========================== | 2505 | ================== |
2019 | 2506 | ||
2020 | The ``populate_sdk_*`` classes support SDK creation and consist of the | 2507 | The :ref:`ref-classes-populate-sdk-*` classes support SDK creation and consist of the |
2021 | following classes: | 2508 | following classes: |
2022 | 2509 | ||
2023 | - ``populate_sdk_base``: The base class supporting SDK creation under | 2510 | - :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`: The base class supporting SDK creation under |
2024 | all package managers (i.e. DEB, RPM, and opkg). | 2511 | all package managers (i.e. DEB, RPM, and opkg). |
2025 | 2512 | ||
2026 | - ``populate_sdk_deb``: Supports creation of the SDK given the Debian | 2513 | - :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the Debian |
2027 | package manager. | 2514 | package manager. |
2028 | 2515 | ||
2029 | - ``populate_sdk_rpm``: Supports creation of the SDK given the RPM | 2516 | - :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the RPM |
2030 | package manager. | 2517 | package manager. |
2031 | 2518 | ||
2032 | - ``populate_sdk_ipk``: Supports creation of the SDK given the opkg | 2519 | - :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the opkg |
2033 | (IPK format) package manager. | 2520 | (IPK format) package manager. |
2034 | 2521 | ||
2035 | - ``populate_sdk_ext``: Supports extensible SDK creation under all | 2522 | - :ref:`populate_sdk_ext <ref-classes-populate-sdk-*>`: Supports extensible SDK creation under all |
2036 | package managers. | 2523 | package managers. |
2037 | 2524 | ||
2038 | The ``populate_sdk_base`` class inherits the appropriate | 2525 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class inherits the appropriate |
2039 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on | 2526 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on |
2040 | :term:`IMAGE_PKGTYPE`. | 2527 | :term:`IMAGE_PKGTYPE`. |
2041 | 2528 | ||
2042 | The base class ensures all source and destination directories are | 2529 | The base class ensures all source and destination directories are |
2043 | established and then populates the SDK. After populating the SDK, the | 2530 | established and then populates the SDK. After populating the SDK, the |
2044 | ``populate_sdk_base`` class constructs two sysroots: | 2531 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class constructs two sysroots: |
2045 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which | 2532 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which |
2046 | contains the cross-compiler and associated tooling, and the target, | 2533 | contains the cross-compiler and associated tooling, and the target, |
2047 | which contains a target root filesystem that is configured for the SDK | 2534 | which contains a target root filesystem that is configured for the SDK |
2048 | usage. These two images reside in :term:`SDK_OUTPUT`, | 2535 | usage. These two images reside in :term:`SDK_OUTPUT`, |
2049 | which consists of the following: | 2536 | which consists of the following:: |
2050 | :: | ||
2051 | 2537 | ||
2052 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs | 2538 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs |
2053 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs | 2539 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs |
@@ -2055,9 +2541,9 @@ which consists of the following: | |||
2055 | Finally, the base populate SDK class creates the toolchain environment | 2541 | Finally, the base populate SDK class creates the toolchain environment |
2056 | setup script, the tarball of the SDK, and the installer. | 2542 | setup script, the tarball of the SDK, and the installer. |
2057 | 2543 | ||
2058 | The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and | 2544 | The respective :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`, :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`, and |
2059 | ``populate_sdk_ipk`` classes each support the specific type of SDK. | 2545 | :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>` classes each support the specific type of SDK. |
2060 | These classes are inherited by and used with the ``populate_sdk_base`` | 2546 | These classes are inherited by and used with the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
2061 | class. | 2547 | class. |
2062 | 2548 | ||
2063 | For more information on the cross-development toolchain generation, see | 2549 | For more information on the cross-development toolchain generation, see |
@@ -2072,10 +2558,10 @@ Software Development Kit (eSDK) manual. | |||
2072 | 2558 | ||
2073 | .. _ref-classes-prexport: | 2559 | .. _ref-classes-prexport: |
2074 | 2560 | ||
2075 | ``prexport.bbclass`` | 2561 | ``prexport`` |
2076 | ==================== | 2562 | ============ |
2077 | 2563 | ||
2078 | The ``prexport`` class provides functionality for exporting | 2564 | The :ref:`ref-classes-prexport` class provides functionality for exporting |
2079 | :term:`PR` values. | 2565 | :term:`PR` values. |
2080 | 2566 | ||
2081 | .. note:: | 2567 | .. note:: |
@@ -2085,10 +2571,10 @@ The ``prexport`` class provides functionality for exporting | |||
2085 | 2571 | ||
2086 | .. _ref-classes-primport: | 2572 | .. _ref-classes-primport: |
2087 | 2573 | ||
2088 | ``primport.bbclass`` | 2574 | ``primport`` |
2089 | ==================== | 2575 | ============ |
2090 | 2576 | ||
2091 | The ``primport`` class provides functionality for importing | 2577 | The :ref:`ref-classes-primport` class provides functionality for importing |
2092 | :term:`PR` values. | 2578 | :term:`PR` values. |
2093 | 2579 | ||
2094 | .. note:: | 2580 | .. note:: |
@@ -2098,130 +2584,142 @@ The ``primport`` class provides functionality for importing | |||
2098 | 2584 | ||
2099 | .. _ref-classes-prserv: | 2585 | .. _ref-classes-prserv: |
2100 | 2586 | ||
2101 | ``prserv.bbclass`` | 2587 | ``prserv`` |
2102 | ================== | 2588 | ========== |
2103 | 2589 | ||
2104 | The ``prserv`` class provides functionality for using a :ref:`PR | 2590 | The :ref:`ref-classes-prserv` class provides functionality for using a :ref:`PR |
2105 | service <dev-manual/common-tasks:working with a pr service>` in order to | 2591 | service <dev-manual/packages:working with a pr service>` in order to |
2106 | automatically manage the incrementing of the :term:`PR` | 2592 | automatically manage the incrementing of the :term:`PR` |
2107 | variable for each recipe. | 2593 | variable for each recipe. |
2108 | 2594 | ||
2109 | This class is enabled by default because it is inherited by the | 2595 | This class is enabled by default because it is inherited by the |
2110 | :ref:`package <ref-classes-package>` class. However, the OpenEmbedded | 2596 | :ref:`ref-classes-package` class. However, the OpenEmbedded |
2111 | build system will not enable the functionality of this class unless | 2597 | build system will not enable the functionality of this class unless |
2112 | :term:`PRSERV_HOST` has been set. | 2598 | :term:`PRSERV_HOST` has been set. |
2113 | 2599 | ||
2114 | .. _ref-classes-ptest: | 2600 | .. _ref-classes-ptest: |
2115 | 2601 | ||
2116 | ``ptest.bbclass`` | 2602 | ``ptest`` |
2117 | ================= | 2603 | ========= |
2118 | 2604 | ||
2119 | The ``ptest`` class provides functionality for packaging and installing | 2605 | The :ref:`ref-classes-ptest` class provides functionality for packaging and installing |
2120 | runtime tests for recipes that build software that provides these tests. | 2606 | runtime tests for recipes that build software that provides these tests. |
2121 | 2607 | ||
2122 | This class is intended to be inherited by individual recipes. However, | 2608 | This class is intended to be inherited by individual recipes. However, |
2123 | the class' functionality is largely disabled unless "ptest" appears in | 2609 | the class' functionality is largely disabled unless "ptest" appears in |
2124 | :term:`DISTRO_FEATURES`. See the | 2610 | :term:`DISTRO_FEATURES`. See the |
2125 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | 2611 | ":ref:`dev-manual/packages:testing packages with ptest`" |
2126 | section in the Yocto Project Development Tasks Manual for more information | 2612 | section in the Yocto Project Development Tasks Manual for more information |
2127 | on ptest. | 2613 | on ptest. |
2128 | 2614 | ||
2615 | .. _ref-classes-ptest-cargo: | ||
2616 | |||
2617 | ``ptest-cargo`` | ||
2618 | =============== | ||
2619 | |||
2620 | The :ref:`ref-classes-ptest-cargo` class is a class which extends the | ||
2621 | :ref:`ref-classes-cargo` class and adds ``compile_ptest_cargo`` and | ||
2622 | ``install_ptest_cargo`` steps to respectively build and install | ||
2623 | test suites defined in the ``Cargo.toml`` file, into a dedicated | ||
2624 | ``-ptest`` package. | ||
2625 | |||
2129 | .. _ref-classes-ptest-gnome: | 2626 | .. _ref-classes-ptest-gnome: |
2130 | 2627 | ||
2131 | ``ptest-gnome.bbclass`` | 2628 | ``ptest-gnome`` |
2132 | ======================= | 2629 | =============== |
2133 | 2630 | ||
2134 | Enables package tests (ptests) specifically for GNOME packages, which | 2631 | Enables package tests (ptests) specifically for GNOME packages, which |
2135 | have tests intended to be executed with ``gnome-desktop-testing``. | 2632 | have tests intended to be executed with ``gnome-desktop-testing``. |
2136 | 2633 | ||
2137 | For information on setting up and running ptests, see the | 2634 | For information on setting up and running ptests, see the |
2138 | ":ref:`dev-manual/common-tasks:testing packages with ptest`" | 2635 | ":ref:`dev-manual/packages:testing packages with ptest`" |
2139 | section in the Yocto Project Development Tasks Manual. | 2636 | section in the Yocto Project Development Tasks Manual. |
2140 | 2637 | ||
2141 | .. _ref-classes-python-dir: | 2638 | .. _ref-classes-python3-dir: |
2142 | 2639 | ||
2143 | ``python-dir.bbclass`` | 2640 | ``python3-dir`` |
2144 | ====================== | 2641 | =============== |
2145 | 2642 | ||
2146 | The ``python-dir`` class provides the base version, location, and site | 2643 | The :ref:`ref-classes-python3-dir` class provides the base version, location, and site |
2147 | package location for Python. | 2644 | package location for Python 3. |
2148 | 2645 | ||
2149 | .. _ref-classes-python3native: | 2646 | .. _ref-classes-python3native: |
2150 | 2647 | ||
2151 | ``python3native.bbclass`` | 2648 | ``python3native`` |
2152 | ========================= | 2649 | ================= |
2153 | 2650 | ||
2154 | The ``python3native`` class supports using the native version of Python | 2651 | The :ref:`ref-classes-python3native` class supports using the native version of Python |
2155 | 3 built by the build system rather than support of the version provided | 2652 | 3 built by the build system rather than support of the version provided |
2156 | by the build host. | 2653 | by the build host. |
2157 | 2654 | ||
2158 | .. _ref-classes-pythonnative: | 2655 | .. _ref-classes-python3targetconfig: |
2159 | 2656 | ||
2160 | ``pythonnative.bbclass`` | 2657 | ``python3targetconfig`` |
2161 | ======================== | 2658 | ======================= |
2162 | 2659 | ||
2163 | When inherited by a recipe, the ``pythonnative`` class supports using | 2660 | The :ref:`ref-classes-python3targetconfig` class supports using the native version of Python |
2164 | the native version of Python built by the build system rather than using | 2661 | 3 built by the build system rather than support of the version provided |
2165 | the version provided by the build host. | 2662 | by the build host, except that the configuration for the target machine |
2663 | is accessible (such as correct installation directories). This also adds a | ||
2664 | dependency on target ``python3``, so should only be used where appropriate | ||
2665 | in order to avoid unnecessarily lengthening builds. | ||
2166 | 2666 | ||
2167 | .. _ref-classes-qemu: | 2667 | .. _ref-classes-qemu: |
2168 | 2668 | ||
2169 | ``qemu.bbclass`` | 2669 | ``qemu`` |
2170 | ================ | 2670 | ======== |
2171 | 2671 | ||
2172 | The ``qemu`` class provides functionality for recipes that either need | 2672 | The :ref:`ref-classes-qemu` class provides functionality for recipes that either need |
2173 | QEMU or test for the existence of QEMU. Typically, this class is used to | 2673 | QEMU or test for the existence of QEMU. Typically, this class is used to |
2174 | run programs for a target system on the build host using QEMU's | 2674 | run programs for a target system on the build host using QEMU's |
2175 | application emulation mode. | 2675 | application emulation mode. |
2176 | 2676 | ||
2177 | .. _ref-classes-recipe_sanity: | 2677 | .. _ref-classes-recipe_sanity: |
2178 | 2678 | ||
2179 | ``recipe_sanity.bbclass`` | 2679 | ``recipe_sanity`` |
2180 | ========================= | 2680 | ================= |
2181 | 2681 | ||
2182 | The ``recipe_sanity`` class checks for the presence of any host system | 2682 | The :ref:`ref-classes-recipe_sanity` class checks for the presence of any host system |
2183 | recipe prerequisites that might affect the build (e.g. variables that | 2683 | recipe prerequisites that might affect the build (e.g. variables that |
2184 | are set or software that is present). | 2684 | are set or software that is present). |
2185 | 2685 | ||
2186 | .. _ref-classes-relocatable: | 2686 | .. _ref-classes-relocatable: |
2187 | 2687 | ||
2188 | ``relocatable.bbclass`` | 2688 | ``relocatable`` |
2189 | ======================= | 2689 | =============== |
2190 | 2690 | ||
2191 | The ``relocatable`` class enables relocation of binaries when they are | 2691 | The :ref:`ref-classes-relocatable` class enables relocation of binaries when they are |
2192 | installed into the sysroot. | 2692 | installed into the sysroot. |
2193 | 2693 | ||
2194 | This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class | 2694 | This class makes use of the :ref:`ref-classes-chrpath` class and is used by |
2195 | and is used by both the :ref:`cross <ref-classes-cross>` and | 2695 | both the :ref:`ref-classes-cross` and :ref:`ref-classes-native` classes. |
2196 | :ref:`native <ref-classes-native>` classes. | ||
2197 | 2696 | ||
2198 | .. _ref-classes-remove-libtool: | 2697 | .. _ref-classes-remove-libtool: |
2199 | 2698 | ||
2200 | ``remove-libtool.bbclass`` | 2699 | ``remove-libtool`` |
2201 | ========================== | 2700 | ================== |
2202 | 2701 | ||
2203 | The ``remove-libtool`` class adds a post function to the | 2702 | The :ref:`ref-classes-remove-libtool` class adds a post function to the |
2204 | :ref:`ref-tasks-install` task to remove all ``.la`` files | 2703 | :ref:`ref-tasks-install` task to remove all ``.la`` files |
2205 | installed by ``libtool``. Removing these files results in them being | 2704 | installed by ``libtool``. Removing these files results in them being |
2206 | absent from both the sysroot and target packages. | 2705 | absent from both the sysroot and target packages. |
2207 | 2706 | ||
2208 | If a recipe needs the ``.la`` files to be installed, then the recipe can | 2707 | If a recipe needs the ``.la`` files to be installed, then the recipe can |
2209 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: | 2708 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:: |
2210 | :: | ||
2211 | 2709 | ||
2212 | REMOVE_LIBTOOL_LA = "0" | 2710 | REMOVE_LIBTOOL_LA = "0" |
2213 | 2711 | ||
2214 | .. note:: | 2712 | .. note:: |
2215 | 2713 | ||
2216 | The ``remove-libtool`` class is not enabled by default. | 2714 | The :ref:`ref-classes-remove-libtool` class is not enabled by default. |
2217 | 2715 | ||
2218 | .. _ref-classes-report-error: | 2716 | .. _ref-classes-report-error: |
2219 | 2717 | ||
2220 | ``report-error.bbclass`` | 2718 | ``report-error`` |
2221 | ======================== | 2719 | ================ |
2222 | 2720 | ||
2223 | The ``report-error`` class supports enabling the :ref:`error reporting | 2721 | The :ref:`ref-classes-report-error` class supports enabling the :ref:`error reporting |
2224 | tool <dev-manual/common-tasks:using the error reporting tool>`", | 2722 | tool <dev-manual/error-reporting-tool:using the error reporting tool>`", |
2225 | which allows you to submit build error information to a central database. | 2723 | which allows you to submit build error information to a central database. |
2226 | 2724 | ||
2227 | The class collects debug information for recipe, recipe version, task, | 2725 | The class collects debug information for recipe, recipe version, task, |
@@ -2232,10 +2730,10 @@ are created and stored in | |||
2232 | 2730 | ||
2233 | .. _ref-classes-rm-work: | 2731 | .. _ref-classes-rm-work: |
2234 | 2732 | ||
2235 | ``rm_work.bbclass`` | 2733 | ``rm_work`` |
2236 | =================== | 2734 | =========== |
2237 | 2735 | ||
2238 | The ``rm_work`` class supports deletion of temporary workspace, which | 2736 | The :ref:`ref-classes-rm-work` class supports deletion of temporary workspace, which |
2239 | can ease your hard drive demands during builds. | 2737 | can ease your hard drive demands during builds. |
2240 | 2738 | ||
2241 | The OpenEmbedded build system can use a substantial amount of disk space | 2739 | The OpenEmbedded build system can use a substantial amount of disk space |
@@ -2244,61 +2742,76 @@ under the ``${TMPDIR}/work`` directory for each recipe. Once the build | |||
2244 | system generates the packages for a recipe, the work files for that | 2742 | system generates the packages for a recipe, the work files for that |
2245 | recipe are no longer needed. However, by default, the build system | 2743 | recipe are no longer needed. However, by default, the build system |
2246 | preserves these files for inspection and possible debugging purposes. If | 2744 | preserves these files for inspection and possible debugging purposes. If |
2247 | you would rather have these files deleted to save disk space as the | 2745 | you would rather have these files deleted to save disk space as the build |
2248 | build progresses, you can enable ``rm_work`` by adding the following to | 2746 | progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to |
2249 | your ``local.conf`` file, which is found in the :term:`Build Directory`. | 2747 | your ``local.conf`` file, which is found in the :term:`Build Directory`:: |
2250 | :: | ||
2251 | 2748 | ||
2252 | INHERIT += "rm_work" | 2749 | INHERIT += "rm_work" |
2253 | 2750 | ||
2254 | If you are | 2751 | If you are modifying and building source code out of the work directory for a |
2255 | modifying and building source code out of the work directory for a | 2752 | recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your |
2256 | recipe, enabling ``rm_work`` will potentially result in your changes to | 2753 | changes to the source being lost. To exclude some recipes from having their work |
2257 | the source being lost. To exclude some recipes from having their work | 2754 | directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the |
2258 | directories deleted by ``rm_work``, you can add the names of the recipe | 2755 | recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, |
2259 | or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which | 2756 | which can also be set in your ``local.conf`` file. Here is an example:: |
2260 | can also be set in your ``local.conf`` file. Here is an example: | ||
2261 | :: | ||
2262 | 2757 | ||
2263 | RM_WORK_EXCLUDE += "busybox glibc" | 2758 | RM_WORK_EXCLUDE += "busybox glibc" |
2264 | 2759 | ||
2265 | .. _ref-classes-rootfs*: | 2760 | .. _ref-classes-rootfs*: |
2266 | 2761 | ||
2267 | ``rootfs*.bbclass`` | 2762 | ``rootfs*`` |
2268 | =================== | 2763 | =========== |
2269 | 2764 | ||
2270 | The ``rootfs*`` classes support creating the root filesystem for an | 2765 | The :ref:`ref-classes-rootfs*` classes support creating the root filesystem for an |
2271 | image and consist of the following classes: | 2766 | image and consist of the following classes: |
2272 | 2767 | ||
2273 | - The ``rootfs-postcommands`` class, which defines filesystem | 2768 | - The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class, which defines filesystem |
2274 | post-processing functions for image recipes. | 2769 | post-processing functions for image recipes. |
2275 | 2770 | ||
2276 | - The ``rootfs_deb`` class, which supports creation of root filesystems | 2771 | - The :ref:`rootfs_deb <ref-classes-rootfs*>` class, which supports creation of root filesystems |
2277 | for images built using ``.deb`` packages. | 2772 | for images built using ``.deb`` packages. |
2278 | 2773 | ||
2279 | - The ``rootfs_rpm`` class, which supports creation of root filesystems | 2774 | - The :ref:`rootfs_rpm <ref-classes-rootfs*>` class, which supports creation of root filesystems |
2280 | for images built using ``.rpm`` packages. | 2775 | for images built using ``.rpm`` packages. |
2281 | 2776 | ||
2282 | - The ``rootfs_ipk`` class, which supports creation of root filesystems | 2777 | - The :ref:`rootfs_ipk <ref-classes-rootfs*>` class, which supports creation of root filesystems |
2283 | for images built using ``.ipk`` packages. | 2778 | for images built using ``.ipk`` packages. |
2284 | 2779 | ||
2285 | - The ``rootfsdebugfiles`` class, which installs additional files found | 2780 | - The :ref:`rootfsdebugfiles <ref-classes-rootfs*>` class, which installs additional files found |
2286 | on the build host directly into the root filesystem. | 2781 | on the build host directly into the root filesystem. |
2287 | 2782 | ||
2288 | The root filesystem is created from packages using one of the | 2783 | The root filesystem is created from packages using one of the |
2289 | ``rootfs*.bbclass`` files as determined by the | 2784 | :ref:`ref-classes-rootfs*` files as determined by the :term:`PACKAGE_CLASSES` |
2290 | :term:`PACKAGE_CLASSES` variable. | 2785 | variable. |
2291 | 2786 | ||
2292 | For information on how root filesystem images are created, see the | 2787 | For information on how root filesystem images are created, see the |
2293 | ":ref:`overview-manual/concepts:image generation`" | 2788 | ":ref:`overview-manual/concepts:image generation`" |
2294 | section in the Yocto Project Overview and Concepts Manual. | 2789 | section in the Yocto Project Overview and Concepts Manual. |
2295 | 2790 | ||
2791 | .. _ref-classes-rust: | ||
2792 | |||
2793 | ``rust`` | ||
2794 | ======== | ||
2795 | |||
2796 | The :ref:`ref-classes-rust` class is an internal class which is just used | ||
2797 | in the "rust" recipe, to build the Rust compiler and runtime | ||
2798 | library. Except for this recipe, it is not intended to be used directly. | ||
2799 | |||
2800 | .. _ref-classes-rust-common: | ||
2801 | |||
2802 | ``rust-common`` | ||
2803 | =============== | ||
2804 | |||
2805 | The :ref:`ref-classes-rust-common` class is an internal class to the | ||
2806 | :ref:`ref-classes-cargo_common` and :ref:`ref-classes-rust` classes and is not | ||
2807 | intended to be used directly. | ||
2808 | |||
2296 | .. _ref-classes-sanity: | 2809 | .. _ref-classes-sanity: |
2297 | 2810 | ||
2298 | ``sanity.bbclass`` | 2811 | ``sanity`` |
2299 | ================== | 2812 | ========== |
2300 | 2813 | ||
2301 | The ``sanity`` class checks to see if prerequisite software is present | 2814 | The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present |
2302 | on the host system so that users can be notified of potential problems | 2815 | on the host system so that users can be notified of potential problems |
2303 | that might affect their build. The class also performs basic user | 2816 | that might affect their build. The class also performs basic user |
2304 | configuration checks from the ``local.conf`` configuration file to | 2817 | configuration checks from the ``local.conf`` configuration file to |
@@ -2307,72 +2820,117 @@ usually determines whether to include this class. | |||
2307 | 2820 | ||
2308 | .. _ref-classes-scons: | 2821 | .. _ref-classes-scons: |
2309 | 2822 | ||
2310 | ``scons.bbclass`` | 2823 | ``scons`` |
2311 | ================= | 2824 | ========= |
2312 | 2825 | ||
2313 | The ``scons`` class supports recipes that need to build software that | 2826 | The :ref:`ref-classes-scons` class supports recipes that need to build software |
2314 | uses the SCons build system. You can use the | 2827 | that uses the SCons build system. You can use the :term:`EXTRA_OESCONS` |
2315 | :term:`EXTRA_OESCONS` variable to specify | 2828 | variable to specify additional configuration options you want to pass SCons |
2316 | additional configuration options you want to pass SCons command line. | 2829 | command line. |
2317 | 2830 | ||
2318 | .. _ref-classes-sdl: | 2831 | .. _ref-classes-sdl: |
2319 | 2832 | ||
2320 | ``sdl.bbclass`` | 2833 | ``sdl`` |
2321 | =============== | 2834 | ======= |
2322 | 2835 | ||
2323 | The ``sdl`` class supports recipes that need to build software that uses | 2836 | The :ref:`ref-classes-sdl` class supports recipes that need to build software that uses |
2324 | the Simple DirectMedia Layer (SDL) library. | 2837 | the Simple DirectMedia Layer (SDL) library. |
2325 | 2838 | ||
2326 | .. _ref-classes-setuptools: | 2839 | .. _ref-classes-python_setuptools_build_meta: |
2327 | 2840 | ||
2328 | ``setuptools.bbclass`` | 2841 | ``python_setuptools_build_meta`` |
2329 | ====================== | 2842 | ================================ |
2843 | |||
2844 | The :ref:`ref-classes-python_setuptools_build_meta` class enables building | ||
2845 | Python modules which declare the | ||
2846 | `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant | ||
2847 | ``setuptools.build_meta`` ``build-backend`` in the ``[build-system]`` | ||
2848 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). | ||
2330 | 2849 | ||
2331 | The ``setuptools`` class supports Python version 2.x extensions that use | 2850 | Python modules built with ``setuptools.build_meta`` can be pure Python or |
2332 | build systems based on ``setuptools``. If your recipe uses these build | 2851 | include ``C`` or ``Rust`` extensions). |
2333 | systems, the recipe needs to inherit the ``setuptools`` class. | 2852 | |
2853 | Internally this uses the :ref:`ref-classes-python_pep517` class. | ||
2334 | 2854 | ||
2335 | .. _ref-classes-setuptools3: | 2855 | .. _ref-classes-setuptools3: |
2336 | 2856 | ||
2337 | ``setuptools3.bbclass`` | 2857 | ``setuptools3`` |
2338 | ======================= | 2858 | =============== |
2339 | 2859 | ||
2340 | The ``setuptools3`` class supports Python version 3.x extensions that | 2860 | The :ref:`ref-classes-setuptools3` class supports Python version 3.x extensions |
2341 | use build systems based on ``setuptools3``. If your recipe uses these | 2861 | that use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` |
2342 | build systems, the recipe needs to inherit the ``setuptools3`` class. | 2862 | and have not migrated to the official ``pyproject.toml`` format). If your recipe |
2863 | uses these build systems, the recipe needs to inherit the | ||
2864 | :ref:`ref-classes-setuptools3` class. | ||
2343 | 2865 | ||
2344 | .. _ref-classes-sign_rpm: | 2866 | .. note:: |
2867 | |||
2868 | The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-compile` task now calls | ||
2869 | ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format | ||
2870 | (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__). | ||
2871 | |||
2872 | A consequence of this is that legacy software still using deprecated | ||
2873 | ``distutils`` from the Python standard library cannot be packaged as | ||
2874 | ``wheels``. A common solution is the replace | ||
2875 | ``from distutils.core import setup`` with ``from setuptools import setup``. | ||
2876 | |||
2877 | .. note:: | ||
2345 | 2878 | ||
2346 | ``sign_rpm.bbclass`` | 2879 | The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-install` task now |
2880 | installs the ``wheel`` binary archive. In current versions of | ||
2881 | ``setuptools`` the legacy ``setup.py install`` method is deprecated. If | ||
2882 | the ``setup.py`` cannot be used with wheels, for example it creates files | ||
2883 | outside of the Python module or standard entry points, then | ||
2884 | :ref:`ref-classes-setuptools3_legacy` should be used. | ||
2885 | |||
2886 | .. _ref-classes-setuptools3_legacy: | ||
2887 | |||
2888 | ``setuptools3_legacy`` | ||
2889 | ====================== | ||
2890 | |||
2891 | The :ref:`ref-classes-setuptools3_legacy` class supports | ||
2892 | Python version 3.x extensions that use build systems based on ``setuptools`` | ||
2893 | (e.g. only have a ``setup.py`` and have not migrated to the official | ||
2894 | ``pyproject.toml`` format). Unlike :ref:`ref-classes-setuptools3`, | ||
2895 | this uses the traditional ``setup.py`` ``build`` and ``install`` commands and | ||
2896 | not wheels. This use of ``setuptools`` like this is | ||
2897 | `deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__ | ||
2898 | but still relatively common. | ||
2899 | |||
2900 | .. _ref-classes-setuptools3-base: | ||
2901 | |||
2902 | ``setuptools3-base`` | ||
2347 | ==================== | 2903 | ==================== |
2348 | 2904 | ||
2349 | The ``sign_rpm`` class supports generating signed RPM packages. | 2905 | The :ref:`ref-classes-setuptools3-base` class provides a reusable base for |
2906 | other classes that support building Python version 3.x extensions. If you need | ||
2907 | functionality that is not provided by the :ref:`ref-classes-setuptools3` class, | ||
2908 | you may want to ``inherit setuptools3-base``. Some recipes do not need the tasks | ||
2909 | in the :ref:`ref-classes-setuptools3` class and inherit this class instead. | ||
2350 | 2910 | ||
2351 | .. _ref-classes-sip: | 2911 | .. _ref-classes-sign_rpm: |
2352 | 2912 | ||
2353 | ``sip.bbclass`` | 2913 | ``sign_rpm`` |
2354 | =============== | 2914 | ============ |
2355 | 2915 | ||
2356 | The ``sip`` class supports recipes that build or package SIP-based | 2916 | The :ref:`ref-classes-sign_rpm` class supports generating signed RPM packages. |
2357 | Python bindings. | ||
2358 | 2917 | ||
2359 | .. _ref-classes-siteconfig: | 2918 | .. _ref-classes-siteconfig: |
2360 | 2919 | ||
2361 | ``siteconfig.bbclass`` | 2920 | ``siteconfig`` |
2362 | ====================== | 2921 | ============== |
2363 | 2922 | ||
2364 | The ``siteconfig`` class provides functionality for handling site | 2923 | The :ref:`ref-classes-siteconfig` class provides functionality for handling site |
2365 | configuration. The class is used by the | 2924 | configuration. The class is used by the :ref:`ref-classes-autotools` class to |
2366 | :ref:`autotools <ref-classes-autotools>` class to accelerate the | 2925 | accelerate the :ref:`ref-tasks-configure` task. |
2367 | :ref:`ref-tasks-configure` task. | ||
2368 | 2926 | ||
2369 | .. _ref-classes-siteinfo: | 2927 | .. _ref-classes-siteinfo: |
2370 | 2928 | ||
2371 | ``siteinfo.bbclass`` | 2929 | ``siteinfo`` |
2372 | ==================== | 2930 | ============ |
2373 | 2931 | ||
2374 | The ``siteinfo`` class provides information about the targets that might | 2932 | The :ref:`ref-classes-siteinfo` class provides information about the targets |
2375 | be needed by other classes or recipes. | 2933 | that might be needed by other classes or recipes. |
2376 | 2934 | ||
2377 | As an example, consider Autotools, which can require tests that must | 2935 | As an example, consider Autotools, which can require tests that must |
2378 | execute on the target hardware. Since this is not possible in general | 2936 | execute on the target hardware. Since this is not possible in general |
@@ -2381,20 +2939,20 @@ results so these tests can be skipped over but still make the correct | |||
2381 | values available. The ``meta/site directory`` contains test results | 2939 | values available. The ``meta/site directory`` contains test results |
2382 | sorted into different categories such as architecture, endianness, and | 2940 | sorted into different categories such as architecture, endianness, and |
2383 | the ``libc`` used. Site information provides a list of files containing | 2941 | the ``libc`` used. Site information provides a list of files containing |
2384 | data relevant to the current build in the ``CONFIG_SITE`` variable that | 2942 | data relevant to the current build in the :term:`CONFIG_SITE` variable that |
2385 | Autotools automatically picks up. | 2943 | Autotools automatically picks up. |
2386 | 2944 | ||
2387 | The class also provides variables like ``SITEINFO_ENDIANNESS`` and | 2945 | The class also provides variables like :term:`SITEINFO_ENDIANNESS` and |
2388 | ``SITEINFO_BITS`` that can be used elsewhere in the metadata. | 2946 | :term:`SITEINFO_BITS` that can be used elsewhere in the metadata. |
2389 | 2947 | ||
2390 | .. _ref-classes-sstate: | 2948 | .. _ref-classes-sstate: |
2391 | 2949 | ||
2392 | ``sstate.bbclass`` | 2950 | ``sstate`` |
2393 | ================== | 2951 | ========== |
2394 | 2952 | ||
2395 | The ``sstate`` class provides support for Shared State (sstate). By | 2953 | The :ref:`ref-classes-sstate` class provides support for Shared State (sstate). |
2396 | default, the class is enabled through the | 2954 | By default, the class is enabled through the :term:`INHERIT_DISTRO` variable's |
2397 | :term:`INHERIT_DISTRO` variable's default value. | 2955 | default value. |
2398 | 2956 | ||
2399 | For more information on sstate, see the | 2957 | For more information on sstate, see the |
2400 | ":ref:`overview-manual/concepts:shared state cache`" | 2958 | ":ref:`overview-manual/concepts:shared state cache`" |
@@ -2402,10 +2960,10 @@ section in the Yocto Project Overview and Concepts Manual. | |||
2402 | 2960 | ||
2403 | .. _ref-classes-staging: | 2961 | .. _ref-classes-staging: |
2404 | 2962 | ||
2405 | ``staging.bbclass`` | 2963 | ``staging`` |
2406 | =================== | 2964 | =========== |
2407 | 2965 | ||
2408 | The ``staging`` class installs files into individual recipe work | 2966 | The :ref:`ref-classes-staging` class installs files into individual recipe work |
2409 | directories for sysroots. The class contains the following key tasks: | 2967 | directories for sysroots. The class contains the following key tasks: |
2410 | 2968 | ||
2411 | - The :ref:`ref-tasks-populate_sysroot` task, | 2969 | - The :ref:`ref-tasks-populate_sysroot` task, |
@@ -2418,25 +2976,25 @@ directories for sysroots. The class contains the following key tasks: | |||
2418 | installs the files into the individual recipe work directories (i.e. | 2976 | installs the files into the individual recipe work directories (i.e. |
2419 | :term:`WORKDIR`). | 2977 | :term:`WORKDIR`). |
2420 | 2978 | ||
2421 | The code in the ``staging`` class is complex and basically works in two | 2979 | The code in the :ref:`ref-classes-staging` class is complex and basically works |
2422 | stages: | 2980 | in two stages: |
2423 | 2981 | ||
2424 | - *Stage One:* The first stage addresses recipes that have files they | 2982 | - *Stage One:* The first stage addresses recipes that have files they |
2425 | want to share with other recipes that have dependencies on the | 2983 | want to share with other recipes that have dependencies on the |
2426 | originating recipe. Normally these dependencies are installed through | 2984 | originating recipe. Normally these dependencies are installed through |
2427 | the :ref:`ref-tasks-install` task into | 2985 | the :ref:`ref-tasks-install` task into |
2428 | ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task | 2986 | ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task |
2429 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This | 2987 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This |
2430 | subset of files is controlled by the | 2988 | subset of files is controlled by the |
2431 | :term:`SYSROOT_DIRS`, | 2989 | :term:`SYSROOT_DIRS`, |
2432 | :term:`SYSROOT_DIRS_NATIVE`, and | 2990 | :term:`SYSROOT_DIRS_NATIVE`, and |
2433 | :term:`SYSROOT_DIRS_BLACKLIST` | 2991 | :term:`SYSROOT_DIRS_IGNORE` |
2434 | variables. | 2992 | variables. |
2435 | 2993 | ||
2436 | .. note:: | 2994 | .. note:: |
2437 | 2995 | ||
2438 | Additionally, a recipe can customize the files further by | 2996 | Additionally, a recipe can customize the files further by |
2439 | declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` | 2997 | declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS` |
2440 | variable. | 2998 | variable. |
2441 | 2999 | ||
2442 | A shared state (sstate) object is built from these files and the | 3000 | A shared state (sstate) object is built from these files and the |
@@ -2478,11 +3036,11 @@ stages: | |||
2478 | recommended for general use, the files do allow some issues such | 3036 | recommended for general use, the files do allow some issues such |
2479 | as user creation and module indexes to be addressed. | 3037 | as user creation and module indexes to be addressed. |
2480 | 3038 | ||
2481 | Because recipes can have other dependencies outside of ``DEPENDS`` | 3039 | Because recipes can have other dependencies outside of :term:`DEPENDS` |
2482 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), | 3040 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), |
2483 | the sysroot creation function ``extend_recipe_sysroot`` is also added | 3041 | the sysroot creation function ``extend_recipe_sysroot`` is also added |
2484 | as a pre-function for those tasks whose dependencies are not through | 3042 | as a pre-function for those tasks whose dependencies are not through |
2485 | ``DEPENDS`` but operate similarly. | 3043 | :term:`DEPENDS` but operate similarly. |
2486 | 3044 | ||
2487 | When installing dependencies into the sysroot, the code traverses the | 3045 | When installing dependencies into the sysroot, the code traverses the |
2488 | dependency graph and processes dependencies in exactly the same way | 3046 | dependency graph and processes dependencies in exactly the same way |
@@ -2492,8 +3050,7 @@ stages: | |||
2492 | dependencies traversed or installed. The same sstate dependency code | 3050 | dependencies traversed or installed. The same sstate dependency code |
2493 | is used so that builds should be identical regardless of whether | 3051 | is used so that builds should be identical regardless of whether |
2494 | sstate was used or not. For a closer look, see the | 3052 | sstate was used or not. For a closer look, see the |
2495 | ``setscene_depvalid()`` function in the | 3053 | ``setscene_depvalid()`` function in the :ref:`ref-classes-sstate` class. |
2496 | :ref:`sstate <ref-classes-sstate>` class. | ||
2497 | 3054 | ||
2498 | The build system is careful to maintain manifests of the files it | 3055 | The build system is careful to maintain manifests of the files it |
2499 | installs so that any given dependency can be installed as needed. The | 3056 | installs so that any given dependency can be installed as needed. The |
@@ -2502,11 +3059,11 @@ stages: | |||
2502 | 3059 | ||
2503 | .. _ref-classes-syslinux: | 3060 | .. _ref-classes-syslinux: |
2504 | 3061 | ||
2505 | ``syslinux.bbclass`` | 3062 | ``syslinux`` |
2506 | ==================== | 3063 | ============ |
2507 | 3064 | ||
2508 | The ``syslinux`` class provides syslinux-specific functions for building | 3065 | The :ref:`ref-classes-syslinux` class provides syslinux-specific functions for |
2509 | bootable images. | 3066 | building bootable images. |
2510 | 3067 | ||
2511 | The class supports the following variables: | 3068 | The class supports the following variables: |
2512 | 3069 | ||
@@ -2545,11 +3102,11 @@ The class supports the following variables: | |||
2545 | 3102 | ||
2546 | .. _ref-classes-systemd: | 3103 | .. _ref-classes-systemd: |
2547 | 3104 | ||
2548 | ``systemd.bbclass`` | 3105 | ``systemd`` |
2549 | =================== | 3106 | =========== |
2550 | 3107 | ||
2551 | The ``systemd`` class provides support for recipes that install systemd | 3108 | The :ref:`ref-classes-systemd` class provides support for recipes that install |
2552 | unit files. | 3109 | systemd unit files. |
2553 | 3110 | ||
2554 | The functionality for this class is disabled unless you have "systemd" | 3111 | The functionality for this class is disabled unless you have "systemd" |
2555 | in :term:`DISTRO_FEATURES`. | 3112 | in :term:`DISTRO_FEATURES`. |
@@ -2566,36 +3123,35 @@ You should set :term:`SYSTEMD_SERVICE` to the | |||
2566 | name of the service file. You should also use a package name override to | 3123 | name of the service file. You should also use a package name override to |
2567 | indicate the package to which the value applies. If the value applies to | 3124 | indicate the package to which the value applies. If the value applies to |
2568 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here | 3125 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here |
2569 | is an example from the connman recipe: | 3126 | is an example from the connman recipe:: |
2570 | :: | ||
2571 | 3127 | ||
2572 | SYSTEMD_SERVICE_${PN} = "connman.service" | 3128 | SYSTEMD_SERVICE:${PN} = "connman.service" |
2573 | 3129 | ||
2574 | Services are set up to start on boot automatically | 3130 | Services are set up to start on boot automatically |
2575 | unless you have set | 3131 | unless you have set |
2576 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". | 3132 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". |
2577 | 3133 | ||
2578 | For more information on ``systemd``, see the | 3134 | For more information on :ref:`ref-classes-systemd`, see the |
2579 | ":ref:`dev-manual/common-tasks:selecting an initialization manager`" | 3135 | ":ref:`dev-manual/init-manager:selecting an initialization manager`" |
2580 | section in the Yocto Project Development Tasks Manual. | 3136 | section in the Yocto Project Development Tasks Manual. |
2581 | 3137 | ||
2582 | .. _ref-classes-systemd-boot: | 3138 | .. _ref-classes-systemd-boot: |
2583 | 3139 | ||
2584 | ``systemd-boot.bbclass`` | 3140 | ``systemd-boot`` |
2585 | ======================== | 3141 | ================ |
2586 | 3142 | ||
2587 | The ``systemd-boot`` class provides functions specific to the | 3143 | The :ref:`ref-classes-systemd-boot` class provides functions specific to the |
2588 | systemd-boot bootloader for building bootable images. This is an | 3144 | systemd-boot bootloader for building bootable images. This is an |
2589 | internal class and is not intended to be used directly. | 3145 | internal class and is not intended to be used directly. |
2590 | 3146 | ||
2591 | .. note:: | 3147 | .. note:: |
2592 | 3148 | ||
2593 | The ``systemd-boot`` class is a result from merging the ``gummiboot`` class | 3149 | The :ref:`ref-classes-systemd-boot` class is a result from merging the ``gummiboot`` class |
2594 | used in previous Yocto Project releases with the ``systemd`` project. | 3150 | used in previous Yocto Project releases with the ``systemd`` project. |
2595 | 3151 | ||
2596 | Set the :term:`EFI_PROVIDER` variable to | 3152 | Set the :term:`EFI_PROVIDER` variable to ":ref:`ref-classes-systemd-boot`" to |
2597 | "systemd-boot" to use this class. Doing so creates a standalone EFI | 3153 | use this class. Doing so creates a standalone EFI bootloader that is not |
2598 | bootloader that is not dependent on systemd. | 3154 | dependent on systemd. |
2599 | 3155 | ||
2600 | For information on more variables used and supported in this class, see | 3156 | For information on more variables used and supported in this class, see |
2601 | the :term:`SYSTEMD_BOOT_CFG`, | 3157 | the :term:`SYSTEMD_BOOT_CFG`, |
@@ -2608,76 +3164,71 @@ for more information. | |||
2608 | 3164 | ||
2609 | .. _ref-classes-terminal: | 3165 | .. _ref-classes-terminal: |
2610 | 3166 | ||
2611 | ``terminal.bbclass`` | 3167 | ``terminal`` |
2612 | ==================== | 3168 | ============ |
2613 | 3169 | ||
2614 | The ``terminal`` class provides support for starting a terminal session. | 3170 | The :ref:`ref-classes-terminal` class provides support for starting a terminal |
2615 | The :term:`OE_TERMINAL` variable controls which | 3171 | session. The :term:`OE_TERMINAL` variable controls which terminal emulator is |
2616 | terminal emulator is used for the session. | 3172 | used for the session. |
2617 | 3173 | ||
2618 | Other classes use the ``terminal`` class anywhere a separate terminal | 3174 | Other classes use the :ref:`ref-classes-terminal` class anywhere a separate |
2619 | session needs to be started. For example, the | 3175 | terminal session needs to be started. For example, the :ref:`ref-classes-patch` |
2620 | :ref:`patch <ref-classes-patch>` class assuming | 3176 | class assuming :term:`PATCHRESOLVE` is set to "user", the |
2621 | :term:`PATCHRESOLVE` is set to "user", the | 3177 | :ref:`ref-classes-cml1` class, and the :ref:`ref-classes-devshell` class all |
2622 | :ref:`cml1 <ref-classes-cml1>` class, and the | 3178 | use the :ref:`ref-classes-terminal` class. |
2623 | :ref:`devshell <ref-classes-devshell>` class all use the ``terminal`` | ||
2624 | class. | ||
2625 | 3179 | ||
2626 | .. _ref-classes-testimage*: | 3180 | .. _ref-classes-testimage: |
2627 | 3181 | ||
2628 | ``testimage*.bbclass`` | 3182 | ``testimage`` |
2629 | ====================== | 3183 | ============= |
2630 | 3184 | ||
2631 | The ``testimage*`` classes support running automated tests against | 3185 | The :ref:`ref-classes-testimage` class supports running automated tests against |
2632 | images using QEMU and on actual hardware. The classes handle loading the | 3186 | images using QEMU and on actual hardware. The classes handle loading the |
2633 | tests and starting the image. To use the classes, you need to perform | 3187 | tests and starting the image. To use the classes, you need to perform |
2634 | steps to set up the environment. | 3188 | steps to set up the environment. |
2635 | 3189 | ||
2636 | .. note:: | 3190 | To enable this class, add the following to your configuration:: |
2637 | 3191 | ||
2638 | Best practices include using :term:`IMAGE_CLASSES` rather than | 3192 | IMAGE_CLASSES += "testimage" |
2639 | :term:`INHERIT` to inherit the ``testimage`` class for automated image | ||
2640 | testing. | ||
2641 | 3193 | ||
2642 | The tests are commands that run on the target system over ``ssh``. Each | 3194 | The tests are commands that run on the target system over ``ssh``. Each |
2643 | test is written in Python and makes use of the ``unittest`` module. | 3195 | test is written in Python and makes use of the ``unittest`` module. |
2644 | 3196 | ||
2645 | The ``testimage.bbclass`` runs tests on an image when called using the | 3197 | The :ref:`ref-classes-testimage` class runs tests on an image when called using the |
2646 | following: | 3198 | following:: |
2647 | :: | ||
2648 | 3199 | ||
2649 | $ bitbake -c testimage image | 3200 | $ bitbake -c testimage image |
2650 | 3201 | ||
2651 | The ``testimage-auto`` class | 3202 | Alternatively, if you wish to have tests automatically run for each image |
2652 | runs tests on an image after the image is constructed (i.e. | 3203 | after it is built, you can set :term:`TESTIMAGE_AUTO`:: |
2653 | :term:`TESTIMAGE_AUTO` must be set to "1"). | 3204 | |
3205 | TESTIMAGE_AUTO = "1" | ||
2654 | 3206 | ||
2655 | For information on how to enable, run, and create new tests, see the | 3207 | For information on how to enable, run, and create new tests, see the |
2656 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 3208 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
2657 | section in the Yocto Project Development Tasks Manual. | 3209 | section in the Yocto Project Development Tasks Manual. |
2658 | 3210 | ||
2659 | .. _ref-classes-testsdk: | 3211 | .. _ref-classes-testsdk: |
2660 | 3212 | ||
2661 | ``testsdk.bbclass`` | 3213 | ``testsdk`` |
2662 | =================== | 3214 | =========== |
2663 | 3215 | ||
2664 | This class supports running automated tests against software development | 3216 | This class supports running automated tests against software development |
2665 | kits (SDKs). The ``testsdk`` class runs tests on an SDK when called | 3217 | kits (SDKs). The :ref:`ref-classes-testsdk` class runs tests on an SDK when called |
2666 | using the following: | 3218 | using the following:: |
2667 | :: | ||
2668 | 3219 | ||
2669 | $ bitbake -c testsdk image | 3220 | $ bitbake -c testsdk image |
2670 | 3221 | ||
2671 | .. note:: | 3222 | .. note:: |
2672 | 3223 | ||
2673 | Best practices include using :term:`IMAGE_CLASSES` rather than | 3224 | Best practices include using :term:`IMAGE_CLASSES` rather than |
2674 | :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK | 3225 | :term:`INHERIT` to inherit the :ref:`ref-classes-testsdk` class for automated SDK |
2675 | testing. | 3226 | testing. |
2676 | 3227 | ||
2677 | .. _ref-classes-texinfo: | 3228 | .. _ref-classes-texinfo: |
2678 | 3229 | ||
2679 | ``texinfo.bbclass`` | 3230 | ``texinfo`` |
2680 | =================== | 3231 | =========== |
2681 | 3232 | ||
2682 | This class should be inherited by recipes whose upstream packages invoke | 3233 | This class should be inherited by recipes whose upstream packages invoke |
2683 | the ``texinfo`` utilities at build-time. Native and cross recipes are | 3234 | the ``texinfo`` utilities at build-time. Native and cross recipes are |
@@ -2694,10 +3245,10 @@ host system. | |||
2694 | 3245 | ||
2695 | .. _ref-classes-toaster: | 3246 | .. _ref-classes-toaster: |
2696 | 3247 | ||
2697 | ``toaster.bbclass`` | 3248 | ``toaster`` |
2698 | =================== | 3249 | =========== |
2699 | 3250 | ||
2700 | The ``toaster`` class collects information about packages and images and | 3251 | The :ref:`ref-classes-toaster` class collects information about packages and images and |
2701 | sends them as events that the BitBake user interface can receive. The | 3252 | sends them as events that the BitBake user interface can receive. The |
2702 | class is enabled when the Toaster user interface is running. | 3253 | class is enabled when the Toaster user interface is running. |
2703 | 3254 | ||
@@ -2705,49 +3256,84 @@ This class is not intended to be used directly. | |||
2705 | 3256 | ||
2706 | .. _ref-classes-toolchain-scripts: | 3257 | .. _ref-classes-toolchain-scripts: |
2707 | 3258 | ||
2708 | ``toolchain-scripts.bbclass`` | 3259 | ``toolchain-scripts`` |
2709 | ============================= | 3260 | ===================== |
2710 | 3261 | ||
2711 | The ``toolchain-scripts`` class provides the scripts used for setting up | 3262 | The :ref:`ref-classes-toolchain-scripts` class provides the scripts used for setting up |
2712 | the environment for installed SDKs. | 3263 | the environment for installed SDKs. |
2713 | 3264 | ||
2714 | .. _ref-classes-typecheck: | 3265 | .. _ref-classes-typecheck: |
2715 | 3266 | ||
2716 | ``typecheck.bbclass`` | 3267 | ``typecheck`` |
2717 | ===================== | 3268 | ============= |
2718 | 3269 | ||
2719 | The ``typecheck`` class provides support for validating the values of | 3270 | The :ref:`ref-classes-typecheck` class provides support for validating the values of |
2720 | variables set at the configuration level against their defined types. | 3271 | variables set at the configuration level against their defined types. |
2721 | The OpenEmbedded build system allows you to define the type of a | 3272 | The OpenEmbedded build system allows you to define the type of a |
2722 | variable using the "type" varflag. Here is an example: | 3273 | variable using the "type" varflag. Here is an example:: |
2723 | :: | ||
2724 | 3274 | ||
2725 | IMAGE_FEATURES[type] = "list" | 3275 | IMAGE_FEATURES[type] = "list" |
2726 | 3276 | ||
2727 | .. _ref-classes-uboot-config: | 3277 | .. _ref-classes-uboot-config: |
2728 | 3278 | ||
2729 | ``uboot-config.bbclass`` | 3279 | ``uboot-config`` |
2730 | ======================== | 3280 | ================ |
2731 | 3281 | ||
2732 | The ``uboot-config`` class provides support for U-Boot configuration for | 3282 | The :ref:`ref-classes-uboot-config` class provides support for U-Boot configuration for |
2733 | a machine. Specify the machine in your recipe as follows: | 3283 | a machine. Specify the machine in your recipe as follows:: |
2734 | :: | ||
2735 | 3284 | ||
2736 | UBOOT_CONFIG ??= <default> | 3285 | UBOOT_CONFIG ??= <default> |
2737 | UBOOT_CONFIG[foo] = "config,images" | 3286 | UBOOT_CONFIG[foo] = "config,images,binary" |
2738 | 3287 | ||
2739 | You can also specify the machine using this method: | 3288 | You can also specify the machine using this method:: |
2740 | :: | ||
2741 | 3289 | ||
2742 | UBOOT_MACHINE = "config" | 3290 | UBOOT_MACHINE = "config" |
2743 | 3291 | ||
2744 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional | 3292 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional |
2745 | information. | 3293 | information. |
2746 | 3294 | ||
3295 | .. _ref-classes-uboot-sign: | ||
3296 | |||
3297 | ``uboot-sign`` | ||
3298 | ============== | ||
3299 | |||
3300 | The :ref:`ref-classes-uboot-sign` class provides support for U-Boot verified boot. | ||
3301 | It is intended to be inherited from U-Boot recipes. | ||
3302 | |||
3303 | The variables used by this class are: | ||
3304 | |||
3305 | - :term:`SPL_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when | ||
3306 | building the FIT image. | ||
3307 | - :term:`SPL_SIGN_ENABLE`: enable signing the FIT image. | ||
3308 | - :term:`SPL_SIGN_KEYDIR`: directory containing the signing keys. | ||
3309 | - :term:`SPL_SIGN_KEYNAME`: base filename of the signing keys. | ||
3310 | - :term:`UBOOT_FIT_ADDRESS_CELLS`: ``#address-cells`` value for the FIT image. | ||
3311 | - :term:`UBOOT_FIT_DESC`: description string encoded into the FIT image. | ||
3312 | - :term:`UBOOT_FIT_GENERATE_KEYS`: generate the keys if they don't exist yet. | ||
3313 | - :term:`UBOOT_FIT_HASH_ALG`: hash algorithm for the FIT image. | ||
3314 | - :term:`UBOOT_FIT_KEY_GENRSA_ARGS`: ``openssl genrsa`` arguments. | ||
3315 | - :term:`UBOOT_FIT_KEY_REQ_ARGS`: ``openssl req`` arguments. | ||
3316 | - :term:`UBOOT_FIT_SIGN_ALG`: signature algorithm for the FIT image. | ||
3317 | - :term:`UBOOT_FIT_SIGN_NUMBITS`: size of the private key for FIT image | ||
3318 | signing. | ||
3319 | - :term:`UBOOT_FIT_KEY_SIGN_PKCS`: algorithm for the public key certificate | ||
3320 | for FIT image signing. | ||
3321 | - :term:`UBOOT_FITIMAGE_ENABLE`: enable the generation of a U-Boot FIT image. | ||
3322 | - :term:`UBOOT_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when | ||
3323 | rebuilding the FIT image containing the kernel. | ||
3324 | |||
3325 | See U-Boot's documentation for details about `verified boot | ||
3326 | <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/verified-boot.txt>`__ | ||
3327 | and the `signature process | ||
3328 | <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/signature.txt>`__. | ||
3329 | |||
3330 | See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class | ||
3331 | imitates. | ||
3332 | |||
2747 | .. _ref-classes-uninative: | 3333 | .. _ref-classes-uninative: |
2748 | 3334 | ||
2749 | ``uninative.bbclass`` | 3335 | ``uninative`` |
2750 | ===================== | 3336 | ============= |
2751 | 3337 | ||
2752 | Attempts to isolate the build system from the host distribution's C | 3338 | Attempts to isolate the build system from the host distribution's C |
2753 | library in order to make re-use of native shared state artifacts across | 3339 | library in order to make re-use of native shared state artifacts across |
@@ -2762,21 +3348,21 @@ yourself, publish the resulting tarball (e.g. via HTTP) and set | |||
2762 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an | 3348 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an |
2763 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. | 3349 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. |
2764 | 3350 | ||
2765 | The ``uninative`` class is also used unconditionally by the extensible | 3351 | The :ref:`ref-classes-uninative` class is also used unconditionally by the extensible |
2766 | SDK. When building the extensible SDK, ``uninative-tarball`` is built | 3352 | SDK. When building the extensible SDK, ``uninative-tarball`` is built |
2767 | and the resulting tarball is included within the SDK. | 3353 | and the resulting tarball is included within the SDK. |
2768 | 3354 | ||
2769 | .. _ref-classes-update-alternatives: | 3355 | .. _ref-classes-update-alternatives: |
2770 | 3356 | ||
2771 | ``update-alternatives.bbclass`` | 3357 | ``update-alternatives`` |
2772 | =============================== | 3358 | ======================= |
2773 | 3359 | ||
2774 | The ``update-alternatives`` class helps the alternatives system when | 3360 | The :ref:`ref-classes-update-alternatives` class helps the alternatives system when |
2775 | multiple sources provide the same command. This situation occurs when | 3361 | multiple sources provide the same command. This situation occurs when |
2776 | several programs that have the same or similar function are installed | 3362 | several programs that have the same or similar function are installed |
2777 | with the same name. For example, the ``ar`` command is available from | 3363 | with the same name. For example, the ``ar`` command is available from |
2778 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The | 3364 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The |
2779 | ``update-alternatives`` class handles renaming the binaries so that | 3365 | :ref:`ref-classes-update-alternatives` class handles renaming the binaries so that |
2780 | multiple packages can be installed without conflicts. The ``ar`` command | 3366 | multiple packages can be installed without conflicts. The ``ar`` command |
2781 | still works regardless of which packages are installed or subsequently | 3367 | still works regardless of which packages are installed or subsequently |
2782 | removed. The class renames the conflicting binary in each package and | 3368 | removed. The class renames the conflicting binary in each package and |
@@ -2796,7 +3382,7 @@ To use this class, you need to define a number of variables: | |||
2796 | These variables list alternative commands needed by a package, provide | 3382 | These variables list alternative commands needed by a package, provide |
2797 | pathnames for links, default links for targets, and so forth. For | 3383 | pathnames for links, default links for targets, and so forth. For |
2798 | details on how to use this class, see the comments in the | 3384 | details on how to use this class, see the comments in the |
2799 | :yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes/update-alternatives.bbclass>` | 3385 | :yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes-recipe/update-alternatives.bbclass>` |
2800 | file. | 3386 | file. |
2801 | 3387 | ||
2802 | .. note:: | 3388 | .. note:: |
@@ -2806,43 +3392,42 @@ file. | |||
2806 | 3392 | ||
2807 | .. _ref-classes-update-rc.d: | 3393 | .. _ref-classes-update-rc.d: |
2808 | 3394 | ||
2809 | ``update-rc.d.bbclass`` | 3395 | ``update-rc.d`` |
2810 | ======================= | 3396 | =============== |
2811 | 3397 | ||
2812 | The ``update-rc.d`` class uses ``update-rc.d`` to safely install an | 3398 | The :ref:`ref-classes-update-rc.d` class uses ``update-rc.d`` to safely install an |
2813 | initialization script on behalf of the package. The OpenEmbedded build | 3399 | initialization script on behalf of the package. The OpenEmbedded build |
2814 | system takes care of details such as making sure the script is stopped | 3400 | system takes care of details such as making sure the script is stopped |
2815 | before a package is removed and started when the package is installed. | 3401 | before a package is removed and started when the package is installed. |
2816 | 3402 | ||
2817 | Three variables control this class: ``INITSCRIPT_PACKAGES``, | 3403 | Three variables control this class: :term:`INITSCRIPT_PACKAGES`, |
2818 | ``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links | 3404 | :term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links |
2819 | for details. | 3405 | for details. |
2820 | 3406 | ||
2821 | .. _ref-classes-useradd: | 3407 | .. _ref-classes-useradd: |
2822 | 3408 | ||
2823 | ``useradd*.bbclass`` | 3409 | ``useradd*`` |
2824 | ==================== | 3410 | ============ |
2825 | 3411 | ||
2826 | The ``useradd*`` classes support the addition of users or groups for | 3412 | The :ref:`useradd* <ref-classes-useradd>` classes support the addition of users or groups for |
2827 | usage by the package on the target. For example, if you have packages | 3413 | usage by the package on the target. For example, if you have packages |
2828 | that contain system services that should be run under their own user or | 3414 | that contain system services that should be run under their own user or |
2829 | group, you can use these classes to enable creation of the user or | 3415 | group, you can use these classes to enable creation of the user or |
2830 | group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` | 3416 | group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb |
3417 | </openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>` | ||
2831 | recipe in the :term:`Source Directory` provides a simple | 3418 | recipe in the :term:`Source Directory` provides a simple |
2832 | example that shows how to add three users and groups to two packages. | 3419 | example that shows how to add three users and groups to two packages. |
2833 | See the ``useradd-example.bb`` recipe for more information on how to use | ||
2834 | these classes. | ||
2835 | 3420 | ||
2836 | The ``useradd_base`` class provides basic functionality for user or | 3421 | The :ref:`useradd_base <ref-classes-useradd>` class provides basic functionality for user or |
2837 | groups settings. | 3422 | groups settings. |
2838 | 3423 | ||
2839 | The ``useradd*`` classes support the | 3424 | The :ref:`useradd* <ref-classes-useradd>` classes support the |
2840 | :term:`USERADD_PACKAGES`, | 3425 | :term:`USERADD_PACKAGES`, |
2841 | :term:`USERADD_PARAM`, | 3426 | :term:`USERADD_PARAM`, |
2842 | :term:`GROUPADD_PARAM`, and | 3427 | :term:`GROUPADD_PARAM`, and |
2843 | :term:`GROUPMEMS_PARAM` variables. | 3428 | :term:`GROUPMEMS_PARAM` variables. |
2844 | 3429 | ||
2845 | The ``useradd-staticids`` class supports the addition of users or groups | 3430 | The :ref:`useradd-staticids <ref-classes-useradd>` class supports the addition of users or groups |
2846 | that have static user identification (``uid``) and group identification | 3431 | that have static user identification (``uid``) and group identification |
2847 | (``gid``) values. | 3432 | (``gid``) values. |
2848 | 3433 | ||
@@ -2858,61 +3443,58 @@ set static values, the OpenEmbedded build system looks in | |||
2858 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` | 3443 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` |
2859 | files for the values. | 3444 | files for the values. |
2860 | 3445 | ||
2861 | To use static ``uid`` and ``gid`` values, you need to set some | 3446 | To use static ``uid`` and ``gid`` values, you need to set some variables. See |
2862 | variables. See the :term:`USERADDEXTENSION`, | 3447 | the :term:`USERADDEXTENSION`, :term:`USERADD_UID_TABLES`, |
2863 | :term:`USERADD_UID_TABLES`, | 3448 | :term:`USERADD_GID_TABLES`, and :term:`USERADD_ERROR_DYNAMIC` variables. |
2864 | :term:`USERADD_GID_TABLES`, and | 3449 | You can also see the :ref:`ref-classes-useradd` class for additional |
2865 | :term:`USERADD_ERROR_DYNAMIC` variables. | 3450 | information. |
2866 | You can also see the :ref:`useradd <ref-classes-useradd>` class for | ||
2867 | additional information. | ||
2868 | 3451 | ||
2869 | .. note:: | 3452 | .. note:: |
2870 | 3453 | ||
2871 | You do not use the ``useradd-staticids`` class directly. You either enable | 3454 | You do not use the :ref:`useradd-staticids <ref-classes-useradd>` class directly. You either enable |
2872 | or disable the class by setting the ``USERADDEXTENSION`` variable. If you | 3455 | or disable the class by setting the :term:`USERADDEXTENSION` variable. If you |
2873 | enable or disable the class in a configured system, :term:`TMPDIR` might | 3456 | enable or disable the class in a configured system, :term:`TMPDIR` might |
2874 | contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` | 3457 | contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR` |
2875 | directory will correct this condition. | 3458 | directory will correct this condition. |
2876 | 3459 | ||
2877 | .. _ref-classes-utility-tasks: | 3460 | .. _ref-classes-utility-tasks: |
2878 | 3461 | ||
2879 | ``utility-tasks.bbclass`` | 3462 | ``utility-tasks`` |
2880 | ========================= | 3463 | ================= |
2881 | 3464 | ||
2882 | The ``utility-tasks`` class provides support for various "utility" type | 3465 | The :ref:`ref-classes-utility-tasks` class provides support for various |
2883 | tasks that are applicable to all recipes, such as | 3466 | "utility" type tasks that are applicable to all recipes, such as |
2884 | :ref:`ref-tasks-clean` and | 3467 | :ref:`ref-tasks-clean` and :ref:`ref-tasks-listtasks`. |
2885 | :ref:`ref-tasks-listtasks`. | ||
2886 | 3468 | ||
2887 | This class is enabled by default because it is inherited by the | 3469 | This class is enabled by default because it is inherited by the |
2888 | :ref:`base <ref-classes-base>` class. | 3470 | :ref:`ref-classes-base` class. |
2889 | 3471 | ||
2890 | .. _ref-classes-utils: | 3472 | .. _ref-classes-utils: |
2891 | 3473 | ||
2892 | ``utils.bbclass`` | 3474 | ``utils`` |
2893 | ================= | 3475 | ========= |
2894 | 3476 | ||
2895 | The ``utils`` class provides some useful Python functions that are | 3477 | The :ref:`ref-classes-utils` class provides some useful Python functions that are |
2896 | typically used in inline Python expressions (e.g. ``${@...}``). One | 3478 | typically used in inline Python expressions (e.g. ``${@...}``). One |
2897 | example use is for ``bb.utils.contains()``. | 3479 | example use is for ``bb.utils.contains()``. |
2898 | 3480 | ||
2899 | This class is enabled by default because it is inherited by the | 3481 | This class is enabled by default because it is inherited by the |
2900 | :ref:`base <ref-classes-base>` class. | 3482 | :ref:`ref-classes-base` class. |
2901 | 3483 | ||
2902 | .. _ref-classes-vala: | 3484 | .. _ref-classes-vala: |
2903 | 3485 | ||
2904 | ``vala.bbclass`` | 3486 | ``vala`` |
2905 | ================ | 3487 | ======== |
2906 | 3488 | ||
2907 | The ``vala`` class supports recipes that need to build software written | 3489 | The :ref:`ref-classes-vala` class supports recipes that need to build software written |
2908 | using the Vala programming language. | 3490 | using the Vala programming language. |
2909 | 3491 | ||
2910 | .. _ref-classes-waf: | 3492 | .. _ref-classes-waf: |
2911 | 3493 | ||
2912 | ``waf.bbclass`` | 3494 | ``waf`` |
2913 | =============== | 3495 | ======= |
2914 | 3496 | ||
2915 | The ``waf`` class supports recipes that need to build software that uses | 3497 | The :ref:`ref-classes-waf` class supports recipes that need to build software that uses |
2916 | the Waf build system. You can use the | 3498 | the Waf build system. You can use the |
2917 | :term:`EXTRA_OECONF` or | 3499 | :term:`EXTRA_OECONF` or |
2918 | :term:`PACKAGECONFIG_CONFARGS` variables | 3500 | :term:`PACKAGECONFIG_CONFARGS` variables |