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