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