Andrew Geissler | f034379 | 2020-11-18 10:42:21 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2 | |
| 3 | ******* |
| 4 | Classes |
| 5 | ******* |
| 6 | |
| 7 | Class files are used to abstract common functionality and share it |
| 8 | amongst multiple recipe (``.bb``) files. To use a class file, you simply |
| 9 | make sure the recipe inherits the class. In most cases, when a recipe |
| 10 | inherits a class it is enough to enable its features. There are cases, |
| 11 | however, where in the recipe you might need to set variables or override |
| 12 | some default behavior. |
| 13 | |
| 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 |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 16 | ``.bbclass`` and are usually placed in one of a set of subdirectories |
| 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 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 24 | Class files can also be pointed to by |
| 25 | :term:`BUILDDIR` (e.g. ``build/``) in the same way as |
| 26 | ``.conf`` files in the ``conf`` directory. Class files are searched for |
| 27 | in :term:`BBPATH` using the same method by which ``.conf`` |
| 28 | files are searched. |
| 29 | |
| 30 | This chapter discusses only the most useful and important classes. Other |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 31 | classes do exist within the ``meta/classes*`` directories in the Source |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 32 | Directory. You can reference the ``.bbclass`` files directly for more |
| 33 | information. |
| 34 | |
| 35 | .. _ref-classes-allarch: |
| 36 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 37 | ``allarch`` |
| 38 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 39 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 40 | The :ref:`ref-classes-allarch` class is inherited by recipes that do not produce |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 41 | architecture-specific output. The class disables functionality that is |
| 42 | normally needed for recipes that produce executable binaries (such as |
| 43 | building the cross-compiler and a C library as pre-requisites, and |
| 44 | splitting out of debug symbols during packaging). |
| 45 | |
| 46 | .. note:: |
| 47 | |
| 48 | Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that |
| 49 | produce packages that depend on tunings through use of the |
| 50 | :term:`RDEPENDS` and |
| 51 | :term:`TUNE_PKGARCH` variables, should never be |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 52 | configured for all architectures using :ref:`ref-classes-allarch`. This is the case |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 53 | even if the recipes do not produce architecture-specific output. |
| 54 | |
| 55 | Configuring such recipes for all architectures causes the |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 56 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 57 | have different signatures for the machines with different tunings. |
| 58 | Additionally, unnecessary rebuilds occur every time an image for a |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 59 | different :term:`MACHINE` is built even when the recipe never changes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 60 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 61 | By default, all recipes inherit the :ref:`ref-classes-base` and |
| 62 | :ref:`ref-classes-package` classes, which enable |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 63 | functionality needed for recipes that produce executable output. If your |
| 64 | recipe, for example, only produces packages that contain configuration |
| 65 | files, media files, or scripts (e.g. Python and Perl), then it should |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 66 | inherit the :ref:`ref-classes-allarch` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 67 | |
| 68 | .. _ref-classes-archiver: |
| 69 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 70 | ``archiver`` |
| 71 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 72 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 73 | The :ref:`ref-classes-archiver` class supports releasing source code and other |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 74 | materials with the binaries. |
| 75 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 76 | For more details on the source :ref:`ref-classes-archiver`, see the |
| 77 | ":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 78 | section in the Yocto Project Development Tasks Manual. You can also see |
| 79 | the :term:`ARCHIVER_MODE` variable for information |
| 80 | about the variable flags (varflags) that help control archive creation. |
| 81 | |
| 82 | .. _ref-classes-autotools: |
| 83 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 84 | ``autotools*`` |
| 85 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 86 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 87 | The :ref:`autotools* <ref-classes-autotools>` classes support packages built with the |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 88 | :wikipedia:`GNU Autotools <GNU_Autotools>`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 89 | |
| 90 | The ``autoconf``, ``automake``, and ``libtool`` packages bring |
| 91 | standardization. This class defines a set of tasks (e.g. ``configure``, |
| 92 | ``compile`` and so forth) that work for all Autotooled packages. It |
| 93 | should usually be enough to define a few standard variables and then |
| 94 | simply ``inherit autotools``. These classes can also work with software |
| 95 | that emulates Autotools. For more information, see the |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 96 | ":ref:`dev-manual/new-recipe:building an autotooled package`" section |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 97 | in the Yocto Project Development Tasks Manual. |
| 98 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 99 | By default, the :ref:`autotools* <ref-classes-autotools>` classes use out-of-tree builds (i.e. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 100 | ``autotools.bbclass`` building with ``B != S``). |
| 101 | |
| 102 | If the software being built by a recipe does not support using |
| 103 | out-of-tree builds, you should have the recipe inherit the |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 104 | :ref:`autotools-brokensep <ref-classes-autotools>` class. The :ref:`autotools-brokensep <ref-classes-autotools>` class behaves |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 105 | the same as the :ref:`ref-classes-autotools` class but builds with :term:`B` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 106 | == :term:`S`. This method is useful when out-of-tree build |
| 107 | support is either not present or is broken. |
| 108 | |
| 109 | .. note:: |
| 110 | |
| 111 | It is recommended that out-of-tree support be fixed and used if at |
| 112 | all possible. |
| 113 | |
| 114 | It's useful to have some idea of how the tasks defined by the |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 115 | :ref:`autotools* <ref-classes-autotools>` classes work and what they do behind the scenes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 116 | |
Andrew Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 117 | - :ref:`ref-tasks-configure` --- regenerates the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 118 | configure script (using ``autoreconf``) and then launches it with a |
| 119 | standard set of arguments used during cross-compilation. You can pass |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 120 | additional parameters to ``configure`` through the :term:`EXTRA_OECONF` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 121 | or :term:`PACKAGECONFIG_CONFARGS` |
| 122 | variables. |
| 123 | |
Andrew Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 124 | - :ref:`ref-tasks-compile` --- runs ``make`` with |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 125 | arguments that specify the compiler and linker. You can pass |
Andrew Geissler | 5f35090 | 2021-07-23 13:09:54 -0400 | [diff] [blame] | 126 | additional arguments through the :term:`EXTRA_OEMAKE` variable. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 127 | |
Andrew Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 128 | - :ref:`ref-tasks-install` --- runs ``make install`` and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 129 | passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. |
| 130 | |
| 131 | .. _ref-classes-base: |
| 132 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 133 | ``base`` |
| 134 | ======== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 135 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 136 | The :ref:`ref-classes-base` class is special in that every ``.bb`` file implicitly |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 137 | inherits the class. This class contains definitions for standard basic |
| 138 | tasks such as fetching, unpacking, configuring (empty by default), |
| 139 | compiling (runs any ``Makefile`` present), installing (empty by default) |
| 140 | and packaging (empty by default). These classes are often overridden or |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 141 | extended by other classes such as the :ref:`ref-classes-autotools` class or the |
| 142 | :ref:`ref-classes-package` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 143 | |
| 144 | The class also contains some commonly used functions such as |
| 145 | ``oe_runmake``, which runs ``make`` with the arguments specified in |
| 146 | :term:`EXTRA_OEMAKE` variable as well as the |
| 147 | arguments passed directly to ``oe_runmake``. |
| 148 | |
| 149 | .. _ref-classes-bash-completion: |
| 150 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 151 | ``bash-completion`` |
| 152 | =================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 153 | |
| 154 | Sets up packaging and dependencies appropriate for recipes that build |
| 155 | software that includes bash-completion data. |
| 156 | |
| 157 | .. _ref-classes-bin-package: |
| 158 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 159 | ``bin_package`` |
| 160 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 161 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 162 | The :ref:`ref-classes-bin-package` class is a helper class for recipes that extract the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 163 | contents of a binary package (e.g. an RPM) and install those contents |
| 164 | rather than building the binary from source. The binary package is |
| 165 | extracted and new packages in the configured output package format are |
| 166 | created. Extraction and installation of proprietary binaries is a good |
| 167 | example use for this class. |
| 168 | |
| 169 | .. note:: |
| 170 | |
| 171 | For RPMs and other packages that do not contain a subdirectory, you |
| 172 | should specify an appropriate fetcher parameter to point to the |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 173 | subdirectory. For example, if BitBake is using the Git fetcher (``git://``), |
| 174 | the "subpath" parameter limits the checkout to a specific subpath |
| 175 | of the tree. Here is an example where ``${BP}`` is used so that the files |
| 176 | are extracted into the subdirectory expected by the default value of |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 177 | :term:`S`:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 178 | |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 179 | SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 180 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 181 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for |
| 182 | more information on supported BitBake Fetchers. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 183 | |
| 184 | .. _ref-classes-binconfig: |
| 185 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 186 | ``binconfig`` |
| 187 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 188 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 189 | The :ref:`ref-classes-binconfig` class helps to correct paths in shell scripts. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 190 | |
| 191 | Before ``pkg-config`` had become widespread, libraries shipped shell |
| 192 | scripts to give information about the libraries and include paths needed |
| 193 | to build software (usually named ``LIBNAME-config``). This class assists |
| 194 | any recipe using such scripts. |
| 195 | |
| 196 | During staging, the OpenEmbedded build system installs such scripts into |
| 197 | the ``sysroots/`` directory. Inheriting this class results in all paths |
| 198 | in these scripts being changed to point into the ``sysroots/`` directory |
| 199 | so that all builds that use the script use the correct directories for |
| 200 | the cross compiling layout. See the |
| 201 | :term:`BINCONFIG_GLOB` variable for more |
| 202 | information. |
| 203 | |
| 204 | .. _ref-classes-binconfig-disabled: |
| 205 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 206 | ``binconfig-disabled`` |
| 207 | ====================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 208 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 209 | An alternative version of the :ref:`ref-classes-binconfig` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 210 | class, which disables binary configuration scripts by making them return |
| 211 | an error in favor of using ``pkg-config`` to query the information. The |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 212 | scripts to be disabled should be specified using the :term:`BINCONFIG` |
| 213 | variable within the recipe inheriting the class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 214 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 215 | .. _ref-classes-buildhistory: |
| 216 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 217 | ``buildhistory`` |
| 218 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 219 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 220 | The :ref:`ref-classes-buildhistory` class records a history of build output metadata, |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 221 | which can be used to detect possible regressions as well as used for |
| 222 | analysis of the build output. For more information on using Build |
| 223 | History, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 224 | ":ref:`dev-manual/build-quality:maintaining build output quality`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 225 | section in the Yocto Project Development Tasks Manual. |
| 226 | |
| 227 | .. _ref-classes-buildstats: |
| 228 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 229 | ``buildstats`` |
| 230 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 231 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 232 | The :ref:`ref-classes-buildstats` class records performance statistics about each task |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 233 | executed during the build (e.g. elapsed time, CPU usage, and I/O usage). |
| 234 | |
| 235 | When you use this class, the output goes into the |
| 236 | :term:`BUILDSTATS_BASE` directory, which defaults |
| 237 | to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using |
| 238 | ``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading |
| 239 | chart of the entire build process and can be useful for highlighting |
| 240 | bottlenecks. |
| 241 | |
| 242 | Collecting build statistics is enabled by default through the |
| 243 | :term:`USER_CLASSES` variable from your |
| 244 | ``local.conf`` file. Consequently, you do not have to do anything to |
| 245 | enable the class. However, if you want to disable the class, simply |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 246 | remove ":ref:`ref-classes-buildstats`" from the :term:`USER_CLASSES` list. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 247 | |
| 248 | .. _ref-classes-buildstats-summary: |
| 249 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 250 | ``buildstats-summary`` |
| 251 | ====================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 252 | |
| 253 | When inherited globally, prints statistics at the end of the build on |
| 254 | sstate re-use. In order to function, this class requires the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 255 | :ref:`ref-classes-buildstats` class be enabled. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 256 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 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 and a ``src`` |
| 270 | subdirectory. |
| 271 | |
| 272 | You will find a simple example in the |
| 273 | :oe_git:`rust-hello-world_git.bb </openembedded-core/tree/meta/recipes-extended/rust-example/rust-hello-world_git.bb>` |
| 274 | recipe. A more complex example, with package dependencies, is the |
| 275 | :oe_git:`uutils-coreutils </meta-openembedded/tree/meta-oe/recipes-core/uutils-coreutils>` |
| 276 | recipe, which was generated by the `cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ |
| 277 | tool. |
| 278 | |
| 279 | This class inherits the :ref:`ref-classes-cargo_common` class. |
| 280 | |
| 281 | .. _ref-classes-cargo_common: |
| 282 | |
| 283 | ``cargo_common`` |
| 284 | ================ |
| 285 | |
| 286 | The :ref:`ref-classes-cargo_common` class is an internal class |
| 287 | that is not intended to be used directly. |
| 288 | |
| 289 | An exception is the "rust" recipe, to build the Rust compiler and runtime |
| 290 | library, which is built by Cargo but cannot use the :ref:`ref-classes-cargo` |
| 291 | class. This is why this class was introduced. |
| 292 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 293 | .. _ref-classes-ccache: |
| 294 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 295 | .. _ref-classes-cargo-update-recipe-crates: |
| 296 | |
| 297 | ``cargo-update-recipe-crates`` |
| 298 | =============================== |
| 299 | |
| 300 | The :ref:`ref-classes-cargo-update-recipe-crates` class allows |
| 301 | recipe developers to update the list of Cargo crates in :term:`SRC_URI` |
| 302 | by reading the ``Cargo.lock`` file in the source tree. |
| 303 | |
| 304 | To do so, create a recipe for your program, for example using |
| 305 | :doc:`devtool </ref-manual/devtool-reference>`, |
| 306 | make it inherit the :ref:`ref-classes-cargo` and |
| 307 | :ref:`ref-classes-cargo-update-recipe-crates` and run:: |
| 308 | |
| 309 | bitbake -c update_crates recipe |
| 310 | |
| 311 | This creates a ``recipe-crates.inc`` file that you can include in your |
| 312 | recipe:: |
| 313 | |
| 314 | require ${BPN}-crates.inc |
| 315 | |
| 316 | That's also something you can achieve by using the |
| 317 | `cargo-bitbake <https://crates.io/crates/cargo-bitbake>`__ tool. |
| 318 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 319 | ``ccache`` |
| 320 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 321 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 322 | The :ref:`ref-classes-ccache` class enables the C/C++ Compiler Cache for the build. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 323 | This class is used to give a minor performance boost during the build. |
Andrew Geissler | 7e0e3c0 | 2022-02-25 20:34:39 +0000 | [diff] [blame] | 324 | |
| 325 | See https://ccache.samba.org/ for information on the C/C++ Compiler |
| 326 | Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>` |
| 327 | file for details about how to enable this mechanism in your configuration |
| 328 | file, how to disable it for specific recipes, and how to share ``ccache`` |
| 329 | files between builds. |
| 330 | |
| 331 | However, using the class can lead to unexpected side-effects. Thus, using |
| 332 | this class is not recommended. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 333 | |
| 334 | .. _ref-classes-chrpath: |
| 335 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 336 | ``chrpath`` |
| 337 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 338 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 339 | The :ref:`ref-classes-chrpath` class is a wrapper around the "chrpath" utility, which |
| 340 | is used during the build process for :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, and |
| 341 | :ref:`ref-classes-cross-canadian` recipes to change ``RPATH`` records within binaries |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 342 | in order to make them relocatable. |
| 343 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 344 | .. _ref-classes-cmake: |
| 345 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 346 | ``cmake`` |
| 347 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 348 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 349 | The :ref:`ref-classes-cmake` class allows recipes to build software using the |
| 350 | `CMake <https://cmake.org/overview/>`__ build system. You can use the |
| 351 | :term:`EXTRA_OECMAKE` variable to specify additional configuration options to |
| 352 | pass to the ``cmake`` command line. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 353 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 354 | By default, the :ref:`ref-classes-cmake` class uses |
| 355 | `Ninja <https://ninja-build.org/>`__ instead of GNU make for building, which |
| 356 | offers better build performance. If a recipe is broken with Ninja, then the |
| 357 | recipe can set the :term:`OECMAKE_GENERATOR` variable to ``Unix Makefiles`` to |
| 358 | use GNU make instead. |
| 359 | |
| 360 | If you need to install custom CMake toolchain files supplied by the application |
| 361 | being built, you should install them (during :ref:`ref-tasks-install`) to the |
| 362 | preferred CMake Module directory: ``${D}${datadir}/cmake/modules/``. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 363 | |
| 364 | .. _ref-classes-cml1: |
| 365 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 366 | ``cml1`` |
| 367 | ======== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 368 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 369 | The :ref:`ref-classes-cml1` class provides basic support for the Linux kernel style |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 370 | build configuration system. |
| 371 | |
| 372 | .. _ref-classes-compress_doc: |
| 373 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 374 | ``compress_doc`` |
| 375 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 376 | |
| 377 | Enables compression for man pages and info pages. This class is intended |
| 378 | to be inherited globally. The default compression mechanism is gz (gzip) |
| 379 | but you can select an alternative mechanism by setting the |
| 380 | :term:`DOC_COMPRESS` variable. |
| 381 | |
| 382 | .. _ref-classes-copyleft_compliance: |
| 383 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 384 | ``copyleft_compliance`` |
| 385 | ======================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 386 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 387 | The :ref:`ref-classes-copyleft_compliance` class preserves source code for the purposes |
| 388 | of license compliance. This class is an alternative to the :ref:`ref-classes-archiver` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 389 | class and is still used by some users even though it has been deprecated |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 390 | in favor of the :ref:`ref-classes-archiver` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 391 | |
| 392 | .. _ref-classes-copyleft_filter: |
| 393 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 394 | ``copyleft_filter`` |
| 395 | =================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 396 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 397 | A class used by the :ref:`ref-classes-archiver` and |
| 398 | :ref:`ref-classes-copyleft_compliance` classes |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 399 | for filtering licenses. The ``copyleft_filter`` class is an internal |
| 400 | class and is not intended to be used directly. |
| 401 | |
| 402 | .. _ref-classes-core-image: |
| 403 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 404 | ``core-image`` |
| 405 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 406 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 407 | The :ref:`ref-classes-core-image` class provides common definitions for the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 408 | ``core-image-*`` image recipes, such as support for additional |
| 409 | :term:`IMAGE_FEATURES`. |
| 410 | |
| 411 | .. _ref-classes-cpan: |
| 412 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 413 | ``cpan*`` |
| 414 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 415 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 416 | The :ref:`cpan* <ref-classes-cpan>` classes support Perl modules. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 417 | |
| 418 | Recipes for Perl modules are simple. These recipes usually only need to |
| 419 | point to the source's archive and then inherit the proper class file. |
| 420 | Building is split into two methods depending on which method the module |
| 421 | authors used. |
| 422 | |
| 423 | - Modules that use old ``Makefile.PL``-based build system require |
| 424 | ``cpan.bbclass`` in their recipes. |
| 425 | |
| 426 | - Modules that use ``Build.PL``-based build system require using |
| 427 | ``cpan_build.bbclass`` in their recipes. |
| 428 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 429 | Both build methods inherit the :ref:`cpan-base <ref-classes-cpan>` class for basic Perl |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 430 | support. |
| 431 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 432 | .. _ref-classes-create-spdx: |
| 433 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 434 | ``create-spdx`` |
| 435 | =============== |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 436 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 437 | The :ref:`ref-classes-create-spdx` class provides support for |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 438 | automatically creating :term:`SPDX` :term:`SBOM` documents based upon image |
| 439 | and SDK contents. |
| 440 | |
| 441 | This class is meant to be inherited globally from a configuration file:: |
| 442 | |
| 443 | INHERIT += "create-spdx" |
| 444 | |
| 445 | The toplevel :term:`SPDX` output file is generated in JSON format as a |
| 446 | ``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the |
| 447 | :term:`Build Directory`. There are other related files in the same directory, |
| 448 | as well as in ``tmp/deploy/spdx``. |
| 449 | |
| 450 | The exact behaviour of this class, and the amount of output can be controlled |
| 451 | by the :term:`SPDX_PRETTY`, :term:`SPDX_ARCHIVE_PACKAGED`, |
| 452 | :term:`SPDX_ARCHIVE_SOURCES` and :term:`SPDX_INCLUDE_SOURCES` variables. |
| 453 | |
| 454 | See the description of these variables and the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 455 | ":ref:`dev-manual/sbom:creating a software bill of materials`" |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 456 | section in the Yocto Project Development Manual for more details. |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 457 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 458 | .. _ref-classes-cross: |
| 459 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 460 | ``cross`` |
| 461 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 462 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 463 | The :ref:`ref-classes-cross` class provides support for the recipes that build the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 464 | cross-compilation tools. |
| 465 | |
| 466 | .. _ref-classes-cross-canadian: |
| 467 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 468 | ``cross-canadian`` |
| 469 | ================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 470 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 471 | The :ref:`ref-classes-cross-canadian` class provides support for the recipes that build |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 472 | the Canadian Cross-compilation tools for SDKs. See the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 473 | ":ref:`overview-manual/concepts:cross-development toolchain generation`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 474 | section in the Yocto Project Overview and Concepts Manual for more |
| 475 | discussion on these cross-compilation tools. |
| 476 | |
| 477 | .. _ref-classes-crosssdk: |
| 478 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 479 | ``crosssdk`` |
| 480 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 481 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 482 | The :ref:`ref-classes-crosssdk` class provides support for the recipes that build the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 483 | cross-compilation tools used for building SDKs. See the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 484 | ":ref:`overview-manual/concepts:cross-development toolchain generation`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 485 | section in the Yocto Project Overview and Concepts Manual for more |
| 486 | discussion on these cross-compilation tools. |
| 487 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 488 | .. _ref-classes-cve-check: |
| 489 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 490 | ``cve-check`` |
| 491 | ============= |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 492 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 493 | The :ref:`ref-classes-cve-check` class looks for known CVEs (Common Vulnerabilities |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 494 | and Exposures) while building with BitBake. This class is meant to be |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 495 | inherited globally from a configuration file:: |
| 496 | |
| 497 | INHERIT += "cve-check" |
| 498 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 499 | To filter out obsolete CVE database entries which are known not to impact software from Poky and OE-Core, |
| 500 | add following line to the build configuration file:: |
| 501 | |
| 502 | include cve-extra-exclusions.inc |
| 503 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 504 | You can also look for vulnerabilities in specific packages by passing |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 505 | ``-c cve_check`` to BitBake. |
| 506 | |
| 507 | After building the software with Bitbake, CVE check output reports are available in ``tmp/deploy/cve`` |
| 508 | and image specific summaries in ``tmp/deploy/images/*.cve`` or ``tmp/deploy/images/*.json`` files. |
| 509 | |
| 510 | When building, the CVE checker will emit build time warnings for any detected |
| 511 | issues which are in the state ``Unpatched``, meaning that CVE issue seems to affect the software component |
| 512 | and version being compiled and no patches to address the issue are applied. Other states |
| 513 | for detected CVE issues are: ``Patched`` meaning that a patch to address the issue is already |
| 514 | applied, and ``Ignored`` meaning that the issue can be ignored. |
| 515 | |
| 516 | The ``Patched`` state of a CVE issue is detected from patch files with the format |
| 517 | ``CVE-ID.patch``, e.g. ``CVE-2019-20633.patch``, in the :term:`SRC_URI` and using |
| 518 | CVE metadata of format ``CVE: CVE-ID`` in the commit message of the patch file. |
| 519 | |
| 520 | If the recipe lists the ``CVE-ID`` in :term:`CVE_CHECK_IGNORE` variable, then the CVE state is reported |
| 521 | as ``Ignored``. Multiple CVEs can be listed separated by spaces. Example:: |
| 522 | |
| 523 | CVE_CHECK_IGNORE += "CVE-2020-29509 CVE-2020-29511" |
| 524 | |
| 525 | If CVE check reports that a recipe contains false positives or false negatives, these may be |
| 526 | fixed in recipes by adjusting the CVE product name using :term:`CVE_PRODUCT` and :term:`CVE_VERSION` variables. |
| 527 | :term:`CVE_PRODUCT` defaults to the plain recipe name :term:`BPN` which can be adjusted to one or more CVE |
| 528 | database vendor and product pairs using the syntax:: |
| 529 | |
| 530 | CVE_PRODUCT = "flex_project:flex" |
| 531 | |
| 532 | where ``flex_project`` is the CVE database vendor name and ``flex`` is the product name. Similarly |
| 533 | if the default recipe version :term:`PV` does not match the version numbers of the software component |
| 534 | in upstream releases or the CVE database, then the :term:`CVE_VERSION` variable can be used to set the |
| 535 | CVE database compatible version number, for example:: |
| 536 | |
| 537 | CVE_VERSION = "2.39" |
| 538 | |
| 539 | Any bugs or missing or incomplete information in the CVE database entries should be fixed in the CVE database |
| 540 | via the `NVD feedback form <https://nvd.nist.gov/info/contact-form>`__. |
| 541 | |
| 542 | Users should note that security is a process, not a product, and thus also CVE checking, analyzing results, |
| 543 | patching and updating the software should be done as a regular process. The data and assumptions |
| 544 | required for CVE checker to reliably detect issues are frequently broken in various ways. |
| 545 | These can only be detected by reviewing the details of the issues and iterating over the generated reports, |
| 546 | and following what happens in other Linux distributions and in the greater open source community. |
| 547 | |
| 548 | You will find some more details in the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 549 | ":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`" |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 550 | section in the Development Tasks Manual. |
| 551 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 552 | .. _ref-classes-debian: |
| 553 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 554 | ``debian`` |
| 555 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 556 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 557 | The :ref:`ref-classes-debian` class renames output packages so that they follow the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 558 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and |
| 559 | ``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library |
| 560 | name and version as part of the package name. |
| 561 | |
| 562 | If a recipe creates packages for multiple libraries (shared object files |
| 563 | of ``.so`` type), use the :term:`LEAD_SONAME` |
| 564 | variable in the recipe to specify the library on which to apply the |
| 565 | naming scheme. |
| 566 | |
| 567 | .. _ref-classes-deploy: |
| 568 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 569 | ``deploy`` |
| 570 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 571 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 572 | The :ref:`ref-classes-deploy` class handles deploying files to the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 573 | :term:`DEPLOY_DIR_IMAGE` directory. The main |
| 574 | function of this class is to allow the deploy step to be accelerated by |
| 575 | shared state. Recipes that inherit this class should define their own |
| 576 | :ref:`ref-tasks-deploy` function to copy the files to be |
| 577 | deployed to :term:`DEPLOYDIR`, and use ``addtask`` to |
| 578 | add the task at the appropriate place, which is usually after |
| 579 | :ref:`ref-tasks-compile` or |
| 580 | :ref:`ref-tasks-install`. The class then takes care of |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 581 | staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 582 | |
| 583 | .. _ref-classes-devshell: |
| 584 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 585 | ``devshell`` |
| 586 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 587 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 588 | The :ref:`ref-classes-devshell` class adds the :ref:`ref-tasks-devshell` task. Distribution |
| 589 | policy dictates whether to include this class. See the ":ref:`dev-manual/development-shell:using a development shell`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 590 | section in the Yocto Project Development Tasks Manual for more |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 591 | information about using :ref:`ref-classes-devshell`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 592 | |
| 593 | .. _ref-classes-devupstream: |
| 594 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 595 | ``devupstream`` |
| 596 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 597 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 598 | The :ref:`ref-classes-devupstream` class uses |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 599 | :term:`BBCLASSEXTEND` to add a variant of the |
| 600 | recipe that fetches from an alternative URI (e.g. Git) instead of a |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 601 | tarball. Following is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 602 | |
| 603 | BBCLASSEXTEND = "devupstream:target" |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 604 | SRC_URI:class-devupstream = "git://git.example.com/example;branch=main" |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 605 | SRCREV:class-devupstream = "abcd1234" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 606 | |
| 607 | Adding the above statements to your recipe creates a variant that has |
| 608 | :term:`DEFAULT_PREFERENCE` set to "-1". |
| 609 | Consequently, you need to select the variant of the recipe to use it. |
| 610 | Any development-specific adjustments can be done by using the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 611 | ``class-devupstream`` override. Here is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 612 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 613 | DEPENDS:append:class-devupstream = " gperf-native" |
| 614 | do_configure:prepend:class-devupstream() { |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 615 | touch ${S}/README |
| 616 | } |
| 617 | |
| 618 | The class |
| 619 | currently only supports creating a development variant of the target |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 620 | recipe, not :ref:`ref-classes-native` or :ref:`ref-classes-nativesdk` variants. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 621 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 622 | The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 623 | support for :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk` variants. Consequently, this |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 624 | functionality can be added in a future release. |
| 625 | |
| 626 | Support for other version control systems such as Subversion is limited |
| 627 | due to BitBake's automatic fetch dependencies (e.g. |
| 628 | ``subversion-native``). |
| 629 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 630 | .. _ref-classes-externalsrc: |
| 631 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 632 | ``externalsrc`` |
| 633 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 634 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 635 | The :ref:`ref-classes-externalsrc` class supports building software from source code |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 636 | that is external to the OpenEmbedded build system. Building software |
| 637 | from an external source tree means that the build system's normal fetch, |
| 638 | unpack, and patch process is not used. |
| 639 | |
| 640 | By default, the OpenEmbedded build system uses the :term:`S` |
| 641 | and :term:`B` variables to locate unpacked recipe source code |
| 642 | and to build it, respectively. When your recipe inherits the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 643 | :ref:`ref-classes-externalsrc` class, you use the |
| 644 | :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` variables to |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 645 | ultimately define :term:`S` and :term:`B`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 646 | |
| 647 | By default, this class expects the source code to support recipe builds |
| 648 | that use the :term:`B` variable to point to the directory in |
| 649 | which the OpenEmbedded build system places the generated objects built |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 650 | from the recipes. By default, the :term:`B` directory is set to the |
| 651 | following, which is separate from the source directory (:term:`S`):: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 652 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 653 | ${WORKDIR}/${BPN}-{PV}/ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 654 | |
| 655 | See these variables for more information: |
| 656 | :term:`WORKDIR`, :term:`BPN`, and |
| 657 | :term:`PV`, |
| 658 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 659 | For more information on the :ref:`ref-classes-externalsrc` class, see the comments in |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 660 | ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 661 | For information on how to use the :ref:`ref-classes-externalsrc` class, see the |
| 662 | ":ref:`dev-manual/building:building software from an external source`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 663 | section in the Yocto Project Development Tasks Manual. |
| 664 | |
| 665 | .. _ref-classes-extrausers: |
| 666 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 667 | ``extrausers`` |
| 668 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 669 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 670 | The :ref:`ref-classes-extrausers` class allows additional user and group configuration |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 671 | to be applied at the image level. Inheriting this class either globally |
| 672 | or from an image recipe allows additional user and group operations to |
| 673 | be performed using the |
| 674 | :term:`EXTRA_USERS_PARAMS` variable. |
| 675 | |
| 676 | .. note:: |
| 677 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 678 | The user and group operations added using the :ref:`ref-classes-extrausers` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 679 | class are not tied to a specific recipe outside of the recipe for the |
| 680 | image. Thus, the operations can be performed across the image as a |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 681 | whole. Use the :ref:`ref-classes-useradd` class to add user and group |
| 682 | configuration to a specific recipe. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 683 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 684 | Here is an example that uses this class in an image recipe:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 685 | |
| 686 | inherit extrausers |
| 687 | EXTRA_USERS_PARAMS = "\ |
| 688 | useradd -p '' tester; \ |
| 689 | groupadd developers; \ |
| 690 | userdel nobody; \ |
| 691 | groupdel -g video; \ |
| 692 | groupmod -g 1020 developers; \ |
| 693 | usermod -s /bin/sh tester; \ |
| 694 | " |
| 695 | |
| 696 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 697 | passwords. First on host, create the (escaped) password hash:: |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 698 | |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 699 | printf "%q" $(mkpasswd -m sha256crypt tester01) |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 700 | |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 701 | The resulting hash is set to a variable and used in ``useradd`` command parameters:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 702 | |
| 703 | inherit extrausers |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 704 | PASSWD = "\$X\$ABC123\$A-Long-Hash" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 705 | EXTRA_USERS_PARAMS = "\ |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 706 | useradd -p '${PASSWD}' tester-jim; \ |
| 707 | useradd -p '${PASSWD}' tester-sue; \ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 708 | " |
| 709 | |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 710 | Finally, here is an example that sets the root password:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 711 | |
| 712 | inherit extrausers |
| 713 | EXTRA_USERS_PARAMS = "\ |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 714 | usermod -p '${PASSWD}' root; \ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 715 | " |
| 716 | |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 717 | .. note:: |
| 718 | |
| 719 | From a security perspective, hardcoding a default password is not |
Andrew Geissler | 87f5cff | 2022-09-30 13:13:31 -0500 | [diff] [blame] | 720 | generally a good idea or even legal in some jurisdictions. It is |
| 721 | recommended that you do not do this if you are building a production |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 722 | image. |
| 723 | |
| 724 | |
Andrew Geissler | 6ce62a2 | 2020-11-30 19:58:47 -0600 | [diff] [blame] | 725 | .. _ref-classes-features_check: |
| 726 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 727 | ``features_check`` |
| 728 | ================== |
Andrew Geissler | 6ce62a2 | 2020-11-30 19:58:47 -0600 | [diff] [blame] | 729 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 730 | The :ref:`ref-classes-features_check` class allows individual recipes to check |
| 731 | for required and conflicting :term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` |
| 732 | or :term:`COMBINED_FEATURES`. |
Andrew Geissler | 6ce62a2 | 2020-11-30 19:58:47 -0600 | [diff] [blame] | 733 | |
| 734 | This class provides support for the following variables: |
| 735 | |
| 736 | - :term:`REQUIRED_DISTRO_FEATURES` |
| 737 | - :term:`CONFLICT_DISTRO_FEATURES` |
| 738 | - :term:`ANY_OF_DISTRO_FEATURES` |
| 739 | - ``REQUIRED_MACHINE_FEATURES`` |
| 740 | - ``CONFLICT_MACHINE_FEATURES`` |
| 741 | - ``ANY_OF_MACHINE_FEATURES`` |
| 742 | - ``REQUIRED_COMBINED_FEATURES`` |
| 743 | - ``CONFLICT_COMBINED_FEATURES`` |
| 744 | - ``ANY_OF_COMBINED_FEATURES`` |
| 745 | |
| 746 | If any conditions specified in the recipe using the above |
| 747 | variables are not met, the recipe will be skipped, and if the |
| 748 | build system attempts to build the recipe then an error will be |
| 749 | triggered. |
| 750 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 751 | .. _ref-classes-fontcache: |
| 752 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 753 | ``fontcache`` |
| 754 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 755 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 756 | The :ref:`ref-classes-fontcache` class generates the proper post-install and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 757 | post-remove (postinst and postrm) scriptlets for font packages. These |
| 758 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts |
| 759 | to the font information cache. Since the cache files are |
| 760 | architecture-specific, ``fc-cache`` runs using QEMU if the postinst |
| 761 | scriptlets need to be run on the build host during image creation. |
| 762 | |
| 763 | If the fonts being installed are in packages other than the main |
| 764 | package, set :term:`FONT_PACKAGES` to specify the |
| 765 | packages containing the fonts. |
| 766 | |
| 767 | .. _ref-classes-fs-uuid: |
| 768 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 769 | ``fs-uuid`` |
| 770 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 771 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 772 | The :ref:`ref-classes-fs-uuid` class extracts UUID from |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 773 | ``${``\ :term:`ROOTFS`\ ``}``, which must have been built |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 774 | by the time that this function gets called. The :ref:`ref-classes-fs-uuid` class only |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 775 | works on ``ext`` file systems and depends on ``tune2fs``. |
| 776 | |
| 777 | .. _ref-classes-gconf: |
| 778 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 779 | ``gconf`` |
| 780 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 781 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 782 | The :ref:`ref-classes-gconf` class provides common functionality for recipes that need |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 783 | to install GConf schemas. The schemas will be put into a separate |
| 784 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created |
| 785 | automatically when this class is inherited. This package uses the |
| 786 | appropriate post-install and post-remove (postinst/postrm) scriptlets to |
| 787 | register and unregister the schemas in the target image. |
| 788 | |
| 789 | .. _ref-classes-gettext: |
| 790 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 791 | ``gettext`` |
| 792 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 793 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 794 | The :ref:`ref-classes-gettext` class provides support for building |
| 795 | software that uses the GNU ``gettext`` internationalization and localization |
| 796 | system. All recipes building software that use ``gettext`` should inherit this |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 797 | class. |
| 798 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 799 | .. _ref-classes-github-releases: |
| 800 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 801 | ``github-releases`` |
| 802 | =================== |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 803 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 804 | For recipes that fetch release tarballs from github, the :ref:`ref-classes-github-releases` |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 805 | class sets up a standard way for checking available upstream versions |
| 806 | (to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)). |
| 807 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 808 | To use it, add ":ref:`ref-classes-github-releases`" to the inherit line in the recipe, |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 809 | and if the default value of :term:`GITHUB_BASE_URI` is not suitable, |
| 810 | then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}`` |
| 811 | in the value you set for :term:`SRC_URI` within the recipe. |
| 812 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 813 | .. _ref-classes-gnomebase: |
| 814 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 815 | ``gnomebase`` |
| 816 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 817 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 818 | The :ref:`ref-classes-gnomebase` class is the base class for recipes that build |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 819 | software from the GNOME stack. This class sets |
| 820 | :term:`SRC_URI` to download the source from the GNOME |
| 821 | mirrors as well as extending :term:`FILES` with the typical |
| 822 | GNOME installation paths. |
| 823 | |
Andrew Geissler | c5535c9 | 2023-01-27 16:10:19 -0600 | [diff] [blame] | 824 | .. _ref-classes-go: |
| 825 | |
| 826 | ``go`` |
| 827 | ====== |
| 828 | |
| 829 | The :ref:`ref-classes-go` class supports building Go programs. The behavior of |
| 830 | this class is controlled by the mandatory :term:`GO_IMPORT` variable, and |
| 831 | by the optional :term:`GO_INSTALL` and :term:`GO_INSTALL_FILTEROUT` ones. |
| 832 | |
| 833 | To build a Go program with the Yocto Project, you can use the |
| 834 | :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` |
| 835 | recipe as an example. |
| 836 | |
| 837 | .. _ref-classes-go-mod: |
| 838 | |
| 839 | ``go-mod`` |
| 840 | ========== |
| 841 | |
| 842 | The :ref:`ref-classes-go-mod` class allows to use Go modules, and inherits the |
| 843 | :ref:`ref-classes-go` class. |
| 844 | |
| 845 | See the associated :term:`GO_WORKDIR` variable. |
| 846 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 847 | .. _ref-classes-gobject-introspection: |
| 848 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 849 | ``gobject-introspection`` |
| 850 | ========================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 851 | |
| 852 | Provides support for recipes building software that supports GObject |
| 853 | introspection. This functionality is only enabled if the |
| 854 | "gobject-introspection-data" feature is in |
| 855 | :term:`DISTRO_FEATURES` as well as |
| 856 | "qemu-usermode" being in |
| 857 | :term:`MACHINE_FEATURES`. |
| 858 | |
| 859 | .. note:: |
| 860 | |
Andrew Geissler | fc113ea | 2023-03-31 09:59:46 -0500 | [diff] [blame^] | 861 | This functionality is :ref:`backfilled <ref-features-backfill>` by default |
| 862 | and, if not applicable, should be disabled through |
| 863 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 864 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 865 | |
| 866 | .. _ref-classes-grub-efi: |
| 867 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 868 | ``grub-efi`` |
| 869 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 870 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 871 | The :ref:`ref-classes-grub-efi` class provides ``grub-efi``-specific functions for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 872 | building bootable images. |
| 873 | |
| 874 | This class supports several variables: |
| 875 | |
| 876 | - :term:`INITRD`: Indicates list of filesystem images to |
| 877 | concatenate and use as an initial RAM disk (initrd) (optional). |
| 878 | |
| 879 | - :term:`ROOTFS`: Indicates a filesystem image to include |
| 880 | as the root filesystem (optional). |
| 881 | |
| 882 | - :term:`GRUB_GFXSERIAL`: Set this to "1" to have |
| 883 | graphics and serial in the boot menu. |
| 884 | |
| 885 | - :term:`LABELS`: A list of targets for the automatic |
| 886 | configuration. |
| 887 | |
| 888 | - :term:`APPEND`: An override list of append strings for |
| 889 | each ``LABEL``. |
| 890 | |
| 891 | - :term:`GRUB_OPTS`: Additional options to add to the |
| 892 | configuration (optional). Options are delimited using semi-colon |
| 893 | characters (``;``). |
| 894 | |
| 895 | - :term:`GRUB_TIMEOUT`: Timeout before executing |
| 896 | the default ``LABEL`` (optional). |
| 897 | |
| 898 | .. _ref-classes-gsettings: |
| 899 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 900 | ``gsettings`` |
| 901 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 902 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 903 | The :ref:`ref-classes-gsettings` class provides common functionality for recipes that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 904 | need to install GSettings (glib) schemas. The schemas are assumed to be |
| 905 | part of the main package. Appropriate post-install and post-remove |
| 906 | (postinst/postrm) scriptlets are added to register and unregister the |
| 907 | schemas in the target image. |
| 908 | |
| 909 | .. _ref-classes-gtk-doc: |
| 910 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 911 | ``gtk-doc`` |
| 912 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 913 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 914 | The :ref:`ref-classes-gtk-doc` class is a helper class to pull in the appropriate |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 915 | ``gtk-doc`` dependencies and disable ``gtk-doc``. |
| 916 | |
| 917 | .. _ref-classes-gtk-icon-cache: |
| 918 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 919 | ``gtk-icon-cache`` |
| 920 | ================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 921 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 922 | The :ref:`ref-classes-gtk-icon-cache` class generates the proper post-install and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 923 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and |
| 924 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add |
| 925 | the fonts to GTK+'s icon cache. Since the cache files are |
| 926 | architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if |
| 927 | the postinst scriptlets need to be run on the build host during image |
| 928 | creation. |
| 929 | |
| 930 | .. _ref-classes-gtk-immodules-cache: |
| 931 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 932 | ``gtk-immodules-cache`` |
| 933 | ======================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 934 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 935 | The :ref:`ref-classes-gtk-immodules-cache` class generates the proper post-install and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 936 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ |
| 937 | input method modules for virtual keyboards. These scriptlets call |
| 938 | ``gtk-update-icon-cache`` to add the input method modules to the cache. |
| 939 | Since the cache files are architecture-specific, |
| 940 | ``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets |
| 941 | need to be run on the build host during image creation. |
| 942 | |
| 943 | If the input method modules being installed are in packages other than |
| 944 | the main package, set |
| 945 | :term:`GTKIMMODULES_PACKAGES` to specify |
| 946 | the packages containing the modules. |
| 947 | |
| 948 | .. _ref-classes-gzipnative: |
| 949 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 950 | ``gzipnative`` |
| 951 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 952 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 953 | The :ref:`ref-classes-gzipnative` class enables the use of different native versions of |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 954 | ``gzip`` and ``pigz`` rather than the versions of these tools from the |
| 955 | build host. |
| 956 | |
| 957 | .. _ref-classes-icecc: |
| 958 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 959 | ``icecc`` |
| 960 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 961 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 962 | The :ref:`ref-classes-icecc` class supports |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 963 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates |
| 964 | taking compile jobs and distributing them among remote machines. |
| 965 | |
| 966 | The class stages directories with symlinks from ``gcc`` and ``g++`` to |
| 967 | ``icecc``, for both native and cross compilers. Depending on each |
| 968 | configure or compile, the OpenEmbedded build system adds the directories |
| 969 | at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and |
Andrew Geissler | 87f5cff | 2022-09-30 13:13:31 -0500 | [diff] [blame] | 970 | ``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 971 | compilers, respectively. |
| 972 | |
| 973 | For the cross compiler, the class creates a ``tar.gz`` file that |
| 974 | contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which |
| 975 | is the version of the cross-compiler used in the cross-development |
| 976 | toolchain, accordingly. |
| 977 | |
Andrew Geissler | 87f5cff | 2022-09-30 13:13:31 -0500 | [diff] [blame] | 978 | The class handles all three different compile stages (i.e native, |
| 979 | cross-kernel and target) and creates the necessary environment |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 980 | ``tar.gz`` file to be used by the remote machines. The class also |
| 981 | supports SDK generation. |
| 982 | |
| 983 | If :term:`ICECC_PATH` is not set in your |
| 984 | ``local.conf`` file, then the class tries to locate the ``icecc`` binary |
| 985 | using ``which``. If :term:`ICECC_ENV_EXEC` is set |
| 986 | in your ``local.conf`` file, the variable should point to the |
| 987 | ``icecc-create-env`` script provided by the user. If you do not point to |
| 988 | a user-provided script, the build system uses the default script |
Andrew Geissler | 87f5cff | 2022-09-30 13:13:31 -0500 | [diff] [blame] | 989 | provided by the recipe :oe_git:`icecc-create-env_0.1.bb |
| 990 | </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 991 | |
| 992 | .. note:: |
| 993 | |
| 994 | This script is a modified version and not the one that comes with |
Andrew Geissler | 87f5cff | 2022-09-30 13:13:31 -0500 | [diff] [blame] | 995 | ``icecream``. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 996 | |
| 997 | If you do not want the Icecream distributed compile support to apply to |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 998 | specific recipes or classes, you can ask them to be ignored by Icecream |
| 999 | by listing the recipes and classes using the |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 1000 | :term:`ICECC_RECIPE_DISABLE` and |
| 1001 | :term:`ICECC_CLASS_DISABLE` variables, |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1002 | respectively, in your ``local.conf`` file. Doing so causes the |
| 1003 | OpenEmbedded build system to handle these compilations locally. |
| 1004 | |
| 1005 | Additionally, you can list recipes using the |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 1006 | :term:`ICECC_RECIPE_ENABLE` variable in |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1007 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes |
| 1008 | using an empty :term:`PARALLEL_MAKE` variable. |
| 1009 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1010 | Inheriting the :ref:`ref-classes-icecc` class changes all sstate signatures. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1011 | Consequently, if a development team has a dedicated build system that |
| 1012 | populates :term:`SSTATE_MIRRORS` and they want to |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1013 | reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1014 | system need to either inherit the :ref:`ref-classes-icecc` class or nobody should. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1015 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1016 | At the distribution level, you can inherit the :ref:`ref-classes-icecc` class to be |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1017 | sure that all builders start with the same sstate signatures. After |
| 1018 | inheriting the class, you can then disable the feature by setting the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1019 | :term:`ICECC_DISABLED` variable to "1" as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1020 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1021 | INHERIT_DISTRO:append = " icecc" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1022 | ICECC_DISABLED ??= "1" |
| 1023 | |
| 1024 | This practice |
| 1025 | makes sure everyone is using the same signatures but also requires |
| 1026 | individuals that do want to use Icecream to enable the feature |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1027 | individually as follows in your ``local.conf`` file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1028 | |
| 1029 | ICECC_DISABLED = "" |
| 1030 | |
| 1031 | .. _ref-classes-image: |
| 1032 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1033 | ``image`` |
| 1034 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1035 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1036 | The :ref:`ref-classes-image` class helps support creating images in different formats. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1037 | First, the root filesystem is created from packages using one of the |
| 1038 | ``rootfs*.bbclass`` files (depending on the package format used) and |
| 1039 | then one or more image files are created. |
| 1040 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1041 | - The :term:`IMAGE_FSTYPES` variable controls the types of images to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1042 | generate. |
| 1043 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1044 | - The :term:`IMAGE_INSTALL` variable controls the list of packages to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1045 | install into the image. |
| 1046 | |
| 1047 | For information on customizing images, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1048 | ":ref:`dev-manual/customizing-images:customizing images`" section |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1049 | in the Yocto Project Development Tasks Manual. For information on how |
| 1050 | images are created, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 1051 | ":ref:`overview-manual/concepts:images`" section in the |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1052 | Yocto Project Overview and Concepts Manual. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1053 | |
| 1054 | .. _ref-classes-image-buildinfo: |
| 1055 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1056 | ``image-buildinfo`` |
| 1057 | =================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1058 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1059 | The :ref:`ref-classes-image-buildinfo` class writes a plain text file containing |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1060 | build information to the target filesystem at ``${sysconfdir}/buildinfo`` |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 1061 | by default (as specified by :term:`IMAGE_BUILDINFO_FILE`). |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1062 | This can be useful for manually determining the origin of any given |
| 1063 | image. It writes out two sections: |
| 1064 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1065 | #. `Build Configuration`: a list of variables and their values (specified |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1066 | by :term:`IMAGE_BUILDINFO_VARS`, which defaults to :term:`DISTRO` and |
| 1067 | :term:`DISTRO_VERSION`) |
| 1068 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1069 | #. `Layer Revisions`: the revisions of all of the layers used in the |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1070 | build. |
| 1071 | |
| 1072 | Additionally, when building an SDK it will write the same contents |
| 1073 | to ``/buildinfo`` by default (as specified by |
| 1074 | :term:`SDK_BUILDINFO_FILE`). |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1075 | |
| 1076 | .. _ref-classes-image_types: |
| 1077 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1078 | ``image_types`` |
| 1079 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1080 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1081 | The :ref:`ref-classes-image_types` class defines all of the standard image output types |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1082 | that you can enable through the |
| 1083 | :term:`IMAGE_FSTYPES` variable. You can use this |
| 1084 | class as a reference on how to add support for custom image output |
| 1085 | types. |
| 1086 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1087 | By default, the :ref:`ref-classes-image` class automatically |
| 1088 | enables the :ref:`ref-classes-image_types` class. The :ref:`ref-classes-image` class uses the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1089 | ``IMGCLASSES`` variable as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1090 | |
| 1091 | IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" |
| 1092 | IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" |
| 1093 | IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" |
| 1094 | IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" |
| 1095 | IMGCLASSES += "image_types_wic" |
| 1096 | IMGCLASSES += "rootfs-postcommands" |
| 1097 | IMGCLASSES += "image-postinst-intercepts" |
| 1098 | inherit ${IMGCLASSES} |
| 1099 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1100 | The :ref:`ref-classes-image_types` class also handles conversion and compression of images. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1101 | |
| 1102 | .. note:: |
| 1103 | |
| 1104 | To build a VMware VMDK image, you need to add "wic.vmdk" to |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1105 | :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1106 | Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1107 | |
| 1108 | .. _ref-classes-image-live: |
| 1109 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1110 | ``image-live`` |
| 1111 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1112 | |
| 1113 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live |
| 1114 | images contain syslinux for legacy booting, as well as the bootloader |
| 1115 | specified by :term:`EFI_PROVIDER` if |
| 1116 | :term:`MACHINE_FEATURES` contains "efi". |
| 1117 | |
| 1118 | Normally, you do not use this class directly. Instead, you add "live" to |
| 1119 | :term:`IMAGE_FSTYPES`. |
| 1120 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1121 | .. _ref-classes-insane: |
| 1122 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1123 | ``insane`` |
| 1124 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1125 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1126 | The :ref:`ref-classes-insane` class adds a step to the package generation process so |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1127 | that output quality assurance checks are generated by the OpenEmbedded |
| 1128 | build system. A range of checks are performed that check the build's |
| 1129 | output for common problems that show up during runtime. Distribution |
| 1130 | policy usually dictates whether to include this class. |
| 1131 | |
| 1132 | You can configure the sanity checks so that specific test failures |
| 1133 | either raise a warning or an error message. Typically, failures for new |
| 1134 | tests generate a warning. Subsequent failures for the same test would |
| 1135 | then generate an error message once the metadata is in a known and good |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 1136 | condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1137 | and error messages you might encounter using a default configuration. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1138 | |
| 1139 | Use the :term:`WARN_QA` and |
| 1140 | :term:`ERROR_QA` variables to control the behavior of |
| 1141 | these checks at the global level (i.e. in your custom distro |
| 1142 | configuration). However, to skip one or more checks in recipes, you |
| 1143 | should use :term:`INSANE_SKIP`. For example, to skip |
| 1144 | the check for symbolic link ``.so`` files in the main package of a |
| 1145 | recipe, add the following to the recipe. You need to realize that the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1146 | package name override, in this example ``${PN}``, must be used:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1147 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1148 | INSANE_SKIP:${PN} += "dev-so" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1149 | |
| 1150 | Please keep in mind that the QA checks |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 1151 | are meant to detect real or potential problems in the packaged |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1152 | output. So exercise caution when disabling these checks. |
| 1153 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1154 | Here are the tests you can list with the :term:`WARN_QA` and |
Andrew Geissler | 5f35090 | 2021-07-23 13:09:54 -0400 | [diff] [blame] | 1155 | :term:`ERROR_QA` variables: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1156 | |
| 1157 | - ``already-stripped:`` Checks that produced binaries have not |
| 1158 | already been stripped prior to the build system extracting debug |
| 1159 | symbols. It is common for upstream software projects to default to |
| 1160 | stripping debug symbols for output binaries. In order for debugging |
| 1161 | to work on the target using ``-dbg`` packages, this stripping must be |
| 1162 | disabled. |
| 1163 | |
| 1164 | - ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit |
| 1165 | size, and endianness of any binaries to ensure they match the target |
| 1166 | architecture. This test fails if any binaries do not match the type |
| 1167 | since there would be an incompatibility. The test could indicate that |
| 1168 | the wrong compiler or compiler options have been used. Sometimes |
| 1169 | software, like bootloaders, might need to bypass this check. |
| 1170 | |
| 1171 | - ``buildpaths:`` Checks for paths to locations on the build host |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1172 | inside the output files. Not only can these leak information about |
| 1173 | the build environment, they also hinder binary reproducibility. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1174 | |
| 1175 | - ``build-deps:`` Determines if a build-time dependency that is |
| 1176 | specified through :term:`DEPENDS`, explicit |
| 1177 | :term:`RDEPENDS`, or task-level dependencies exists |
| 1178 | to match any runtime dependency. This determination is particularly |
| 1179 | useful to discover where runtime dependencies are detected and added |
| 1180 | during packaging. If no explicit dependency has been specified within |
| 1181 | the metadata, at the packaging stage it is too late to ensure that |
| 1182 | the dependency is built, and thus you can end up with an error when |
| 1183 | the package is installed into the image during the |
| 1184 | :ref:`ref-tasks-rootfs` task because the auto-detected |
| 1185 | dependency was not satisfied. An example of this would be where the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1186 | :ref:`ref-classes-update-rc.d` class automatically |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1187 | adds a dependency on the ``initscripts-functions`` package to |
| 1188 | packages that install an initscript that refers to |
| 1189 | ``/etc/init.d/functions``. The recipe should really have an explicit |
Andrew Geissler | 5f35090 | 2021-07-23 13:09:54 -0400 | [diff] [blame] | 1190 | :term:`RDEPENDS` for the package in question on ``initscripts-functions`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1191 | so that the OpenEmbedded build system is able to ensure that the |
| 1192 | ``initscripts`` recipe is actually built and thus the |
| 1193 | ``initscripts-functions`` package is made available. |
| 1194 | |
| 1195 | - ``compile-host-path:`` Checks the |
| 1196 | :ref:`ref-tasks-compile` log for indications that |
| 1197 | paths to locations on the build host were used. Using such paths |
| 1198 | might result in host contamination of the build output. |
| 1199 | |
| 1200 | - ``debug-deps:`` Checks that all packages except ``-dbg`` packages |
| 1201 | do not depend on ``-dbg`` packages, which would cause a packaging |
| 1202 | bug. |
| 1203 | |
| 1204 | - ``debug-files:`` Checks for ``.debug`` directories in anything but |
| 1205 | the ``-dbg`` package. The debug files should all be in the ``-dbg`` |
| 1206 | package. Thus, anything packaged elsewhere is incorrect packaging. |
| 1207 | |
| 1208 | - ``dep-cmp:`` Checks for invalid version comparison statements in |
| 1209 | runtime dependency relationships between packages (i.e. in |
| 1210 | :term:`RDEPENDS`, |
| 1211 | :term:`RRECOMMENDS`, |
| 1212 | :term:`RSUGGESTS`, |
| 1213 | :term:`RPROVIDES`, |
| 1214 | :term:`RREPLACES`, and |
| 1215 | :term:`RCONFLICTS` variable values). Any invalid |
| 1216 | comparisons might trigger failures or undesirable behavior when |
| 1217 | passed to the package manager. |
| 1218 | |
| 1219 | - ``desktop:`` Runs the ``desktop-file-validate`` program against any |
| 1220 | ``.desktop`` files to validate their contents against the |
| 1221 | specification for ``.desktop`` files. |
| 1222 | |
| 1223 | - ``dev-deps:`` Checks that all packages except ``-dev`` or |
| 1224 | ``-staticdev`` packages do not depend on ``-dev`` packages, which |
| 1225 | would be a packaging bug. |
| 1226 | |
| 1227 | - ``dev-so:`` Checks that the ``.so`` symbolic links are in the |
| 1228 | ``-dev`` package and not in any of the other packages. In general, |
| 1229 | these symlinks are only useful for development purposes. Thus, the |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 1230 | ``-dev`` package is the correct location for them. In very rare |
| 1231 | cases, such as dynamically loaded modules, these symlinks |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1232 | are needed instead in the main package. |
| 1233 | |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 1234 | - ``empty-dirs:`` Checks that packages are not installing files to |
| 1235 | directories that are normally expected to be empty (such as ``/tmp``) |
| 1236 | The list of directories that are checked is specified by the |
| 1237 | :term:`QA_EMPTY_DIRS` variable. |
| 1238 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1239 | - ``file-rdeps:`` Checks that file-level dependencies identified by |
| 1240 | the OpenEmbedded build system at packaging time are satisfied. For |
| 1241 | example, a shell script might start with the line ``#!/bin/bash``. |
| 1242 | This line would translate to a file dependency on ``/bin/bash``. Of |
| 1243 | the three package managers that the OpenEmbedded build system |
| 1244 | supports, only RPM directly handles file-level dependencies, |
| 1245 | resolving them automatically to packages providing the files. |
| 1246 | However, the lack of that functionality in the other two package |
| 1247 | managers does not mean the dependencies do not still need resolving. |
| 1248 | This QA check attempts to ensure that explicitly declared |
| 1249 | :term:`RDEPENDS` exist to handle any file-level |
| 1250 | dependency detected in packaged files. |
| 1251 | |
| 1252 | - ``files-invalid:`` Checks for :term:`FILES` variable |
| 1253 | values that contain "//", which is invalid. |
| 1254 | |
| 1255 | - ``host-user-contaminated:`` Checks that no package produced by the |
| 1256 | recipe contains any files outside of ``/home`` with a user or group |
| 1257 | ID that matches the user running BitBake. A match usually indicates |
| 1258 | that the files are being installed with an incorrect UID/GID, since |
| 1259 | target IDs are independent from host IDs. For additional information, |
| 1260 | see the section describing the |
| 1261 | :ref:`ref-tasks-install` task. |
| 1262 | |
| 1263 | - ``incompatible-license:`` Report when packages are excluded from |
| 1264 | being created due to being marked with a license that is in |
| 1265 | :term:`INCOMPATIBLE_LICENSE`. |
| 1266 | |
| 1267 | - ``install-host-path:`` Checks the |
| 1268 | :ref:`ref-tasks-install` log for indications that |
| 1269 | paths to locations on the build host were used. Using such paths |
| 1270 | might result in host contamination of the build output. |
| 1271 | |
| 1272 | - ``installed-vs-shipped:`` Reports when files have been installed |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 1273 | within :ref:`ref-tasks-install` but have not been included in any package by |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1274 | way of the :term:`FILES` variable. Files that do not |
| 1275 | appear in any package cannot be present in an image later on in the |
| 1276 | build process. Ideally, all installed files should be packaged or not |
| 1277 | installed at all. These files can be deleted at the end of |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 1278 | :ref:`ref-tasks-install` if the files are not needed in any package. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1279 | |
| 1280 | - ``invalid-chars:`` Checks that the recipe metadata variables |
| 1281 | :term:`DESCRIPTION`, |
| 1282 | :term:`SUMMARY`, :term:`LICENSE`, and |
| 1283 | :term:`SECTION` do not contain non-UTF-8 characters. |
| 1284 | Some package managers do not support such characters. |
| 1285 | |
| 1286 | - ``invalid-packageconfig:`` Checks that no undefined features are |
| 1287 | being added to :term:`PACKAGECONFIG`. For |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1288 | example, any name "foo" for which the following form does not exist:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1289 | |
| 1290 | PACKAGECONFIG[foo] = "..." |
| 1291 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1292 | - ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1293 | file containing these paths is incorrect since ``libtool`` adds the |
| 1294 | correct sysroot prefix when using the files automatically itself. |
| 1295 | |
| 1296 | - ``ldflags:`` Ensures that the binaries were linked with the |
| 1297 | :term:`LDFLAGS` options provided by the build system. |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1298 | If this test fails, check that the :term:`LDFLAGS` variable is being |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1299 | passed to the linker command. |
| 1300 | |
| 1301 | - ``libdir:`` Checks for libraries being installed into incorrect |
| 1302 | (possibly hardcoded) installation paths. For example, this test will |
| 1303 | catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is |
| 1304 | "lib32". Another example is when recipes install |
| 1305 | ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". |
| 1306 | |
| 1307 | - ``libexec:`` Checks if a package contains files in |
| 1308 | ``/usr/libexec``. This check is not performed if the ``libexecdir`` |
| 1309 | variable has been set explicitly to ``/usr/libexec``. |
| 1310 | |
| 1311 | - ``packages-list:`` Checks for the same package being listed |
| 1312 | multiple times through the :term:`PACKAGES` variable |
| 1313 | value. Installing the package in this manner can cause errors during |
| 1314 | packaging. |
| 1315 | |
| 1316 | - ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an |
| 1317 | invalid format. |
| 1318 | |
| 1319 | - ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an |
| 1320 | invalid format. |
| 1321 | |
| 1322 | - ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify |
| 1323 | 'link' where the specified target already exists. |
| 1324 | |
| 1325 | - ``perms:`` Currently, this check is unused but reserved. |
| 1326 | |
| 1327 | - ``pkgconfig:`` Checks ``.pc`` files for any |
| 1328 | :term:`TMPDIR`/:term:`WORKDIR` paths. |
| 1329 | Any ``.pc`` file containing these paths is incorrect since |
| 1330 | ``pkg-config`` itself adds the correct sysroot prefix when the files |
| 1331 | are accessed. |
| 1332 | |
| 1333 | - ``pkgname:`` Checks that all packages in |
| 1334 | :term:`PACKAGES` have names that do not contain |
| 1335 | invalid characters (i.e. characters other than 0-9, a-z, ., +, and |
| 1336 | -). |
| 1337 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1338 | - ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1339 | undefined during :ref:`ref-tasks-package`. |
| 1340 | |
| 1341 | - ``pkgvarcheck:`` Checks through the variables |
| 1342 | :term:`RDEPENDS`, |
| 1343 | :term:`RRECOMMENDS`, |
| 1344 | :term:`RSUGGESTS`, |
| 1345 | :term:`RCONFLICTS`, |
| 1346 | :term:`RPROVIDES`, |
| 1347 | :term:`RREPLACES`, :term:`FILES`, |
| 1348 | :term:`ALLOW_EMPTY`, ``pkg_preinst``, |
| 1349 | ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if |
| 1350 | there are variable sets that are not package-specific. Using these |
| 1351 | variables without a package suffix is bad practice, and might |
| 1352 | unnecessarily complicate dependencies of other packages within the |
| 1353 | same recipe or have other unintended consequences. |
| 1354 | |
| 1355 | - ``pn-overrides:`` Checks that a recipe does not have a name |
| 1356 | (:term:`PN`) value that appears in |
| 1357 | :term:`OVERRIDES`. If a recipe is named such that |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 1358 | its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g. |
| 1359 | :term:`PN` happens to be the same as :term:`MACHINE` or |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1360 | :term:`DISTRO`), it can have unexpected consequences. |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1361 | For example, assignments such as ``FILES:${PN} = "xyz"`` effectively |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1362 | turn into ``FILES = "xyz"``. |
| 1363 | |
| 1364 | - ``rpaths:`` Checks for rpaths in the binaries that contain build |
Andrew Geissler | 5f35090 | 2021-07-23 13:09:54 -0400 | [diff] [blame] | 1365 | system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1366 | options are being passed to the linker commands and your binaries |
| 1367 | have potential security issues. |
| 1368 | |
| 1369 | - ``split-strip:`` Reports that splitting or stripping debug symbols |
| 1370 | from binaries has failed. |
| 1371 | |
| 1372 | - ``staticdev:`` Checks for static library files (``*.a``) in |
| 1373 | non-``staticdev`` packages. |
| 1374 | |
| 1375 | - ``symlink-to-sysroot:`` Checks for symlinks in packages that point |
| 1376 | into :term:`TMPDIR` on the host. Such symlinks will |
| 1377 | work on the host, but are clearly invalid when running on the target. |
| 1378 | |
| 1379 | - ``textrel:`` Checks for ELF binaries that contain relocations in |
| 1380 | their ``.text`` sections, which can result in a performance impact at |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1381 | runtime. See the explanation for the ``ELF binary`` message in |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 1382 | ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1383 | issues. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1384 | |
| 1385 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying |
| 1386 | for a package are also declared on the recipe level (i.e. any license |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1387 | in ``LICENSE:*`` should appear in :term:`LICENSE`). |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1388 | |
| 1389 | - ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) |
| 1390 | in the binaries that by default on a standard system are searched by |
| 1391 | the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will |
| 1392 | not cause any breakage, they do waste space and are unnecessary. |
| 1393 | |
| 1394 | - ``var-undefined:`` Reports when variables fundamental to packaging |
| 1395 | (i.e. :term:`WORKDIR`, |
| 1396 | :term:`DEPLOY_DIR`, :term:`D`, |
| 1397 | :term:`PN`, and :term:`PKGD`) are undefined |
| 1398 | during :ref:`ref-tasks-package`. |
| 1399 | |
| 1400 | - ``version-going-backwards:`` If Build History is enabled, reports |
| 1401 | when a package being written out has a lower version than the |
| 1402 | previously written package under the same name. If you are placing |
| 1403 | output packages into a feed and upgrading packages on a target system |
| 1404 | using that feed, the version of a package going backwards can result |
| 1405 | in the target system not correctly upgrading to the "new" version of |
| 1406 | the package. |
| 1407 | |
| 1408 | .. note:: |
| 1409 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 1410 | This is only relevant when you are using runtime package management |
| 1411 | on your target system. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1412 | |
| 1413 | - ``xorg-driver-abi:`` Checks that all packages containing Xorg |
| 1414 | drivers have ABI dependencies. The ``xserver-xorg`` recipe provides |
| 1415 | driver ABI names. All drivers should depend on the ABI versions that |
| 1416 | they have been built against. Driver recipes that include |
| 1417 | ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will |
| 1418 | automatically get these versions. Consequently, you should only need |
| 1419 | to explicitly add dependencies to binary driver recipes. |
| 1420 | |
| 1421 | .. _ref-classes-insserv: |
| 1422 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1423 | ``insserv`` |
| 1424 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1425 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1426 | The :ref:`ref-classes-insserv` class uses the ``insserv`` utility to update the order |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1427 | of symbolic links in ``/etc/rc?.d/`` within an image based on |
| 1428 | dependencies specified by LSB headers in the ``init.d`` scripts |
| 1429 | themselves. |
| 1430 | |
| 1431 | .. _ref-classes-kernel: |
| 1432 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1433 | ``kernel`` |
| 1434 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1435 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1436 | The :ref:`ref-classes-kernel` class handles building Linux kernels. The class contains |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1437 | code to build all kernel trees. All needed headers are staged into the |
Andrew Geissler | 5f35090 | 2021-07-23 13:09:54 -0400 | [diff] [blame] | 1438 | :term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1439 | using the :ref:`ref-classes-module` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1440 | |
| 1441 | This means that each built kernel module is packaged separately and |
| 1442 | inter-module dependencies are created by parsing the ``modinfo`` output. |
| 1443 | If all modules are required, then installing the ``kernel-modules`` |
| 1444 | package installs all packages with modules and various other kernel |
| 1445 | packages such as ``kernel-vmlinux``. |
| 1446 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1447 | The :ref:`ref-classes-kernel` class contains logic that allows you to embed an initial |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 1448 | RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For |
| 1449 | information on how to build an :term:`Initramfs`, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1450 | ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section in |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1451 | the Yocto Project Development Tasks Manual. |
| 1452 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1453 | Various other classes are used by the :ref:`ref-classes-kernel` and :ref:`ref-classes-module` classes |
| 1454 | internally including the :ref:`ref-classes-kernel-arch`, :ref:`ref-classes-module-base`, and |
| 1455 | :ref:`ref-classes-linux-kernel-base` classes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1456 | |
| 1457 | .. _ref-classes-kernel-arch: |
| 1458 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1459 | ``kernel-arch`` |
| 1460 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1461 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1462 | The :ref:`ref-classes-kernel-arch` class sets the ``ARCH`` environment variable for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1463 | Linux kernel compilation (including modules). |
| 1464 | |
| 1465 | .. _ref-classes-kernel-devicetree: |
| 1466 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1467 | ``kernel-devicetree`` |
| 1468 | ===================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1469 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1470 | The :ref:`ref-classes-kernel-devicetree` class, which is inherited by the |
| 1471 | :ref:`ref-classes-kernel` class, supports device tree generation. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1472 | |
| 1473 | .. _ref-classes-kernel-fitimage: |
| 1474 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1475 | ``kernel-fitimage`` |
| 1476 | =================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1477 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1478 | The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image, |
| 1479 | device trees, a U-boot script, a :term:`Initramfs` bundle and a RAM disk |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1480 | into a single FIT image. In theory, a FIT image can support any number |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1481 | of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees. |
| 1482 | However, :ref:`ref-classes-kernel-fitimage` currently only supports |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 1483 | limited usecases: just one kernel image, an optional U-boot script, |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1484 | an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1485 | device tree. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1486 | |
| 1487 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1488 | is set to include ":ref:`ref-classes-kernel-fitimage`" and :term:`KERNEL_IMAGETYPE` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1489 | is set to "fitImage". |
| 1490 | |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1491 | The options for the device tree compiler passed to ``mkimage -D`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1492 | when creating the FIT image are specified using the |
| 1493 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. |
| 1494 | |
| 1495 | Only a single kernel can be added to the FIT image created by |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1496 | :ref:`ref-classes-kernel-fitimage` and the kernel image in FIT is mandatory. The |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1497 | address where the kernel image is to be loaded by U-Boot is |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1498 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by |
| 1499 | :term:`UBOOT_ENTRYPOINT`. |
| 1500 | |
| 1501 | Multiple device trees can be added to the FIT image created by |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1502 | :ref:`ref-classes-kernel-fitimage` and the device tree is optional. |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1503 | The address where the device tree is to be loaded by U-Boot is |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1504 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1505 | and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1506 | |
| 1507 | Only a single RAM disk can be added to the FIT image created by |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1508 | :ref:`ref-classes-kernel-fitimage` and the RAM disk in FIT is optional. |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1509 | The address where the RAM disk image is to be loaded by U-Boot |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1510 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by |
| 1511 | :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1512 | :term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` |
| 1513 | is set to 0. |
| 1514 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1515 | Only a single :term:`Initramfs` bundle can be added to the FIT image created by |
| 1516 | :ref:`ref-classes-kernel-fitimage` and the :term:`Initramfs` bundle in FIT is optional. |
| 1517 | In case of :term:`Initramfs`, the kernel is configured to be bundled with the root filesystem |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1518 | in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin). |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1519 | When the kernel is copied to RAM and executed, it unpacks the :term:`Initramfs` root filesystem. |
| 1520 | The :term:`Initramfs` bundle can be enabled when :term:`INITRAMFS_IMAGE` |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1521 | is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1. |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1522 | The address where the :term:`Initramfs` bundle is to be loaded by U-boot is specified |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1523 | by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`. |
| 1524 | |
| 1525 | Only a single U-boot boot script can be added to the FIT image created by |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1526 | :ref:`ref-classes-kernel-fitimage` and the boot script is optional. |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1527 | The boot script is specified in the ITS file as a text file containing |
| 1528 | U-boot commands. When using a boot script the user should configure the |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 1529 | U-boot :ref:`ref-tasks-install` task to copy the script to sysroot. |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1530 | So the script can be included in the FIT image by the :ref:`ref-classes-kernel-fitimage` |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 1531 | class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to |
| 1532 | load the boot script from the FIT image and executes it. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1533 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1534 | The FIT image generated by :ref:`ref-classes-kernel-fitimage` class is signed when the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1535 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, |
| 1536 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set |
| 1537 | appropriately. The default values used for :term:`FIT_HASH_ALG` and |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1538 | :term:`FIT_SIGN_ALG` in :ref:`ref-classes-kernel-fitimage` are "sha256" and |
Andrew Geissler | c3d88e4 | 2020-10-02 09:45:00 -0500 | [diff] [blame] | 1539 | "rsa2048" respectively. The keys for signing fitImage can be generated using |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1540 | the :ref:`ref-classes-kernel-fitimage` class when both :term:`FIT_GENERATE_KEYS` and |
Andrew Geissler | c3d88e4 | 2020-10-02 09:45:00 -0500 | [diff] [blame] | 1541 | :term:`UBOOT_SIGN_ENABLE` are set to "1". |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1542 | |
| 1543 | |
| 1544 | .. _ref-classes-kernel-grub: |
| 1545 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1546 | ``kernel-grub`` |
| 1547 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1548 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1549 | The :ref:`ref-classes-kernel-grub` class updates the boot area and the boot menu with |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1550 | the kernel as the priority boot mechanism while installing a RPM to |
| 1551 | update the kernel on a deployed target. |
| 1552 | |
| 1553 | .. _ref-classes-kernel-module-split: |
| 1554 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1555 | ``kernel-module-split`` |
| 1556 | ======================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1557 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1558 | The :ref:`ref-classes-kernel-module-split` class provides common functionality for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1559 | splitting Linux kernel modules into separate packages. |
| 1560 | |
| 1561 | .. _ref-classes-kernel-uboot: |
| 1562 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1563 | ``kernel-uboot`` |
| 1564 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1565 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1566 | The :ref:`ref-classes-kernel-uboot` class provides support for building from |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1567 | vmlinux-style kernel sources. |
| 1568 | |
| 1569 | .. _ref-classes-kernel-uimage: |
| 1570 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1571 | ``kernel-uimage`` |
| 1572 | ================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1573 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1574 | The :ref:`ref-classes-kernel-uimage` class provides support to pack uImage. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1575 | |
| 1576 | .. _ref-classes-kernel-yocto: |
| 1577 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1578 | ``kernel-yocto`` |
| 1579 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1580 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1581 | The :ref:`ref-classes-kernel-yocto` class provides common functionality for building |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1582 | from linux-yocto style kernel source repositories. |
| 1583 | |
| 1584 | .. _ref-classes-kernelsrc: |
| 1585 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1586 | ``kernelsrc`` |
| 1587 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1588 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1589 | The :ref:`ref-classes-kernelsrc` class sets the Linux kernel source and version. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1590 | |
| 1591 | .. _ref-classes-lib_package: |
| 1592 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1593 | ``lib_package`` |
| 1594 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1595 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1596 | The :ref:`ref-classes-lib_package` class supports recipes that build libraries and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1597 | produce executable binaries, where those binaries should not be |
| 1598 | installed by default along with the library. Instead, the binaries are |
| 1599 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to |
| 1600 | make their installation optional. |
| 1601 | |
| 1602 | .. _ref-classes-libc*: |
| 1603 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1604 | ``libc*`` |
| 1605 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1606 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1607 | The :ref:`ref-classes-libc*` classes support recipes that build packages with ``libc``: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1608 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 1609 | - The :ref:`libc-common <ref-classes-libc*>` class provides common support for building with |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1610 | ``libc``. |
| 1611 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 1612 | - The :ref:`libc-package <ref-classes-libc*>` class supports packaging up ``glibc`` and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1613 | ``eglibc``. |
| 1614 | |
| 1615 | .. _ref-classes-license: |
| 1616 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1617 | ``license`` |
| 1618 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1619 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1620 | The :ref:`ref-classes-license` class provides license manifest creation and license |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1621 | exclusion. This class is enabled by default using the default value for |
| 1622 | the :term:`INHERIT_DISTRO` variable. |
| 1623 | |
| 1624 | .. _ref-classes-linux-kernel-base: |
| 1625 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1626 | ``linux-kernel-base`` |
| 1627 | ===================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1628 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1629 | The :ref:`ref-classes-linux-kernel-base` class provides common functionality for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1630 | recipes that build out of the Linux kernel source tree. These builds |
| 1631 | goes beyond the kernel itself. For example, the Perf recipe also |
| 1632 | inherits this class. |
| 1633 | |
| 1634 | .. _ref-classes-linuxloader: |
| 1635 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1636 | ``linuxloader`` |
| 1637 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1638 | |
| 1639 | Provides the function ``linuxloader()``, which gives the value of the |
| 1640 | dynamic loader/linker provided on the platform. This value is used by a |
| 1641 | number of other classes. |
| 1642 | |
| 1643 | .. _ref-classes-logging: |
| 1644 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1645 | ``logging`` |
| 1646 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1647 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1648 | The :ref:`ref-classes-logging` class provides the standard shell functions used to log |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1649 | messages for various BitBake severity levels (i.e. ``bbplain``, |
| 1650 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). |
| 1651 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1652 | This class is enabled by default since it is inherited by the :ref:`ref-classes-base` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1653 | class. |
| 1654 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 1655 | .. _ref-classes-meson: |
| 1656 | |
| 1657 | ``meson`` |
| 1658 | ========= |
| 1659 | |
| 1660 | The :ref:`ref-classes-meson` class allows to create recipes that build software |
| 1661 | using the `Meson <https://mesonbuild.com/>`__ build system. You can use |
| 1662 | the :term:`MESON_BUILDTYPE` and :term:`EXTRA_OEMESON` variables to specify |
| 1663 | additional configuration options to be passed using the ``meson`` command line. |
| 1664 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1665 | .. _ref-classes-metadata_scm: |
| 1666 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1667 | ``metadata_scm`` |
| 1668 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1669 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1670 | The :ref:`ref-classes-metadata_scm` class provides functionality for querying the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1671 | branch and revision of a Source Code Manager (SCM) repository. |
| 1672 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1673 | The :ref:`ref-classes-base` class uses this class to print the revisions of |
| 1674 | each layer before starting every build. The :ref:`ref-classes-metadata_scm` |
| 1675 | class is enabled by default because it is inherited by the |
| 1676 | :ref:`ref-classes-base` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1677 | |
| 1678 | .. _ref-classes-migrate_localcount: |
| 1679 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1680 | ``migrate_localcount`` |
| 1681 | ====================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1682 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1683 | The :ref:`ref-classes-migrate_localcount` class verifies a recipe's localcount data and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1684 | increments it appropriately. |
| 1685 | |
| 1686 | .. _ref-classes-mime: |
| 1687 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1688 | ``mime`` |
| 1689 | ======== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1690 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1691 | The :ref:`ref-classes-mime` class generates the proper post-install and post-remove |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1692 | (postinst/postrm) scriptlets for packages that install MIME type files. |
| 1693 | These scriptlets call ``update-mime-database`` to add the MIME types to |
| 1694 | the shared database. |
| 1695 | |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 1696 | .. _ref-classes-mime-xdg: |
| 1697 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1698 | ``mime-xdg`` |
| 1699 | ============ |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 1700 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1701 | The :ref:`ref-classes-mime-xdg` class generates the proper |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 1702 | post-install and post-remove (postinst/postrm) scriptlets for packages |
| 1703 | that install ``.desktop`` files containing ``MimeType`` entries. |
| 1704 | These scriptlets call ``update-desktop-database`` to add the MIME types |
| 1705 | to the database of MIME types handled by desktop files. |
| 1706 | |
| 1707 | Thanks to this class, when users open a file through a file browser |
| 1708 | on recently created images, they don't have to choose the application |
| 1709 | to open the file from the pool of all known applications, even the ones |
| 1710 | that cannot open the selected file. |
| 1711 | |
| 1712 | If you have recipes installing their ``.desktop`` files as absolute |
| 1713 | symbolic links, the detection of such files cannot be done by the current |
| 1714 | implementation of this class. In this case, you have to add the corresponding |
| 1715 | package names to the :term:`MIME_XDG_PACKAGES` variable. |
| 1716 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1717 | .. _ref-classes-mirrors: |
| 1718 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1719 | ``mirrors`` |
| 1720 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1721 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1722 | The :ref:`ref-classes-mirrors` class sets up some standard |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1723 | :term:`MIRRORS` entries for source code mirrors. These |
| 1724 | mirrors provide a fall-back path in case the upstream source specified |
| 1725 | in :term:`SRC_URI` within recipes is unavailable. |
| 1726 | |
| 1727 | This class is enabled by default since it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1728 | :ref:`ref-classes-base` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1729 | |
| 1730 | .. _ref-classes-module: |
| 1731 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1732 | ``module`` |
| 1733 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1734 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1735 | The :ref:`ref-classes-module` class provides support for building out-of-tree Linux |
| 1736 | kernel modules. The class inherits the :ref:`ref-classes-module-base` and |
| 1737 | :ref:`ref-classes-kernel-module-split` classes, and implements the |
| 1738 | :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The class provides |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1739 | everything needed to build and package a kernel module. |
| 1740 | |
| 1741 | For general information on out-of-tree Linux kernel modules, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 1742 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1743 | section in the Yocto Project Linux Kernel Development Manual. |
| 1744 | |
| 1745 | .. _ref-classes-module-base: |
| 1746 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1747 | ``module-base`` |
| 1748 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1749 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1750 | The :ref:`ref-classes-module-base` class provides the base functionality for |
| 1751 | building Linux kernel modules. Typically, a recipe that builds software that |
| 1752 | includes one or more kernel modules and has its own means of building the module |
| 1753 | inherits this class as opposed to inheriting the :ref:`ref-classes-module` |
| 1754 | class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1755 | |
| 1756 | .. _ref-classes-multilib*: |
| 1757 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1758 | ``multilib*`` |
| 1759 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1760 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1761 | The :ref:`ref-classes-multilib*` classes provide support for building libraries with |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1762 | different target optimizations or target architectures and installing |
| 1763 | them side-by-side in the same image. |
| 1764 | |
| 1765 | For more information on using the Multilib feature, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1766 | ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1767 | section in the Yocto Project Development Tasks Manual. |
| 1768 | |
| 1769 | .. _ref-classes-native: |
| 1770 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1771 | ``native`` |
| 1772 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1773 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1774 | The :ref:`ref-classes-native` class provides common functionality for recipes that |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1775 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler |
| 1776 | or other tools from the build host). |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1777 | |
| 1778 | You can create a recipe that builds tools that run natively on the host |
| 1779 | a couple different ways: |
| 1780 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1781 | - Create a ``myrecipe-native.bb`` recipe that inherits the :ref:`ref-classes-native` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1782 | class. If you use this method, you must order the inherit statement |
| 1783 | in the recipe after all other inherit statements so that the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1784 | :ref:`ref-classes-native` class is inherited last. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1785 | |
| 1786 | .. note:: |
| 1787 | |
| 1788 | When creating a recipe this way, the recipe name must follow this |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1789 | naming convention:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1790 | |
| 1791 | myrecipe-native.bb |
| 1792 | |
| 1793 | |
| 1794 | Not using this naming convention can lead to subtle problems |
| 1795 | caused by existing code that depends on that naming convention. |
| 1796 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1797 | - Create or modify a target recipe that contains the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1798 | |
| 1799 | BBCLASSEXTEND = "native" |
| 1800 | |
| 1801 | Inside the |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1802 | recipe, use ``:class-native`` and ``:class-target`` overrides to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1803 | specify any functionality specific to the respective native or target |
| 1804 | case. |
| 1805 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1806 | Although applied differently, the :ref:`ref-classes-native` class is used with both |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1807 | methods. The advantage of the second method is that you do not need to |
| 1808 | have two separate recipes (assuming you need both) for native and |
| 1809 | target. All common parts of the recipe are automatically shared. |
| 1810 | |
| 1811 | .. _ref-classes-nativesdk: |
| 1812 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1813 | ``nativesdk`` |
| 1814 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1815 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1816 | The :ref:`ref-classes-nativesdk` class provides common functionality for recipes that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1817 | wish to build tools to run as part of an SDK (i.e. tools that run on |
| 1818 | :term:`SDKMACHINE`). |
| 1819 | |
| 1820 | You can create a recipe that builds tools that run on the SDK machine a |
| 1821 | couple different ways: |
| 1822 | |
Andrew Geissler | eff2747 | 2021-10-29 15:35:00 -0500 | [diff] [blame] | 1823 | - Create a ``nativesdk-myrecipe.bb`` recipe that inherits the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1824 | :ref:`ref-classes-nativesdk` class. If you use this method, you must order the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1825 | inherit statement in the recipe after all other inherit statements so |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1826 | that the :ref:`ref-classes-nativesdk` class is inherited last. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1827 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1828 | - Create a :ref:`ref-classes-nativesdk` variant of any recipe by adding the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1829 | |
| 1830 | BBCLASSEXTEND = "nativesdk" |
| 1831 | |
| 1832 | Inside the |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 1833 | recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1834 | specify any functionality specific to the respective SDK machine or |
| 1835 | target case. |
| 1836 | |
| 1837 | .. note:: |
| 1838 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 1839 | When creating a recipe, you must follow this naming convention:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1840 | |
| 1841 | nativesdk-myrecipe.bb |
| 1842 | |
| 1843 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 1844 | Not doing so can lead to subtle problems because there is code that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1845 | depends on the naming convention. |
| 1846 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1847 | Although applied differently, the :ref:`ref-classes-nativesdk` class is used with both |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1848 | methods. The advantage of the second method is that you do not need to |
| 1849 | have two separate recipes (assuming you need both) for the SDK machine |
| 1850 | and the target. All common parts of the recipe are automatically shared. |
| 1851 | |
| 1852 | .. _ref-classes-nopackages: |
| 1853 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1854 | ``nopackages`` |
| 1855 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1856 | |
| 1857 | Disables packaging tasks for those recipes and classes where packaging |
| 1858 | is not needed. |
| 1859 | |
| 1860 | .. _ref-classes-npm: |
| 1861 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1862 | ``npm`` |
| 1863 | ======= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1864 | |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 1865 | Provides support for building Node.js software fetched using the |
| 1866 | :wikipedia:`node package manager (NPM) <Npm_(software)>`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1867 | |
| 1868 | .. note:: |
| 1869 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 1870 | Currently, recipes inheriting this class must use the ``npm://`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1871 | fetcher to have dependencies fetched and packaged automatically. |
| 1872 | |
| 1873 | For information on how to create NPM packages, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1874 | ":ref:`dev-manual/packages:creating node package manager (npm) packages`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1875 | section in the Yocto Project Development Tasks Manual. |
| 1876 | |
| 1877 | .. _ref-classes-oelint: |
| 1878 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1879 | ``oelint`` |
| 1880 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1881 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1882 | The :ref:`ref-classes-oelint` class is an obsolete lint checking tool available in |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1883 | ``meta/classes`` in the :term:`Source Directory`. |
| 1884 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 1885 | There are some classes that could be generally useful in OE-Core but |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1886 | are never actually used within OE-Core itself. The :ref:`ref-classes-oelint` class is |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 1887 | one such example. However, being aware of this class can reduce the |
| 1888 | proliferation of different versions of similar classes across multiple |
| 1889 | layers. |
| 1890 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1891 | .. _ref-classes-overlayfs: |
| 1892 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1893 | ``overlayfs`` |
| 1894 | ============= |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1895 | |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1896 | It's often desired in Embedded System design to have a read-only root filesystem. |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1897 | But a lot of different applications might want to have read-write access to |
| 1898 | some parts of a filesystem. It can be especially useful when your update mechanism |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1899 | overwrites the whole root filesystem, but you may want your application data to be preserved |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1900 | between updates. The :ref:`ref-classes-overlayfs` class provides a way |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1901 | to achieve that by means of ``overlayfs`` and at the same time keeping the base |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1902 | root filesystem read-only. |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1903 | |
| 1904 | To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper |
| 1905 | layer in your machine configuration. The underlying file system can be anything that |
| 1906 | is supported by ``overlayfs``. This has to be done in your machine configuration:: |
| 1907 | |
| 1908 | OVERLAYFS_MOUNT_POINT[data] = "/data" |
| 1909 | |
| 1910 | .. note:: |
| 1911 | |
| 1912 | * QA checks fail to catch file existence if you redefine this variable in your recipe! |
| 1913 | * Only the existence of the systemd mount unit file is checked, not its contents. |
| 1914 | * To get more details on ``overlayfs``, its internals and supported operations, please refer |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 1915 | to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`__. |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1916 | |
| 1917 | The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP |
| 1918 | (e.g. in ``systemd-machine-units`` recipe) and it's installed into the image. |
| 1919 | |
| 1920 | Then you can specify writable directories on a recipe basis (e.g. in my-application.bb):: |
| 1921 | |
| 1922 | OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" |
| 1923 | |
| 1924 | To support several mount points you can use a different variable flag. Assuming we |
| 1925 | want to have a writable location on the file system, but do not need that the data |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1926 | survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` |
| 1927 | file system. |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1928 | |
| 1929 | In your machine configuration:: |
| 1930 | |
| 1931 | OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" |
| 1932 | |
| 1933 | and then in your recipe:: |
| 1934 | |
| 1935 | OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" |
| 1936 | |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1937 | On a practical note, your application recipe might require multiple |
| 1938 | overlays to be mounted before running to avoid writing to the underlying |
| 1939 | file system (which can be forbidden in case of read-only file system) |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1940 | To achieve that :ref:`ref-classes-overlayfs` provides a ``systemd`` |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1941 | helper service for mounting overlays. This helper service is named |
| 1942 | ``${PN}-overlays.service`` and can be depended on in your application recipe |
| 1943 | (named ``application`` in the following example) ``systemd`` unit by adding |
| 1944 | to the unit the following:: |
| 1945 | |
| 1946 | [Unit] |
| 1947 | After=application-overlays.service |
| 1948 | Requires=application-overlays.service |
| 1949 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1950 | .. note:: |
| 1951 | |
| 1952 | The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it. |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1953 | In order to get ``/etc`` in overlayfs, see :ref:`ref-classes-overlayfs-etc`. |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1954 | |
| 1955 | .. _ref-classes-overlayfs-etc: |
| 1956 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 1957 | ``overlayfs-etc`` |
| 1958 | ================= |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 1959 | |
| 1960 | In order to have the ``/etc`` directory in overlayfs a special handling at early |
| 1961 | boot stage is required. The idea is to supply a custom init script that mounts |
| 1962 | ``/etc`` before launching the actual init program, because the latter already |
| 1963 | requires ``/etc`` to be mounted. |
| 1964 | |
| 1965 | Example usage in image recipe:: |
| 1966 | |
| 1967 | IMAGE_FEATURES += "overlayfs-etc" |
| 1968 | |
| 1969 | .. note:: |
| 1970 | |
| 1971 | This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES` |
| 1972 | |
| 1973 | Your machine configuration should define at least the device, mount point, and file system type |
| 1974 | you are going to use for ``overlayfs``:: |
| 1975 | |
| 1976 | OVERLAYFS_ETC_MOUNT_POINT = "/data" |
| 1977 | OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" |
| 1978 | OVERLAYFS_ETC_FSTYPE ?= "ext4" |
| 1979 | |
| 1980 | To control more mount options you should consider setting mount options |
| 1981 | (``defaults`` is used by default):: |
| 1982 | |
| 1983 | OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync" |
| 1984 | |
| 1985 | The class provides two options for ``/sbin/init`` generation: |
| 1986 | |
| 1987 | - The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig`` |
| 1988 | and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage |
| 1989 | that you won't need to change any kernel parameters in order to make it work, |
| 1990 | but it poses a restriction that package-management can't be used, because updating |
| 1991 | the init manager would remove the generated script. |
| 1992 | |
| 1993 | - If you wish to keep original init as is, you can set:: |
| 1994 | |
| 1995 | OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0" |
| 1996 | |
| 1997 | Then the generated init will be named ``/sbin/preinit`` and you would need to extend your |
| 1998 | kernel parameters manually in your bootloader configuration. |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 1999 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2000 | .. _ref-classes-own-mirrors: |
| 2001 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2002 | ``own-mirrors`` |
| 2003 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2004 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2005 | The :ref:`ref-classes-own-mirrors` class makes it easier to set up your own |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2006 | :term:`PREMIRRORS` from which to first fetch source |
| 2007 | before attempting to fetch it from the upstream specified in |
| 2008 | :term:`SRC_URI` within each recipe. |
| 2009 | |
| 2010 | To use this class, inherit it globally and specify |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 2011 | :term:`SOURCE_MIRROR_URL`. Here is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2012 | |
| 2013 | INHERIT += "own-mirrors" |
| 2014 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" |
| 2015 | |
| 2016 | You can specify only a single URL |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2017 | in :term:`SOURCE_MIRROR_URL`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2018 | |
| 2019 | .. _ref-classes-package: |
| 2020 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2021 | ``package`` |
| 2022 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2023 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2024 | The :ref:`ref-classes-package` class supports generating packages from a build's |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2025 | output. The core generic functionality is in ``package.bbclass``. The |
| 2026 | code specific to particular package types resides in these |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2027 | package-specific classes: :ref:`ref-classes-package_deb`, |
| 2028 | :ref:`ref-classes-package_rpm`, :ref:`ref-classes-package_ipk`, and |
| 2029 | :ref:`ref-classes-package_tar`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2030 | |
| 2031 | .. note:: |
| 2032 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2033 | The :ref:`ref-classes-package_tar` class is broken and |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2034 | not supported. It is recommended that you do not use this class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2035 | |
| 2036 | You can control the list of resulting package formats by using the |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2037 | :term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2038 | configuration file, which is located in the :term:`Build Directory`. |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2039 | When defining the variable, you can specify one or more package types. |
| 2040 | Since images are generated from packages, a packaging class is needed |
| 2041 | to enable image generation. The first class listed in this variable is |
| 2042 | used for image generation. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2043 | |
| 2044 | If you take the optional step to set up a repository (package feed) on |
| 2045 | the development host that can be used by DNF, you can install packages |
| 2046 | from the feed while you are running the image on the target (i.e. |
| 2047 | runtime installation of packages). For more information, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2048 | ":ref:`dev-manual/packages:using runtime package management`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2049 | section in the Yocto Project Development Tasks Manual. |
| 2050 | |
| 2051 | The package-specific class you choose can affect build-time performance |
| 2052 | and has space ramifications. In general, building a package with IPK |
| 2053 | takes about thirty percent less time as compared to using RPM to build |
| 2054 | the same or similar package. This comparison takes into account a |
| 2055 | complete build of the package with all dependencies previously built. |
| 2056 | The reason for this discrepancy is because the RPM package manager |
| 2057 | creates and processes more :term:`Metadata` than the IPK package |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2058 | manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2059 | ":ref:`ref-classes-package_ipk`" if you are building smaller systems. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2060 | |
| 2061 | Before making your package manager decision, however, you should |
| 2062 | consider some further things about using RPM: |
| 2063 | |
| 2064 | - RPM starts to provide more abilities than IPK due to the fact that it |
| 2065 | processes more Metadata. For example, this information includes |
| 2066 | individual file types, file checksum generation and evaluation on |
| 2067 | install, sparse file support, conflict detection and resolution for |
| 2068 | Multilib systems, ACID style upgrade, and repackaging abilities for |
| 2069 | rollbacks. |
| 2070 | |
| 2071 | - For smaller systems, the extra space used for the Berkeley Database |
| 2072 | and the amount of metadata when using RPM can affect your ability to |
| 2073 | perform on-device upgrades. |
| 2074 | |
| 2075 | You can find additional information on the effects of the package class |
| 2076 | at these two Yocto Project mailing list links: |
| 2077 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2078 | - :yocto_lists:`/pipermail/poky/2011-May/006362.html` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2079 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2080 | - :yocto_lists:`/pipermail/poky/2011-May/006363.html` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2081 | |
| 2082 | .. _ref-classes-package_deb: |
| 2083 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2084 | ``package_deb`` |
| 2085 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2086 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2087 | The :ref:`ref-classes-package_deb` class provides support for creating packages that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2088 | use the Debian (i.e. ``.deb``) file format. The class ensures the |
| 2089 | packages are written out in a ``.deb`` file format to the |
| 2090 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. |
| 2091 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2092 | This class inherits the :ref:`ref-classes-package` class and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2093 | is enabled through the :term:`PACKAGE_CLASSES` |
| 2094 | variable in the ``local.conf`` file. |
| 2095 | |
| 2096 | .. _ref-classes-package_ipk: |
| 2097 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2098 | ``package_ipk`` |
| 2099 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2100 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2101 | The :ref:`ref-classes-package_ipk` class provides support for creating packages that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2102 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages |
| 2103 | are written out in a ``.ipk`` file format to the |
| 2104 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. |
| 2105 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2106 | This class inherits the :ref:`ref-classes-package` class and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2107 | is enabled through the :term:`PACKAGE_CLASSES` |
| 2108 | variable in the ``local.conf`` file. |
| 2109 | |
| 2110 | .. _ref-classes-package_rpm: |
| 2111 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2112 | ``package_rpm`` |
| 2113 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2114 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2115 | The :ref:`ref-classes-package_rpm` class provides support for creating packages that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2116 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages |
| 2117 | are written out in a ``.rpm`` file format to the |
| 2118 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. |
| 2119 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2120 | This class inherits the :ref:`ref-classes-package` class and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2121 | is enabled through the :term:`PACKAGE_CLASSES` |
| 2122 | variable in the ``local.conf`` file. |
| 2123 | |
| 2124 | .. _ref-classes-package_tar: |
| 2125 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2126 | ``package_tar`` |
| 2127 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2128 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2129 | The :ref:`ref-classes-package_tar` class provides support for creating tarballs. The |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2130 | class ensures the packages are written out in a tarball format to the |
| 2131 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. |
| 2132 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2133 | This class inherits the :ref:`ref-classes-package` class and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2134 | is enabled through the :term:`PACKAGE_CLASSES` |
| 2135 | variable in the ``local.conf`` file. |
| 2136 | |
| 2137 | .. note:: |
| 2138 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2139 | You cannot specify the :ref:`ref-classes-package_tar` class first using the |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2140 | :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2141 | file formats for your image or SDK. |
| 2142 | |
| 2143 | .. _ref-classes-packagedata: |
| 2144 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2145 | ``packagedata`` |
| 2146 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2147 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2148 | The :ref:`ref-classes-packagedata` class provides common functionality for reading |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2149 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These |
| 2150 | files contain information about each output package produced by the |
| 2151 | OpenEmbedded build system. |
| 2152 | |
| 2153 | This class is enabled by default because it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2154 | :ref:`ref-classes-package` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2155 | |
| 2156 | .. _ref-classes-packagegroup: |
| 2157 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2158 | ``packagegroup`` |
| 2159 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2160 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2161 | The :ref:`ref-classes-packagegroup` class sets default values appropriate for package |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2162 | group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2163 | so forth). It is highly recommended that all package group recipes |
| 2164 | inherit this class. |
| 2165 | |
| 2166 | For information on how to use this class, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2167 | ":ref:`dev-manual/customizing-images:customizing images using custom package groups`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2168 | section in the Yocto Project Development Tasks Manual. |
| 2169 | |
| 2170 | Previously, this class was called the ``task`` class. |
| 2171 | |
| 2172 | .. _ref-classes-patch: |
| 2173 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2174 | ``patch`` |
| 2175 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2176 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2177 | The :ref:`ref-classes-patch` class provides all functionality for applying patches |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2178 | during the :ref:`ref-tasks-patch` task. |
| 2179 | |
| 2180 | This class is enabled by default because it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2181 | :ref:`ref-classes-base` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2182 | |
| 2183 | .. _ref-classes-perlnative: |
| 2184 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2185 | ``perlnative`` |
| 2186 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2187 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2188 | When inherited by a recipe, the :ref:`ref-classes-perlnative` class supports using the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2189 | native version of Perl built by the build system rather than using the |
| 2190 | version provided by the build host. |
| 2191 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2192 | .. _ref-classes-pypi: |
| 2193 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2194 | ``pypi`` |
| 2195 | ======== |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2196 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2197 | The :ref:`ref-classes-pypi` class sets variables appropriately for recipes that build |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2198 | Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index. |
| 2199 | By default it determines the PyPI package name based upon :term:`BPN` |
| 2200 | (stripping the "python-" or "python3-" prefix off if present), however in |
| 2201 | some cases you may need to set it manually in the recipe by setting |
| 2202 | :term:`PYPI_PACKAGE`. |
| 2203 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2204 | Variables set by the :ref:`ref-classes-pypi` class include :term:`SRC_URI`, :term:`SECTION`, |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2205 | :term:`HOMEPAGE`, :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX` |
| 2206 | and :term:`CVE_PRODUCT`. |
| 2207 | |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2208 | .. _ref-classes-python_flit_core: |
| 2209 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2210 | ``python_flit_core`` |
| 2211 | ==================== |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2212 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2213 | The :ref:`ref-classes-python_flit_core` class enables building Python modules which declare |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2214 | the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant |
| 2215 | ``flit_core.buildapi`` ``build-backend`` in the ``[build-system]`` |
| 2216 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). |
| 2217 | |
| 2218 | Python modules built with ``flit_core.buildapi`` are pure Python (no |
| 2219 | ``C`` or ``Rust`` extensions). |
| 2220 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2221 | Internally this uses the :ref:`ref-classes-python_pep517` class. |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2222 | |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2223 | .. _ref-classes-python_pep517: |
| 2224 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2225 | ``python_pep517`` |
| 2226 | ================= |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2227 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2228 | The :ref:`ref-classes-python_pep517` class builds and installs a Python ``wheel`` binary |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2229 | archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__). |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2230 | |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2231 | Recipes wouldn't inherit this directly, instead typically another class will |
Andrew Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 2232 | inherit this and add the relevant native dependencies. |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2233 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2234 | Examples of classes which do this are :ref:`ref-classes-python_flit_core`, |
| 2235 | :ref:`ref-classes-python_setuptools_build_meta`, and |
| 2236 | :ref:`ref-classes-python_poetry_core`. |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2237 | |
| 2238 | .. _ref-classes-python_poetry_core: |
| 2239 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2240 | ``python_poetry_core`` |
| 2241 | ====================== |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2242 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2243 | The :ref:`ref-classes-python_poetry_core` class enables building Python modules which use the |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2244 | `Poetry Core <https://python-poetry.org>`__ build system. |
| 2245 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2246 | Internally this uses the :ref:`ref-classes-python_pep517` class. |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2247 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 2248 | .. _ref-classes-python_pyo3: |
| 2249 | |
| 2250 | ``python_pyo3`` |
| 2251 | =============== |
| 2252 | |
| 2253 | The :ref:`ref-classes-python_pyo3` class helps make sure that Python extensions |
| 2254 | written in Rust and built with `PyO3 <https://pyo3.rs/>`__, properly set up the |
| 2255 | environment for cross compilation. |
| 2256 | |
| 2257 | This class is internal to the :ref:`ref-classes-python-setuptools3_rust` class |
| 2258 | and is not meant to be used directly in recipes. |
| 2259 | |
| 2260 | .. _ref-classes-python-setuptools3_rust: |
| 2261 | |
| 2262 | ``python-setuptools3_rust`` |
| 2263 | =========================== |
| 2264 | |
| 2265 | The :ref:`ref-classes-python-setuptools3_rust` class enables building Python |
| 2266 | extensions implemented in Rust with `PyO3 <https://pyo3.rs/>`__, which allows |
| 2267 | to compile and distribute Python extensions written in Rust as easily |
| 2268 | as if they were written in C. |
| 2269 | |
| 2270 | This class inherits the :ref:`ref-classes-setuptools3` and |
| 2271 | :ref:`ref-classes-python_pyo3` classes. |
| 2272 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2273 | .. _ref-classes-pixbufcache: |
| 2274 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2275 | ``pixbufcache`` |
| 2276 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2277 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2278 | The :ref:`ref-classes-pixbufcache` class generates the proper post-install and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2279 | post-remove (postinst/postrm) scriptlets for packages that install |
| 2280 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets |
| 2281 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. |
| 2282 | Since the cache files are architecture-specific, ``update_pixbuf_cache`` |
| 2283 | is run using QEMU if the postinst scriptlets need to be run on the build |
| 2284 | host during image creation. |
| 2285 | |
| 2286 | If the pixbuf loaders being installed are in packages other than the |
| 2287 | recipe's main package, set |
| 2288 | :term:`PIXBUF_PACKAGES` to specify the packages |
| 2289 | containing the loaders. |
| 2290 | |
| 2291 | .. _ref-classes-pkgconfig: |
| 2292 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2293 | ``pkgconfig`` |
| 2294 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2295 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2296 | The :ref:`ref-classes-pkgconfig` class provides a standard way to get header and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2297 | library information by using ``pkg-config``. This class aims to smooth |
| 2298 | integration of ``pkg-config`` into libraries that use it. |
| 2299 | |
| 2300 | During staging, BitBake installs ``pkg-config`` data into the |
| 2301 | ``sysroots/`` directory. By making use of sysroot functionality within |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2302 | ``pkg-config``, the :ref:`ref-classes-pkgconfig` class no longer has to manipulate the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2303 | files. |
| 2304 | |
| 2305 | .. _ref-classes-populate-sdk: |
| 2306 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2307 | ``populate_sdk`` |
| 2308 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2309 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2310 | The :ref:`ref-classes-populate-sdk` class provides support for SDK-only recipes. For |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2311 | information on advantages gained when building a cross-development |
| 2312 | toolchain using the :ref:`ref-tasks-populate_sdk` |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 2313 | task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2314 | section in the Yocto Project Application Development and the Extensible |
| 2315 | Software Development Kit (eSDK) manual. |
| 2316 | |
| 2317 | .. _ref-classes-populate-sdk-*: |
| 2318 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2319 | ``populate_sdk_*`` |
| 2320 | ================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2321 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2322 | The :ref:`ref-classes-populate-sdk-*` classes support SDK creation and consist of the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2323 | following classes: |
| 2324 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2325 | - :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`: The base class supporting SDK creation under |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2326 | all package managers (i.e. DEB, RPM, and opkg). |
| 2327 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2328 | - :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the Debian |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2329 | package manager. |
| 2330 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2331 | - :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the RPM |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2332 | package manager. |
| 2333 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2334 | - :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the opkg |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2335 | (IPK format) package manager. |
| 2336 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2337 | - :ref:`populate_sdk_ext <ref-classes-populate-sdk-*>`: Supports extensible SDK creation under all |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2338 | package managers. |
| 2339 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2340 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class inherits the appropriate |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2341 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on |
| 2342 | :term:`IMAGE_PKGTYPE`. |
| 2343 | |
| 2344 | The base class ensures all source and destination directories are |
| 2345 | established and then populates the SDK. After populating the SDK, the |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2346 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class constructs two sysroots: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2347 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which |
| 2348 | contains the cross-compiler and associated tooling, and the target, |
| 2349 | which contains a target root filesystem that is configured for the SDK |
| 2350 | usage. These two images reside in :term:`SDK_OUTPUT`, |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 2351 | which consists of the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2352 | |
| 2353 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs |
| 2354 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs |
| 2355 | |
| 2356 | Finally, the base populate SDK class creates the toolchain environment |
| 2357 | setup script, the tarball of the SDK, and the installer. |
| 2358 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2359 | The respective :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`, :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`, and |
| 2360 | :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>` classes each support the specific type of SDK. |
| 2361 | These classes are inherited by and used with the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2362 | class. |
| 2363 | |
| 2364 | For more information on the cross-development toolchain generation, see |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 2365 | the ":ref:`overview-manual/concepts:cross-development toolchain generation`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2366 | section in the Yocto Project Overview and Concepts Manual. For |
| 2367 | information on advantages gained when building a cross-development |
| 2368 | toolchain using the :ref:`ref-tasks-populate_sdk` |
| 2369 | task, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 2370 | ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2371 | section in the Yocto Project Application Development and the Extensible |
| 2372 | Software Development Kit (eSDK) manual. |
| 2373 | |
| 2374 | .. _ref-classes-prexport: |
| 2375 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2376 | ``prexport`` |
| 2377 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2378 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2379 | The :ref:`ref-classes-prexport` class provides functionality for exporting |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2380 | :term:`PR` values. |
| 2381 | |
| 2382 | .. note:: |
| 2383 | |
| 2384 | This class is not intended to be used directly. Rather, it is enabled |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2385 | when using "``bitbake-prserv-tool export``". |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2386 | |
| 2387 | .. _ref-classes-primport: |
| 2388 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2389 | ``primport`` |
| 2390 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2391 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2392 | The :ref:`ref-classes-primport` class provides functionality for importing |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2393 | :term:`PR` values. |
| 2394 | |
| 2395 | .. note:: |
| 2396 | |
| 2397 | This class is not intended to be used directly. Rather, it is enabled |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2398 | when using "``bitbake-prserv-tool import``". |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2399 | |
| 2400 | .. _ref-classes-prserv: |
| 2401 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2402 | ``prserv`` |
| 2403 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2404 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2405 | The :ref:`ref-classes-prserv` class provides functionality for using a :ref:`PR |
| 2406 | service <dev-manual/packages:working with a pr service>` in order to |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2407 | automatically manage the incrementing of the :term:`PR` |
| 2408 | variable for each recipe. |
| 2409 | |
| 2410 | This class is enabled by default because it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2411 | :ref:`ref-classes-package` class. However, the OpenEmbedded |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2412 | build system will not enable the functionality of this class unless |
| 2413 | :term:`PRSERV_HOST` has been set. |
| 2414 | |
| 2415 | .. _ref-classes-ptest: |
| 2416 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2417 | ``ptest`` |
| 2418 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2419 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2420 | The :ref:`ref-classes-ptest` class provides functionality for packaging and installing |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2421 | runtime tests for recipes that build software that provides these tests. |
| 2422 | |
| 2423 | This class is intended to be inherited by individual recipes. However, |
| 2424 | the class' functionality is largely disabled unless "ptest" appears in |
| 2425 | :term:`DISTRO_FEATURES`. See the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2426 | ":ref:`dev-manual/packages:testing packages with ptest`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2427 | section in the Yocto Project Development Tasks Manual for more information |
| 2428 | on ptest. |
| 2429 | |
| 2430 | .. _ref-classes-ptest-gnome: |
| 2431 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2432 | ``ptest-gnome`` |
| 2433 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2434 | |
| 2435 | Enables package tests (ptests) specifically for GNOME packages, which |
| 2436 | have tests intended to be executed with ``gnome-desktop-testing``. |
| 2437 | |
| 2438 | For information on setting up and running ptests, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2439 | ":ref:`dev-manual/packages:testing packages with ptest`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2440 | section in the Yocto Project Development Tasks Manual. |
| 2441 | |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 2442 | .. _ref-classes-python3-dir: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2443 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2444 | ``python3-dir`` |
| 2445 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2446 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2447 | The :ref:`ref-classes-python3-dir` class provides the base version, location, and site |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 2448 | package location for Python 3. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2449 | |
| 2450 | .. _ref-classes-python3native: |
| 2451 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2452 | ``python3native`` |
| 2453 | ================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2454 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2455 | The :ref:`ref-classes-python3native` class supports using the native version of Python |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2456 | 3 built by the build system rather than support of the version provided |
| 2457 | by the build host. |
| 2458 | |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 2459 | .. _ref-classes-python3targetconfig: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2460 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2461 | ``python3targetconfig`` |
| 2462 | ======================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2463 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2464 | The :ref:`ref-classes-python3targetconfig` class supports using the native version of Python |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 2465 | 3 built by the build system rather than support of the version provided |
| 2466 | by the build host, except that the configuration for the target machine |
| 2467 | is accessible (such as correct installation directories). This also adds a |
| 2468 | dependency on target ``python3``, so should only be used where appropriate |
| 2469 | in order to avoid unnecessarily lengthening builds. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2470 | |
| 2471 | .. _ref-classes-qemu: |
| 2472 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2473 | ``qemu`` |
| 2474 | ======== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2475 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2476 | The :ref:`ref-classes-qemu` class provides functionality for recipes that either need |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2477 | QEMU or test for the existence of QEMU. Typically, this class is used to |
| 2478 | run programs for a target system on the build host using QEMU's |
| 2479 | application emulation mode. |
| 2480 | |
| 2481 | .. _ref-classes-recipe_sanity: |
| 2482 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2483 | ``recipe_sanity`` |
| 2484 | ================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2485 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2486 | The :ref:`ref-classes-recipe_sanity` class checks for the presence of any host system |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2487 | recipe prerequisites that might affect the build (e.g. variables that |
| 2488 | are set or software that is present). |
| 2489 | |
| 2490 | .. _ref-classes-relocatable: |
| 2491 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2492 | ``relocatable`` |
| 2493 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2494 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2495 | The :ref:`ref-classes-relocatable` class enables relocation of binaries when they are |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2496 | installed into the sysroot. |
| 2497 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2498 | This class makes use of the :ref:`ref-classes-chrpath` class and is used by |
| 2499 | both the :ref:`ref-classes-cross` and :ref:`ref-classes-native` classes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2500 | |
| 2501 | .. _ref-classes-remove-libtool: |
| 2502 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2503 | ``remove-libtool`` |
| 2504 | ================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2505 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2506 | The :ref:`ref-classes-remove-libtool` class adds a post function to the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2507 | :ref:`ref-tasks-install` task to remove all ``.la`` files |
| 2508 | installed by ``libtool``. Removing these files results in them being |
| 2509 | absent from both the sysroot and target packages. |
| 2510 | |
| 2511 | If a recipe needs the ``.la`` files to be installed, then the recipe can |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 2512 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2513 | |
| 2514 | REMOVE_LIBTOOL_LA = "0" |
| 2515 | |
| 2516 | .. note:: |
| 2517 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2518 | The :ref:`ref-classes-remove-libtool` class is not enabled by default. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2519 | |
| 2520 | .. _ref-classes-report-error: |
| 2521 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2522 | ``report-error`` |
| 2523 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2524 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2525 | The :ref:`ref-classes-report-error` class supports enabling the :ref:`error reporting |
| 2526 | tool <dev-manual/error-reporting-tool:using the error reporting tool>`", |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2527 | which allows you to submit build error information to a central database. |
| 2528 | |
| 2529 | The class collects debug information for recipe, recipe version, task, |
| 2530 | machine, distro, build system, target system, host distro, branch, |
| 2531 | commit, and log. From the information, report files using a JSON format |
| 2532 | are created and stored in |
| 2533 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. |
| 2534 | |
| 2535 | .. _ref-classes-rm-work: |
| 2536 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2537 | ``rm_work`` |
| 2538 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2539 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2540 | The :ref:`ref-classes-rm-work` class supports deletion of temporary workspace, which |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2541 | can ease your hard drive demands during builds. |
| 2542 | |
| 2543 | The OpenEmbedded build system can use a substantial amount of disk space |
| 2544 | during the build process. A portion of this space is the work files |
| 2545 | under the ``${TMPDIR}/work`` directory for each recipe. Once the build |
| 2546 | system generates the packages for a recipe, the work files for that |
| 2547 | recipe are no longer needed. However, by default, the build system |
| 2548 | preserves these files for inspection and possible debugging purposes. If |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2549 | you would rather have these files deleted to save disk space as the build |
| 2550 | progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2551 | your ``local.conf`` file, which is found in the :term:`Build Directory`:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2552 | |
| 2553 | INHERIT += "rm_work" |
| 2554 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2555 | If you are modifying and building source code out of the work directory for a |
| 2556 | recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your |
| 2557 | changes to the source being lost. To exclude some recipes from having their work |
| 2558 | directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the |
| 2559 | recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, |
| 2560 | which can also be set in your ``local.conf`` file. Here is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2561 | |
| 2562 | RM_WORK_EXCLUDE += "busybox glibc" |
| 2563 | |
| 2564 | .. _ref-classes-rootfs*: |
| 2565 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2566 | ``rootfs*`` |
| 2567 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2568 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2569 | The :ref:`ref-classes-rootfs*` classes support creating the root filesystem for an |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2570 | image and consist of the following classes: |
| 2571 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2572 | - The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class, which defines filesystem |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2573 | post-processing functions for image recipes. |
| 2574 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2575 | - The :ref:`rootfs_deb <ref-classes-rootfs*>` class, which supports creation of root filesystems |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2576 | for images built using ``.deb`` packages. |
| 2577 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2578 | - The :ref:`rootfs_rpm <ref-classes-rootfs*>` class, which supports creation of root filesystems |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2579 | for images built using ``.rpm`` packages. |
| 2580 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2581 | - The :ref:`rootfs_ipk <ref-classes-rootfs*>` class, which supports creation of root filesystems |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2582 | for images built using ``.ipk`` packages. |
| 2583 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2584 | - The :ref:`rootfsdebugfiles <ref-classes-rootfs*>` class, which installs additional files found |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2585 | on the build host directly into the root filesystem. |
| 2586 | |
| 2587 | The root filesystem is created from packages using one of the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2588 | :ref:`ref-classes-rootfs*` files as determined by the :term:`PACKAGE_CLASSES` |
| 2589 | variable. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2590 | |
| 2591 | For information on how root filesystem images are created, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 2592 | ":ref:`overview-manual/concepts:image generation`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2593 | section in the Yocto Project Overview and Concepts Manual. |
| 2594 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 2595 | .. _ref-classes-rust: |
| 2596 | |
| 2597 | ``rust`` |
| 2598 | ======== |
| 2599 | |
| 2600 | The :ref:`ref-classes-rust` class is an internal class which is just used |
| 2601 | in the "rust" recipe, to build the Rust compiler and runtime |
| 2602 | library. Except for this recipe, it is not intended to be used directly. |
| 2603 | |
| 2604 | .. _ref-classes-rust-common: |
| 2605 | |
| 2606 | ``rust-common`` |
| 2607 | =============== |
| 2608 | |
| 2609 | The :ref:`ref-classes-rust-common` class is an internal class to the |
| 2610 | :ref:`ref-classes-cargo_common` and :ref:`ref-classes-rust` classes and is not |
| 2611 | intended to be used directly. |
| 2612 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2613 | .. _ref-classes-sanity: |
| 2614 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2615 | ``sanity`` |
| 2616 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2617 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2618 | The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2619 | on the host system so that users can be notified of potential problems |
| 2620 | that might affect their build. The class also performs basic user |
| 2621 | configuration checks from the ``local.conf`` configuration file to |
| 2622 | prevent common mistakes that cause build failures. Distribution policy |
| 2623 | usually determines whether to include this class. |
| 2624 | |
| 2625 | .. _ref-classes-scons: |
| 2626 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2627 | ``scons`` |
| 2628 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2629 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2630 | The :ref:`ref-classes-scons` class supports recipes that need to build software |
| 2631 | that uses the SCons build system. You can use the :term:`EXTRA_OESCONS` |
| 2632 | variable to specify additional configuration options you want to pass SCons |
| 2633 | command line. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2634 | |
| 2635 | .. _ref-classes-sdl: |
| 2636 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2637 | ``sdl`` |
| 2638 | ======= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2639 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2640 | The :ref:`ref-classes-sdl` class supports recipes that need to build software that uses |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2641 | the Simple DirectMedia Layer (SDL) library. |
| 2642 | |
Patrick Williams | 4585273 | 2022-04-02 08:58:32 -0500 | [diff] [blame] | 2643 | .. _ref-classes-python_setuptools_build_meta: |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2644 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2645 | ``python_setuptools_build_meta`` |
| 2646 | ================================ |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2647 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2648 | The :ref:`ref-classes-python_setuptools_build_meta` class enables building |
| 2649 | Python modules which declare the |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2650 | `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant |
| 2651 | ``setuptools.build_meta`` ``build-backend`` in the ``[build-system]`` |
| 2652 | section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__). |
| 2653 | |
| 2654 | Python modules built with ``setuptools.build_meta`` can be pure Python or |
| 2655 | include ``C`` or ``Rust`` extensions). |
| 2656 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2657 | Internally this uses the :ref:`ref-classes-python_pep517` class. |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2658 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2659 | .. _ref-classes-setuptools3: |
| 2660 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2661 | ``setuptools3`` |
| 2662 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2663 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2664 | The :ref:`ref-classes-setuptools3` class supports Python version 3.x extensions |
| 2665 | that use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` |
| 2666 | and have not migrated to the official ``pyproject.toml`` format). If your recipe |
| 2667 | uses these build systems, the recipe needs to inherit the |
| 2668 | :ref:`ref-classes-setuptools3` class. |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2669 | |
| 2670 | .. note:: |
| 2671 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2672 | The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-compile` task now calls |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2673 | ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format |
| 2674 | (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__). |
| 2675 | |
| 2676 | A consequence of this is that legacy software still using deprecated |
| 2677 | ``distutils`` from the Python standard library cannot be packaged as |
| 2678 | ``wheels``. A common solution is the replace |
| 2679 | ``from distutils.core import setup`` with ``from setuptools import setup``. |
| 2680 | |
| 2681 | .. note:: |
| 2682 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2683 | The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-install` task now |
| 2684 | installs the ``wheel`` binary archive. In current versions of |
| 2685 | ``setuptools`` the legacy ``setup.py install`` method is deprecated. If |
| 2686 | the ``setup.py`` cannot be used with wheels, for example it creates files |
| 2687 | outside of the Python module or standard entry points, then |
| 2688 | :ref:`ref-classes-setuptools3_legacy` should be used. |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2689 | |
| 2690 | .. _ref-classes-setuptools3_legacy: |
| 2691 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2692 | ``setuptools3_legacy`` |
| 2693 | ====================== |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2694 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2695 | The :ref:`ref-classes-setuptools3_legacy` class supports |
| 2696 | Python version 3.x extensions that use build systems based on ``setuptools`` |
| 2697 | (e.g. only have a ``setup.py`` and have not migrated to the official |
| 2698 | ``pyproject.toml`` format). Unlike :ref:`ref-classes-setuptools3`, |
| 2699 | this uses the traditional ``setup.py`` ``build`` and ``install`` commands and |
| 2700 | not wheels. This use of ``setuptools`` like this is |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 2701 | `deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__ |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2702 | but still relatively common. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2703 | |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 2704 | .. _ref-classes-setuptools3-base: |
| 2705 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2706 | ``setuptools3-base`` |
| 2707 | ==================== |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 2708 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2709 | The :ref:`ref-classes-setuptools3-base` class provides a reusable base for |
| 2710 | other classes that support building Python version 3.x extensions. If you need |
| 2711 | functionality that is not provided by the :ref:`ref-classes-setuptools3` class, |
| 2712 | you may want to ``inherit setuptools3-base``. Some recipes do not need the tasks |
| 2713 | in the :ref:`ref-classes-setuptools3` class and inherit this class instead. |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 2714 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2715 | .. _ref-classes-sign_rpm: |
| 2716 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2717 | ``sign_rpm`` |
| 2718 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2719 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2720 | The :ref:`ref-classes-sign_rpm` class supports generating signed RPM packages. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2721 | |
| 2722 | .. _ref-classes-siteconfig: |
| 2723 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2724 | ``siteconfig`` |
| 2725 | ============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2726 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2727 | The :ref:`ref-classes-siteconfig` class provides functionality for handling site |
| 2728 | configuration. The class is used by the :ref:`ref-classes-autotools` class to |
| 2729 | accelerate the :ref:`ref-tasks-configure` task. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2730 | |
| 2731 | .. _ref-classes-siteinfo: |
| 2732 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2733 | ``siteinfo`` |
| 2734 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2735 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2736 | The :ref:`ref-classes-siteinfo` class provides information about the targets |
| 2737 | that might be needed by other classes or recipes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2738 | |
| 2739 | As an example, consider Autotools, which can require tests that must |
| 2740 | execute on the target hardware. Since this is not possible in general |
| 2741 | when cross compiling, site information is used to provide cached test |
| 2742 | results so these tests can be skipped over but still make the correct |
| 2743 | values available. The ``meta/site directory`` contains test results |
| 2744 | sorted into different categories such as architecture, endianness, and |
| 2745 | the ``libc`` used. Site information provides a list of files containing |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2746 | data relevant to the current build in the :term:`CONFIG_SITE` variable that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2747 | Autotools automatically picks up. |
| 2748 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2749 | The class also provides variables like :term:`SITEINFO_ENDIANNESS` and |
| 2750 | :term:`SITEINFO_BITS` that can be used elsewhere in the metadata. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2751 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2752 | .. _ref-classes-sstate: |
| 2753 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2754 | ``sstate`` |
| 2755 | ========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2756 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2757 | The :ref:`ref-classes-sstate` class provides support for Shared State (sstate). |
| 2758 | By default, the class is enabled through the :term:`INHERIT_DISTRO` variable's |
| 2759 | default value. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2760 | |
| 2761 | For more information on sstate, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 2762 | ":ref:`overview-manual/concepts:shared state cache`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2763 | section in the Yocto Project Overview and Concepts Manual. |
| 2764 | |
| 2765 | .. _ref-classes-staging: |
| 2766 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2767 | ``staging`` |
| 2768 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2769 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2770 | The :ref:`ref-classes-staging` class installs files into individual recipe work |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2771 | directories for sysroots. The class contains the following key tasks: |
| 2772 | |
| 2773 | - The :ref:`ref-tasks-populate_sysroot` task, |
| 2774 | which is responsible for handing the files that end up in the recipe |
| 2775 | sysroots. |
| 2776 | |
| 2777 | - The |
| 2778 | :ref:`ref-tasks-prepare_recipe_sysroot` |
| 2779 | task (a "partner" task to the ``populate_sysroot`` task), which |
| 2780 | installs the files into the individual recipe work directories (i.e. |
| 2781 | :term:`WORKDIR`). |
| 2782 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2783 | The code in the :ref:`ref-classes-staging` class is complex and basically works |
| 2784 | in two stages: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2785 | |
| 2786 | - *Stage One:* The first stage addresses recipes that have files they |
| 2787 | want to share with other recipes that have dependencies on the |
| 2788 | originating recipe. Normally these dependencies are installed through |
| 2789 | the :ref:`ref-tasks-install` task into |
Patrick Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 2790 | ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2791 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This |
| 2792 | subset of files is controlled by the |
| 2793 | :term:`SYSROOT_DIRS`, |
| 2794 | :term:`SYSROOT_DIRS_NATIVE`, and |
Andrew Geissler | 9aee500 | 2022-03-30 16:27:02 +0000 | [diff] [blame] | 2795 | :term:`SYSROOT_DIRS_IGNORE` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2796 | variables. |
| 2797 | |
| 2798 | .. note:: |
| 2799 | |
| 2800 | Additionally, a recipe can customize the files further by |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2801 | declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2802 | variable. |
| 2803 | |
| 2804 | A shared state (sstate) object is built from these files and the |
| 2805 | files are placed into a subdirectory of |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2806 | :ref:`structure-build-tmp-sysroots-components`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2807 | The files are scanned for hardcoded paths to the original |
| 2808 | installation location. If the location is found in text files, the |
| 2809 | hardcoded locations are replaced by tokens and a list of the files |
| 2810 | needing such replacements is created. These adjustments are referred |
| 2811 | to as "FIXMEs". The list of files that are scanned for paths is |
| 2812 | controlled by the :term:`SSTATE_SCAN_FILES` |
| 2813 | variable. |
| 2814 | |
| 2815 | - *Stage Two:* The second stage addresses recipes that want to use |
| 2816 | something from another recipe and declare a dependency on that recipe |
| 2817 | through the :term:`DEPENDS` variable. The recipe will |
| 2818 | have a |
| 2819 | :ref:`ref-tasks-prepare_recipe_sysroot` |
| 2820 | task and when this task executes, it creates the ``recipe-sysroot`` |
| 2821 | and ``recipe-sysroot-native`` in the recipe work directory (i.e. |
| 2822 | :term:`WORKDIR`). The OpenEmbedded build system |
| 2823 | creates hard links to copies of the relevant files from |
| 2824 | ``sysroots-components`` into the recipe work directory. |
| 2825 | |
| 2826 | .. note:: |
| 2827 | |
| 2828 | If hard links are not possible, the build system uses actual |
| 2829 | copies. |
| 2830 | |
| 2831 | The build system then addresses any "FIXMEs" to paths as defined from |
| 2832 | the list created in the first stage. |
| 2833 | |
| 2834 | Finally, any files in ``${bindir}`` within the sysroot that have the |
| 2835 | prefix "``postinst-``" are executed. |
| 2836 | |
| 2837 | .. note:: |
| 2838 | |
| 2839 | Although such sysroot post installation scripts are not |
| 2840 | recommended for general use, the files do allow some issues such |
| 2841 | as user creation and module indexes to be addressed. |
| 2842 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2843 | Because recipes can have other dependencies outside of :term:`DEPENDS` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2844 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), |
| 2845 | the sysroot creation function ``extend_recipe_sysroot`` is also added |
| 2846 | as a pre-function for those tasks whose dependencies are not through |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 2847 | :term:`DEPENDS` but operate similarly. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2848 | |
| 2849 | When installing dependencies into the sysroot, the code traverses the |
| 2850 | dependency graph and processes dependencies in exactly the same way |
| 2851 | as the dependencies would or would not be when installed from sstate. |
| 2852 | This processing means, for example, a native tool would have its |
| 2853 | native dependencies added but a target library would not have its |
| 2854 | dependencies traversed or installed. The same sstate dependency code |
| 2855 | is used so that builds should be identical regardless of whether |
| 2856 | sstate was used or not. For a closer look, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2857 | ``setscene_depvalid()`` function in the :ref:`ref-classes-sstate` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2858 | |
| 2859 | The build system is careful to maintain manifests of the files it |
| 2860 | installs so that any given dependency can be installed as needed. The |
| 2861 | sstate hash of the installed item is also stored so that if it |
| 2862 | changes, the build system can reinstall it. |
| 2863 | |
| 2864 | .. _ref-classes-syslinux: |
| 2865 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2866 | ``syslinux`` |
| 2867 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2868 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2869 | The :ref:`ref-classes-syslinux` class provides syslinux-specific functions for |
| 2870 | building bootable images. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2871 | |
| 2872 | The class supports the following variables: |
| 2873 | |
| 2874 | - :term:`INITRD`: Indicates list of filesystem images to |
| 2875 | concatenate and use as an initial RAM disk (initrd). This variable is |
| 2876 | optional. |
| 2877 | |
| 2878 | - :term:`ROOTFS`: Indicates a filesystem image to include |
| 2879 | as the root filesystem. This variable is optional. |
| 2880 | |
| 2881 | - :term:`AUTO_SYSLINUXMENU`: Enables creating |
| 2882 | an automatic menu when set to "1". |
| 2883 | |
| 2884 | - :term:`LABELS`: Lists targets for automatic |
| 2885 | configuration. |
| 2886 | |
| 2887 | - :term:`APPEND`: Lists append string overrides for each |
| 2888 | label. |
| 2889 | |
| 2890 | - :term:`SYSLINUX_OPTS`: Lists additional options |
| 2891 | to add to the syslinux file. Semicolon characters separate multiple |
| 2892 | options. |
| 2893 | |
| 2894 | - :term:`SYSLINUX_SPLASH`: Lists a background |
| 2895 | for the VGA boot menu when you are using the boot menu. |
| 2896 | |
| 2897 | - :term:`SYSLINUX_DEFAULT_CONSOLE`: Set |
| 2898 | to "console=ttyX" to change kernel boot default console. |
| 2899 | |
| 2900 | - :term:`SYSLINUX_SERIAL`: Sets an alternate |
| 2901 | serial port. Or, turns off serial when the variable is set with an |
| 2902 | empty string. |
| 2903 | |
| 2904 | - :term:`SYSLINUX_SERIAL_TTY`: Sets an |
| 2905 | alternate "console=tty..." kernel boot argument. |
| 2906 | |
| 2907 | .. _ref-classes-systemd: |
| 2908 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2909 | ``systemd`` |
| 2910 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2911 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2912 | The :ref:`ref-classes-systemd` class provides support for recipes that install |
| 2913 | systemd unit files. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2914 | |
| 2915 | The functionality for this class is disabled unless you have "systemd" |
| 2916 | in :term:`DISTRO_FEATURES`. |
| 2917 | |
| 2918 | Under this class, the recipe or Makefile (i.e. whatever the recipe is |
| 2919 | calling during the :ref:`ref-tasks-install` task) |
| 2920 | installs unit files into |
| 2921 | ``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit |
| 2922 | files being installed go into packages other than the main package, you |
| 2923 | need to set :term:`SYSTEMD_PACKAGES` in your |
| 2924 | recipe to identify the packages in which the files will be installed. |
| 2925 | |
| 2926 | You should set :term:`SYSTEMD_SERVICE` to the |
| 2927 | name of the service file. You should also use a package name override to |
| 2928 | indicate the package to which the value applies. If the value applies to |
| 2929 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 2930 | is an example from the connman recipe:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2931 | |
Patrick Williams | 0ca19cc | 2021-08-16 14:03:13 -0500 | [diff] [blame] | 2932 | SYSTEMD_SERVICE:${PN} = "connman.service" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2933 | |
| 2934 | Services are set up to start on boot automatically |
| 2935 | unless you have set |
| 2936 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". |
| 2937 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2938 | For more information on :ref:`ref-classes-systemd`, see the |
| 2939 | ":ref:`dev-manual/init-manager:selecting an initialization manager`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2940 | section in the Yocto Project Development Tasks Manual. |
| 2941 | |
| 2942 | .. _ref-classes-systemd-boot: |
| 2943 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2944 | ``systemd-boot`` |
| 2945 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2946 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2947 | The :ref:`ref-classes-systemd-boot` class provides functions specific to the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2948 | systemd-boot bootloader for building bootable images. This is an |
| 2949 | internal class and is not intended to be used directly. |
| 2950 | |
| 2951 | .. note:: |
| 2952 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2953 | The :ref:`ref-classes-systemd-boot` class is a result from merging the ``gummiboot`` class |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 2954 | used in previous Yocto Project releases with the ``systemd`` project. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2955 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2956 | Set the :term:`EFI_PROVIDER` variable to ":ref:`ref-classes-systemd-boot`" to |
| 2957 | use this class. Doing so creates a standalone EFI bootloader that is not |
| 2958 | dependent on systemd. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2959 | |
| 2960 | For information on more variables used and supported in this class, see |
| 2961 | the :term:`SYSTEMD_BOOT_CFG`, |
| 2962 | :term:`SYSTEMD_BOOT_ENTRIES`, and |
| 2963 | :term:`SYSTEMD_BOOT_TIMEOUT` variables. |
| 2964 | |
| 2965 | You can also see the `Systemd-boot |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 2966 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2967 | for more information. |
| 2968 | |
| 2969 | .. _ref-classes-terminal: |
| 2970 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2971 | ``terminal`` |
| 2972 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2973 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2974 | The :ref:`ref-classes-terminal` class provides support for starting a terminal |
| 2975 | session. The :term:`OE_TERMINAL` variable controls which terminal emulator is |
| 2976 | used for the session. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2977 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2978 | Other classes use the :ref:`ref-classes-terminal` class anywhere a separate |
| 2979 | terminal session needs to be started. For example, the :ref:`ref-classes-patch` |
| 2980 | class assuming :term:`PATCHRESOLVE` is set to "user", the |
| 2981 | :ref:`ref-classes-cml1` class, and the :ref:`ref-classes-devshell` class all |
| 2982 | use the :ref:`ref-classes-terminal` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2983 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2984 | .. _ref-classes-testimage: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2985 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2986 | ``testimage`` |
| 2987 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2988 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 2989 | The :ref:`ref-classes-testimage` class supports running automated tests against |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2990 | images using QEMU and on actual hardware. The classes handle loading the |
| 2991 | tests and starting the image. To use the classes, you need to perform |
| 2992 | steps to set up the environment. |
| 2993 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2994 | To enable this class, add the following to your configuration:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2995 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 2996 | IMAGE_CLASSES += "testimage" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2997 | |
| 2998 | The tests are commands that run on the target system over ``ssh``. Each |
| 2999 | test is written in Python and makes use of the ``unittest`` module. |
| 3000 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3001 | The :ref:`ref-classes-testimage` class runs tests on an image when called using the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 3002 | following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3003 | |
| 3004 | $ bitbake -c testimage image |
| 3005 | |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 3006 | Alternatively, if you wish to have tests automatically run for each image |
| 3007 | after it is built, you can set :term:`TESTIMAGE_AUTO`:: |
| 3008 | |
| 3009 | TESTIMAGE_AUTO = "1" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3010 | |
| 3011 | For information on how to enable, run, and create new tests, see the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3012 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3013 | section in the Yocto Project Development Tasks Manual. |
| 3014 | |
| 3015 | .. _ref-classes-testsdk: |
| 3016 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3017 | ``testsdk`` |
| 3018 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3019 | |
| 3020 | This class supports running automated tests against software development |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3021 | kits (SDKs). The :ref:`ref-classes-testsdk` class runs tests on an SDK when called |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 3022 | using the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3023 | |
| 3024 | $ bitbake -c testsdk image |
| 3025 | |
| 3026 | .. note:: |
| 3027 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 3028 | Best practices include using :term:`IMAGE_CLASSES` rather than |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3029 | :term:`INHERIT` to inherit the :ref:`ref-classes-testsdk` class for automated SDK |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 3030 | testing. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3031 | |
| 3032 | .. _ref-classes-texinfo: |
| 3033 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3034 | ``texinfo`` |
| 3035 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3036 | |
| 3037 | This class should be inherited by recipes whose upstream packages invoke |
| 3038 | the ``texinfo`` utilities at build-time. Native and cross recipes are |
| 3039 | made to use the dummy scripts provided by ``texinfo-dummy-native``, for |
| 3040 | improved performance. Target architecture recipes use the genuine |
| 3041 | Texinfo utilities. By default, they use the Texinfo utilities on the |
| 3042 | host system. |
| 3043 | |
| 3044 | .. note:: |
| 3045 | |
| 3046 | If you want to use the Texinfo recipe shipped with the build system, |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 3047 | you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo |
| 3048 | from :term:`SANITY_REQUIRED_UTILITIES`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3049 | |
| 3050 | .. _ref-classes-toaster: |
| 3051 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3052 | ``toaster`` |
| 3053 | =========== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3054 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3055 | The :ref:`ref-classes-toaster` class collects information about packages and images and |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3056 | sends them as events that the BitBake user interface can receive. The |
| 3057 | class is enabled when the Toaster user interface is running. |
| 3058 | |
| 3059 | This class is not intended to be used directly. |
| 3060 | |
| 3061 | .. _ref-classes-toolchain-scripts: |
| 3062 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3063 | ``toolchain-scripts`` |
| 3064 | ===================== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3065 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3066 | The :ref:`ref-classes-toolchain-scripts` class provides the scripts used for setting up |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3067 | the environment for installed SDKs. |
| 3068 | |
| 3069 | .. _ref-classes-typecheck: |
| 3070 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3071 | ``typecheck`` |
| 3072 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3073 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3074 | The :ref:`ref-classes-typecheck` class provides support for validating the values of |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3075 | variables set at the configuration level against their defined types. |
| 3076 | The OpenEmbedded build system allows you to define the type of a |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 3077 | variable using the "type" varflag. Here is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3078 | |
| 3079 | IMAGE_FEATURES[type] = "list" |
| 3080 | |
| 3081 | .. _ref-classes-uboot-config: |
| 3082 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3083 | ``uboot-config`` |
| 3084 | ================ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3085 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3086 | The :ref:`ref-classes-uboot-config` class provides support for U-Boot configuration for |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 3087 | a machine. Specify the machine in your recipe as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3088 | |
| 3089 | UBOOT_CONFIG ??= <default> |
| 3090 | UBOOT_CONFIG[foo] = "config,images" |
| 3091 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 3092 | You can also specify the machine using this method:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3093 | |
| 3094 | UBOOT_MACHINE = "config" |
| 3095 | |
| 3096 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional |
| 3097 | information. |
| 3098 | |
| 3099 | .. _ref-classes-uninative: |
| 3100 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3101 | ``uninative`` |
| 3102 | ============= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3103 | |
| 3104 | Attempts to isolate the build system from the host distribution's C |
| 3105 | library in order to make re-use of native shared state artifacts across |
| 3106 | different host distributions practical. With this class enabled, a |
| 3107 | tarball containing a pre-built C library is downloaded at the start of |
| 3108 | the build. In the Poky reference distribution this is enabled by default |
| 3109 | through ``meta/conf/distro/include/yocto-uninative.inc``. Other |
| 3110 | distributions that do not derive from poky can also |
| 3111 | "``require conf/distro/include/yocto-uninative.inc``" to use this. |
| 3112 | Alternatively if you prefer, you can build the uninative-tarball recipe |
| 3113 | yourself, publish the resulting tarball (e.g. via HTTP) and set |
| 3114 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an |
| 3115 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. |
| 3116 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3117 | The :ref:`ref-classes-uninative` class is also used unconditionally by the extensible |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3118 | SDK. When building the extensible SDK, ``uninative-tarball`` is built |
| 3119 | and the resulting tarball is included within the SDK. |
| 3120 | |
| 3121 | .. _ref-classes-update-alternatives: |
| 3122 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3123 | ``update-alternatives`` |
| 3124 | ======================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3125 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3126 | The :ref:`ref-classes-update-alternatives` class helps the alternatives system when |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3127 | multiple sources provide the same command. This situation occurs when |
| 3128 | several programs that have the same or similar function are installed |
| 3129 | with the same name. For example, the ``ar`` command is available from |
| 3130 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3131 | :ref:`ref-classes-update-alternatives` class handles renaming the binaries so that |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3132 | multiple packages can be installed without conflicts. The ``ar`` command |
| 3133 | still works regardless of which packages are installed or subsequently |
| 3134 | removed. The class renames the conflicting binary in each package and |
| 3135 | symlinks the highest priority binary during installation or removal of |
| 3136 | packages. |
| 3137 | |
| 3138 | To use this class, you need to define a number of variables: |
| 3139 | |
| 3140 | - :term:`ALTERNATIVE` |
| 3141 | |
| 3142 | - :term:`ALTERNATIVE_LINK_NAME` |
| 3143 | |
| 3144 | - :term:`ALTERNATIVE_TARGET` |
| 3145 | |
| 3146 | - :term:`ALTERNATIVE_PRIORITY` |
| 3147 | |
| 3148 | These variables list alternative commands needed by a package, provide |
| 3149 | pathnames for links, default links for targets, and so forth. For |
| 3150 | details on how to use this class, see the comments in the |
Patrick Williams | 975a06f | 2022-10-21 14:42:47 -0500 | [diff] [blame] | 3151 | :yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes-recipe/update-alternatives.bbclass>` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3152 | file. |
| 3153 | |
| 3154 | .. note:: |
| 3155 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 3156 | You can use the ``update-alternatives`` command directly in your recipes. |
| 3157 | However, this class simplifies things in most cases. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3158 | |
| 3159 | .. _ref-classes-update-rc.d: |
| 3160 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3161 | ``update-rc.d`` |
| 3162 | =============== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3163 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3164 | The :ref:`ref-classes-update-rc.d` class uses ``update-rc.d`` to safely install an |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3165 | initialization script on behalf of the package. The OpenEmbedded build |
| 3166 | system takes care of details such as making sure the script is stopped |
| 3167 | before a package is removed and started when the package is installed. |
| 3168 | |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 3169 | Three variables control this class: :term:`INITSCRIPT_PACKAGES`, |
| 3170 | :term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3171 | for details. |
| 3172 | |
| 3173 | .. _ref-classes-useradd: |
| 3174 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3175 | ``useradd*`` |
| 3176 | ============ |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3177 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 3178 | The :ref:`useradd* <ref-classes-useradd>` classes support the addition of users or groups for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3179 | usage by the package on the target. For example, if you have packages |
| 3180 | that contain system services that should be run under their own user or |
| 3181 | group, you can use these classes to enable creation of the user or |
Andrew Geissler | 595f630 | 2022-01-24 19:11:47 +0000 | [diff] [blame] | 3182 | group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb |
| 3183 | </openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3184 | recipe in the :term:`Source Directory` provides a simple |
| 3185 | example that shows how to add three users and groups to two packages. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3186 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 3187 | The :ref:`useradd_base <ref-classes-useradd>` class provides basic functionality for user or |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3188 | groups settings. |
| 3189 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 3190 | The :ref:`useradd* <ref-classes-useradd>` classes support the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3191 | :term:`USERADD_PACKAGES`, |
| 3192 | :term:`USERADD_PARAM`, |
| 3193 | :term:`GROUPADD_PARAM`, and |
| 3194 | :term:`GROUPMEMS_PARAM` variables. |
| 3195 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 3196 | The :ref:`useradd-staticids <ref-classes-useradd>` class supports the addition of users or groups |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3197 | that have static user identification (``uid``) and group identification |
| 3198 | (``gid``) values. |
| 3199 | |
| 3200 | The default behavior of the OpenEmbedded build system for assigning |
| 3201 | ``uid`` and ``gid`` values when packages add users and groups during |
| 3202 | package install time is to add them dynamically. This works fine for |
| 3203 | programs that do not care what the values of the resulting users and |
| 3204 | groups become. In these cases, the order of the installation determines |
| 3205 | the final ``uid`` and ``gid`` values. However, if non-deterministic |
| 3206 | ``uid`` and ``gid`` values are a problem, you can override the default, |
| 3207 | dynamic application of these values by setting static values. When you |
| 3208 | set static values, the OpenEmbedded build system looks in |
| 3209 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` |
| 3210 | files for the values. |
| 3211 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3212 | To use static ``uid`` and ``gid`` values, you need to set some variables. See |
| 3213 | the :term:`USERADDEXTENSION`, :term:`USERADD_UID_TABLES`, |
| 3214 | :term:`USERADD_GID_TABLES`, and :term:`USERADD_ERROR_DYNAMIC` variables. |
| 3215 | You can also see the :ref:`ref-classes-useradd` class for additional |
| 3216 | information. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3217 | |
| 3218 | .. note:: |
| 3219 | |
Patrick Williams | 2390b1b | 2022-11-03 13:47:49 -0500 | [diff] [blame] | 3220 | You do not use the :ref:`useradd-staticids <ref-classes-useradd>` class directly. You either enable |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 3221 | or disable the class by setting the :term:`USERADDEXTENSION` variable. If you |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 3222 | enable or disable the class in a configured system, :term:`TMPDIR` might |
Andrew Geissler | 0903674 | 2021-06-25 14:25:14 -0500 | [diff] [blame] | 3223 | contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3224 | directory will correct this condition. |
| 3225 | |
| 3226 | .. _ref-classes-utility-tasks: |
| 3227 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3228 | ``utility-tasks`` |
| 3229 | ================= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3230 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3231 | The :ref:`ref-classes-utility-tasks` class provides support for various |
| 3232 | "utility" type tasks that are applicable to all recipes, such as |
| 3233 | :ref:`ref-tasks-clean` and :ref:`ref-tasks-listtasks`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3234 | |
| 3235 | This class is enabled by default because it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3236 | :ref:`ref-classes-base` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3237 | |
| 3238 | .. _ref-classes-utils: |
| 3239 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3240 | ``utils`` |
| 3241 | ========= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3242 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3243 | The :ref:`ref-classes-utils` class provides some useful Python functions that are |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3244 | typically used in inline Python expressions (e.g. ``${@...}``). One |
| 3245 | example use is for ``bb.utils.contains()``. |
| 3246 | |
| 3247 | This class is enabled by default because it is inherited by the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3248 | :ref:`ref-classes-base` class. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3249 | |
| 3250 | .. _ref-classes-vala: |
| 3251 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3252 | ``vala`` |
| 3253 | ======== |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3254 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3255 | The :ref:`ref-classes-vala` class supports recipes that need to build software written |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3256 | using the Vala programming language. |
| 3257 | |
| 3258 | .. _ref-classes-waf: |
| 3259 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3260 | ``waf`` |
| 3261 | ======= |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3262 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 3263 | The :ref:`ref-classes-waf` class supports recipes that need to build software that uses |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 3264 | the Waf build system. You can use the |
| 3265 | :term:`EXTRA_OECONF` or |
| 3266 | :term:`PACKAGECONFIG_CONFARGS` variables |
| 3267 | to specify additional configuration options to be passed on the Waf |
| 3268 | command line. |