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