summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-terms.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-05 15:43:42 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:27 +0000
commit60cfd0785b2d64ec808e08ad9f716047542d8ba9 (patch)
tree7c103c1a8bab35c1e0814566fde3215936596290 /documentation/ref-manual/ref-terms.xml
parentc06a654c1d14f20b31256298543e2e3504acc0a9 (diff)
downloadpoky-60cfd0785b2d64ec808e08ad9f716047542d8ba9.tar.gz
ref-manual: Separated terms into separate chapter
Pulling out some introductory information from the old "Introduction" chapter of the ref-manual has isolated the system requirements and term definitions sections. I have decided to create a new chapter for terms as they are a reference item. This leaves system requirements also alone as a new chapter. So, I dumped the introduction.xml chapter in favor of the two new chapters. (From yocto-docs rev: 35c41b3008845c94e10be19b37409b0d1a469ff5) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-terms.xml')
-rw-r--r--documentation/ref-manual/ref-terms.xml436
1 files changed, 436 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml
new file mode 100644
index 0000000000..f5ff7df5fb
--- /dev/null
+++ b/documentation/ref-manual/ref-terms.xml
@@ -0,0 +1,436 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-terms'>
6<title>Yocto Project Terms</title>
7
8 <para>
9 Following is a list of terms and definitions users new to the Yocto
10 Project development environment might find helpful.
11 While some of these terms are universal, the list includes them
12 just in case:
13 <itemizedlist>
14 <listitem><para>
15 <emphasis>Append Files:</emphasis>
16 Files that append build information to a recipe file.
17 Append files are known as BitBake append files and
18 <filename>.bbappend</filename> files.
19 The OpenEmbedded build system expects every append file to have
20 a corresponding recipe (<filename>.bb</filename>) file.
21 Furthermore, the append file and corresponding recipe file
22 must use the same root filename.
23 The filenames can differ only in the file type suffix used
24 (e.g.
25 <filename>formfactor_0.0.bb</filename> and
26 <filename>formfactor_0.0.bbappend</filename>).</para>
27
28 <para>Information in append files extends or overrides the
29 information in the similarly-named recipe file.
30 For an example of an append file in use, see the
31 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
32 section in the Yocto Project Development Tasks Manual.
33 <note>
34 Append files can also use wildcard patterns in their
35 version numbers so they can be applied to more than one
36 version of the underlying recipe file.
37 </note>
38 </para></listitem>
39 <listitem><para id='bitbake-term'>
40 <emphasis>BitBake:</emphasis>
41 The task executor and scheduler used by the OpenEmbedded build
42 system to build images.
43 For more information on BitBake, see the
44 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
45 </para></listitem>
46 <listitem><para id='board-support-package-bsp-term'>
47 <emphasis>Board Support Package (BSP):</emphasis>
48 A group of drivers, definitions, and other components that
49 provide support for a specific hardware configuration.
50 For more information on BSPs, see the
51 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
52 </para></listitem>
53 <listitem>
54 <para id='build-directory'>
55 <emphasis>Build Directory:</emphasis>
56 This term refers to the area used by the OpenEmbedded build
57 system for builds.
58 The area is created when you <filename>source</filename> the
59 setup environment script that is found in the Source Directory
60 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
61 The
62 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
63 variable points to the Build Directory.</para>
64
65 <para>You have a lot of flexibility when creating the Build
66 Directory.
67 Following are some examples that show how to create the
68 directory.
69 The examples assume your
70 <link linkend='source-directory'>Source Directory</link> is
71 named <filename>poky</filename>:
72 <itemizedlist>
73 <listitem><para>Create the Build Directory inside your
74 Source Directory and let the name of the Build
75 Directory default to <filename>build</filename>:
76 <literallayout class='monospaced'>
77 $ cd $HOME/poky
78 $ source &OE_INIT_FILE;
79 </literallayout>
80 </para></listitem>
81 <listitem><para>Create the Build Directory inside your
82 home directory and specifically name it
83 <filename>test-builds</filename>:
84 <literallayout class='monospaced'>
85 $ cd $HOME
86 $ source poky/&OE_INIT_FILE; test-builds
87 </literallayout>
88 </para></listitem>
89 <listitem><para>
90 Provide a directory path and specifically name the
91 Build Directory.
92 Any intermediate folders in the pathname must exist.
93 This next example creates a Build Directory named
94 <filename>YP-&POKYVERSION;</filename>
95 in your home directory within the existing
96 directory <filename>mybuilds</filename>:
97 <literallayout class='monospaced'>
98 $cd $HOME
99 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
100 </literallayout>
101 </para></listitem>
102 </itemizedlist>
103 <note>
104 By default, the Build Directory contains
105 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
106 which is a temporary directory the build system uses for
107 its work.
108 <filename>TMPDIR</filename> cannot be under NFS.
109 Thus, by default, the Build Directory cannot be under NFS.
110 However, if you need the Build Directory to be under NFS,
111 you can set this up by setting <filename>TMPDIR</filename>
112 in your <filename>local.conf</filename> file
113 to use a local drive.
114 Doing so effectively separates <filename>TMPDIR</filename>
115 from <filename>TOPDIR</filename>, which is the Build
116 Directory.
117 </note>
118 </para></listitem>
119 <listitem><para id='hardware-build-system-term'>
120 <emphasis>Build System:</emphasis>
121 The system used to build images in a Yocto Project
122 Development environment.
123 The build system is sometimes referred to as the
124 development host.
125 </para></listitem>
126 <listitem><para>
127 <emphasis>Classes:</emphasis>
128 Files that provide for logic encapsulation and inheritance so
129 that commonly used patterns can be defined once and then
130 easily used in multiple recipes.
131 For reference information on the Yocto Project classes, see the
132 "<link linkend='ref-classes'>Classes</link>" chapter.
133 Class files end with the <filename>.bbclass</filename>
134 filename extension.
135 </para></listitem>
136 <listitem><para>
137 <emphasis>Configuration File:</emphasis>
138 Configuration information in various <filename>.conf</filename>
139 files provides global definitions of variables.
140 The <filename>conf/local.conf</filename> configuration file in
141 the
142 <link linkend='build-directory'>Build Directory</link>
143 contains user-defined variables that affect every build.
144 The <filename>meta-poky/conf/distro/poky.conf</filename>
145 configuration file defines Yocto "distro" configuration
146 variables used only when building with this policy.
147 Machine configuration files, which
148 are located throughout the
149 <link linkend='source-directory'>Source Directory</link>, define
150 variables for specific hardware and are only used when building
151 for that target (e.g. the
152 <filename>machine/beaglebone.conf</filename> configuration
153 file defines variables for the Texas Instruments ARM Cortex-A8
154 development board).
155 Configuration files end with a <filename>.conf</filename>
156 filename extension.
157 </para></listitem>
158 <listitem><para id='cross-development-toolchain'>
159 <emphasis>Cross-Development Toolchain:</emphasis>
160 In general, a cross-development toolchain is a collection of
161 software development tools and utilities that run on one
162 architecture and allow you to develop software for a
163 different, or targeted, architecture.
164 These toolchains contain cross-compilers, linkers, and
165 debuggers that are specific to the target architecture.</para>
166
167 <para>The Yocto Project supports two different cross-development
168 toolchains:
169 <itemizedlist>
170 <listitem><para>
171 A toolchain only used by and within
172 BitBake when building an image for a target
173 architecture.
174 </para></listitem>
175 <listitem><para>A relocatable toolchain used outside of
176 BitBake by developers when developing applications
177 that will run on a targeted device.
178 </para></listitem>
179 </itemizedlist></para>
180
181 <para>Creation of these toolchains is simple and automated.
182 For information on toolchain concepts as they apply to the
183 Yocto Project, see the
184 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
185 section.
186 You can also find more information on using the
187 relocatable toolchain in the
188 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
189 manual.
190 </para></listitem>
191 <listitem><para>
192 <emphasis>Image:</emphasis>
193 An image is an artifact of the BitBake build process given
194 a collection of recipes and related Metadata.
195 Images are the binary output that run on specific hardware or
196 QEMU and are used for specific use-cases.
197 For a list of the supported image types that the Yocto Project
198 provides, see the
199 "<link linkend='ref-images'>Images</link>"
200 chapter.
201 </para></listitem>
202 <listitem><para>
203 <emphasis>Layer:</emphasis>
204 A collection of recipes representing the core,
205 a BSP, or an application stack.
206 For a discussion specifically on BSP Layers, see the
207 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
208 section in the Yocto Project Board Support Packages (BSP)
209 Developer's Guide.
210 </para></listitem>
211 <listitem><para id='metadata'>
212 <emphasis>Metadata:</emphasis>
213 The files that BitBake parses when building an image.
214 In general, Metadata includes recipes, classes, and
215 configuration files.
216 In the context of the kernel ("kernel Metadata"), the
217 term refers to the kernel config fragments and features
218 contained in the
219 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
220 Git repository.
221 </para></listitem>
222 <listitem><para id='oe-core'>
223 <emphasis>OE-Core:</emphasis>
224 A core set of Metadata originating with OpenEmbedded (OE)
225 that is shared between OE and the Yocto Project.
226 This Metadata is found in the <filename>meta</filename>
227 directory of the
228 <link linkend='source-directory'>Source Directory</link>.
229 </para></listitem>
230 <listitem><para id='build-system-term'>
231 <emphasis>OpenEmbedded Build System:</emphasis>
232 The build system specific to the Yocto Project.
233 The OpenEmbedded build system is based on another project known
234 as "Poky", which uses
235 <link linkend='bitbake-term'>BitBake</link> as the task
236 executor.
237 Throughout the Yocto Project documentation set, the
238 OpenEmbedded build system is sometimes referred to simply
239 as "the build system".
240 If other build systems, such as a host or target build system
241 are referenced, the documentation clearly states the
242 difference.
243 <note>
244 For some historical information about Poky, see the
245 <link linkend='poky'>Poky</link> term.
246 </note>
247 </para></listitem>
248 <listitem><para>
249 <emphasis>Package:</emphasis>
250 In the context of the Yocto Project, this term refers to a
251 recipe's packaged output produced by BitBake (i.e. a
252 "baked recipe").
253 A package is generally the compiled binaries produced from the
254 recipe's sources.
255 You "bake" something by running it through BitBake.</para>
256
257 <para>It is worth noting that the term "package" can,
258 in general, have subtle meanings.
259 For example, the packages referred to in the
260 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
261 section in the Yocto Project Quick Start are compiled binaries
262 that, when installed, add functionality to your Linux
263 distribution.</para>
264
265 <para>Another point worth noting is that historically within
266 the Yocto Project, recipes were referred to as packages - thus,
267 the existence of several BitBake variables that are seemingly
268 mis-named,
269 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
270 <link linkend='var-PV'><filename>PV</filename></link>, and
271 <link linkend='var-PE'><filename>PE</filename></link>).
272 </para></listitem>
273 <listitem><para>
274 <emphasis>Package Groups:</emphasis>
275 Arbitrary groups of software Recipes.
276 You use package groups to hold recipes that, when built,
277 usually accomplish a single task.
278 For example, a package group could contain the recipes for a
279 company’s proprietary or value-add software.
280 Or, the package group could contain the recipes that enable
281 graphics.
282 A package group is really just another recipe.
283 Because package group files are recipes, they end with the
284 <filename>.bb</filename> filename extension.
285 </para></listitem>
286 <listitem><para id='poky'>
287 <emphasis>Poky:</emphasis>
288 The term "poky", which is pronounced
289 <emphasis>Pah</emphasis>-kee, can mean several things:
290 <itemizedlist>
291 <listitem><para>
292 In its most general sense, poky is an open-source
293 project that was initially developed by OpenedHand.
294 OpenedHand developed poky off of the existing
295 OpenEmbedded build system to create a commercially
296 supportable build system for embedded Linux.
297 After Intel Corporation acquired OpenedHand, the
298 poky project became the basis for the Yocto Project's
299 build system.
300 </para></listitem>
301 <listitem><para>
302 Within the Yocto Project
303 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
304 "poky" exists as a separate Git
305 repository from which you can clone to yield a local
306 Git repository that is a copy on your host system.
307 Thus, "poky" can refer to the upstream or
308 local copy of the files used for development within
309 the Yocto Project.
310 </para></listitem>
311 <listitem><para>
312 Finally, "poky" can refer to the default
313 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
314 (i.e. distribution) created when you use the Yocto
315 Project in conjunction with the
316 <filename>poky</filename> repository to build an image.
317 </para></listitem>
318 </itemizedlist>
319 </para></listitem>
320 <listitem><para>
321 <emphasis>Recipe:</emphasis>
322 A set of instructions for building packages.
323 A recipe describes where you get source code, which patches
324 to apply, how to configure the source, how to compile it and so on.
325 Recipes also describe dependencies for libraries or for other
326 recipes.
327 Recipes represent the logical unit of execution, the software
328 to build, the images to build, and use the
329 <filename>.bb</filename> file extension.
330 </para></listitem>
331 <listitem><para id='reference-kit-term'>
332 <emphasis>Reference Kit:</emphasis>
333 A working example of a system, which includes a
334 <link linkend='board-support-package-bsp-term'>BSP</link>
335 as well as a
336 <link linkend='hardware-build-system-term'>build system</link>
337 and other components, that can work on specific hardware.
338 </para></listitem>
339 <listitem>
340 <para id='source-directory'>
341 <emphasis>Source Directory:</emphasis>
342 This term refers to the directory structure created as a result
343 of creating a local copy of the <filename>poky</filename> Git
344 repository <filename>git://git.yoctoproject.org/poky</filename>
345 or expanding a released <filename>poky</filename> tarball.
346 <note>
347 Creating a local copy of the <filename>poky</filename>
348 Git repository is the recommended method for setting up
349 your Source Directory.
350 </note>
351 Sometimes you might hear the term "poky directory" used to refer
352 to this directory structure.
353 <note>
354 The OpenEmbedded build system does not support file or
355 directory names that contain spaces.
356 Be sure that the Source Directory you use does not contain
357 these types of names.
358 </note></para>
359
360 <para>The Source Directory contains BitBake, Documentation,
361 Metadata and other files that all support the Yocto Project.
362 Consequently, you must have the Source Directory in place on
363 your development system in order to do any development using
364 the Yocto Project.</para>
365
366 <para>When you create a local copy of the Git repository, you
367 can name the repository anything you like.
368 Throughout much of the documentation, "poky"
369 is used as the name of the top-level folder of the local copy of
370 the poky Git repository.
371 So, for example, cloning the <filename>poky</filename> Git
372 repository results in a local Git repository whose top-level
373 folder is also named "poky".</para>
374
375 <para>While it is not recommended that you use tarball expansion
376 to set up the Source Directory, if you do, the top-level
377 directory name of the Source Directory is derived from the
378 Yocto Project release tarball.
379 For example, downloading and unpacking
380 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
381 Source Directory whose root folder is named
382 <filename>&YOCTO_POKY;</filename>.</para>
383
384 <para>It is important to understand the differences between the
385 Source Directory created by unpacking a released tarball as
386 compared to cloning
387 <filename>git://git.yoctoproject.org/poky</filename>.
388 When you unpack a tarball, you have an exact copy of the files
389 based on the time of release - a fixed release point.
390 Any changes you make to your local files in the Source Directory
391 are on top of the release and will remain local only.
392 On the other hand, when you clone the <filename>poky</filename>
393 Git repository, you have an active development repository with
394 access to the upstream repository's branches and tags.
395 In this case, any local changes you make to the local
396 Source Directory can be later applied to active development
397 branches of the upstream <filename>poky</filename> Git
398 repository.</para>
399
400 <para>For more information on concepts related to Git
401 repositories, branches, and tags, see the
402 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
403 section in the Yocto Project Overview Manual.
404 </para></listitem>
405 <listitem><para><emphasis>Task:</emphasis>
406 A unit of execution for BitBake (e.g.
407 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
408 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
409 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
410 and so forth).
411 </para></listitem>
412 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
413 A web interface to the Yocto Project's
414 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
415 The interface enables you to configure and run your builds.
416 Information about builds is collected and stored in a database.
417 For information on Toaster, see the
418 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
419 </para></listitem>
420 <listitem><para>
421 <emphasis>Upstream:</emphasis>
422 A reference to source code or repositories
423 that are not local to the development system but located in a
424 master area that is controlled by the maintainer of the source
425 code.
426 For example, in order for a developer to work on a particular
427 piece of code, they need to first get a copy of it from an
428 "upstream" source.
429 </para></listitem>
430 </itemizedlist>
431 </para>
432
433</chapter>
434<!--
435vim: expandtab tw=80 ts=4
436-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-02-03 11:56:20 +0000