blob: cba514c3454987e8abecfbef52dbf56aad8457e3 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050013 :term:`Append Files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050014 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
Andrew Geisslerd159c7f2021-09-02 21:05:58 -050024 the ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
25 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050026
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
Andrew Geisslerc926e172021-05-07 16:11:35 -050029 append file named as follows::
Andrew Geissler95ac1b82021-03-31 14:34:31 -050030
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031 busybox_1.21.%.bbappend
32
33 That append file
Andrew Geisslereff27472021-10-29 15:35:00 -050034 would match any ``busybox_1.21.x.bb`` version of the recipe. So,
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050047 The use of the "%" character is limited in that it only works
Andrew Geisslerc9f78652020-09-18 14:11:35 -050048 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050052 :term:`BitBake`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050057 :term:`Board Support Package (BSP)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058 A group of drivers, definitions, and other components that provide support
59 for a specific hardware configuration. For more information on BSPs, see
Andrew Geissler09209ee2020-12-13 08:44:15 -060060 the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061
Andrew Geissler4c19ea12020-10-27 13:52:24 -050062 :term:`Build Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050063 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060066 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
Andrew Geisslerc9f78652020-09-18 14:11:35 -050067 :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
Andrew Geissler95ac1b82021-03-31 14:34:31 -050078 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079 $ 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086 $ 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
Andrew Geissler9aee5002022-03-30 16:27:02 +000091 ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092
93 .. code-block:: shell
94
Andrew Geissler9aee5002022-03-30 16:27:02 +000095 $ source poky/oe-init-build-env mybuilds/YP-&DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096
97 .. note::
98
Andrew Geissler4c19ea12020-10-27 13:52:24 -050099 By default, the Build Directory contains :term:`TMPDIR`, which is a
Andrew Geissler09036742021-06-25 14:25:14 -0500100 temporary directory the build system uses for its work. :term:`TMPDIR` cannot
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101 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
Andrew Geissler09036742021-06-25 14:25:14 -0500103 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500105 Build Directory.
106
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500107 :term:`Build Host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500112 :term:`Classes`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113 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,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600116 see the ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117 ``.bbclass`` filename extension.
118
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500119 :term:`Configuration File`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500136 :term:`Container Layer`
Andrew Geissler595f6302022-01-24 19:11:47 +0000137 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
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000151 :yocto_git:`meta-security </meta-security>`)
Andrew Geissler595f6302022-01-24 19:11:47 +0000152 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.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500159 :term:`Cross-Development Toolchain`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600176 ":ref:`overview-manual/concepts:Cross-Development
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177 Toolchain Generation`" section in the Yocto Project Overview and Concepts
178 Manual. You can also find more information on using the relocatable
Andrew Geissler09209ee2020-12-13 08:44:15 -0600179 toolchain in the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500180
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500181 :term:`Extensible Software Development Kit (eSDK)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600186 For information on the eSDK, see the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500188 :term:`Image`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600193 ":ref:`ref-manual/images:Images`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500195 :term:`Layer`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600205 ":ref:`overview-manual/yp-intro:The Yocto Project Layer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206 Model`" section in the Yocto Project Overview and Concepts Manual. For
207 more detailed information on layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600208 ":ref:`dev-manual/common-tasks:Understanding and Creating
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500214 :term:`Metadata`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600230 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231 Git repository.
232
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500233 :term:`OpenEmbedded-Core (OE-Core)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600244 Project :yocto_git:`Source Repositories </poky>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500245
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500246 :term:`OpenEmbedded Build System`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500247 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500258 For some historical information about Poky, see the :term:`Poky` term.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500259
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500260 :term:`Package`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600268 ":ref:`ref-manual/system-requirements:required packages for the build host`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500269 section are compiled binaries that, when installed, add functionality to
270 your Linux distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500278 :term:`Package Groups`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500287 :term:`Poky`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500312 :term:`Recipe`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500313 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500320 :term:`Reference Kit`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500321 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500326 :term:`Source Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327 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
Andrew Geissler9aee5002022-03-30 16:27:02 +0000360 While it is not recommended that you use tarball extraction to set up
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500361 the Source Directory, if you do, the top-level directory name of the
362 Source Directory is derived from the Yocto Project release tarball.
Andrew Geissler9aee5002022-03-30 16:27:02 +0000363 For example, downloading and unpacking poky tarballs from
364 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/`
365 results in a Source Directory whose root folder is named poky.
366
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500367
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600383 ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500384 section in the Yocto Project Overview and Concepts Manual.
385
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500386 :term:`Task`
Andrew Geissler5199d832021-09-24 16:47:35 -0500387 A per-recipe unit of execution for BitBake (e.g.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388 :ref:`ref-tasks-compile`,
389 :ref:`ref-tasks-fetch`,
390 :ref:`ref-tasks-patch`, and so forth).
Andrew Geissler5199d832021-09-24 16:47:35 -0500391 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.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500398 :term:`Toaster`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500399 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600403 :doc:`/toaster-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500405 :term:`Upstream`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500406 A reference to source code or repositories that are not
Andrew Geissler595f6302022-01-24 19:11:47 +0000407 local to the development system but located in a remote area that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500408 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.