blob: 32658051a591c8042802a478d55dd52181f1c8ad [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
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
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 Geissler95ac1b82021-03-31 14:34:31 -050091 ``YP-&POKYVERSION;`` within the existing directory ``mybuilds``:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092
93 .. code-block:: shell
94
Andrew Geissler95ac1b82021-03-31 14:34:31 -050095 $ source poky/oe-init-build-env mybuilds/YP-&POKYVERSION;
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 Geisslerc9f78652020-09-18 14:11:35 -0500137 Layers that hold other layers. An example of a container layer is
138 OpenEmbedded's `meta-openembedded
139 <https://github.com/openembedded/meta-openembedded>`_ layer. The
140 ``meta-openembedded`` layer contains many ``meta-*`` layers.
141
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500142 :term:`Cross-Development Toolchain`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500143 In general, a cross-development toolchain is a collection of software
144 development tools and utilities that run on one architecture and allow you
145 to develop software for a different, or targeted, architecture. These
146 toolchains contain cross-compilers, linkers, and debuggers that are
147 specific to the target architecture.
148
149 The Yocto Project supports two different cross-development toolchains:
150
151 - A toolchain only used by and within BitBake when building an image for a
152 target architecture.
153
154 - A relocatable toolchain used outside of BitBake by developers when
155 developing applications that will run on a targeted device.
156
157 Creation of these toolchains is simple and automated. For information on
158 toolchain concepts as they apply to the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600159 ":ref:`overview-manual/concepts:Cross-Development
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160 Toolchain Generation`" section in the Yocto Project Overview and Concepts
161 Manual. You can also find more information on using the relocatable
Andrew Geissler09209ee2020-12-13 08:44:15 -0600162 toolchain in the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500164 :term:`Extensible Software Development Kit (eSDK)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500165 A custom SDK for application developers. This eSDK allows developers to
166 incorporate their library and programming changes back into the image to
167 make their code available to other application developers.
168
Andrew Geissler09209ee2020-12-13 08:44:15 -0600169 For information on the eSDK, see the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500170
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500171 :term:`Image`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500172 An image is an artifact of the BitBake build process given a collection of
173 recipes and related Metadata. Images are the binary output that run on
174 specific hardware or QEMU and are used for specific use-cases. For a list
175 of the supported image types that the Yocto Project provides, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600176 ":ref:`ref-manual/images:Images`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500178 :term:`Layer`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179 A collection of related recipes. Layers allow you to consolidate related
180 metadata to customize your build. Layers also isolate information used
181 when building for multiple architectures. Layers are hierarchical in
182 their ability to override previous specifications. You can include any
183 number of available layers from the Yocto Project and customize the build
184 by adding your layers after them. You can search the Layer Index for
185 layers used within Yocto Project.
186
187 For introductory information on layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600188 ":ref:`overview-manual/yp-intro:The Yocto Project Layer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189 Model`" section in the Yocto Project Overview and Concepts Manual. For
190 more detailed information on layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600191 ":ref:`dev-manual/common-tasks:Understanding and Creating
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500192 Layers`" section in the Yocto Project Development Tasks Manual. For a
193 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
194 Layers`" section in the Yocto Project Board Support Packages (BSP)
195 Developer's Guide.
196
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500197 :term:`Metadata`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198 A key element of the Yocto Project is the Metadata that
199 is used to construct a Linux distribution and is contained in the
200 files that the :term:`OpenEmbedded Build System`
201 parses when building an image. In general, Metadata includes recipes,
202 configuration files, and other information that refers to the build
203 instructions themselves, as well as the data used to control what
204 things get built and the effects of the build. Metadata also includes
205 commands and data used to indicate what versions of software are
206 used, from where they are obtained, and changes or additions to the
207 software itself (patches or auxiliary files) that are used to fix
208 bugs or customize the software for use in a particular situation.
209 OpenEmbedded-Core is an important set of validated metadata.
210
211 In the context of the kernel ("kernel Metadata"), the term refers to
212 the kernel config fragments and features contained in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600213 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214 Git repository.
215
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500216 :term:`OpenEmbedded-Core (OE-Core)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217 OE-Core is metadata comprised of
218 foundational recipes, classes, and associated files that are meant to
219 be common among many different OpenEmbedded-derived systems,
220 including the Yocto Project. OE-Core is a curated subset of an
221 original repository developed by the OpenEmbedded community that has
222 been pared down into a smaller, core set of continuously validated
223 recipes. The result is a tightly controlled and an quality-assured
224 core set of recipes.
225
226 You can see the Metadata in the ``meta`` directory of the Yocto
Andrew Geissler09209ee2020-12-13 08:44:15 -0600227 Project :yocto_git:`Source Repositories </poky>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500229 :term:`OpenEmbedded Build System`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230 The build system specific to the Yocto
231 Project. The OpenEmbedded build system is based on another project
232 known as "Poky", which uses :term:`BitBake` as the task
233 executor. Throughout the Yocto Project documentation set, the
234 OpenEmbedded build system is sometimes referred to simply as "the
235 build system". If other build systems, such as a host or target build
236 system are referenced, the documentation clearly states the
237 difference.
238
239 .. note::
240
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500241 For some historical information about Poky, see the :term:`Poky` term.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500243 :term:`Package`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244 In the context of the Yocto Project, this term refers to a
245 recipe's packaged output produced by BitBake (i.e. a "baked recipe").
246 A package is generally the compiled binaries produced from the
247 recipe's sources. You "bake" something by running it through BitBake.
248
249 It is worth noting that the term "package" can, in general, have
250 subtle meanings. For example, the packages referred to in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600251 ":ref:`ref-manual/system-requirements:required packages for the build host`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500252 section are compiled binaries that, when installed, add functionality to
253 your Linux distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
255 Another point worth noting is that historically within the Yocto
256 Project, recipes were referred to as packages - thus, the existence
257 of several BitBake variables that are seemingly mis-named, (e.g.
258 :term:`PR`, :term:`PV`, and
259 :term:`PE`).
260
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500261 :term:`Package Groups`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500262 Arbitrary groups of software Recipes. You use
263 package groups to hold recipes that, when built, usually accomplish a
264 single task. For example, a package group could contain the recipes
265 for a company's proprietary or value-add software. Or, the package
266 group could contain the recipes that enable graphics. A package group
267 is really just another recipe. Because package group files are
268 recipes, they end with the ``.bb`` filename extension.
269
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500270 :term:`Poky`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271 Poky, which is pronounced *Pock*-ee, is a reference embedded
272 distribution and a reference test configuration. Poky provides the
273 following:
274
275 - A base-level functional distro used to illustrate how to customize
276 a distribution.
277
278 - A means by which to test the Yocto Project components (i.e. Poky
279 is used to validate the Yocto Project).
280
281 - A vehicle through which you can download the Yocto Project.
282
283 Poky is not a product level distro. Rather, it is a good starting
284 point for customization.
285
286 .. note::
287
288 Poky began as an open-source project initially developed by
289 OpenedHand. OpenedHand developed Poky from the existing
290 OpenEmbedded build system to create a commercially supportable
291 build system for embedded Linux. After Intel Corporation acquired
292 OpenedHand, the poky project became the basis for the Yocto
293 Project's build system.
294
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500295 :term:`Recipe`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296 A set of instructions for building packages. A recipe
297 describes where you get source code, which patches to apply, how to
298 configure the source, how to compile it and so on. Recipes also
299 describe dependencies for libraries or for other recipes. Recipes
300 represent the logical unit of execution, the software to build, the
301 images to build, and use the ``.bb`` file extension.
302
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500303 :term:`Reference Kit`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304 A working example of a system, which includes a
305 :term:`BSP<Board Support Package (BSP)>` as well as a
306 :term:`build host<Build Host>` and other components, that can
307 work on specific hardware.
308
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500309 :term:`Source Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500310 This term refers to the directory structure
311 created as a result of creating a local copy of the ``poky`` Git
312 repository ``git://git.yoctoproject.org/poky`` or expanding a
313 released ``poky`` tarball.
314
315 .. note::
316
317 Creating a local copy of the
318 poky
319 Git repository is the recommended method for setting up your
320 Source Directory.
321
322 Sometimes you might hear the term "poky directory" used to refer to
323 this directory structure.
324
325 .. note::
326
327 The OpenEmbedded build system does not support file or directory
328 names that contain spaces. Be sure that the Source Directory you
329 use does not contain these types of names.
330
331 The Source Directory contains BitBake, Documentation, Metadata and
332 other files that all support the Yocto Project. Consequently, you
333 must have the Source Directory in place on your development system in
334 order to do any development using the Yocto Project.
335
336 When you create a local copy of the Git repository, you can name the
337 repository anything you like. Throughout much of the documentation,
338 "poky" is used as the name of the top-level folder of the local copy
339 of the poky Git repository. So, for example, cloning the ``poky`` Git
340 repository results in a local Git repository whose top-level folder
341 is also named "poky".
342
343 While it is not recommended that you use tarball expansion to set up
344 the Source Directory, if you do, the top-level directory name of the
345 Source Directory is derived from the Yocto Project release tarball.
346 For example, downloading and unpacking
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500347 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600348 results in a Source Directory whose root folder is named
349 ``&YOCTO_POKY;``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500350
351 It is important to understand the differences between the Source
352 Directory created by unpacking a released tarball as compared to
353 cloning ``git://git.yoctoproject.org/poky``. When you unpack a
354 tarball, you have an exact copy of the files based on the time of
355 release - a fixed release point. Any changes you make to your local
356 files in the Source Directory are on top of the release and will
357 remain local only. On the other hand, when you clone the ``poky`` Git
358 repository, you have an active development repository with access to
359 the upstream repository's branches and tags. In this case, any local
360 changes you make to the local Source Directory can be later applied
361 to active development branches of the upstream ``poky`` Git
362 repository.
363
364 For more information on concepts related to Git repositories,
365 branches, and tags, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600366 ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500367 section in the Yocto Project Overview and Concepts Manual.
368
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500369 :term:`Task`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370 A unit of execution for BitBake (e.g.
371 :ref:`ref-tasks-compile`,
372 :ref:`ref-tasks-fetch`,
373 :ref:`ref-tasks-patch`, and so forth).
374
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500375 :term:`Toaster`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500376 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
377 The interface enables you to
378 configure and run your builds. Information about builds is collected
379 and stored in a database. For information on Toaster, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600380 :doc:`/toaster-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500381
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500382 :term:`Upstream`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500383 A reference to source code or repositories that are not
384 local to the development system but located in a master area that is
385 controlled by the maintainer of the source code. For example, in
386 order for a developer to work on a particular piece of code, they
387 need to first get a copy of it from an "upstream" source.