summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-structure.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-structure.xml')
-rw-r--r--documentation/ref-manual/ref-structure.xml1129
1 files changed, 1129 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
new file mode 100644
index 0000000000..e7ca7b334b
--- /dev/null
+++ b/documentation/ref-manual/ref-structure.xml
@@ -0,0 +1,1129 @@
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-structure'>
6
7<title>Source Directory Structure</title>
8
9<para>
10 The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
11 Understanding them and knowing where they are located is key to using the Yocto Project well.
12 This chapter describes the Source Directory and gives information about the various
13 files and directories.
14</para>
15
16<para>
17 For information on how to establish a local Source Directory on your development system, see the
18 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
19 section in the Yocto Project Development Manual.
20</para>
21
22<note>
23 The OpenEmbedded build system does not support file or directory names that
24 contain spaces.
25 Be sure that the Source Directory you use does not contain these types
26 of names.
27</note>
28
29<section id='structure-core'>
30 <title>Top-Level Core Components</title>
31
32 <para>
33 This section describes the top-level components of the
34 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
35 </para>
36
37 <section id='structure-core-bitbake'>
38 <title><filename>bitbake/</filename></title>
39
40 <para>
41 This directory includes a copy of BitBake for ease of use.
42 The copy usually matches the current stable BitBake release from
43 the BitBake project.
44 BitBake, a
45 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
46 interpreter, reads the Yocto Project Metadata and runs the tasks
47 defined by that data.
48 Failures are usually from the Metadata and not from BitBake itself.
49 Consequently, most users do not need to worry about BitBake.
50 </para>
51
52 <para>
53 When you run the <filename>bitbake</filename> command, the
54 main BitBake executable, which resides in the
55 <filename>bitbake/bin/</filename> directory, starts.
56 Sourcing an environment setup script (e.g.
57 <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
58 or
59 <link linkend="structure-memres-core-script"><filename>oe-init-build-env-memres</filename></link>)
60 places the <filename>scripts</filename> and
61 <filename>bitbake/bin</filename> directories (in that order) into
62 the shell's <filename>PATH</filename> environment variable.
63 </para>
64
65 <para>
66 For more information on BitBake, see the
67 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
68 </para>
69 </section>
70
71 <section id='structure-core-build'>
72 <title><filename>build/</filename></title>
73
74 <para>
75 This directory contains user configuration files and the output
76 generated by the OpenEmbedded build system in its standard configuration where
77 the source tree is combined with the output.
78 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
79 is created initially when you <filename>source</filename>
80 the OpenEmbedded build environment setup script
81 (i.e.
82 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
83 or
84 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
85 </para>
86
87 <para>
88 It is also possible to place output and configuration
89 files in a directory separate from the
90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
91 by providing a directory name when you <filename>source</filename>
92 the setup script.
93 For information on separating output from your local
94 Source Directory files, see the
95 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
96 and
97 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
98 sections.
99 </para>
100 </section>
101
102 <section id='handbook'>
103 <title><filename>documentation/</filename></title>
104
105 <para>
106 This directory holds the source for the Yocto Project documentation
107 as well as templates and tools that allow you to generate PDF and HTML
108 versions of the manuals.
109 Each manual is contained in a sub-folder.
110 For example, the files for this manual reside in
111 the <filename>ref-manual/</filename> directory.
112 </para>
113 </section>
114
115 <section id='structure-core-meta'>
116 <title><filename>meta/</filename></title>
117
118 <para>
119 This directory contains the OpenEmbedded Core metadata.
120 The directory holds recipes, common classes, and machine
121 configuration for emulated targets (<filename>qemux86</filename>,
122 <filename>qemuarm</filename>, and so forth.)
123 </para>
124 </section>
125
126 <section id='structure-core-meta-yocto'>
127 <title><filename>meta-yocto/</filename></title>
128
129 <para>
130 This directory contains the configuration for the Poky
131 reference distribution.
132 </para>
133 </section>
134
135 <section id='structure-core-meta-yocto-bsp'>
136 <title><filename>meta-yocto-bsp/</filename></title>
137
138 <para>
139 This directory contains the Yocto Project reference
140 hardware Board Support Packages (BSPs).
141 For more information on BSPs, see the
142 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
143 Package (BSP) Developer's Guide</ulink>.
144 </para>
145 </section>
146
147 <section id='structure-meta-selftest'>
148 <title><filename>meta-selftest/</filename></title>
149
150 <para>
151 This directory adds additional recipes and append files
152 used by the OpenEmbedded selftests to verify the behavior
153 of the build system.
154 </para>
155
156 <para>
157 You do not have to add this layer to your
158 <filename>bblayers.conf</filename> file unless you want to run the
159 selftests.
160 </para>
161 </section>
162
163 <section id='structure-meta-skeleton'>
164 <title><filename>meta-skeleton/</filename></title>
165
166 <para>
167 This directory contains template recipes for BSP and kernel development.
168 </para>
169 </section>
170
171 <section id='structure-core-scripts'>
172 <title><filename>scripts/</filename></title>
173
174 <para>
175 This directory contains various integration scripts that implement
176 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
177 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
178 and
179 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
180 scripts append this directory to the shell's
181 <filename>PATH</filename> environment variable.
182 </para>
183
184 <para>
185 The <filename>scripts</filename> directory has useful scripts that assist in contributing
186 back to the Yocto Project, such as <filename>create-pull-request</filename> and
187 <filename>send-pull-request</filename>.
188 </para>
189 </section>
190
191 <section id='structure-core-script'>
192 <title><filename>&OE_INIT_FILE;</filename></title>
193
194 <para>
195 This script is one of two scripts that set up the OpenEmbedded build
196 environment.
197 For information on the other script, see the
198 "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
199 section.
200 </para>
201
202 <para>
203 Running this script with the <filename>source</filename> command in
204 a shell makes changes to <filename>PATH</filename> and sets other
205 core BitBake variables based on the current working directory.
206 You need to run an environment setup script before running BitBake
207 commands.
208 The script uses other scripts within the
209 <filename>scripts</filename> directory to do the bulk of the work.
210 </para>
211
212 <para>
213 When you run this script, your Yocto Project environment is set
214 up, a
215 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
216 is created, your working directory becomes the Build Directory,
217 and you are presented with a list of common BitBake targets.
218 Here is an example:
219 <literallayout class='monospaced'>
220 $ source oe-init-build-env
221
222 ### Shell environment set up for builds. ###
223
224 You can now run 'bitbake &lt;target&gt;'
225
226 Common targets are:
227 core-image-minimal
228 core-image-sato
229 meta-toolchain
230 adt-installer
231 meta-ide-support
232
233 You can also run generated qemu images with a command like 'runqemu qemux86'
234 </literallayout>
235 The script gets its default list of common targets from the
236 <filename>conf-notes.txt</filename> file, which is found in the
237 <filename>meta-yocto</filename> directory within the
238 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
239 Should you have custom distributions, it is very easy to modify
240 this configuration file to include your targets for your
241 distribution.
242 See the
243 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
244 section in the Yocto Project Development Manual for more
245 information.
246 </para>
247
248 <para>
249 By default, running this script without a
250 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
251 argument creates the <filename>build</filename> directory
252 in your current working directory.
253 If you provide a Build Directory argument when you
254 <filename>source</filename> the script, you direct the OpenEmbedded
255 build system to create a Build Directory of your choice.
256 For example, the following command creates a Build Directory named
257 <filename>mybuilds</filename> that is outside of the
258 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
259 <literallayout class='monospaced'>
260 $ source &OE_INIT_FILE; ~/mybuilds
261 </literallayout>
262 The OpenEmbedded build system uses the template configuration
263 files, which are found by default in the
264 <filename>meta-yocto/conf</filename> directory in the
265 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
266 See the
267 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
268 section in the Yocto Project Development Manual for more
269 information.
270 <note>
271 The OpenEmbedded build system does not support file or directory names that
272 contain spaces.
273 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
274 from a Source Directory that contains spaces in either the filenames
275 or directory names, the script returns an error indicating no such
276 file or directory.
277 Be sure to use a Source Directory free of names containing spaces.
278 </note>
279 </para>
280 </section>
281
282 <section id='structure-memres-core-script'>
283 <title><filename>oe-init-build-env-memres</filename></title>
284
285 <para>
286 This script is one of two scripts that set up the OpenEmbedded
287 build environment.
288 Aside from setting up the environment, this script starts a
289 memory-resident BitBake server.
290 For information on the other setup script, see the
291 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
292 section.
293 </para>
294
295 <para>
296 Memory-resident BitBake resides in memory until you specifically
297 remove it using the following BitBake command:
298 <literallayout class='monospaced'>
299 $ bitbake -m
300 </literallayout>
301 </para>
302
303 <para>
304 Running this script with the <filename>source</filename> command in
305 a shell makes changes to <filename>PATH</filename> and sets other
306 core BitBake variables based on the current working directory.
307 One of these variables is the
308 <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
309 variable, which allows the OpenEmbedded build system to locate
310 the server that is running BitBake.
311 </para>
312
313 <para>
314 You need to run an environment setup script before using BitBake
315 commands.
316 Following is the script syntax:
317 <literallayout class='monospaced'>
318 $ source oe-init-build-env-memres <replaceable>port_number</replaceable> <replaceable>build_dir</replaceable>
319 </literallayout>
320 The script uses other scripts within the
321 <filename>scripts</filename> directory to do the bulk of the work.
322 </para>
323
324 <para>
325 If you do not provide a port number with the script, the
326 BitBake server at port "12345" is started.
327 </para>
328
329 <para>
330 When you run this script, your Yocto Project environment is set
331 up, a
332 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
333 is created, your working directory becomes the Build Directory,
334 and you are presented with a list of common BitBake targets.
335 Here is an example:
336 <literallayout class='monospaced'>
337 $ source oe-init-build-env-memres
338 No port specified, using dynamically selected port
339
340 ### Shell environment set up for builds. ###
341
342 You can now run 'bitbake &lt;target&gt;'
343
344 Common targets are:
345 core-image-minimal
346 core-image-sato
347 meta-toolchain
348 adt-installer
349 meta-ide-support
350
351 You can also run generated qemu images with a command like 'runqemu qemux86'
352 Bitbake server started on demand as needed, use bitbake -m to shut it down
353 </literallayout>
354 The script gets its default list of common targets from the
355 <filename>conf-notes.txt</filename> file, which is found in the
356 <filename>meta-yocto</filename> directory within the
357 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
358 Should you have custom distributions, it is very easy to modify
359 this configuration file to include your targets for your
360 distribution.
361 See the
362 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
363 section in the Yocto Project Development Manual for more
364 information.
365 </para>
366
367 <para>
368 By default, running this script without a
369 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
370 argument creates a build directory named
371 <filename>build</filename>.
372 If you provide a Build Directory argument when you
373 <filename>source</filename> the script, the Build Directory is
374 created using that name.
375 For example, the following command starts the BitBake server using
376 the default port "12345" and creates a Build Directory named
377 <filename>mybuilds</filename> that is outside of the
378 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
379 <literallayout class='monospaced'>
380 $ source oe-init-build-env-memres ~/mybuilds
381 </literallayout>
382 The OpenEmbedded build system uses the template configuration
383 files, which are found by default in the
384 <filename>meta-yocto/conf</filename> directory in the
385 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
386 See the
387 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
388 section in the Yocto Project Development Manual for more
389 information.
390 <note>
391 The OpenEmbedded build system does not support file or
392 directory names that contain spaces.
393 If you attempt to run the
394 <filename>oe-init-build-env-memres</filename> script
395 from a Source Directory that contains spaces in either the
396 filenames or directory names, the script returns an error
397 indicating no such file or directory.
398 Be sure to use a Source Directory free of names containing
399 spaces.
400 </note>
401 </para>
402 </section>
403
404 <section id='structure-basic-top-level'>
405 <title><filename>LICENSE, README, and README.hardware</filename></title>
406
407 <para>
408 These files are standard top-level files.
409 </para>
410 </section>
411</section>
412
413<section id='structure-build'>
414 <title>The Build Directory - <filename>build/</filename></title>
415
416 <para>
417 The OpenEmbedded build system creates the
418 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
419 when you run one of the build environment setup scripts (i.e.
420 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
421 or
422 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
423 </para>
424
425 <para>
426 If you do not give the Build Directory a specific name when you run
427 a setup script, the name defaults to <filename>build</filename>.
428 </para>
429
430 <para>
431 The
432 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable
433 points to the Build Directory.
434 </para>
435
436 <section id='structure-build-buildhistory'>
437 <title><filename>build/buildhistory</filename></title>
438
439 <para>
440 The OpenEmbedded build system creates this directory when you
441 enable the build history feature.
442 The directory tracks build information into image, packages, and
443 SDK subdirectories.
444 For information on the build history feature, see the
445 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
446 section.
447 </para>
448 </section>
449
450 <section id='structure-build-conf-local.conf'>
451 <title><filename>build/conf/local.conf</filename></title>
452
453 <para>
454 This configuration file contains all the local user configurations
455 for your build environment.
456 The <filename>local.conf</filename> file contains documentation on
457 the various configuration options.
458 Any variable set here overrides any variable set elsewhere within
459 the environment unless that variable is hard-coded within a file
460 (e.g. by using '=' instead of '?=').
461 Some variables are hard-coded for various reasons but these
462 variables are relatively rare.
463 </para>
464
465 <para>
466 Edit this file to set the
467 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
468 for which you want to build, which package types you wish to use
469 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
470 the location from which you want to access downloaded files
471 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
472 and how you want your host machine to use resources
473 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
474 and
475 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
476 </para>
477
478 <para>
479 If <filename>local.conf</filename> is not present when you
480 start the build, the OpenEmbedded build system creates it from
481 <filename>local.conf.sample</filename> when
482 you <filename>source</filename> the top-level build environment
483 setup script (i.e.
484 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
485 or
486 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
487 </para>
488
489 <para>
490 The source <filename>local.conf.sample</filename> file used
491 depends on the <filename>$TEMPLATECONF</filename> script variable,
492 which defaults to <filename>meta-yocto/conf</filename>
493 when you are building from the Yocto Project development
494 environment and defaults to <filename>meta/conf</filename> when
495 you are building from the OpenEmbedded Core environment.
496 Because the script variable points to the source of the
497 <filename>local.conf.sample</filename> file, this implies that
498 you can configure your build environment from any layer by setting
499 the variable in the top-level build environment setup script as
500 follows:
501 <literallayout class='monospaced'>
502 TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
503 </literallayout>
504 Once the build process gets the sample file, it uses
505 <filename>sed</filename> to substitute final
506 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
507 values for all <filename>##OEROOT##</filename> values.
508 <note>
509 You can see how the <filename>TEMPLATECONF</filename> variable
510 is used by looking at the
511 <filename>scripts/oe-setup-builddir</filename> script in the
512 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
513 You can find the Yocto Project version of the
514 <filename>local.conf.sample</filename> file in the
515 <filename>meta-yocto/conf</filename> directory.
516 </note>
517 </para>
518 </section>
519
520 <section id='structure-build-conf-bblayers.conf'>
521 <title><filename>build/conf/bblayers.conf</filename></title>
522
523 <para>
524 This configuration file defines
525 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
526 which are directory trees, traversed (or walked) by BitBake.
527 The <filename>bblayers.conf</filename> file uses the
528 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
529 variable to list the layers BitBake tries to find, and uses the
530 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
531 variable to list layers that must not be removed.
532 </para>
533
534 <para>
535 If <filename>bblayers.conf</filename> is not present when you
536 start the build, the OpenEmbedded build system creates it from
537 <filename>bblayers.conf.sample</filename> when
538 you <filename>source</filename> the top-level build environment
539 setup script (i.e.
540 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
541 or
542 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
543 </para>
544
545 <para>
546 The source <filename>bblayers.conf.sample</filename> file used
547 depends on the <filename>$TEMPLATECONF</filename> script variable,
548 which defaults to <filename>meta-yocto/conf</filename>
549 when you are building from the Yocto Project development
550 environment and defaults to <filename>meta/conf</filename> when
551 you are building from the OpenEmbedded Core environment.
552 Because the script variable points to the source of the
553 <filename>bblayers.conf.sample</filename> file, this implies that
554 you can base your build from any layer by setting the variable in
555 the top-level build environment setup script as follows:
556 <literallayout class='monospaced'>
557 TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
558 </literallayout>
559 Once the build process gets the sample file, it uses
560 <filename>sed</filename> to substitute final
561 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
562 values for all <filename>##OEROOT##</filename> values.
563 <note>
564 You can see how the <filename>TEMPLATECONF</filename> variable
565 <filename>scripts/oe-setup-builddir</filename> script in the
566 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
567 You can find the Yocto Project version of the
568 <filename>bblayers.conf.sample</filename> file in the
569 <filename>meta-yocto/conf</filename> directory.
570 </note>
571 </para>
572 </section>
573
574 <section id='structure-build-conf-sanity_info'>
575 <title><filename>build/conf/sanity_info</filename></title>
576
577 <para>
578 This file indicates the state of the sanity checks and is created
579 during the build.
580 </para>
581 </section>
582
583 <section id='structure-build-downloads'>
584 <title><filename>build/downloads/</filename></title>
585
586 <para>
587 This directory contains downloaded upstream source tarballs.
588 You can reuse the directory for multiple builds or move
589 the directory to another location.
590 You can control the location of this directory through the
591 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
592 </para>
593 </section>
594
595 <section id='structure-build-sstate-cache'>
596 <title><filename>build/sstate-cache/</filename></title>
597
598 <para>
599 This directory contains the shared state cache.
600 You can reuse the directory for multiple builds or move
601 the directory to another location.
602 You can control the location of this directory through the
603 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
604 </para>
605 </section>
606
607 <section id='structure-build-tmp'>
608 <title><filename>build/tmp/</filename></title>
609
610 <para>
611 The OpenEmbedded build system creates and uses this directory
612 for all the build system's output.
613 The
614 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
615 variable points to this directory.
616 </para>
617
618 <para>
619 BitBake creates this directory if it does not exist.
620 As a last resort, to clean up a build and start it from scratch
621 (other than the downloads), you can remove everything in the
622 <filename>tmp</filename> directory or get rid of the
623 directory completely.
624 If you do, you should also completely remove the
625 <filename>build/sstate-cache</filename> directory.
626 </para>
627 </section>
628
629 <section id='structure-build-tmp-buildstats'>
630 <title><filename>build/tmp/buildstats/</filename></title>
631
632 <para>
633 This directory stores the build statistics.
634 </para>
635 </section>
636
637 <section id='structure-build-tmp-cache'>
638 <title><filename>build/tmp/cache/</filename></title>
639
640 <para>
641 When BitBake parses the metadata, it creates a cache file of the result that can
642 be used when subsequently running commands.
643 BitBake stores these results here on a per-machine basis.
644 </para>
645 </section>
646
647 <section id='structure-build-tmp-deploy'>
648 <title><filename>build/tmp/deploy/</filename></title>
649
650 <para>
651 This directory contains any "end result" output from the
652 OpenEmbedded build process.
653 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
654 variable points to this directory.
655 For more detail on the contents of the <filename>deploy</filename>
656 directory, see the
657 "<link linkend='images-dev-environment'>Images</link>" and
658 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
659 sections.
660 </para>
661 </section>
662
663 <section id='structure-build-tmp-deploy-deb'>
664 <title><filename>build/tmp/deploy/deb/</filename></title>
665
666 <para>
667 This directory receives any <filename>.deb</filename> packages produced by
668 the build process.
669 The packages are sorted into feeds for different architecture types.
670 </para>
671 </section>
672
673 <section id='structure-build-tmp-deploy-rpm'>
674 <title><filename>build/tmp/deploy/rpm/</filename></title>
675
676 <para>
677 This directory receives any <filename>.rpm</filename> packages produced by
678 the build process.
679 The packages are sorted into feeds for different architecture types.
680 </para>
681 </section>
682
683 <section id='structure-build-tmp-deploy-ipk'>
684 <title><filename>build/tmp/deploy/ipk/</filename></title>
685
686 <para>
687 This directory receives <filename>.ipk</filename> packages produced by
688 the build process.
689 </para>
690 </section>
691
692 <section id='structure-build-tmp-deploy-licenses'>
693 <title><filename>build/tmp/deploy/licenses/</filename></title>
694
695 <para>
696 This directory receives package licensing information.
697 For example, the directory contains sub-directories for <filename>bash</filename>,
698 <filename>busybox</filename>, and <filename>glibc</filename> (among others) that in turn
699 contain appropriate <filename>COPYING</filename> license files with other licensing information.
700 For information on licensing, see the
701 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
702 section.
703 </para>
704 </section>
705
706 <section id='structure-build-tmp-deploy-images'>
707 <title><filename>build/tmp/deploy/images/</filename></title>
708
709 <para>
710 This directory receives complete filesystem images.
711 If you want to flash the resulting image from a build onto a device, look here for the image.
712 </para>
713
714 <para>
715 Be careful when deleting files in this directory.
716 You can safely delete old images from this directory (e.g.
717 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
718 etc.).
719 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
720 bootloader and other supplementary files might be deployed here prior to building an
721 image.
722 Because these files are not directly produced from the image, if you
723 delete them they will not be automatically re-created when you build the image again.
724 </para>
725
726 <para>
727 If you do accidentally delete files here, you will need to force them to be
728 re-created.
729 In order to do that, you will need to know the target that produced them.
730 For example, these commands rebuild and re-create the kernel files:
731 <literallayout class='monospaced'>
732 $ bitbake -c clean virtual/kernel
733 $ bitbake virtual/kernel
734 </literallayout>
735 </para>
736 </section>
737
738 <section id='structure-build-tmp-deploy-sdk'>
739 <title><filename>build/tmp/deploy/sdk/</filename></title>
740
741 <para>
742 The OpenEmbedded build system creates this directory to hold
743 toolchain installer scripts, which when executed, install the
744 sysroot that matches your target hardware.
745 You can find out more about these installers in the
746 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
747 section in the Yocto Project Application Developer's Guide.
748 </para>
749 </section>
750
751 <section id='structure-build-tmp-sstate-control'>
752 <title><filename>build/tmp/sstate-control/</filename></title>
753
754 <para>
755 The OpenEmbedded build system uses this directory for the
756 shared state manifest files.
757 The shared state code uses these files to record the files
758 installed by each sstate task so that the files can be removed
759 when cleaning the recipe or when a newer version is about to
760 be installed.
761 The build system also uses the manifests to detect and produce
762 a warning when files from one task are overwriting those from
763 another.
764 </para>
765 </section>
766
767 <section id='structure-build-tmp-sysroots'>
768 <title><filename>build/tmp/sysroots/</filename></title>
769
770 <para>
771 This directory contains shared header files and libraries as well as other shared
772 data.
773 Packages that need to share output with other packages do so within this directory.
774 The directory is subdivided by architecture so multiple builds can run within
775 the one Build Directory.
776 </para>
777 </section>
778
779 <section id='structure-build-tmp-stamps'>
780 <title><filename>build/tmp/stamps/</filename></title>
781
782 <para>
783 This directory holds information that BitBake uses for accounting purposes
784 to track what tasks have run and when they have run.
785 The directory is sub-divided by architecture, package name, and
786 version.
787 Following is an example:
788 <literallayout class='monospaced'>
789 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
790 </literallayout>
791 Although the files in the directory are empty of data,
792 BitBake uses the filenames and timestamps for tracking purposes.
793 </para>
794 </section>
795
796 <section id='structure-build-tmp-log'>
797 <title><filename>build/tmp/log/</filename></title>
798
799 <para>
800 This directory contains general logs that are not otherwise placed using the
801 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
802 Examples of logs are the output from the
803 <filename>do_check_pkg</filename> or
804 <filename>do_distro_check</filename> tasks.
805 Running a build does not necessarily mean this directory is created.
806 </para>
807 </section>
808
809 <section id='structure-build-tmp-work'>
810 <title><filename>build/tmp/work/</filename></title>
811
812 <para>
813 This directory contains architecture-specific work sub-directories
814 for packages built by BitBake.
815 All tasks execute from the appropriate work directory.
816 For example, the source for a particular package is unpacked,
817 patched, configured and compiled all within its own work directory.
818 Within the work directory, organization is based on the package group
819 and version for which the source is being compiled
820 as defined by the
821 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
822 </para>
823
824 <para>
825 It is worth considering the structure of a typical work directory.
826 As an example, consider <filename>linux-yocto-kernel-3.0</filename>
827 on the machine <filename>qemux86</filename>
828 built within the Yocto Project.
829 For this package, a work directory of
830 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
831 referred to as the
832 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
833 Within this directory, the source is unpacked to
834 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
835 (See the
836 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>"
837 section in the Yocto Project Development Manual for more information.)
838 Within the <filename>linux-qemux86-standard-build</filename> directory,
839 standard Quilt directories <filename>linux-3.0/patches</filename>
840 and <filename>linux-3.0/.pc</filename> are created,
841 and standard Quilt commands can be used.
842 </para>
843
844 <para>
845 There are other directories generated within <filename>WORKDIR</filename>.
846 The most important directory is <filename>WORKDIR/temp/</filename>,
847 which has log files for each task (<filename>log.do_*.pid</filename>)
848 and contains the scripts BitBake runs for each task
849 (<filename>run.do_*.pid</filename>).
850 The <filename>WORKDIR/image/</filename> directory is where "make
851 install" places its output that is then split into sub-packages
852 within <filename>WORKDIR/packages-split/</filename>.
853 </para>
854 </section>
855
856 <section id='structure-build-work-shared'>
857 <title><filename>build/tmp/work-shared/</filename></title>
858
859 <para>
860 For efficiency, the OpenEmbedded build system creates and uses
861 this directory to hold recipes that share a work directory with
862 other recipes.
863 In practice, this is only used for <filename>gcc</filename>
864 and its variants (e.g. <filename>gcc-cross</filename>,
865 <filename>libgcc</filename>, <filename>gcc-runtime</filename>,
866 and so forth).
867 </para>
868 </section>
869</section>
870
871<section id='structure-meta'>
872 <title>The Metadata - <filename>meta/</filename></title>
873
874 <para>
875 As mentioned previously,
876 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core
877 of the Yocto Project.
878 Metadata has several important subdivisions:
879 </para>
880
881 <section id='structure-meta-classes'>
882 <title><filename>meta/classes/</filename></title>
883
884 <para>
885 This directory contains the <filename>*.bbclass</filename> files.
886 Class files are used to abstract common code so it can be reused by multiple
887 packages.
888 Every package inherits the <filename>base.bbclass</filename> file.
889 Examples of other important classes are <filename>autotools.bbclass</filename>, which
890 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
891 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
892 for working with the Linux kernel.
893 Functions like image generation or packaging also have their specific class files
894 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
895 <filename>package*.bbclass</filename>.
896 </para>
897
898 <para>
899 For reference information on classes, see the
900 "<link linkend='ref-classes'>Classes</link>" chapter.
901 </para>
902 </section>
903
904 <section id='structure-meta-conf'>
905 <title><filename>meta/conf/</filename></title>
906
907 <para>
908 This directory contains the core set of configuration files that start from
909 <filename>bitbake.conf</filename> and from which all other configuration
910 files are included.
911 See the include statements at the end of the
912 <filename>bitbake.conf</filename> file and you will note that even
913 <filename>local.conf</filename> is loaded from there.
914 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
915 these by using the (<filename>local.conf</filename>) file, machine file or
916 the distribution configuration file.
917 </para>
918 </section>
919
920 <section id='structure-meta-conf-machine'>
921 <title><filename>meta/conf/machine/</filename></title>
922
923 <para>
924 This directory contains all the machine configuration files.
925 If you set <filename>MACHINE = "qemux86"</filename>,
926 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
927 directory.
928 The <filename>include</filename> directory contains various data common to multiple machines.
929 If you want to add support for a new machine to the Yocto Project, look in this directory.
930 </para>
931 </section>
932
933 <section id='structure-meta-conf-distro'>
934 <title><filename>meta/conf/distro/</filename></title>
935
936 <para>
937 The contents of this directory controls any distribution-specific
938 configurations.
939 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
940 This directory includes the versions and the
941 <filename>SRCDATE</filename> definitions for applications that are configured here.
942 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
943 Although this file mainly inherits its configuration from Poky.
944 </para>
945 </section>
946
947 <section id='structure-meta-conf-machine-sdk'>
948 <title><filename>meta/conf/machine-sdk/</filename></title>
949
950 <para>
951 The OpenEmbedded build system searches this directory for
952 configuration files that correspond to the value of
953 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
954 By default, 32-bit and 64-bit x86 files ship with the Yocto
955 Project that support some SDK hosts.
956 However, it is possible to extend that support to other SDK hosts
957 by adding additional configuration files in this subdirectory
958 within another layer.
959 </para>
960 </section>
961
962 <section id='structure-meta-files'>
963 <title><filename>meta/files/</filename></title>
964
965 <para>
966 This directory contains common license files and several text files
967 used by the build system.
968 The text files contain minimal device information and
969 lists of files and directories with known permissions.
970 </para>
971 </section>
972
973 <section id='structure-meta-lib'>
974 <title><filename>meta/lib/</filename></title>
975
976 <para>
977 This directory contains OpenEmbedded Python library code
978 used during the build process.
979 </para>
980 </section>
981
982 <section id='structure-meta-recipes-bsp'>
983 <title><filename>meta/recipes-bsp/</filename></title>
984
985 <para>
986 This directory contains anything linking to specific hardware or hardware
987 configuration information such as "u-boot" and "grub".
988 </para>
989 </section>
990
991 <section id='structure-meta-recipes-connectivity'>
992 <title><filename>meta/recipes-connectivity/</filename></title>
993
994 <para>
995 This directory contains libraries and applications related to communication with other devices.
996 </para>
997 </section>
998
999 <section id='structure-meta-recipes-core'>
1000 <title><filename>meta/recipes-core/</filename></title>
1001
1002 <para>
1003 This directory contains what is needed to build a basic working Linux image
1004 including commonly used dependencies.
1005 </para>
1006 </section>
1007
1008 <section id='structure-meta-recipes-devtools'>
1009 <title><filename>meta/recipes-devtools/</filename></title>
1010
1011 <para>
1012 This directory contains tools that are primarily used by the build system.
1013 The tools, however, can also be used on targets.
1014 </para>
1015 </section>
1016
1017 <section id='structure-meta-recipes-extended'>
1018 <title><filename>meta/recipes-extended/</filename></title>
1019
1020 <para>
1021 This directory contains non-essential applications that add features compared to the
1022 alternatives in core.
1023 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
1024 compliance.
1025 </para>
1026 </section>
1027
1028 <section id='structure-meta-recipes-gnome'>
1029 <title><filename>meta/recipes-gnome/</filename></title>
1030
1031 <para>
1032 This directory contains all things related to the GTK+ application framework.
1033 </para>
1034 </section>
1035
1036 <section id='structure-meta-recipes-graphics'>
1037 <title><filename>meta/recipes-graphics/</filename></title>
1038
1039 <para>
1040 This directory contains X and other graphically related system libraries
1041 </para>
1042 </section>
1043
1044 <section id='structure-meta-recipes-kernel'>
1045 <title><filename>meta/recipes-kernel/</filename></title>
1046
1047 <para>
1048 This directory contains the kernel and generic applications and libraries that
1049 have strong kernel dependencies.
1050 </para>
1051 </section>
1052
1053 <section id='structure-meta-recipes-lsb4'>
1054 <title><filename>meta/recipes-lsb4/</filename></title>
1055
1056 <para>
1057 This directory contains recipes specifically added to support
1058 the Linux Standard Base (LSB) version 4.x.
1059 </para>
1060 </section>
1061
1062 <section id='structure-meta-recipes-multimedia'>
1063 <title><filename>meta/recipes-multimedia/</filename></title>
1064
1065 <para>
1066 This directory contains codecs and support utilities for audio, images and video.
1067 </para>
1068 </section>
1069
1070 <section id='structure-meta-recipes-qt'>
1071 <title><filename>meta/recipes-qt/</filename></title>
1072
1073 <para>
1074 This directory contains all things related to the Qt application framework.
1075 </para>
1076 </section>
1077
1078 <section id='structure-meta-recipes-rt'>
1079 <title><filename>meta/recipes-rt/</filename></title>
1080
1081 <para>
1082 This directory contains package and image recipes for using and testing
1083 the <filename>PREEMPT_RT</filename> kernel.
1084 </para>
1085 </section>
1086
1087 <section id='structure-meta-recipes-sato'>
1088 <title><filename>meta/recipes-sato/</filename></title>
1089
1090 <para>
1091 This directory contains the Sato demo/reference UI/UX and its associated applications
1092 and configuration data.
1093 </para>
1094 </section>
1095
1096 <section id='structure-meta-recipes-support'>
1097 <title><filename>meta/recipes-support/</filename></title>
1098
1099 <para>
1100 This directory contains recipes used by other recipes, but that are
1101 not directly included in images (i.e. dependencies of other
1102 recipes).
1103 </para>
1104 </section>
1105
1106 <section id='structure-meta-site'>
1107 <title><filename>meta/site/</filename></title>
1108
1109 <para>
1110 This directory contains a list of cached results for various architectures.
1111 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1112 the tests not able to run on a live system, the information in this directory is
1113 passed to "autoconf" for the various architectures.
1114 </para>
1115 </section>
1116
1117 <section id='structure-meta-recipes-txt'>
1118 <title><filename>meta/recipes.txt</filename></title>
1119
1120 <para>
1121 This file is a description of the contents of <filename>recipes-*</filename>.
1122 </para>
1123 </section>
1124</section>
1125
1126</chapter>
1127<!--
1128vim: expandtab tw=80 ts=4
1129-->