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