summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/ref-structure.xml126
1 files changed, 63 insertions, 63 deletions
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 08699d8ec4..27f17dd919 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -8,11 +8,11 @@
8 8
9<para> 9<para>
10 The <link linkend='source-directory'>Source Directory</link> 10 The <link linkend='source-directory'>Source Directory</link>
11 consists of several components. 11 consists of numerous files, directories and subdirectories;
12 Understanding them and knowing where they are located is key to using the 12 understanding their locations and contents is key to using the
13 Yocto Project well. 13 Yocto Project effectively.
14 This chapter describes the Source Directory and gives information about 14 This chapter describes the Source Directory and gives information about
15 the various files and directories. 15 those files and directories.
16</para> 16</para>
17 17
18<para> 18<para>
@@ -22,12 +22,12 @@
22 section in the Yocto Project Development Tasks Manual. 22 section in the Yocto Project Development Tasks Manual.
23</para> 23</para>
24 24
25<note> 25 <note>
26 The OpenEmbedded build system does not support file or directory names that 26 The OpenEmbedded build system does not support file or directory names that
27 contain spaces. 27 contain spaces.
28 Be sure that the Source Directory you use does not contain these types 28 Be sure that the Source Directory you use does not contain these types
29 of names. 29 of names.
30</note> 30 </note>
31 31
32<section id='structure-core'> 32<section id='structure-core'>
33 <title>Top-Level Core Components</title> 33 <title>Top-Level Core Components</title>
@@ -48,18 +48,18 @@
48 <link linkend='metadata'>Metadata</link> 48 <link linkend='metadata'>Metadata</link>
49 interpreter, reads the Yocto Project Metadata and runs the tasks 49 interpreter, reads the Yocto Project Metadata and runs the tasks
50 defined by that data. 50 defined by that data.
51 Failures are usually from the Metadata and not from BitBake itself. 51 Failures are usually caused by errors in your Metadata and not from BitBake itself;
52 Consequently, most users do not need to worry about BitBake. 52 consequently, most users do not need to worry about BitBake.
53 </para> 53 </para>
54 54
55 <para> 55 <para>
56 When you run the <filename>bitbake</filename> command, the 56 When you run the <filename>bitbake</filename> command, the
57 main BitBake executable, which resides in the 57 main BitBake executable (which resides in the
58 <filename>bitbake/bin/</filename> directory, starts. 58 <filename>bitbake/bin/</filename> directory) starts.
59 Sourcing the environment setup script (i.e. 59 Sourcing the environment setup script (i.e.
60 <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>) 60 <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>)
61 places the <filename>scripts</filename> and 61 places the <filename>scripts/</filename> and
62 <filename>bitbake/bin</filename> directories (in that order) into 62 <filename>bitbake/bin/</filename> directories (in that order) into
63 the shell's <filename>PATH</filename> environment variable. 63 the shell's <filename>PATH</filename> environment variable.
64 </para> 64 </para>
65 65
@@ -91,7 +91,7 @@
91 by providing a directory name when you <filename>source</filename> 91 by providing a directory name when you <filename>source</filename>
92 the setup script. 92 the setup script.
93 For information on separating output from your local 93 For information on separating output from your local
94 Source Directory files, see the 94 Source Directory files (commonly described as an "out of tree" build), see the
95 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>" 95 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
96 section. 96 section.
97 </para> 97 </para>
@@ -104,8 +104,8 @@
104 This directory holds the source for the Yocto Project documentation 104 This directory holds the source for the Yocto Project documentation
105 as well as templates and tools that allow you to generate PDF and HTML 105 as well as templates and tools that allow you to generate PDF and HTML
106 versions of the manuals. 106 versions of the manuals.
107 Each manual is contained in a sub-folder. 107 Each manual is contained in its own sub-folder;
108 For example, the files for this manual reside in 108 for example, the files for this reference manual reside in
109 the <filename>ref-manual/</filename> directory. 109 the <filename>ref-manual/</filename> directory.
110 </para> 110 </para>
111 </section> 111 </section>
@@ -114,9 +114,9 @@
114 <title><filename>meta/</filename></title> 114 <title><filename>meta/</filename></title>
115 115
116 <para> 116 <para>
117 This directory contains the OpenEmbedded-Core metadata. 117 This directory contains the minimal, underlying OpenEmbedded-Core metadata.
118 The directory holds recipes, common classes, and machine 118 The directory holds recipes, common classes, and machine
119 configuration for emulated targets (<filename>qemux86</filename>, 119 configuration for strictly emulated targets (<filename>qemux86</filename>,
120 <filename>qemuarm</filename>, and so forth.) 120 <filename>qemuarm</filename>, and so forth.)
121 </para> 121 </para>
122 </section> 122 </section>
@@ -125,8 +125,8 @@
125 <title><filename>meta-poky/</filename></title> 125 <title><filename>meta-poky/</filename></title>
126 126
127 <para> 127 <para>
128 This directory contains the configuration for the Poky 128 Designed above the <filename>meta/</filename> content, this directory
129 reference distribution. 129 adds just enough metadata to define the Poky reference distribution.
130 </para> 130 </para>
131 </section> 131 </section>
132 132
@@ -148,9 +148,6 @@
148 This directory adds additional recipes and append files 148 This directory adds additional recipes and append files
149 used by the OpenEmbedded selftests to verify the behavior 149 used by the OpenEmbedded selftests to verify the behavior
150 of the build system. 150 of the build system.
151 </para>
152
153 <para>
154 You do not have to add this layer to your 151 You do not have to add this layer to your
155 <filename>bblayers.conf</filename> file unless you want to run the 152 <filename>bblayers.conf</filename> file unless you want to run the
156 selftests. 153 selftests.
@@ -172,7 +169,7 @@
172 This directory contains various integration scripts that implement 169 This directory contains various integration scripts that implement
173 extra functionality in the Yocto Project environment (e.g. QEMU scripts). 170 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
174 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link> 171 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
175 script appends this directory to the shell's 172 script prepends this directory to the shell's
176 <filename>PATH</filename> environment variable. 173 <filename>PATH</filename> environment variable.
177 </para> 174 </para>
178 175
@@ -202,7 +199,8 @@
202 up, a 199 up, a
203 <link linkend='build-directory'>Build Directory</link> 200 <link linkend='build-directory'>Build Directory</link>
204 is created, your working directory becomes the Build Directory, 201 is created, your working directory becomes the Build Directory,
205 and you are presented with a list of common BitBake targets. 202 and you are presented with some simple suggestions as to what to do
203 next, including a list of some possible targets to build.
206 Here is an example: 204 Here is an example:
207 <literallayout class='monospaced'> 205 <literallayout class='monospaced'>
208 $ source oe-init-build-env 206 $ source oe-init-build-env
@@ -219,12 +217,12 @@
219 217
220 You can also run generated qemu images with a command like 'runqemu qemux86-64' 218 You can also run generated qemu images with a command like 'runqemu qemux86-64'
221 </literallayout> 219 </literallayout>
222 The script gets its default list of common targets from the 220 The default output of the <filename>oe-init-build-env</filename> script
223 <filename>conf-notes.txt</filename> file, which is found in the 221 is from the <filename>conf-notes.txt</filename> file, which is found in the
224 <filename>meta-poky</filename> directory within the 222 <filename>meta-poky</filename> directory within the
225 <link linkend='source-directory'>Source Directory</link>. 223 <link linkend='source-directory'>Source Directory</link>.
226 Should you have custom distributions, it is very easy to modify 224 If you design a custom distribution, you can include your own version
227 this configuration file to include your targets for your 225 of this configuration file to mention the targets defined by your
228 distribution. 226 distribution.
229 See the 227 See the
230 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" 228 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
@@ -234,20 +232,20 @@
234 232
235 <para> 233 <para>
236 By default, running this script without a Build Directory 234 By default, running this script without a Build Directory
237 argument creates the <filename>build</filename> directory 235 argument creates the <filename>build/</filename> directory
238 in your current working directory. 236 in your current working directory.
239 If you provide a Build Directory argument when you 237 If you provide a Build Directory argument when you
240 <filename>source</filename> the script, you direct the OpenEmbedded 238 <filename>source</filename> the script, you direct the OpenEmbedded
241 build system to create a Build Directory of your choice. 239 build system to create a Build Directory of your choice.
242 For example, the following command creates a Build Directory named 240 For example, the following command creates a Build Directory named
243 <filename>mybuilds</filename> that is outside of the 241 <filename>mybuilds/</filename> that is outside of the
244 <link linkend='source-directory'>Source Directory</link>: 242 <link linkend='source-directory'>Source Directory</link>:
245 <literallayout class='monospaced'> 243 <literallayout class='monospaced'>
246 $ source &OE_INIT_FILE; ~/mybuilds 244 $ source &OE_INIT_FILE; ~/mybuilds
247 </literallayout> 245 </literallayout>
248 The OpenEmbedded build system uses the template configuration 246 The OpenEmbedded build system uses the template configuration
249 files, which are found by default in the 247 files, which are found by default in the
250 <filename>meta-poky/conf</filename> directory in the 248 <filename>meta-poky/conf/</filename> directory in the
251 Source Directory. 249 Source Directory.
252 See the 250 See the
253 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" 251 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
@@ -280,28 +278,26 @@
280 <para> 278 <para>
281 The OpenEmbedded build system creates the 279 The OpenEmbedded build system creates the
282 <link linkend='build-directory'>Build Directory</link> 280 <link linkend='build-directory'>Build Directory</link>
283 when you run the build environment setup scripts (i.e. 281 when you run the build environment setup script
284 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). 282 <link
285 </para> 283linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
286
287 <para>
288 If you do not give the Build Directory a specific name when you run 284 If you do not give the Build Directory a specific name when you run
289 a setup script, the name defaults to <filename>build</filename>. 285 the setup script, the name defaults to <filename>build/</filename>.
290 </para> 286 </para>
291 287
292 <para> 288 <para>
293 The 289 For subsequent parsing and processing, the name of the Build
294 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable 290 directory is available via the
295 points to the Build Directory. 291 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable.
296 </para> 292 </para>
297 293
298 <section id='structure-build-buildhistory'> 294 <section id='structure-build-buildhistory'>
299 <title><filename>build/buildhistory</filename></title> 295 <title><filename>build/buildhistory/</filename></title>
300 296
301 <para> 297 <para>
302 The OpenEmbedded build system creates this directory when you 298 The OpenEmbedded build system creates this directory when you
303 enable the build history feature. 299 enable build history via the <filename>buildhistory</filename> class file.
304 The directory tracks build information into image, packages, and 300 The directory organizes build information into image, packages, and
305 SDK subdirectories. 301 SDK subdirectories.
306 For information on the build history feature, see the 302 For information on the build history feature, see the
307 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" 303 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
@@ -320,14 +316,14 @@
320 Any variable set here overrides any variable set elsewhere within 316 Any variable set here overrides any variable set elsewhere within
321 the environment unless that variable is hard-coded within a file 317 the environment unless that variable is hard-coded within a file
322 (e.g. by using '=' instead of '?='). 318 (e.g. by using '=' instead of '?=').
323 Some variables are hard-coded for various reasons but these 319 Some variables are hard-coded for various reasons but such
324 variables are relatively rare. 320 variables are relatively rare.
325 </para> 321 </para>
326 322
327 <para> 323 <para>
328 Edit this file to set the 324 At a minimum, you would normally edit this file to select the target
329 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> 325 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>,
330 for which you want to build, which package types you wish to use 326 which package types you wish to use
331 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), 327 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
332 and the location from which you want to access downloaded files 328 and the location from which you want to access downloaded files
333 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>). 329 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>).
@@ -338,16 +334,16 @@
338 start the build, the OpenEmbedded build system creates it from 334 start the build, the OpenEmbedded build system creates it from
339 <filename>local.conf.sample</filename> when 335 <filename>local.conf.sample</filename> when
340 you <filename>source</filename> the top-level build environment 336 you <filename>source</filename> the top-level build environment
341 setup script (i.e. 337 setup script
342 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). 338 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
343 </para> 339 </para>
344 340
345 <para> 341 <para>
346 The source <filename>local.conf.sample</filename> file used 342 The source <filename>local.conf.sample</filename> file used
347 depends on the <filename>$TEMPLATECONF</filename> script variable, 343 depends on the <filename>$TEMPLATECONF</filename> script variable,
348 which defaults to <filename>meta-poky/conf</filename> 344 which defaults to <filename>meta-poky/conf/</filename>
349 when you are building from the Yocto Project development 345 when you are building from the Yocto Project development
350 environment and defaults to <filename>meta/conf</filename> when 346 environment, and to <filename>meta/conf/</filename> when
351 you are building from the OpenEmbedded-Core environment. 347 you are building from the OpenEmbedded-Core environment.
352 Because the script variable points to the source of the 348 Because the script variable points to the source of the
353 <filename>local.conf.sample</filename> file, this implies that 349 <filename>local.conf.sample</filename> file, this implies that
@@ -395,11 +391,12 @@
395 </para> 391 </para>
396 392
397 <para> 393 <para>
398 The source <filename>bblayers.conf.sample</filename> file used 394 As with the <filename>local.conf</filename> file,
395 the source <filename>bblayers.conf.sample</filename> file used
399 depends on the <filename>$TEMPLATECONF</filename> script variable, 396 depends on the <filename>$TEMPLATECONF</filename> script variable,
400 which defaults to <filename>meta-poky/conf</filename> 397 which defaults to <filename>meta-poky/conf/</filename>
401 when you are building from the Yocto Project development 398 when you are building from the Yocto Project development
402 environment and defaults to <filename>meta/conf</filename> when 399 environment, and to <filename>meta/conf/</filename> when
403 you are building from the OpenEmbedded-Core environment. 400 you are building from the OpenEmbedded-Core environment.
404 Because the script variable points to the source of the 401 Because the script variable points to the source of the
405 <filename>bblayers.conf.sample</filename> file, this implies that 402 <filename>bblayers.conf.sample</filename> file, this implies that
@@ -418,7 +415,7 @@
418 <link linkend='source-directory'>Source Directory</link>. 415 <link linkend='source-directory'>Source Directory</link>.
419 You can find the Yocto Project version of the 416 You can find the Yocto Project version of the
420 <filename>bblayers.conf.sample</filename> file in the 417 <filename>bblayers.conf.sample</filename> file in the
421 <filename>meta-poky/conf</filename> directory. 418 <filename>meta-poky/conf/</filename> directory.
422 </note> 419 </note>
423 </para> 420 </para>
424 </section> 421 </section>
@@ -572,8 +569,11 @@
572 <title><filename>build/tmp/deploy/images/</filename></title> 569 <title><filename>build/tmp/deploy/images/</filename></title>
573 570
574 <para> 571 <para>
575 This directory receives complete filesystem images. 572 This directory is populated with the basic output objects of the
576 If you want to flash the resulting image from a build onto a device, look here for the image. 573 build (think of them as the "generated artifacts" of the build process),
574 including things like the boot loader image, kernel, root filesystem and more.
575 If you want to flash the resulting image from a build onto a device,
576 look here for the necessary components.
577 </para> 577 </para>
578 578
579 <para> 579 <para>
@@ -604,7 +604,7 @@
604 604
605 <para> 605 <para>
606 The OpenEmbedded build system creates this directory to hold 606 The OpenEmbedded build system creates this directory to hold
607 toolchain installer scripts, which when executed, install the 607 toolchain installer scripts which, when executed, install the
608 sysroot that matches your target hardware. 608 sysroot that matches your target hardware.
609 You can find out more about these installers in the 609 You can find out more about these installers in the
610 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" 610 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
@@ -1038,7 +1038,7 @@
1038 <title><filename>meta/recipes-graphics/</filename></title> 1038 <title><filename>meta/recipes-graphics/</filename></title>
1039 1039
1040 <para> 1040 <para>
1041 This directory contains X and other graphically related system libraries 1041 This directory contains X and other graphically related system libraries.
1042 </para> 1042 </para>
1043 </section> 1043 </section>
1044 1044