1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3******************* 4Yocto Project Terms 5******************* 6 7Following is a list of terms and definitions users new to the Yocto Project 8development environment might find helpful. While some of these terms are 9universal, the list includes them just in case: 10 11.. glossary:: 12 13 :term:`Append Files` 14 Files that append build information to a recipe file. Append files are 15 known as BitBake append files and ``.bbappend`` files. The OpenEmbedded 16 build system expects every append file to have a corresponding recipe 17 (``.bb``) file. Furthermore, the append file and corresponding recipe file 18 must use the same root filename. The filenames can differ only in the 19 file type suffix used (e.g. ``formfactor_0.0.bb`` and 20 ``formfactor_0.0.bbappend``). 21 22 Information in append files extends or overrides the information in the 23 similarly-named recipe file. For an example of an append file in use, see 24 the ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`" 25 section in the Yocto Project Development Tasks Manual. 26 27 When you name an append file, you can use the "``%``" wildcard character 28 to allow for matching recipe names. For example, suppose you have an 29 append file named as follows:: 30 31 busybox_1.21.%.bbappend 32 33 That append file 34 would match any ``busybox_1.21.x.bb`` version of the recipe. So, 35 the append file would match any of the following recipe names: 36 37 .. code-block:: shell 38 39 busybox_1.21.1.bb 40 busybox_1.21.2.bb 41 busybox_1.21.3.bb 42 busybox_1.21.10.bb 43 busybox_1.21.25.bb 44 45 .. note:: 46 47 The use of the "%" character is limited in that it only works 48 directly in front of the .bbappend portion of the append file's 49 name. You cannot use the wildcard character in any other location of 50 the name. 51 52 :term:`BitBake` 53 The task executor and scheduler used by the OpenEmbedded build system to 54 build images. For more information on BitBake, see the :doc:`BitBake User 55 Manual <bitbake:index>`. 56 57 :term:`Board Support Package (BSP)` 58 A group of drivers, definitions, and other components that provide support 59 for a specific hardware configuration. For more information on BSPs, see 60 the :doc:`/bsp-guide/index`. 61 62 :term:`Build Directory` 63 This term refers to the area used by the OpenEmbedded build system for 64 builds. The area is created when you ``source`` the setup environment 65 script that is found in the Source Directory 66 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The 67 :term:`TOPDIR` variable points to the Build Directory. 68 69 You have a lot of flexibility when creating the Build Directory. 70 Following are some examples that show how to create the directory. The 71 examples assume your :term:`Source Directory` is named ``poky``: 72 73 - Create the Build Directory inside your Source Directory and let 74 the name of the Build Directory default to ``build``: 75 76 .. code-block:: shell 77 78 $ cd poky 79 $ source oe-init-build-env 80 81 - Create the Build Directory inside your home directory and 82 specifically name it ``test-builds``: 83 84 .. code-block:: shell 85 86 $ source poky/oe-init-build-env test-builds 87 88 - Provide a directory path and specifically name the Build 89 Directory. Any intermediate folders in the pathname must exist. 90 This next example creates a Build Directory named 91 ``YP-&DISTRO;`` within the existing directory ``mybuilds``: 92 93 .. code-block:: shell 94 95 $ source poky/oe-init-build-env mybuilds/YP-&DISTRO; 96 97 .. note:: 98 99 By default, the Build Directory contains :term:`TMPDIR`, which is a 100 temporary directory the build system uses for its work. :term:`TMPDIR` cannot 101 be under NFS. Thus, by default, the Build Directory cannot be under 102 NFS. However, if you need the Build Directory to be under NFS, you can 103 set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local 104 drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the 105 Build Directory. 106 107 :term:`Build Host` 108 The system used to build images in a Yocto Project Development 109 environment. The build system is sometimes referred to as the development 110 host. 111 112 :term:`Classes` 113 Files that provide for logic encapsulation and inheritance so that 114 commonly used patterns can be defined once and then easily used in 115 multiple recipes. For reference information on the Yocto Project classes, 116 see the ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the 117 ``.bbclass`` filename extension. 118 119 :term:`Configuration File` 120 Files that hold global definitions of variables, user-defined variables, 121 and hardware configuration information. These files tell the OpenEmbedded 122 build system what to build and what to put into the image to support a 123 particular platform. 124 125 Configuration files end with a ``.conf`` filename extension. The 126 :file:`conf/local.conf` configuration file in the :term:`Build Directory` 127 contains user-defined variables that affect every build. The 128 :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto 129 "distro" configuration variables used only when building with this 130 policy. Machine configuration files, which are located throughout the 131 :term:`Source Directory`, define variables for specific hardware and are 132 only used when building for that target (e.g. the 133 :file:`machine/beaglebone.conf` configuration file defines variables for 134 the Texas Instruments ARM Cortex-A8 development board). 135 136 :term:`Container Layer` 137 A flexible definition that typically refers to a single Git checkout 138 which contains multiple (and typically related) sub-layers which can 139 be included independently in your project's ``bblayers.conf`` file. 140 141 In some cases, such as with OpenEmbedded's 142 `meta-openembedded <https://github.com/openembedded/meta-openembedded>`_ 143 layer, the top level ``meta-openembedded/`` directory is not itself an actual layer, 144 so you would never explicitly include it in a ``bblayers.conf`` file; 145 rather, you would include any number of its layer subdirectories, such as 146 `meta-openembedded/meta-oe <https://github.com/openembedded/meta-openembedded/tree/master/meta-oe>`_, 147 `meta-openembedded/meta-python <https://github.com/openembedded/meta-openembedded/tree/master/meta-python>`_ 148 and so on. 149 150 On the other hand, some container layers (such as 151 :yocto_git:`meta-security </meta-security>`) 152 have a top-level directory that is itself an actual layer, as well as 153 a variety of sub-layers, both of which could be included in your 154 ``bblayers.conf`` file. 155 156 In either case, the phrase "container layer" is simply used to describe 157 a directory structure which contains multiple valid OpenEmbedded layers. 158 159 :term:`Cross-Development Toolchain` 160 In general, a cross-development toolchain is a collection of software 161 development tools and utilities that run on one architecture and allow you 162 to develop software for a different, or targeted, architecture. These 163 toolchains contain cross-compilers, linkers, and debuggers that are 164 specific to the target architecture. 165 166 The Yocto Project supports two different cross-development toolchains: 167 168 - A toolchain only used by and within BitBake when building an image for a 169 target architecture. 170 171 - A relocatable toolchain used outside of BitBake by developers when 172 developing applications that will run on a targeted device. 173 174 Creation of these toolchains is simple and automated. For information on 175 toolchain concepts as they apply to the Yocto Project, see the 176 ":ref:`overview-manual/concepts:Cross-Development 177 Toolchain Generation`" section in the Yocto Project Overview and Concepts 178 Manual. You can also find more information on using the relocatable 179 toolchain in the :doc:`/sdk-manual/index` manual. 180 181 :term:`Extensible Software Development Kit (eSDK)` 182 A custom SDK for application developers. This eSDK allows developers to 183 incorporate their library and programming changes back into the image to 184 make their code available to other application developers. 185 186 For information on the eSDK, see the :doc:`/sdk-manual/index` manual. 187 188 :term:`Image` 189 An image is an artifact of the BitBake build process given a collection of 190 recipes and related Metadata. Images are the binary output that run on 191 specific hardware or QEMU and are used for specific use-cases. For a list 192 of the supported image types that the Yocto Project provides, see the 193 ":ref:`ref-manual/images:Images`" chapter. 194 195 :term:`Layer` 196 A collection of related recipes. Layers allow you to consolidate related 197 metadata to customize your build. Layers also isolate information used 198 when building for multiple architectures. Layers are hierarchical in 199 their ability to override previous specifications. You can include any 200 number of available layers from the Yocto Project and customize the build 201 by adding your layers after them. You can search the Layer Index for 202 layers used within Yocto Project. 203 204 For introductory information on layers, see the 205 ":ref:`overview-manual/yp-intro:The Yocto Project Layer 206 Model`" section in the Yocto Project Overview and Concepts Manual. For 207 more detailed information on layers, see the 208 ":ref:`dev-manual/common-tasks:Understanding and Creating 209 Layers`" section in the Yocto Project Development Tasks Manual. For a 210 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP 211 Layers`" section in the Yocto Project Board Support Packages (BSP) 212 Developer's Guide. 213 214 :term:`Metadata` 215 A key element of the Yocto Project is the Metadata that 216 is used to construct a Linux distribution and is contained in the 217 files that the :term:`OpenEmbedded Build System` 218 parses when building an image. In general, Metadata includes recipes, 219 configuration files, and other information that refers to the build 220 instructions themselves, as well as the data used to control what 221 things get built and the effects of the build. Metadata also includes 222 commands and data used to indicate what versions of software are 223 used, from where they are obtained, and changes or additions to the 224 software itself (patches or auxiliary files) that are used to fix 225 bugs or customize the software for use in a particular situation. 226 OpenEmbedded-Core is an important set of validated metadata. 227 228 In the context of the kernel ("kernel Metadata"), the term refers to 229 the kernel config fragments and features contained in the 230 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>` 231 Git repository. 232 233 :term:`OpenEmbedded-Core (OE-Core)` 234 OE-Core is metadata comprised of 235 foundational recipes, classes, and associated files that are meant to 236 be common among many different OpenEmbedded-derived systems, 237 including the Yocto Project. OE-Core is a curated subset of an 238 original repository developed by the OpenEmbedded community that has 239 been pared down into a smaller, core set of continuously validated 240 recipes. The result is a tightly controlled and an quality-assured 241 core set of recipes. 242 243 You can see the Metadata in the ``meta`` directory of the Yocto 244 Project :yocto_git:`Source Repositories </poky>`. 245 246 :term:`OpenEmbedded Build System` 247 The build system specific to the Yocto 248 Project. The OpenEmbedded build system is based on another project 249 known as "Poky", which uses :term:`BitBake` as the task 250 executor. Throughout the Yocto Project documentation set, the 251 OpenEmbedded build system is sometimes referred to simply as "the 252 build system". If other build systems, such as a host or target build 253 system are referenced, the documentation clearly states the 254 difference. 255 256 .. note:: 257 258 For some historical information about Poky, see the :term:`Poky` term. 259 260 :term:`Package` 261 In the context of the Yocto Project, this term refers to a 262 recipe's packaged output produced by BitBake (i.e. a "baked recipe"). 263 A package is generally the compiled binaries produced from the 264 recipe's sources. You "bake" something by running it through BitBake. 265 266 It is worth noting that the term "package" can, in general, have 267 subtle meanings. For example, the packages referred to in the 268 ":ref:`ref-manual/system-requirements:required packages for the build host`" 269 section are compiled binaries that, when installed, add functionality to 270 your Linux distribution. 271 272 Another point worth noting is that historically within the Yocto 273 Project, recipes were referred to as packages - thus, the existence 274 of several BitBake variables that are seemingly mis-named, (e.g. 275 :term:`PR`, :term:`PV`, and 276 :term:`PE`). 277 278 :term:`Package Groups` 279 Arbitrary groups of software Recipes. You use 280 package groups to hold recipes that, when built, usually accomplish a 281 single task. For example, a package group could contain the recipes 282 for a company's proprietary or value-add software. Or, the package 283 group could contain the recipes that enable graphics. A package group 284 is really just another recipe. Because package group files are 285 recipes, they end with the ``.bb`` filename extension. 286 287 :term:`Poky` 288 Poky, which is pronounced *Pock*-ee, is a reference embedded 289 distribution and a reference test configuration. Poky provides the 290 following: 291 292 - A base-level functional distro used to illustrate how to customize 293 a distribution. 294 295 - A means by which to test the Yocto Project components (i.e. Poky 296 is used to validate the Yocto Project). 297 298 - A vehicle through which you can download the Yocto Project. 299 300 Poky is not a product level distro. Rather, it is a good starting 301 point for customization. 302 303 .. note:: 304 305 Poky began as an open-source project initially developed by 306 OpenedHand. OpenedHand developed Poky from the existing 307 OpenEmbedded build system to create a commercially supportable 308 build system for embedded Linux. After Intel Corporation acquired 309 OpenedHand, the poky project became the basis for the Yocto 310 Project's build system. 311 312 :term:`Recipe` 313 A set of instructions for building packages. A recipe 314 describes where you get source code, which patches to apply, how to 315 configure the source, how to compile it and so on. Recipes also 316 describe dependencies for libraries or for other recipes. Recipes 317 represent the logical unit of execution, the software to build, the 318 images to build, and use the ``.bb`` file extension. 319 320 :term:`Reference Kit` 321 A working example of a system, which includes a 322 :term:`BSP<Board Support Package (BSP)>` as well as a 323 :term:`build host<Build Host>` and other components, that can 324 work on specific hardware. 325 326 :term:`SBOM` 327 This term means *Software Bill of Materials*. When you distribute 328 software, it offers a description of all the components you used, 329 their corresponding licenses, their dependencies, the changes that were 330 applied and the known vulnerabilities that were fixed. 331 332 This can be used by the recipients of the software to assess 333 their exposure to license compliance and security vulnerability issues. 334 335 See the :wikipedia:`Software Supply Chain <Software_supply_chain>` 336 article on Wikipedia for more details. 337 338 The OpenEmbedded Build System can generate such documentation for your 339 project, in :term:`SPDX` format, based on all the metadata it used to 340 build the software images. See the ":ref:`dev-manual/common-tasks:creating 341 a software bill of materials`" section of the Development Tasks manual. 342 343 :term:`Source Directory` 344 This term refers to the directory structure 345 created as a result of creating a local copy of the ``poky`` Git 346 repository ``git://git.yoctoproject.org/poky`` or expanding a 347 released ``poky`` tarball. 348 349 .. note:: 350 351 Creating a local copy of the 352 poky 353 Git repository is the recommended method for setting up your 354 Source Directory. 355 356 Sometimes you might hear the term "poky directory" used to refer to 357 this directory structure. 358 359 .. note:: 360 361 The OpenEmbedded build system does not support file or directory 362 names that contain spaces. Be sure that the Source Directory you 363 use does not contain these types of names. 364 365 The Source Directory contains BitBake, Documentation, Metadata and 366 other files that all support the Yocto Project. Consequently, you 367 must have the Source Directory in place on your development system in 368 order to do any development using the Yocto Project. 369 370 When you create a local copy of the Git repository, you can name the 371 repository anything you like. Throughout much of the documentation, 372 "poky" is used as the name of the top-level folder of the local copy 373 of the poky Git repository. So, for example, cloning the ``poky`` Git 374 repository results in a local Git repository whose top-level folder 375 is also named "poky". 376 377 While it is not recommended that you use tarball extraction to set up 378 the Source Directory, if you do, the top-level directory name of the 379 Source Directory is derived from the Yocto Project release tarball. 380 For example, downloading and unpacking poky tarballs from 381 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/` 382 results in a Source Directory whose root folder is named poky. 383 384 385 It is important to understand the differences between the Source 386 Directory created by unpacking a released tarball as compared to 387 cloning ``git://git.yoctoproject.org/poky``. When you unpack a 388 tarball, you have an exact copy of the files based on the time of 389 release - a fixed release point. Any changes you make to your local 390 files in the Source Directory are on top of the release and will 391 remain local only. On the other hand, when you clone the ``poky`` Git 392 repository, you have an active development repository with access to 393 the upstream repository's branches and tags. In this case, any local 394 changes you make to the local Source Directory can be later applied 395 to active development branches of the upstream ``poky`` Git 396 repository. 397 398 For more information on concepts related to Git repositories, 399 branches, and tags, see the 400 ":ref:`overview-manual/development-environment:repositories, tags, and branches`" 401 section in the Yocto Project Overview and Concepts Manual. 402 403 :term:`SPDX` 404 This term means *Software Package Data Exchange*, and is used as a open 405 standard for providing a *Software Bill of Materials* (:term:`SBOM`). 406 This standard is developed through a `Linux Foundation project 407 <https://spdx.dev/>`__ and is used by the OpenEmbedded Build System to 408 provide an :term:`SBOM` associated to each a software image. 409 410 For details, see Wikipedia's :wikipedia:`SPDX page <Software_Package_Data_Exchange>` 411 and the ":ref:`dev-manual/common-tasks:creating a software bill of materials`" 412 section of the Development Tasks manual. 413 414 :term:`Task` 415 A per-recipe unit of execution for BitBake (e.g. 416 :ref:`ref-tasks-compile`, 417 :ref:`ref-tasks-fetch`, 418 :ref:`ref-tasks-patch`, and so forth). 419 One of the major benefits of the build system is that, since each 420 recipe will typically spawn the execution of numerous tasks, 421 it is entirely possible that many tasks can execute in parallel, 422 either tasks from separate recipes or independent tasks within 423 the same recipe, potentially up to the parallelism of your 424 build system. 425 426 :term:`Toaster` 427 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. 428 The interface enables you to 429 configure and run your builds. Information about builds is collected 430 and stored in a database. For information on Toaster, see the 431 :doc:`/toaster-manual/index`. 432 433 :term:`Upstream` 434 A reference to source code or repositories that are not 435 local to the development system but located in a remote area that is 436 controlled by the maintainer of the source code. For example, in 437 order for a developer to work on a particular piece of code, they 438 need to first get a copy of it from an "upstream" source. 439