1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3*******************
4Yocto Project Terms
5*******************
6
7Here 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/layers: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 :term:`Build Directory`.
68
69      You have a lot of flexibility when creating the :term:`Build Directory`.
70      Here 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 :term:`Build Directory` inside your Source Directory and let
74            the name of the :term:`Build Directory` default to ``build``:
75
76            .. code-block:: shell
77
78               $ cd poky
79               $ source oe-init-build-env
80
81         -  Create the :term:`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
89            :term:`Build Directory`. Any intermediate folders in the pathname
90            must exist.  This next example creates a :term:`Build Directory`
91            named ``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 :term:`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 :term:`Build Directory` cannot be under
102         NFS. However, if you need the :term:`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         :term:`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:`buildtools`
113      Build tools in binary form, providing required versions of development
114      tools (such as Git, GCC, Python and make), to run the OpenEmbedded build
115      system on a development host without such minimum versions.
116
117      See the ":ref:`system-requirements-buildtools`" paragraph in the
118      Reference Manual for details about downloading or building an archive
119      of such tools.
120
121   :term:`buildtools-extended`
122      A set of :term:`buildtools` binaries extended with additional development
123      tools, such as a required version of the GCC compiler to run the
124      OpenEmbedded build system.
125
126      See the ":ref:`system-requirements-buildtools`" paragraph in the
127      Reference Manual for details about downloading or building an archive
128      of such tools.
129
130   :term:`buildtools-make`
131      A variant of :term:`buildtools`, just providing the required
132      version of ``make`` to run the OpenEmbedded build system.
133
134   :term:`Classes`
135      Files that provide for logic encapsulation and inheritance so that
136      commonly used patterns can be defined once and then easily used in
137      multiple recipes. For reference information on the Yocto Project classes,
138      see the ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the
139      ``.bbclass`` filename extension.
140
141   :term:`Configuration File`
142      Files that hold global definitions of variables, user-defined variables,
143      and hardware configuration information. These files tell the OpenEmbedded
144      build system what to build and what to put into the image to support a
145      particular platform.
146
147      Configuration files end with a ``.conf`` filename extension. The
148      :file:`conf/local.conf` configuration file in the :term:`Build Directory`
149      contains user-defined variables that affect every build. The
150      :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto
151      "distro" configuration variables used only when building with this
152      policy. Machine configuration files, which are located throughout the
153      :term:`Source Directory`, define variables for specific hardware and are
154      only used when building for that target (e.g. the
155      :file:`machine/beaglebone.conf` configuration file defines variables for
156      the Texas Instruments ARM Cortex-A8 development board).
157
158   :term:`Container Layer`
159      A flexible definition that typically refers to a single Git checkout
160      which contains multiple (and typically related) sub-layers which can
161      be included independently in your project's ``bblayers.conf`` file.
162
163      In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
164      layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
165      so you would never explicitly include it in a ``bblayers.conf`` file;
166      rather, you would include any number of its layer subdirectories, such as
167      :oe_git:`meta-oe </meta-openembedded/tree/meta-oe>`, :oe_git:`meta-python
168      </meta-openembedded/tree/meta-python>` and so on.
169
170      On the other hand, some container layers (such as
171      :yocto_git:`meta-security </meta-security>`)
172      have a top-level directory that is itself an actual layer, as well as
173      a variety of sub-layers, both of which could be included in your
174      ``bblayers.conf`` file.
175
176      In either case, the phrase "container layer" is simply used to describe
177      a directory structure which contains multiple valid OpenEmbedded layers.
178
179   :term:`Cross-Development Toolchain`
180      In general, a cross-development toolchain is a collection of software
181      development tools and utilities that run on one architecture and allow you
182      to develop software for a different, or targeted, architecture. These
183      toolchains contain cross-compilers, linkers, and debuggers that are
184      specific to the target architecture.
185
186      The Yocto Project supports two different cross-development toolchains:
187
188      - A toolchain only used by and within BitBake when building an image for a
189        target architecture.
190
191      - A relocatable toolchain used outside of BitBake by developers when
192        developing applications that will run on a targeted device.
193
194      Creation of these toolchains is simple and automated. For information on
195      toolchain concepts as they apply to the Yocto Project, see the
196      ":ref:`overview-manual/concepts:Cross-Development
197      Toolchain Generation`" section in the Yocto Project Overview and Concepts
198      Manual. You can also find more information on using the relocatable
199      toolchain in the :doc:`/sdk-manual/index` manual.
200
201   :term:`Extensible Software Development Kit (eSDK)`
202      A custom SDK for application developers. This eSDK allows developers to
203      incorporate their library and programming changes back into the image to
204      make their code available to other application developers.
205
206      For information on the eSDK, see the :doc:`/sdk-manual/index` manual.
207
208   :term:`Image`
209      An image is an artifact of the BitBake build process given a collection of
210      recipes and related Metadata. Images are the binary output that run on
211      specific hardware or QEMU and are used for specific use-cases. For a list
212      of the supported image types that the Yocto Project provides, see the
213      ":ref:`ref-manual/images:Images`" chapter.
214
215   :term:`Initramfs`
216      An Initial RAM Filesystem (:term:`Initramfs`) is an optionally compressed
217      :wikipedia:`cpio <Cpio>` archive which is extracted
218      by the Linux kernel into RAM in a special :wikipedia:`tmpfs <Tmpfs>`
219      instance, used as the initial root filesystem.
220
221      This is a replacement for the legacy init RAM disk ("initrd")
222      technique, booting on an emulated block device in RAM, but being less
223      efficient because of the overhead of going through a filesystem and
224      having to duplicate accessed file contents in the file cache in RAM,
225      as for any block device.
226
227      .. note::
228
229         As far as bootloaders are concerned, :term:`Initramfs` and "initrd"
230         images are still copied to RAM in the same way. That's why most
231         most bootloaders refer to :term:`Initramfs` images as "initrd"
232         or "init RAM disk".
233
234      This kind of mechanism is typically used for two reasons:
235
236      -  For booting the same kernel binary on multiple systems requiring
237         different device drivers. The :term:`Initramfs` image is then customized
238         for each type of system, to include the specific kernel modules
239         necessary to access the final root filesystem. This technique
240         is used on all GNU / Linux distributions for desktops and servers.
241
242      -  For booting faster. As the root filesystem is extracted into RAM,
243         accessing the first user-space applications is very fast, compared
244         to having to initialize a block device, to access multiple blocks
245         from it, and to go through a filesystem having its own overhead.
246         For example, this allows to display a splashscreen very early,
247         and to later take care of mounting the final root filesystem and
248         loading less time-critical kernel drivers.
249
250      This cpio archive can either be loaded to RAM by the bootloader,
251      or be included in the kernel binary.
252
253      For information on creating and using an :term:`Initramfs`, see the
254      ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
255      section in the Yocto Project Development Tasks Manual.
256
257   :term:`Layer`
258      A collection of related recipes. Layers allow you to consolidate related
259      metadata to customize your build. Layers also isolate information used
260      when building for multiple architectures.  Layers are hierarchical in
261      their ability to override previous specifications. You can include any
262      number of available layers from the Yocto Project and customize the build
263      by adding your layers after them. You can search the Layer Index for
264      layers used within Yocto Project.
265
266      For introductory information on layers, see the
267      ":ref:`overview-manual/yp-intro:The Yocto Project Layer
268      Model`" section in the Yocto Project Overview and Concepts Manual. For
269      more detailed information on layers, see the
270      ":ref:`dev-manual/layers:Understanding and Creating
271      Layers`" section in the Yocto Project Development Tasks Manual. For a
272      discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
273      Layers`" section in the Yocto Project Board Support Packages (BSP)
274      Developer's Guide.
275
276   :term:`LTS`
277      This term means "Long Term Support", and in the context of the Yocto
278      Project, it corresponds to selected stable releases for which bug and
279      security fixes are provided for at least four years. See
280      the :ref:`ref-long-term-support-releases` section for details.
281
282   :term:`Metadata`
283      A key element of the Yocto Project is the Metadata that
284      is used to construct a Linux distribution and is contained in the
285      files that the :term:`OpenEmbedded Build System`
286      parses when building an image. In general, Metadata includes recipes,
287      configuration files, and other information that refers to the build
288      instructions themselves, as well as the data used to control what
289      things get built and the effects of the build. Metadata also includes
290      commands and data used to indicate what versions of software are
291      used, from where they are obtained, and changes or additions to the
292      software itself (patches or auxiliary files) that are used to fix
293      bugs or customize the software for use in a particular situation.
294      OpenEmbedded-Core is an important set of validated metadata.
295
296      In the context of the kernel ("kernel Metadata"), the term refers to
297      the kernel config fragments and features contained in the
298      :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
299      Git repository.
300
301   :term:`Mixin`
302      A :term:`Mixin` layer is a layer which can be created by the community to
303      add a specific feature or support a new version of some package for an
304      :term:`LTS` release. See the :ref:`ref-long-term-support-releases`
305      section for details.
306
307   :term:`OpenEmbedded-Core (OE-Core)`
308      OE-Core is metadata comprised of
309      foundational recipes, classes, and associated files that are meant to
310      be common among many different OpenEmbedded-derived systems,
311      including the Yocto Project. OE-Core is a curated subset of an
312      original repository developed by the OpenEmbedded community that has
313      been pared down into a smaller, core set of continuously validated
314      recipes. The result is a tightly controlled and an quality-assured
315      core set of recipes.
316
317      You can see the Metadata in the ``meta`` directory of the Yocto
318      Project :yocto_git:`Source Repositories </poky>`.
319
320   :term:`OpenEmbedded Build System`
321      The build system specific to the Yocto
322      Project. The OpenEmbedded build system is based on another project
323      known as "Poky", which uses :term:`BitBake` as the task
324      executor. Throughout the Yocto Project documentation set, the
325      OpenEmbedded build system is sometimes referred to simply as "the
326      build system". If other build systems, such as a host or target build
327      system are referenced, the documentation clearly states the
328      difference.
329
330      .. note::
331
332         For some historical information about Poky, see the :term:`Poky` term.
333
334   :term:`Package`
335      In the context of the Yocto Project, this term refers to a
336      recipe's packaged output produced by BitBake (i.e. a "baked recipe").
337      A package is generally the compiled binaries produced from the
338      recipe's sources. You "bake" something by running it through BitBake.
339
340      It is worth noting that the term "package" can, in general, have
341      subtle meanings. For example, the packages referred to in the
342      ":ref:`ref-manual/system-requirements:required packages for the build host`"
343      section are compiled binaries that, when installed, add functionality to
344      your Linux distribution.
345
346      Another point worth noting is that historically within the Yocto
347      Project, recipes were referred to as packages --- thus, the existence
348      of several BitBake variables that are seemingly mis-named, (e.g.
349      :term:`PR`, :term:`PV`, and
350      :term:`PE`).
351
352   :term:`Package Groups`
353      Arbitrary groups of software Recipes. You use
354      package groups to hold recipes that, when built, usually accomplish a
355      single task. For example, a package group could contain the recipes
356      for a company's proprietary or value-add software. Or, the package
357      group could contain the recipes that enable graphics. A package group
358      is really just another recipe. Because package group files are
359      recipes, they end with the ``.bb`` filename extension.
360
361   :term:`Poky`
362      Poky, which is pronounced *Pock*-ee, is a reference embedded
363      distribution and a reference test configuration. Poky provides the
364      following:
365
366      -  A base-level functional distro used to illustrate how to customize
367         a distribution.
368
369      -  A means by which to test the Yocto Project components (i.e. Poky
370         is used to validate the Yocto Project).
371
372      -  A vehicle through which you can download the Yocto Project.
373
374      Poky is not a product level distro. Rather, it is a good starting
375      point for customization.
376
377      .. note::
378
379         Poky began as an open-source project initially developed by
380         OpenedHand. OpenedHand developed Poky from the existing
381         OpenEmbedded build system to create a commercially supportable
382         build system for embedded Linux. After Intel Corporation acquired
383         OpenedHand, the poky project became the basis for the Yocto
384         Project's build system.
385
386   :term:`Recipe`
387      A set of instructions for building packages. A recipe
388      describes where you get source code, which patches to apply, how to
389      configure the source, how to compile it and so on. Recipes also
390      describe dependencies for libraries or for other recipes. Recipes
391      represent the logical unit of execution, the software to build, the
392      images to build, and use the ``.bb`` file extension.
393
394   :term:`Reference Kit`
395      A working example of a system, which includes a
396      :term:`BSP<Board Support Package (BSP)>` as well as a
397      :term:`build host<Build Host>` and other components, that can
398      work on specific hardware.
399
400   :term:`SBOM`
401      This term means *Software Bill of Materials*. When you distribute
402      software, it offers a description of all the components you used,
403      their corresponding licenses, their dependencies, the changes that were
404      applied and the known vulnerabilities that were fixed.
405
406      This can be used by the recipients of the software to assess
407      their exposure to license compliance and security vulnerability issues.
408
409      See the :wikipedia:`Software Supply Chain <Software_supply_chain>`
410      article on Wikipedia for more details.
411
412      The OpenEmbedded Build System can generate such documentation for your
413      project, in :term:`SPDX` format, based on all the metadata it used to
414      build the software images. See the ":ref:`dev-manual/sbom:creating
415      a software bill of materials`" section of the Development Tasks manual.
416
417   :term:`Source Directory`
418     This term refers to the directory structure
419     created as a result of creating a local copy of the ``poky`` Git
420     repository ``git://git.yoctoproject.org/poky`` or expanding a
421     released ``poky`` tarball.
422
423     .. note::
424
425        Creating a local copy of the
426        poky
427        Git repository is the recommended method for setting up your
428        Source Directory.
429
430     Sometimes you might hear the term "poky directory" used to refer to
431     this directory structure.
432
433     .. note::
434
435        The OpenEmbedded build system does not support file or directory
436        names that contain spaces. Be sure that the Source Directory you
437        use does not contain these types of names.
438
439     The Source Directory contains BitBake, Documentation, Metadata and
440     other files that all support the Yocto Project. Consequently, you
441     must have the Source Directory in place on your development system in
442     order to do any development using the Yocto Project.
443
444     When you create a local copy of the Git repository, you can name the
445     repository anything you like. Throughout much of the documentation,
446     "poky" is used as the name of the top-level folder of the local copy
447     of the poky Git repository. So, for example, cloning the ``poky`` Git
448     repository results in a local Git repository whose top-level folder
449     is also named "poky".
450
451     While it is not recommended that you use tarball extraction to set up
452     the Source Directory, if you do, the top-level directory name of the
453     Source Directory is derived from the Yocto Project release tarball.
454     For example, downloading and unpacking poky tarballs from
455     :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/`
456     results in a Source Directory whose root folder is named poky.
457
458
459     It is important to understand the differences between the Source
460     Directory created by unpacking a released tarball as compared to
461     cloning ``git://git.yoctoproject.org/poky``. When you unpack a
462     tarball, you have an exact copy of the files based on the time of
463     release --- a fixed release point. Any changes you make to your local
464     files in the Source Directory are on top of the release and will
465     remain local only. On the other hand, when you clone the ``poky`` Git
466     repository, you have an active development repository with access to
467     the upstream repository's branches and tags. In this case, any local
468     changes you make to the local Source Directory can be later applied
469     to active development branches of the upstream ``poky`` Git
470     repository.
471
472     For more information on concepts related to Git repositories,
473     branches, and tags, see the
474     ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
475     section in the Yocto Project Overview and Concepts Manual.
476
477   :term:`SPDX`
478      This term means *Software Package Data Exchange*, and is used as an open
479      standard for providing a *Software Bill of Materials* (:term:`SBOM`).
480      This standard is developed through a `Linux Foundation project
481      <https://spdx.dev/>`__ and is used by the OpenEmbedded Build System to
482      provide an :term:`SBOM` associated to each software image.
483
484      For details, see Wikipedia's :wikipedia:`SPDX page <Software_Package_Data_Exchange>`
485      and the ":ref:`dev-manual/sbom:creating a software bill of materials`"
486      section of the Development Tasks manual.
487
488   :term:`Sysroot`
489      When cross-compiling, the target file system may be differently laid
490      out and contain different things compared to the host system. The concept
491      of a *sysroot* is directory which looks like the target filesystem and
492      can be used to cross-compile against.
493
494      In the context of cross-compiling toolchains, a *sysroot*
495      typically contains C library and kernel headers, plus the
496      compiled binaries for the C library. A *multilib toolchain*
497      can contain multiple variants of the C library binaries,
498      each compiled for a target instruction set (such as ``armv5``,
499      ``armv7`` and ``armv8``), and possibly optimized for a specific CPU core.
500
501      In the more specific context of the OpenEmbedded build System and
502      of the Yocto Project, each recipe has two sysroots:
503
504      -  A *target sysroot* contains all the **target** libraries and headers
505         needed to build the recipe.
506
507      -  A *native sysroot* contains all the **host** files and executables
508         needed to build the recipe.
509
510      See the :term:`SYSROOT_* <SYSROOT_DESTDIR>` variables controlling
511      how sysroots are created and stored.
512
513   :term:`Task`
514      A per-recipe unit of execution for BitBake (e.g.
515      :ref:`ref-tasks-compile`,
516      :ref:`ref-tasks-fetch`,
517      :ref:`ref-tasks-patch`, and so forth).
518      One of the major benefits of the build system is that, since each
519      recipe will typically spawn the execution of numerous tasks,
520      it is entirely possible that many tasks can execute in parallel,
521      either tasks from separate recipes or independent tasks within
522      the same recipe, potentially up to the parallelism of your
523      build system.
524
525   :term:`Toaster`
526      A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
527      The interface enables you to
528      configure and run your builds. Information about builds is collected
529      and stored in a database. For information on Toaster, see the
530      :doc:`/toaster-manual/index`.
531
532   :term:`Upstream`
533      A reference to source code or repositories that are not
534      local to the development system but located in a remote area that is
535      controlled by the maintainer of the source code. For example, in
536      order for a developer to work on a particular piece of code, they
537      need to first get a copy of it from an "upstream" source.
538