blob: bf461488763b9f79ed5f56a0aacb5777429aa1b1 [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 Geissler09209ee2020-12-13 08:44:15 -060024 the ":ref:`dev-manual/common-tasks:Using .bbappend Files in
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025 Your Layer`" 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
32 busybox_1.21.%.bbappend
33
34 That append file
35 would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
36 the append file would match any of the following recipe names:
37
38 .. code-block:: shell
39
40 busybox_1.21.1.bb
41 busybox_1.21.2.bb
42 busybox_1.21.3.bb
43 busybox_1.21.10.bb
44 busybox_1.21.25.bb
45
46 .. note::
47
Andrew Geissler4c19ea12020-10-27 13:52:24 -050048 The use of the "%" character is limited in that it only works
Andrew Geisslerc9f78652020-09-18 14:11:35 -050049 directly in front of the .bbappend portion of the append file's
50 name. You cannot use the wildcard character in any other location of
51 the name.
52
Andrew Geissler4c19ea12020-10-27 13:52:24 -050053 :term:`BitBake`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050054 The task executor and scheduler used by the OpenEmbedded build system to
55 build images. For more information on BitBake, see the :doc:`BitBake User
56 Manual <bitbake:index>`.
57
Andrew Geissler4c19ea12020-10-27 13:52:24 -050058 :term:`Board Support Package (BSP)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059 A group of drivers, definitions, and other components that provide support
60 for a specific hardware configuration. For more information on BSPs, see
Andrew Geissler09209ee2020-12-13 08:44:15 -060061 the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
Andrew Geissler4c19ea12020-10-27 13:52:24 -050063 :term:`Build Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064 This term refers to the area used by the OpenEmbedded build system for
65 builds. The area is created when you ``source`` the setup environment
66 script that is found in the Source Directory
Andrew Geissler09209ee2020-12-13 08:44:15 -060067 (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068 :term:`TOPDIR` variable points to the Build Directory.
69
70 You have a lot of flexibility when creating the Build Directory.
71 Following are some examples that show how to create the directory. The
72 examples assume your :term:`Source Directory` is named ``poky``:
73
74 - Create the Build Directory inside your Source Directory and let
75 the name of the Build Directory default to ``build``:
76
77 .. code-block:: shell
78
79 $ cd $HOME/poky
80 $ source oe-init-build-env
81
82 - Create the Build Directory inside your home directory and
83 specifically name it ``test-builds``:
84
85 .. code-block:: shell
86
87 $ cd $HOME
88 $ source poky/oe-init-build-env test-builds
89
90 - Provide a directory path and specifically name the Build
91 Directory. Any intermediate folders in the pathname must exist.
92 This next example creates a Build Directory named
Andrew Geisslerd1e89492021-02-12 15:35:20 -060093 ``YP-&POKYVERSION;`` in your home directory within the existing
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094 directory ``mybuilds``:
95
96 .. code-block:: shell
97
98 $ cd $HOME
Andrew Geisslerd1e89492021-02-12 15:35:20 -060099 $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-&POKYVERSION;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100
101 .. note::
102
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500103 By default, the Build Directory contains :term:`TMPDIR`, which is a
104 temporary directory the build system uses for its work. ``TMPDIR`` cannot
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500105 be under NFS. Thus, by default, the Build Directory cannot be under
106 NFS. However, if you need the Build Directory to be under NFS, you can
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500107 set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local
108 drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109 Build Directory.
110
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500111 :term:`Build Host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112 The system used to build images in a Yocto Project Development
113 environment. The build system is sometimes referred to as the development
114 host.
115
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500116 :term:`Classes`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117 Files that provide for logic encapsulation and inheritance so that
118 commonly used patterns can be defined once and then easily used in
119 multiple recipes. For reference information on the Yocto Project classes,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600120 see the ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121 ``.bbclass`` filename extension.
122
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500123 :term:`Configuration File`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500124 Files that hold global definitions of variables, user-defined variables,
125 and hardware configuration information. These files tell the OpenEmbedded
126 build system what to build and what to put into the image to support a
127 particular platform.
128
129 Configuration files end with a ``.conf`` filename extension. The
130 :file:`conf/local.conf` configuration file in the :term:`Build Directory`
131 contains user-defined variables that affect every build. The
132 :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto
133 "distro" configuration variables used only when building with this
134 policy. Machine configuration files, which are located throughout the
135 :term:`Source Directory`, define variables for specific hardware and are
136 only used when building for that target (e.g. the
137 :file:`machine/beaglebone.conf` configuration file defines variables for
138 the Texas Instruments ARM Cortex-A8 development board).
139
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500140 :term:`Container Layer`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141 Layers that hold other layers. An example of a container layer is
142 OpenEmbedded's `meta-openembedded
143 <https://github.com/openembedded/meta-openembedded>`_ layer. The
144 ``meta-openembedded`` layer contains many ``meta-*`` layers.
145
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500146 :term:`Cross-Development Toolchain`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500147 In general, a cross-development toolchain is a collection of software
148 development tools and utilities that run on one architecture and allow you
149 to develop software for a different, or targeted, architecture. These
150 toolchains contain cross-compilers, linkers, and debuggers that are
151 specific to the target architecture.
152
153 The Yocto Project supports two different cross-development toolchains:
154
155 - A toolchain only used by and within BitBake when building an image for a
156 target architecture.
157
158 - A relocatable toolchain used outside of BitBake by developers when
159 developing applications that will run on a targeted device.
160
161 Creation of these toolchains is simple and automated. For information on
162 toolchain concepts as they apply to the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600163 ":ref:`overview-manual/concepts:Cross-Development
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164 Toolchain Generation`" section in the Yocto Project Overview and Concepts
165 Manual. You can also find more information on using the relocatable
Andrew Geissler09209ee2020-12-13 08:44:15 -0600166 toolchain in the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500167
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500168 :term:`Extensible Software Development Kit (eSDK)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169 A custom SDK for application developers. This eSDK allows developers to
170 incorporate their library and programming changes back into the image to
171 make their code available to other application developers.
172
Andrew Geissler09209ee2020-12-13 08:44:15 -0600173 For information on the eSDK, see the :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500174
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500175 :term:`Image`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500176 An image is an artifact of the BitBake build process given a collection of
177 recipes and related Metadata. Images are the binary output that run on
178 specific hardware or QEMU and are used for specific use-cases. For a list
179 of the supported image types that the Yocto Project provides, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600180 ":ref:`ref-manual/images:Images`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500182 :term:`Layer`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183 A collection of related recipes. Layers allow you to consolidate related
184 metadata to customize your build. Layers also isolate information used
185 when building for multiple architectures. Layers are hierarchical in
186 their ability to override previous specifications. You can include any
187 number of available layers from the Yocto Project and customize the build
188 by adding your layers after them. You can search the Layer Index for
189 layers used within Yocto Project.
190
191 For introductory information on layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600192 ":ref:`overview-manual/yp-intro:The Yocto Project Layer
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193 Model`" section in the Yocto Project Overview and Concepts Manual. For
194 more detailed information on layers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600195 ":ref:`dev-manual/common-tasks:Understanding and Creating
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196 Layers`" section in the Yocto Project Development Tasks Manual. For a
197 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
198 Layers`" section in the Yocto Project Board Support Packages (BSP)
199 Developer's Guide.
200
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500201 :term:`Metadata`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202 A key element of the Yocto Project is the Metadata that
203 is used to construct a Linux distribution and is contained in the
204 files that the :term:`OpenEmbedded Build System`
205 parses when building an image. In general, Metadata includes recipes,
206 configuration files, and other information that refers to the build
207 instructions themselves, as well as the data used to control what
208 things get built and the effects of the build. Metadata also includes
209 commands and data used to indicate what versions of software are
210 used, from where they are obtained, and changes or additions to the
211 software itself (patches or auxiliary files) that are used to fix
212 bugs or customize the software for use in a particular situation.
213 OpenEmbedded-Core is an important set of validated metadata.
214
215 In the context of the kernel ("kernel Metadata"), the term refers to
216 the kernel config fragments and features contained in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600217 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218 Git repository.
219
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500220 :term:`OpenEmbedded-Core (OE-Core)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221 OE-Core is metadata comprised of
222 foundational recipes, classes, and associated files that are meant to
223 be common among many different OpenEmbedded-derived systems,
224 including the Yocto Project. OE-Core is a curated subset of an
225 original repository developed by the OpenEmbedded community that has
226 been pared down into a smaller, core set of continuously validated
227 recipes. The result is a tightly controlled and an quality-assured
228 core set of recipes.
229
230 You can see the Metadata in the ``meta`` directory of the Yocto
Andrew Geissler09209ee2020-12-13 08:44:15 -0600231 Project :yocto_git:`Source Repositories </poky>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500232
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500233 :term:`OpenEmbedded Build System`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234 The build system specific to the Yocto
235 Project. The OpenEmbedded build system is based on another project
236 known as "Poky", which uses :term:`BitBake` as the task
237 executor. Throughout the Yocto Project documentation set, the
238 OpenEmbedded build system is sometimes referred to simply as "the
239 build system". If other build systems, such as a host or target build
240 system are referenced, the documentation clearly states the
241 difference.
242
243 .. note::
244
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500245 For some historical information about Poky, see the :term:`Poky` term.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500247 :term:`Package`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248 In the context of the Yocto Project, this term refers to a
249 recipe's packaged output produced by BitBake (i.e. a "baked recipe").
250 A package is generally the compiled binaries produced from the
251 recipe's sources. You "bake" something by running it through BitBake.
252
253 It is worth noting that the term "package" can, in general, have
254 subtle meanings. For example, the packages referred to in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600255 ":ref:`ref-manual/system-requirements:required packages for the build host`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500256 section are compiled binaries that, when installed, add functionality to
257 your Linux distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500258
259 Another point worth noting is that historically within the Yocto
260 Project, recipes were referred to as packages - thus, the existence
261 of several BitBake variables that are seemingly mis-named, (e.g.
262 :term:`PR`, :term:`PV`, and
263 :term:`PE`).
264
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500265 :term:`Package Groups`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500266 Arbitrary groups of software Recipes. You use
267 package groups to hold recipes that, when built, usually accomplish a
268 single task. For example, a package group could contain the recipes
269 for a company's proprietary or value-add software. Or, the package
270 group could contain the recipes that enable graphics. A package group
271 is really just another recipe. Because package group files are
272 recipes, they end with the ``.bb`` filename extension.
273
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500274 :term:`Poky`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500275 Poky, which is pronounced *Pock*-ee, is a reference embedded
276 distribution and a reference test configuration. Poky provides the
277 following:
278
279 - A base-level functional distro used to illustrate how to customize
280 a distribution.
281
282 - A means by which to test the Yocto Project components (i.e. Poky
283 is used to validate the Yocto Project).
284
285 - A vehicle through which you can download the Yocto Project.
286
287 Poky is not a product level distro. Rather, it is a good starting
288 point for customization.
289
290 .. note::
291
292 Poky began as an open-source project initially developed by
293 OpenedHand. OpenedHand developed Poky from the existing
294 OpenEmbedded build system to create a commercially supportable
295 build system for embedded Linux. After Intel Corporation acquired
296 OpenedHand, the poky project became the basis for the Yocto
297 Project's build system.
298
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500299 :term:`Recipe`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500300 A set of instructions for building packages. A recipe
301 describes where you get source code, which patches to apply, how to
302 configure the source, how to compile it and so on. Recipes also
303 describe dependencies for libraries or for other recipes. Recipes
304 represent the logical unit of execution, the software to build, the
305 images to build, and use the ``.bb`` file extension.
306
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500307 :term:`Reference Kit`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500308 A working example of a system, which includes a
309 :term:`BSP<Board Support Package (BSP)>` as well as a
310 :term:`build host<Build Host>` and other components, that can
311 work on specific hardware.
312
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500313 :term:`Source Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500314 This term refers to the directory structure
315 created as a result of creating a local copy of the ``poky`` Git
316 repository ``git://git.yoctoproject.org/poky`` or expanding a
317 released ``poky`` tarball.
318
319 .. note::
320
321 Creating a local copy of the
322 poky
323 Git repository is the recommended method for setting up your
324 Source Directory.
325
326 Sometimes you might hear the term "poky directory" used to refer to
327 this directory structure.
328
329 .. note::
330
331 The OpenEmbedded build system does not support file or directory
332 names that contain spaces. Be sure that the Source Directory you
333 use does not contain these types of names.
334
335 The Source Directory contains BitBake, Documentation, Metadata and
336 other files that all support the Yocto Project. Consequently, you
337 must have the Source Directory in place on your development system in
338 order to do any development using the Yocto Project.
339
340 When you create a local copy of the Git repository, you can name the
341 repository anything you like. Throughout much of the documentation,
342 "poky" is used as the name of the top-level folder of the local copy
343 of the poky Git repository. So, for example, cloning the ``poky`` Git
344 repository results in a local Git repository whose top-level folder
345 is also named "poky".
346
347 While it is not recommended that you use tarball expansion to set up
348 the Source Directory, if you do, the top-level directory name of the
349 Source Directory is derived from the Yocto Project release tarball.
350 For example, downloading and unpacking
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500351 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600352 results in a Source Directory whose root folder is named
353 ``&YOCTO_POKY;``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500354
355 It is important to understand the differences between the Source
356 Directory created by unpacking a released tarball as compared to
357 cloning ``git://git.yoctoproject.org/poky``. When you unpack a
358 tarball, you have an exact copy of the files based on the time of
359 release - a fixed release point. Any changes you make to your local
360 files in the Source Directory are on top of the release and will
361 remain local only. On the other hand, when you clone the ``poky`` Git
362 repository, you have an active development repository with access to
363 the upstream repository's branches and tags. In this case, any local
364 changes you make to the local Source Directory can be later applied
365 to active development branches of the upstream ``poky`` Git
366 repository.
367
368 For more information on concepts related to Git repositories,
369 branches, and tags, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600370 ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500371 section in the Yocto Project Overview and Concepts Manual.
372
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500373 :term:`Task`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500374 A unit of execution for BitBake (e.g.
375 :ref:`ref-tasks-compile`,
376 :ref:`ref-tasks-fetch`,
377 :ref:`ref-tasks-patch`, and so forth).
378
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500379 :term:`Toaster`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500380 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
381 The interface enables you to
382 configure and run your builds. Information about builds is collected
383 and stored in a database. For information on Toaster, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600384 :doc:`/toaster-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500386 :term:`Upstream`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500387 A reference to source code or repositories that are not
388 local to the development system but located in a master area that is
389 controlled by the maintainer of the source code. For example, in
390 order for a developer to work on a particular piece of code, they
391 need to first get a copy of it from an "upstream" source.