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