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