blob: 556bc6b19734cfd3ceda9ad5d9b8b7df2a0b25e7 [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
13 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/dev-manual-common-tasks:Using .bbappend Files in
25 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
48 The use of the " % " character is limited in that it only works
49 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
53 BitBake
54 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
58 Board Support Package (BSP)
59 A group of drivers, definitions, and other components that provide support
60 for a specific hardware configuration. For more information on BSPs, see
61 the :ref:`bsp-guide/bsp-guide:Yocto Project Board Support Package
62 Developer's Guide`.
63
64 Build Directory
65 This term refers to the area used by the OpenEmbedded build system for
66 builds. The area is created when you ``source`` the setup environment
67 script that is found in the Source Directory
68 (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``). The
69 :term:`TOPDIR` variable points to the Build Directory.
70
71 You have a lot of flexibility when creating the Build Directory.
72 Following are some examples that show how to create the directory. The
73 examples assume your :term:`Source Directory` is named ``poky``:
74
75 - Create the Build Directory inside your Source Directory and let
76 the name of the Build Directory default to ``build``:
77
78 .. code-block:: shell
79
80 $ cd $HOME/poky
81 $ source oe-init-build-env
82
83 - Create the Build Directory inside your home directory and
84 specifically name it ``test-builds``:
85
86 .. code-block:: shell
87
88 $ cd $HOME
89 $ source poky/oe-init-build-env test-builds
90
91 - Provide a directory path and specifically name the Build
92 Directory. Any intermediate folders in the pathname must exist.
93 This next example creates a Build Directory named
94 ``YP-POKYVERSION`` in your home directory within the existing
95 directory ``mybuilds``:
96
97 .. code-block:: shell
98
99 $ cd $HOME
100 $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION
101
102 .. note::
103
104 By default, the Build Directory contains :term:`TMPDIR` , which is a
105 temporary directory the build system uses for its work. TMPDIR cannot
106 be under NFS. Thus, by default, the Build Directory cannot be under
107 NFS. However, if you need the Build Directory to be under NFS, you can
108 set this up by setting TMPDIR in your local.conf file to use a local
109 drive. Doing so effectively separates TMPDIR from TOPDIR , which is the
110 Build Directory.
111
112 Build Host
113 The system used to build images in a Yocto Project Development
114 environment. The build system is sometimes referred to as the development
115 host.
116
117 Classes
118 Files that provide for logic encapsulation and inheritance so that
119 commonly used patterns can be defined once and then easily used in
120 multiple recipes. For reference information on the Yocto Project classes,
121 see the ":ref:`ref-manual/ref-classes:Classes`" chapter. Class files end with the
122 ``.bbclass`` filename extension.
123
124 Configuration File
125 Files that hold global definitions of variables, user-defined variables,
126 and hardware configuration information. These files tell the OpenEmbedded
127 build system what to build and what to put into the image to support a
128 particular platform.
129
130 Configuration files end with a ``.conf`` filename extension. The
131 :file:`conf/local.conf` configuration file in the :term:`Build Directory`
132 contains user-defined variables that affect every build. The
133 :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto
134 "distro" configuration variables used only when building with this
135 policy. Machine configuration files, which are located throughout the
136 :term:`Source Directory`, define variables for specific hardware and are
137 only used when building for that target (e.g. the
138 :file:`machine/beaglebone.conf` configuration file defines variables for
139 the Texas Instruments ARM Cortex-A8 development board).
140
141 Container Layer
142 Layers that hold other layers. An example of a container layer is
143 OpenEmbedded's `meta-openembedded
144 <https://github.com/openembedded/meta-openembedded>`_ layer. The
145 ``meta-openembedded`` layer contains many ``meta-*`` layers.
146
147 Cross-Development Toolchain
148 In general, a cross-development toolchain is a collection of software
149 development tools and utilities that run on one architecture and allow you
150 to develop software for a different, or targeted, architecture. These
151 toolchains contain cross-compilers, linkers, and debuggers that are
152 specific to the target architecture.
153
154 The Yocto Project supports two different cross-development toolchains:
155
156 - A toolchain only used by and within BitBake when building an image for a
157 target architecture.
158
159 - A relocatable toolchain used outside of BitBake by developers when
160 developing applications that will run on a targeted device.
161
162 Creation of these toolchains is simple and automated. For information on
163 toolchain concepts as they apply to the Yocto Project, see the
164 ":ref:`overview-manual/overview-manual-concepts:Cross-Development
165 Toolchain Generation`" section in the Yocto Project Overview and Concepts
166 Manual. You can also find more information on using the relocatable
167 toolchain in the :ref:`sdk-manual/sdk-manual:Yocto Project Application
168 Development and the Extensible Software Development Kit (eSDK)` manual.
169
170 Extensible Software Development Kit (eSDK)
171 A custom SDK for application developers. This eSDK allows developers to
172 incorporate their library and programming changes back into the image to
173 make their code available to other application developers.
174
175 For information on the eSDK, see the :ref:`sdk-manual/sdk-manual:Yocto
176 Project Application Development and the Extensible Software Development
177 Kit (eSDK)` manual.
178
179 Image
180 An image is an artifact of the BitBake build process given a collection of
181 recipes and related Metadata. Images are the binary output that run on
182 specific hardware or QEMU and are used for specific use-cases. For a list
183 of the supported image types that the Yocto Project provides, see the
184 ":ref:`ref-manual/ref-images:Images`" chapter.
185
186 Layer
187 A collection of related recipes. Layers allow you to consolidate related
188 metadata to customize your build. Layers also isolate information used
189 when building for multiple architectures. Layers are hierarchical in
190 their ability to override previous specifications. You can include any
191 number of available layers from the Yocto Project and customize the build
192 by adding your layers after them. You can search the Layer Index for
193 layers used within Yocto Project.
194
195 For introductory information on layers, see the
196 ":ref:`overview-manual/overview-manual-yp-intro:The Yocto Project Layer
197 Model`" section in the Yocto Project Overview and Concepts Manual. For
198 more detailed information on layers, see the
199 ":ref:`dev-manual/dev-manual-common-tasks:Understanding and Creating
200 Layers`" section in the Yocto Project Development Tasks Manual. For a
201 discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
202 Layers`" section in the Yocto Project Board Support Packages (BSP)
203 Developer's Guide.
204
205 Metadata
206 A key element of the Yocto Project is the Metadata that
207 is used to construct a Linux distribution and is contained in the
208 files that the :term:`OpenEmbedded Build System`
209 parses when building an image. In general, Metadata includes recipes,
210 configuration files, and other information that refers to the build
211 instructions themselves, as well as the data used to control what
212 things get built and the effects of the build. Metadata also includes
213 commands and data used to indicate what versions of software are
214 used, from where they are obtained, and changes or additions to the
215 software itself (patches or auxiliary files) that are used to fix
216 bugs or customize the software for use in a particular situation.
217 OpenEmbedded-Core is an important set of validated metadata.
218
219 In the context of the kernel ("kernel Metadata"), the term refers to
220 the kernel config fragments and features contained in the
221 :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache>`
222 Git repository.
223
224 OpenEmbedded-Core (OE-Core)
225 OE-Core is metadata comprised of
226 foundational recipes, classes, and associated files that are meant to
227 be common among many different OpenEmbedded-derived systems,
228 including the Yocto Project. OE-Core is a curated subset of an
229 original repository developed by the OpenEmbedded community that has
230 been pared down into a smaller, core set of continuously validated
231 recipes. The result is a tightly controlled and an quality-assured
232 core set of recipes.
233
234 You can see the Metadata in the ``meta`` directory of the Yocto
235 Project :yocto_git:`Source Repositories <>`.
236
237 OpenEmbedded Build System
238 The build system specific to the Yocto
239 Project. The OpenEmbedded build system is based on another project
240 known as "Poky", which uses :term:`BitBake` as the task
241 executor. Throughout the Yocto Project documentation set, the
242 OpenEmbedded build system is sometimes referred to simply as "the
243 build system". If other build systems, such as a host or target build
244 system are referenced, the documentation clearly states the
245 difference.
246
247 .. note::
248
249 For some historical information about Poky, see the
250 Poky
251 term.
252
253 Package
254 In the context of the Yocto Project, this term refers to a
255 recipe's packaged output produced by BitBake (i.e. a "baked recipe").
256 A package is generally the compiled binaries produced from the
257 recipe's sources. You "bake" something by running it through BitBake.
258
259 It is worth noting that the term "package" can, in general, have
260 subtle meanings. For example, the packages referred to in the
261 "`Required Packages for the Build
262 Host <#required-packages-for-the-build-host>`__" section are compiled
263 binaries that, when installed, add functionality to your Linux
264 distribution.
265
266 Another point worth noting is that historically within the Yocto
267 Project, recipes were referred to as packages - thus, the existence
268 of several BitBake variables that are seemingly mis-named, (e.g.
269 :term:`PR`, :term:`PV`, and
270 :term:`PE`).
271
272 Package Groups
273 Arbitrary groups of software Recipes. You use
274 package groups to hold recipes that, when built, usually accomplish a
275 single task. For example, a package group could contain the recipes
276 for a company's proprietary or value-add software. Or, the package
277 group could contain the recipes that enable graphics. A package group
278 is really just another recipe. Because package group files are
279 recipes, they end with the ``.bb`` filename extension.
280
281 Poky
282 Poky, which is pronounced *Pock*-ee, is a reference embedded
283 distribution and a reference test configuration. Poky provides the
284 following:
285
286 - A base-level functional distro used to illustrate how to customize
287 a distribution.
288
289 - A means by which to test the Yocto Project components (i.e. Poky
290 is used to validate the Yocto Project).
291
292 - A vehicle through which you can download the Yocto Project.
293
294 Poky is not a product level distro. Rather, it is a good starting
295 point for customization.
296
297 .. note::
298
299 Poky began as an open-source project initially developed by
300 OpenedHand. OpenedHand developed Poky from the existing
301 OpenEmbedded build system to create a commercially supportable
302 build system for embedded Linux. After Intel Corporation acquired
303 OpenedHand, the poky project became the basis for the Yocto
304 Project's build system.
305
306 Recipe
307 A set of instructions for building packages. A recipe
308 describes where you get source code, which patches to apply, how to
309 configure the source, how to compile it and so on. Recipes also
310 describe dependencies for libraries or for other recipes. Recipes
311 represent the logical unit of execution, the software to build, the
312 images to build, and use the ``.bb`` file extension.
313
314 Reference Kit
315 A working example of a system, which includes a
316 :term:`BSP<Board Support Package (BSP)>` as well as a
317 :term:`build host<Build Host>` and other components, that can
318 work on specific hardware.
319
320 Source Directory
321 This term refers to the directory structure
322 created as a result of creating a local copy of the ``poky`` Git
323 repository ``git://git.yoctoproject.org/poky`` or expanding a
324 released ``poky`` tarball.
325
326 .. note::
327
328 Creating a local copy of the
329 poky
330 Git repository is the recommended method for setting up your
331 Source Directory.
332
333 Sometimes you might hear the term "poky directory" used to refer to
334 this directory structure.
335
336 .. note::
337
338 The OpenEmbedded build system does not support file or directory
339 names that contain spaces. Be sure that the Source Directory you
340 use does not contain these types of names.
341
342 The Source Directory contains BitBake, Documentation, Metadata and
343 other files that all support the Yocto Project. Consequently, you
344 must have the Source Directory in place on your development system in
345 order to do any development using the Yocto Project.
346
347 When you create a local copy of the Git repository, you can name the
348 repository anything you like. Throughout much of the documentation,
349 "poky" is used as the name of the top-level folder of the local copy
350 of the poky Git repository. So, for example, cloning the ``poky`` Git
351 repository results in a local Git repository whose top-level folder
352 is also named "poky".
353
354 While it is not recommended that you use tarball expansion to set up
355 the Source Directory, if you do, the top-level directory name of the
356 Source Directory is derived from the Yocto Project release tarball.
357 For example, downloading and unpacking
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500358 :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500359 results in a Source Directory whose root folder is named ``poky``.
360
361 It is important to understand the differences between the Source
362 Directory created by unpacking a released tarball as compared to
363 cloning ``git://git.yoctoproject.org/poky``. When you unpack a
364 tarball, you have an exact copy of the files based on the time of
365 release - a fixed release point. Any changes you make to your local
366 files in the Source Directory are on top of the release and will
367 remain local only. On the other hand, when you clone the ``poky`` Git
368 repository, you have an active development repository with access to
369 the upstream repository's branches and tags. In this case, any local
370 changes you make to the local Source Directory can be later applied
371 to active development branches of the upstream ``poky`` Git
372 repository.
373
374 For more information on concepts related to Git repositories,
375 branches, and tags, see the
376 ":ref:`overview-manual/overview-manual-development-environment:repositories, tags, and branches`"
377 section in the Yocto Project Overview and Concepts Manual.
378
379 Task
380 A unit of execution for BitBake (e.g.
381 :ref:`ref-tasks-compile`,
382 :ref:`ref-tasks-fetch`,
383 :ref:`ref-tasks-patch`, and so forth).
384
385 Toaster
386 A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
387 The interface enables you to
388 configure and run your builds. Information about builds is collected
389 and stored in a database. For information on Toaster, see the
390 :doc:`../toaster-manual/toaster-manual`.
391
392 Upstream
393 A reference to source code or repositories that are not
394 local to the development system but located in a master area that is
395 controlled by the maintainer of the source code. For example, in
396 order for a developer to work on a particular piece of code, they
397 need to first get a copy of it from an "upstream" source.