summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/introduction.xml823
1 files changed, 416 insertions, 407 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 2e1b8e1740..1fc01fe38a 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -5,10 +5,11 @@
5<chapter id='ref-manual-intro'> 5<chapter id='ref-manual-intro'>
6<title>Introduction</title> 6<title>Introduction</title>
7 7
8<section id='intro-welcome'> 8<section id='ref-welcome'>
9 <title>Introduction</title> 9 <title>Welcome</title>
10 10
11 <para> 11 <para>
12 Welcome to the Yocto Project Reference Manual.
12 This manual provides reference information for the current release 13 This manual provides reference information for the current release
13 of the Yocto Project. 14 of the Yocto Project.
14 The Yocto Project is an open-source collaboration project focused 15 The Yocto Project is an open-source collaboration project focused
@@ -16,419 +17,37 @@
16 Amongst other things, the Yocto Project uses the OpenEmbedded build 17 Amongst other things, the Yocto Project uses the OpenEmbedded build
17 system, which is based on the Poky project, to construct complete 18 system, which is based on the Poky project, to construct complete
18 Linux images. 19 Linux images.
19 You can find complete introductory and getting started information
20 on the Yocto Project by reading the
21 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
22 </para> 20 </para>
23 21
24 <para> 22 <para>
25 For task-based information using the Yocto Project, see the 23 This reference manual is best used after you have an understanding
26 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> 24 of the basics of the Yocto Project.
27 and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. 25 The manual is not meant to be read as a starting point to the
28 For Board Support Package (BSP) structure information, see the 26 Yocto Project.
29 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. 27 Use this manual to find concepts, variable definitions, class
30 For information on how to use a Software Development Kit, (SDK), see the 28 descriptions, and so forth.
31 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. 29 The manual augments working with the Yocto Project during application
32 You can find information on tracing and profiling in the 30 and kernel development.
33 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
34 For information on BitBake, which is the task execution tool the
35 OpenEmbedded build system is based on, see the
36 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
37 Finally, you can also find lots of Yocto Project information on the
38 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
39 </para> 31 </para>
40</section>
41
42<section id='yocto-project-terms'>
43 <title>Yocto Project Terms</title>
44 32
45 <para> 33 <para>
46 Following is a list of terms and definitions users new to the Yocto 34 The Yocto Project Reference Manual does not provide "how-to",
47 Project development environment might find helpful. 35 task-oriented information.
48 While some of these terms are universal, the list includes them 36 You can find complete introductory and getting started information
49 just in case: 37 on the Yocto Project by reading the
50 <itemizedlist> 38 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
51 <listitem><para> 39 You can find "how-to" information in the
52 <emphasis>Append Files:</emphasis> 40 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
53 Files that append build information to a recipe file. 41 <note><title>Tip</title>
54 Append files are known as BitBake append files and 42 For more information about the Yocto Project Documentation set,
55 <filename>.bbappend</filename> files. 43 see the
56 The OpenEmbedded build system expects every append file to have 44 "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
57 a corresponding recipe (<filename>.bb</filename>) file. 45 section.
58 Furthermore, the append file and corresponding recipe file 46 </note>
59 must use the same root filename.
60 The filenames can differ only in the file type suffix used
61 (e.g.
62 <filename>formfactor_0.0.bb</filename> and
63 <filename>formfactor_0.0.bbappend</filename>).</para>
64
65 <para>Information in append files extends or overrides the
66 information in the similarly-named recipe file.
67 For an example of an append file in use, see the
68 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
69 section in the Yocto Project Development Manual.
70 <note>
71 Append files can also use wildcard patterns in their
72 version numbers so they can be applied to more than one
73 version of the underlying recipe file.
74 </note>
75 </para></listitem>
76 <listitem><para id='bitbake-term'>
77 <emphasis>BitBake:</emphasis>
78 The task executor and scheduler used by the OpenEmbedded build
79 system to build images.
80 For more information on BitBake, see the
81 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
82 </para></listitem>
83 <listitem>
84 <para id='build-directory'>
85 <emphasis>Build Directory:</emphasis>
86 This term refers to the area used by the OpenEmbedded build
87 system for builds.
88 The area is created when you <filename>source</filename> the
89 setup environment script that is found in the Source Directory
90 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
91 or
92 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
93 The
94 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
95 variable points to the Build Directory.</para>
96
97 <para>You have a lot of flexibility when creating the Build
98 Directory.
99 Following are some examples that show how to create the
100 directory.
101 The examples assume your
102 <link linkend='source-directory'>Source Directory</link> is
103 named <filename>poky</filename>:
104 <itemizedlist>
105 <listitem><para>Create the Build Directory inside your
106 Source Directory and let the name of the Build
107 Directory default to <filename>build</filename>:
108 <literallayout class='monospaced'>
109 $ cd $HOME/poky
110 $ source &OE_INIT_FILE;
111 </literallayout>
112 </para></listitem>
113 <listitem><para>Create the Build Directory inside your
114 home directory and specifically name it
115 <filename>test-builds</filename>:
116 <literallayout class='monospaced'>
117 $ cd $HOME
118 $ source poky/&OE_INIT_FILE; test-builds
119 </literallayout>
120 </para></listitem>
121 <listitem><para>
122 Provide a directory path and specifically name the
123 Build Directory.
124 Any intermediate folders in the pathname must exist.
125 This next example creates a Build Directory named
126 <filename>YP-&POKYVERSION;</filename>
127 in your home directory within the existing
128 directory <filename>mybuilds</filename>:
129 <literallayout class='monospaced'>
130 $cd $HOME
131 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
132 </literallayout>
133 </para></listitem>
134 </itemizedlist>
135 <note>
136 By default, the Build Directory contains
137 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
138 which is a temporary directory the build system uses for
139 its work.
140 <filename>TMPDIR</filename> cannot be under NFS.
141 Thus, by default, the Build Directory cannot be under NFS.
142 However, if you need the Build Directory to be under NFS,
143 you can set this up by setting <filename>TMPDIR</filename>
144 in your <filename>local.conf</filename> file
145 to use a local drive.
146 Doing so effectively separates <filename>TMPDIR</filename>
147 from <filename>TOPDIR</filename>, which is the Build
148 Directory.
149 </note>
150 </para></listitem>
151 <listitem><para>
152 <emphasis>Classes:</emphasis>
153 Files that provide for logic encapsulation and inheritance so
154 that commonly used patterns can be defined once and then
155 easily used in multiple recipes.
156 For reference information on the Yocto Project classes, see the
157 "<link linkend='ref-classes'>Classes</link>" chapter.
158 Class files end with the <filename>.bbclass</filename>
159 filename extension.
160 </para></listitem>
161 <listitem><para>
162 <emphasis>Configuration File:</emphasis>
163 Configuration information in various <filename>.conf</filename>
164 files provides global definitions of variables.
165 The <filename>conf/local.conf</filename> configuration file in
166 the
167 <link linkend='build-directory'>Build Directory</link>
168 contains user-defined variables that affect every build.
169 The <filename>meta-poky/conf/distro/poky.conf</filename>
170 configuration file defines Yocto "distro" configuration
171 variables used only when building with this policy.
172 Machine configuration files, which
173 are located throughout the
174 <link linkend='source-directory'>Source Directory</link>, define
175 variables for specific hardware and are only used when building
176 for that target (e.g. the
177 <filename>machine/beaglebone.conf</filename> configuration
178 file defines variables for the Texas Instruments ARM Cortex-A8
179 development board).
180 Configuration files end with a <filename>.conf</filename>
181 filename extension.
182 </para></listitem>
183 <listitem><para id='cross-development-toolchain'>
184 <emphasis>Cross-Development Toolchain:</emphasis>
185 In general, a cross-development toolchain is a collection of
186 software development tools and utilities that run on one
187 architecture and allow you to develop software for a
188 different, or targeted, architecture.
189 These toolchains contain cross-compilers, linkers, and
190 debuggers that are specific to the target architecture.</para>
191
192 <para>The Yocto Project supports two different cross-development
193 toolchains:
194 <itemizedlist>
195 <listitem><para>
196 A toolchain only used by and within
197 BitBake when building an image for a target
198 architecture.
199 </para></listitem>
200 <listitem><para>A relocatable toolchain used outside of
201 BitBake by developers when developing applications
202 that will run on a targeted device.
203 </para></listitem>
204 </itemizedlist></para>
205
206 <para>Creation of these toolchains is simple and automated.
207 For information on toolchain concepts as they apply to the
208 Yocto Project, see the
209 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
210 section.
211 You can also find more information on using the
212 relocatable toolchain in the
213 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
214 </para></listitem>
215 <listitem><para>
216 <emphasis>Image:</emphasis>
217 An image is an artifact of the BitBake build process given
218 a collection of recipes and related Metadata.
219 Images are the binary output that run on specific hardware or
220 QEMU and are used for specific use-cases.
221 For a list of the supported image types that the Yocto Project
222 provides, see the
223 "<link linkend='ref-images'>Images</link>"
224 chapter.
225 </para></listitem>
226 <listitem><para>
227 <emphasis>Layer:</emphasis>
228 A collection of recipes representing the core,
229 a BSP, or an application stack.
230 For a discussion specifically on BSP Layers, see the
231 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
232 section in the Yocto Project Board Support Packages (BSP)
233 Developer's Guide.
234 </para></listitem>
235 <listitem><para id='metadata'>
236 <emphasis>Metadata:</emphasis>
237 The files that BitBake parses when building an image.
238 In general, Metadata includes recipes, classes, and
239 configuration files.
240 In the context of the kernel ("kernel Metadata"),
241 it refers to Metadata in the <filename>meta</filename>
242 branches of the kernel source Git repositories.
243 </para></listitem>
244 <listitem><para id='oe-core'>
245 <emphasis>OE-Core:</emphasis>
246 A core set of Metadata originating with OpenEmbedded (OE)
247 that is shared between OE and the Yocto Project.
248 This Metadata is found in the <filename>meta</filename>
249 directory of the
250 <link linkend='source-directory'>Source Directory</link>.
251 </para></listitem>
252 <listitem><para id='build-system-term'>
253 <emphasis>OpenEmbedded Build System:</emphasis>
254 The build system specific to the Yocto Project.
255 The OpenEmbedded build system is based on another project known
256 as "Poky", which uses
257 <link linkend='bitbake-term'>BitBake</link> as the task
258 executor.
259 Throughout the Yocto Project documentation set, the
260 OpenEmbedded build system is sometimes referred to simply
261 as "the build system".
262 If other build systems, such as a host or target build system
263 are referenced, the documentation clearly states the
264 difference.
265 <note>
266 For some historical information about Poky, see the
267 <link linkend='poky'>Poky</link> term.
268 </note>
269 </para></listitem>
270 <listitem><para>
271 <emphasis>Package:</emphasis>
272 In the context of the Yocto Project, this term refers to a
273 recipe's packaged output produced by BitBake (i.e. a
274 "baked recipe").
275 A package is generally the compiled binaries produced from the
276 recipe's sources.
277 You "bake" something by running it through BitBake.</para>
278
279 <para>It is worth noting that the term "package" can,
280 in general, have subtle meanings.
281 For example, the packages referred to in the
282 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
283 section in the Yocto Project Quick Start are compiled binaries
284 that, when installed, add functionality to your Linux
285 distribution.</para>
286
287 <para>Another point worth noting is that historically within
288 the Yocto Project, recipes were referred to as packages - thus,
289 the existence of several BitBake variables that are seemingly
290 mis-named,
291 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
292 <link linkend='var-PV'><filename>PV</filename></link>, and
293 <link linkend='var-PE'><filename>PE</filename></link>).
294 </para></listitem>
295 <listitem><para>
296 <emphasis>Package Groups:</emphasis>
297 Arbitrary groups of software Recipes.
298 You use package groups to hold recipes that, when built,
299 usually accomplish a single task.
300 For example, a package group could contain the recipes for a
301 company’s proprietary or value-add software.
302 Or, the package group could contain the recipes that enable
303 graphics.
304 A package group is really just another recipe.
305 Because package group files are recipes, they end with the
306 <filename>.bb</filename> filename extension.
307 </para></listitem>
308 <listitem><para id='poky'>
309 <emphasis>Poky:</emphasis>
310 The term "poky" can mean several things.
311 In its most general sense, it is an open-source
312 project that was initially developed by OpenedHand.
313 With OpenedHand, poky was developed off of the existing
314 OpenEmbedded build system becoming a commercially
315 supportable build system for embedded Linux.
316 After Intel Corporation acquired OpenedHand, the
317 project poky became the basis for the Yocto Project's
318 build system.</para>
319
320 <para>Within the Yocto Project source repositories,
321 <filename>poky</filename> exists as a separate Git
322 repository you can clone to yield a local copy on your
323 host system.
324 Thus, "poky" can refer to the local copy of the Source
325 Directory used for development within the Yocto
326 Project.</para>
327
328 <para>Finally, "poky" can refer to the default
329 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
330 (i.e. distribution) created when you use the Yocto
331 Project in conjunction with the
332 <filename>poky</filename> repository to build an image.
333 </para></listitem>
334 <listitem><para>
335 <emphasis>Recipe:</emphasis>
336 A set of instructions for building packages.
337 A recipe describes where you get source code, which patches
338 to apply, how to configure the source, how to compile it and so on.
339 Recipes also describe dependencies for libraries or for other
340 recipes.
341 Recipes represent the logical unit of execution, the software
342 to build, the images to build, and use the
343 <filename>.bb</filename> file extension.
344 </para></listitem>
345 <listitem>
346 <para id='source-directory'>
347 <emphasis>Source Directory:</emphasis>
348 This term refers to the directory structure created as a result
349 of creating a local copy of the <filename>poky</filename> Git
350 repository <filename>git://git.yoctoproject.org/poky</filename>
351 or expanding a released <filename>poky</filename> tarball.
352 <note>
353 Creating a local copy of the <filename>poky</filename>
354 Git repository is the recommended method for setting up
355 your Source Directory.
356 </note>
357 Sometimes you might hear the term "poky directory" used to refer
358 to this directory structure.
359 <note>
360 The OpenEmbedded build system does not support file or
361 directory names that contain spaces.
362 Be sure that the Source Directory you use does not contain
363 these types of names.
364 </note></para>
365
366 <para>The Source Directory contains BitBake, Documentation,
367 Metadata and other files that all support the Yocto Project.
368 Consequently, you must have the Source Directory in place on
369 your development system in order to do any development using
370 the Yocto Project.</para>
371
372 <para>When you create a local copy of the Git repository, you
373 can name the repository anything you like.
374 Throughout much of the documentation, "poky"
375 is used as the name of the top-level folder of the local copy of
376 the poky Git repository.
377 So, for example, cloning the <filename>poky</filename> Git
378 repository results in a local Git repository whose top-level
379 folder is also named "poky".</para>
380
381 <para>While it is not recommended that you use tarball expansion
382 to set up the Source Directory, if you do, the top-level
383 directory name of the Source Directory is derived from the
384 Yocto Project release tarball.
385 For example, downloading and unpacking
386 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
387 Source Directory whose root folder is named
388 <filename>&YOCTO_POKY;</filename>.</para>
389
390 <para>It is important to understand the differences between the
391 Source Directory created by unpacking a released tarball as
392 compared to cloning
393 <filename>git://git.yoctoproject.org/poky</filename>.
394 When you unpack a tarball, you have an exact copy of the files
395 based on the time of release - a fixed release point.
396 Any changes you make to your local files in the Source Directory
397 are on top of the release and will remain local only.
398 On the other hand, when you clone the <filename>poky</filename>
399 Git repository, you have an active development repository with
400 access to the upstream repository's branches and tags.
401 In this case, any local changes you make to the local
402 Source Directory can be later applied to active development
403 branches of the upstream <filename>poky</filename> Git
404 repository.</para>
405
406 <para>For more information on concepts related to Git
407 repositories, branches, and tags, see the
408 "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
409 section in the Yocto Project Development Manual.
410 </para></listitem>
411 <listitem><para><emphasis>Task:</emphasis>
412 A unit of execution for BitBake (e.g.
413 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
414 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
415 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
416 and so forth).
417 </para></listitem>
418 <listitem><para>
419 <emphasis>Upstream:</emphasis>
420 A reference to source code or repositories
421 that are not local to the development system but located in a
422 master area that is controlled by the maintainer of the source
423 code.
424 For example, in order for a developer to work on a particular
425 piece of code, they need to first get a copy of it from an
426 "upstream" source.
427 </para></listitem>
428 </itemizedlist>
429 </para> 47 </para>
430</section> 48</section>
431 49
50<!--
432<section id='intro-manualoverview'> 51<section id='intro-manualoverview'>
433 <title>Documentation Overview</title> 52 <title>Documentation Overview</title>
434 <para> 53 <para>
@@ -545,7 +164,7 @@
545 </itemizedlist> 164 </itemizedlist>
546 </para> 165 </para>
547</section> 166</section>
548 167-->
549 168
550<section id='intro-requirements'> 169<section id='intro-requirements'>
551<title>System Requirements</title> 170<title>System Requirements</title>
@@ -1050,6 +669,396 @@
1050 </para> 669 </para>
1051</section> 670</section>
1052 671
672<section id='yocto-project-terms'>
673 <title>Yocto Project Terms</title>
674
675 <para>
676 Following is a list of terms and definitions users new to the Yocto
677 Project development environment might find helpful.
678 While some of these terms are universal, the list includes them
679 just in case:
680 <itemizedlist>
681 <listitem><para>
682 <emphasis>Append Files:</emphasis>
683 Files that append build information to a recipe file.
684 Append files are known as BitBake append files and
685 <filename>.bbappend</filename> files.
686 The OpenEmbedded build system expects every append file to have
687 a corresponding recipe (<filename>.bb</filename>) file.
688 Furthermore, the append file and corresponding recipe file
689 must use the same root filename.
690 The filenames can differ only in the file type suffix used
691 (e.g.
692 <filename>formfactor_0.0.bb</filename> and
693 <filename>formfactor_0.0.bbappend</filename>).</para>
694
695 <para>Information in append files extends or overrides the
696 information in the similarly-named recipe file.
697 For an example of an append file in use, see the
698 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
699 section in the Yocto Project Development Manual.
700 <note>
701 Append files can also use wildcard patterns in their
702 version numbers so they can be applied to more than one
703 version of the underlying recipe file.
704 </note>
705 </para></listitem>
706 <listitem><para id='bitbake-term'>
707 <emphasis>BitBake:</emphasis>
708 The task executor and scheduler used by the OpenEmbedded build
709 system to build images.
710 For more information on BitBake, see the
711 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
712 </para></listitem>
713 <listitem>
714 <para id='build-directory'>
715 <emphasis>Build Directory:</emphasis>
716 This term refers to the area used by the OpenEmbedded build
717 system for builds.
718 The area is created when you <filename>source</filename> the
719 setup environment script that is found in the Source Directory
720 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
721 or
722 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
723 The
724 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
725 variable points to the Build Directory.</para>
726
727 <para>You have a lot of flexibility when creating the Build
728 Directory.
729 Following are some examples that show how to create the
730 directory.
731 The examples assume your
732 <link linkend='source-directory'>Source Directory</link> is
733 named <filename>poky</filename>:
734 <itemizedlist>
735 <listitem><para>Create the Build Directory inside your
736 Source Directory and let the name of the Build
737 Directory default to <filename>build</filename>:
738 <literallayout class='monospaced'>
739 $ cd $HOME/poky
740 $ source &OE_INIT_FILE;
741 </literallayout>
742 </para></listitem>
743 <listitem><para>Create the Build Directory inside your
744 home directory and specifically name it
745 <filename>test-builds</filename>:
746 <literallayout class='monospaced'>
747 $ cd $HOME
748 $ source poky/&OE_INIT_FILE; test-builds
749 </literallayout>
750 </para></listitem>
751 <listitem><para>
752 Provide a directory path and specifically name the
753 Build Directory.
754 Any intermediate folders in the pathname must exist.
755 This next example creates a Build Directory named
756 <filename>YP-&POKYVERSION;</filename>
757 in your home directory within the existing
758 directory <filename>mybuilds</filename>:
759 <literallayout class='monospaced'>
760 $cd $HOME
761 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
762 </literallayout>
763 </para></listitem>
764 </itemizedlist>
765 <note>
766 By default, the Build Directory contains
767 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
768 which is a temporary directory the build system uses for
769 its work.
770 <filename>TMPDIR</filename> cannot be under NFS.
771 Thus, by default, the Build Directory cannot be under NFS.
772 However, if you need the Build Directory to be under NFS,
773 you can set this up by setting <filename>TMPDIR</filename>
774 in your <filename>local.conf</filename> file
775 to use a local drive.
776 Doing so effectively separates <filename>TMPDIR</filename>
777 from <filename>TOPDIR</filename>, which is the Build
778 Directory.
779 </note>
780 </para></listitem>
781 <listitem><para>
782 <emphasis>Classes:</emphasis>
783 Files that provide for logic encapsulation and inheritance so
784 that commonly used patterns can be defined once and then
785 easily used in multiple recipes.
786 For reference information on the Yocto Project classes, see the
787 "<link linkend='ref-classes'>Classes</link>" chapter.
788 Class files end with the <filename>.bbclass</filename>
789 filename extension.
790 </para></listitem>
791 <listitem><para>
792 <emphasis>Configuration File:</emphasis>
793 Configuration information in various <filename>.conf</filename>
794 files provides global definitions of variables.
795 The <filename>conf/local.conf</filename> configuration file in
796 the
797 <link linkend='build-directory'>Build Directory</link>
798 contains user-defined variables that affect every build.
799 The <filename>meta-poky/conf/distro/poky.conf</filename>
800 configuration file defines Yocto "distro" configuration
801 variables used only when building with this policy.
802 Machine configuration files, which
803 are located throughout the
804 <link linkend='source-directory'>Source Directory</link>, define
805 variables for specific hardware and are only used when building
806 for that target (e.g. the
807 <filename>machine/beaglebone.conf</filename> configuration
808 file defines variables for the Texas Instruments ARM Cortex-A8
809 development board).
810 Configuration files end with a <filename>.conf</filename>
811 filename extension.
812 </para></listitem>
813 <listitem><para id='cross-development-toolchain'>
814 <emphasis>Cross-Development Toolchain:</emphasis>
815 In general, a cross-development toolchain is a collection of
816 software development tools and utilities that run on one
817 architecture and allow you to develop software for a
818 different, or targeted, architecture.
819 These toolchains contain cross-compilers, linkers, and
820 debuggers that are specific to the target architecture.</para>
821
822 <para>The Yocto Project supports two different cross-development
823 toolchains:
824 <itemizedlist>
825 <listitem><para>
826 A toolchain only used by and within
827 BitBake when building an image for a target
828 architecture.
829 </para></listitem>
830 <listitem><para>A relocatable toolchain used outside of
831 BitBake by developers when developing applications
832 that will run on a targeted device.
833 </para></listitem>
834 </itemizedlist></para>
835
836 <para>Creation of these toolchains is simple and automated.
837 For information on toolchain concepts as they apply to the
838 Yocto Project, see the
839 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
840 section.
841 You can also find more information on using the
842 relocatable toolchain in the
843 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
844 </para></listitem>
845 <listitem><para>
846 <emphasis>Image:</emphasis>
847 An image is an artifact of the BitBake build process given
848 a collection of recipes and related Metadata.
849 Images are the binary output that run on specific hardware or
850 QEMU and are used for specific use-cases.
851 For a list of the supported image types that the Yocto Project
852 provides, see the
853 "<link linkend='ref-images'>Images</link>"
854 chapter.
855 </para></listitem>
856 <listitem><para>
857 <emphasis>Layer:</emphasis>
858 A collection of recipes representing the core,
859 a BSP, or an application stack.
860 For a discussion specifically on BSP Layers, see the
861 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
862 section in the Yocto Project Board Support Packages (BSP)
863 Developer's Guide.
864 </para></listitem>
865 <listitem><para id='metadata'>
866 <emphasis>Metadata:</emphasis>
867 The files that BitBake parses when building an image.
868 In general, Metadata includes recipes, classes, and
869 configuration files.
870 In the context of the kernel ("kernel Metadata"),
871 it refers to Metadata in the <filename>meta</filename>
872 branches of the kernel source Git repositories.
873 </para></listitem>
874 <listitem><para id='oe-core'>
875 <emphasis>OE-Core:</emphasis>
876 A core set of Metadata originating with OpenEmbedded (OE)
877 that is shared between OE and the Yocto Project.
878 This Metadata is found in the <filename>meta</filename>
879 directory of the
880 <link linkend='source-directory'>Source Directory</link>.
881 </para></listitem>
882 <listitem><para id='build-system-term'>
883 <emphasis>OpenEmbedded Build System:</emphasis>
884 The build system specific to the Yocto Project.
885 The OpenEmbedded build system is based on another project known
886 as "Poky", which uses
887 <link linkend='bitbake-term'>BitBake</link> as the task
888 executor.
889 Throughout the Yocto Project documentation set, the
890 OpenEmbedded build system is sometimes referred to simply
891 as "the build system".
892 If other build systems, such as a host or target build system
893 are referenced, the documentation clearly states the
894 difference.
895 <note>
896 For some historical information about Poky, see the
897 <link linkend='poky'>Poky</link> term.
898 </note>
899 </para></listitem>
900 <listitem><para>
901 <emphasis>Package:</emphasis>
902 In the context of the Yocto Project, this term refers to a
903 recipe's packaged output produced by BitBake (i.e. a
904 "baked recipe").
905 A package is generally the compiled binaries produced from the
906 recipe's sources.
907 You "bake" something by running it through BitBake.</para>
908
909 <para>It is worth noting that the term "package" can,
910 in general, have subtle meanings.
911 For example, the packages referred to in the
912 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
913 section in the Yocto Project Quick Start are compiled binaries
914 that, when installed, add functionality to your Linux
915 distribution.</para>
916
917 <para>Another point worth noting is that historically within
918 the Yocto Project, recipes were referred to as packages - thus,
919 the existence of several BitBake variables that are seemingly
920 mis-named,
921 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
922 <link linkend='var-PV'><filename>PV</filename></link>, and
923 <link linkend='var-PE'><filename>PE</filename></link>).
924 </para></listitem>
925 <listitem><para>
926 <emphasis>Package Groups:</emphasis>
927 Arbitrary groups of software Recipes.
928 You use package groups to hold recipes that, when built,
929 usually accomplish a single task.
930 For example, a package group could contain the recipes for a
931 company’s proprietary or value-add software.
932 Or, the package group could contain the recipes that enable
933 graphics.
934 A package group is really just another recipe.
935 Because package group files are recipes, they end with the
936 <filename>.bb</filename> filename extension.
937 </para></listitem>
938 <listitem><para id='poky'>
939 <emphasis>Poky:</emphasis>
940 The term "poky" can mean several things.
941 In its most general sense, it is an open-source
942 project that was initially developed by OpenedHand.
943 With OpenedHand, poky was developed off of the existing
944 OpenEmbedded build system becoming a commercially
945 supportable build system for embedded Linux.
946 After Intel Corporation acquired OpenedHand, the
947 project poky became the basis for the Yocto Project's
948 build system.</para>
949
950 <para>Within the Yocto Project source repositories,
951 <filename>poky</filename> exists as a separate Git
952 repository you can clone to yield a local copy on your
953 host system.
954 Thus, "poky" can refer to the local copy of the Source
955 Directory used for development within the Yocto
956 Project.</para>
957
958 <para>Finally, "poky" can refer to the default
959 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
960 (i.e. distribution) created when you use the Yocto
961 Project in conjunction with the
962 <filename>poky</filename> repository to build an image.
963 </para></listitem>
964 <listitem><para>
965 <emphasis>Recipe:</emphasis>
966 A set of instructions for building packages.
967 A recipe describes where you get source code, which patches
968 to apply, how to configure the source, how to compile it and so on.
969 Recipes also describe dependencies for libraries or for other
970 recipes.
971 Recipes represent the logical unit of execution, the software
972 to build, the images to build, and use the
973 <filename>.bb</filename> file extension.
974 </para></listitem>
975 <listitem>
976 <para id='source-directory'>
977 <emphasis>Source Directory:</emphasis>
978 This term refers to the directory structure created as a result
979 of creating a local copy of the <filename>poky</filename> Git
980 repository <filename>git://git.yoctoproject.org/poky</filename>
981 or expanding a released <filename>poky</filename> tarball.
982 <note>
983 Creating a local copy of the <filename>poky</filename>
984 Git repository is the recommended method for setting up
985 your Source Directory.
986 </note>
987 Sometimes you might hear the term "poky directory" used to refer
988 to this directory structure.
989 <note>
990 The OpenEmbedded build system does not support file or
991 directory names that contain spaces.
992 Be sure that the Source Directory you use does not contain
993 these types of names.
994 </note></para>
995
996 <para>The Source Directory contains BitBake, Documentation,
997 Metadata and other files that all support the Yocto Project.
998 Consequently, you must have the Source Directory in place on
999 your development system in order to do any development using
1000 the Yocto Project.</para>
1001
1002 <para>When you create a local copy of the Git repository, you
1003 can name the repository anything you like.
1004 Throughout much of the documentation, "poky"
1005 is used as the name of the top-level folder of the local copy of
1006 the poky Git repository.
1007 So, for example, cloning the <filename>poky</filename> Git
1008 repository results in a local Git repository whose top-level
1009 folder is also named "poky".</para>
1010
1011 <para>While it is not recommended that you use tarball expansion
1012 to set up the Source Directory, if you do, the top-level
1013 directory name of the Source Directory is derived from the
1014 Yocto Project release tarball.
1015 For example, downloading and unpacking
1016 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
1017 Source Directory whose root folder is named
1018 <filename>&YOCTO_POKY;</filename>.</para>
1019
1020 <para>It is important to understand the differences between the
1021 Source Directory created by unpacking a released tarball as
1022 compared to cloning
1023 <filename>git://git.yoctoproject.org/poky</filename>.
1024 When you unpack a tarball, you have an exact copy of the files
1025 based on the time of release - a fixed release point.
1026 Any changes you make to your local files in the Source Directory
1027 are on top of the release and will remain local only.
1028 On the other hand, when you clone the <filename>poky</filename>
1029 Git repository, you have an active development repository with
1030 access to the upstream repository's branches and tags.
1031 In this case, any local changes you make to the local
1032 Source Directory can be later applied to active development
1033 branches of the upstream <filename>poky</filename> Git
1034 repository.</para>
1035
1036 <para>For more information on concepts related to Git
1037 repositories, branches, and tags, see the
1038 "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
1039 section in the Yocto Project Development Manual.
1040 </para></listitem>
1041 <listitem><para><emphasis>Task:</emphasis>
1042 A unit of execution for BitBake (e.g.
1043 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
1044 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
1045 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
1046 and so forth).
1047 </para></listitem>
1048 <listitem><para>
1049 <emphasis>Upstream:</emphasis>
1050 A reference to source code or repositories
1051 that are not local to the development system but located in a
1052 master area that is controlled by the maintainer of the source
1053 code.
1054 For example, in order for a developer to work on a particular
1055 piece of code, they need to first get a copy of it from an
1056 "upstream" source.
1057 </para></listitem>
1058 </itemizedlist>
1059 </para>
1060</section>
1061
1053</chapter> 1062</chapter>
1054<!-- 1063<!--
1055vim: expandtab tw=80 ts=4 1064vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 06:53:58 +0000