diff options
Diffstat (limited to 'documentation/ref-manual/ref-terms.rst')
-rw-r--r-- | documentation/ref-manual/ref-terms.rst | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-terms.rst b/documentation/ref-manual/ref-terms.rst new file mode 100644 index 0000000000..600cc23c3e --- /dev/null +++ b/documentation/ref-manual/ref-terms.rst | |||
@@ -0,0 +1,397 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************* | ||
4 | Yocto Project Terms | ||
5 | ******************* | ||
6 | |||
7 | Following is a list of terms and definitions users new to the Yocto Project | ||
8 | development environment might find helpful. While some of these terms are | ||
9 | universal, 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 | ||
358 | :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` | ||
359 | 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. | ||