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-&POKYVERSION;`` within the existing directory ``mybuilds``: 92 93 .. code-block:: shell 94 95 $ source poky/oe-init-build-env mybuilds/YP-&POKYVERSION; 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 `meta-security <https://git.yoctoproject.org/cgit/cgit.cgi/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:`Source Directory` 327 This term refers to the directory structure 328 created as a result of creating a local copy of the ``poky`` Git 329 repository ``git://git.yoctoproject.org/poky`` or expanding a 330 released ``poky`` tarball. 331 332 .. note:: 333 334 Creating a local copy of the 335 poky 336 Git repository is the recommended method for setting up your 337 Source Directory. 338 339 Sometimes you might hear the term "poky directory" used to refer to 340 this directory structure. 341 342 .. note:: 343 344 The OpenEmbedded build system does not support file or directory 345 names that contain spaces. Be sure that the Source Directory you 346 use does not contain these types of names. 347 348 The Source Directory contains BitBake, Documentation, Metadata and 349 other files that all support the Yocto Project. Consequently, you 350 must have the Source Directory in place on your development system in 351 order to do any development using the Yocto Project. 352 353 When you create a local copy of the Git repository, you can name the 354 repository anything you like. Throughout much of the documentation, 355 "poky" is used as the name of the top-level folder of the local copy 356 of the poky Git repository. So, for example, cloning the ``poky`` Git 357 repository results in a local Git repository whose top-level folder 358 is also named "poky". 359 360 While it is not recommended that you use tarball expansion to set up 361 the Source Directory, if you do, the top-level directory name of the 362 Source Directory is derived from the Yocto Project release tarball. 363 For example, downloading and unpacking 364 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` 365 results in a Source Directory whose root folder is named 366 ``&YOCTO_POKY;``. 367 368 It is important to understand the differences between the Source 369 Directory created by unpacking a released tarball as compared to 370 cloning ``git://git.yoctoproject.org/poky``. When you unpack a 371 tarball, you have an exact copy of the files based on the time of 372 release - a fixed release point. Any changes you make to your local 373 files in the Source Directory are on top of the release and will 374 remain local only. On the other hand, when you clone the ``poky`` Git 375 repository, you have an active development repository with access to 376 the upstream repository's branches and tags. In this case, any local 377 changes you make to the local Source Directory can be later applied 378 to active development branches of the upstream ``poky`` Git 379 repository. 380 381 For more information on concepts related to Git repositories, 382 branches, and tags, see the 383 ":ref:`overview-manual/development-environment:repositories, tags, and branches`" 384 section in the Yocto Project Overview and Concepts Manual. 385 386 :term:`Task` 387 A per-recipe unit of execution for BitBake (e.g. 388 :ref:`ref-tasks-compile`, 389 :ref:`ref-tasks-fetch`, 390 :ref:`ref-tasks-patch`, and so forth). 391 One of the major benefits of the build system is that, since each 392 recipe will typically spawn the execution of numerous tasks, 393 it is entirely possible that many tasks can execute in parallel, 394 either tasks from separate recipes or independent tasks within 395 the same recipe, potentially up to the parallelism of your 396 build system. 397 398 :term:`Toaster` 399 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. 400 The interface enables you to 401 configure and run your builds. Information about builds is collected 402 and stored in a database. For information on Toaster, see the 403 :doc:`/toaster-manual/index`. 404 405 :term:`Upstream` 406 A reference to source code or repositories that are not 407 local to the development system but located in a remote area that is 408 controlled by the maintainer of the source code. For example, in 409 order for a developer to work on a particular piece of code, they 410 need to first get a copy of it from an "upstream" source. 411