summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/structure.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/structure.rst')
-rw-r--r--documentation/ref-manual/structure.rst231
1 files changed, 114 insertions, 117 deletions
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index ad3f4ab44a..e4d8b54bb9 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -38,7 +38,7 @@ usually matches the current stable BitBake release from the BitBake
38project. BitBake, a :term:`Metadata` interpreter, reads the 38project. BitBake, a :term:`Metadata` interpreter, reads the
39Yocto Project Metadata and runs the tasks defined by that data. Failures 39Yocto Project Metadata and runs the tasks defined by that data. Failures
40are usually caused by errors in your Metadata and not from BitBake 40are usually caused by errors in your Metadata and not from BitBake
41itself; consequently, most users do not need to worry about BitBake. 41itself.
42 42
43When you run the ``bitbake`` command, the main BitBake executable (which 43When you run the ``bitbake`` command, the main BitBake executable (which
44resides in the ``bitbake/bin/`` directory) starts. Sourcing the 44resides in the ``bitbake/bin/`` directory) starts. Sourcing the
@@ -57,9 +57,8 @@ For more information on BitBake, see the :doc:`BitBake User Manual
57This directory contains user configuration files and the output 57This directory contains user configuration files and the output
58generated by the OpenEmbedded build system in its standard configuration 58generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory` 59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source`` 60is created initially when you ``source`` the OpenEmbedded build environment
61the OpenEmbedded build environment setup script (i.e. 61setup script (i.e. :ref:`structure-core-script`).
62:ref:`structure-core-script`).
63 62
64It is also possible to place output and configuration files in a 63It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by 64directory separate from the :term:`Source Directory` by
@@ -68,6 +67,9 @@ information on separating output from your local Source Directory files
68(commonly described as an "out of tree" build), see the 67(commonly described as an "out of tree" build), see the
69":ref:`structure-core-script`" section. 68":ref:`structure-core-script`" section.
70 69
70See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details
71about the contents of the :term:`Build Directory`.
72
71.. _handbook: 73.. _handbook:
72 74
73``documentation/`` 75``documentation/``
@@ -150,11 +152,10 @@ BitBake commands. The script uses other scripts within the ``scripts``
150directory to do the bulk of the work. 152directory to do the bulk of the work.
151 153
152When you run this script, your Yocto Project environment is set up, a 154When you run this script, your Yocto Project environment is set up, a
153:term:`Build Directory` is created, your working 155:term:`Build Directory` is created, your working directory becomes the
154directory becomes the Build Directory, and you are presented with some 156:term:`Build Directory`, and you are presented with some simple
155simple suggestions as to what to do next, including a list of some 157suggestions as to what to do next, including a list of some possible
156possible targets to build. Here is an example: 158targets to build. Here is an example::
157::
158 159
159 $ source oe-init-build-env 160 $ source oe-init-build-env
160 161
@@ -168,32 +169,33 @@ possible targets to build. Here is an example:
168 meta-toolchain 169 meta-toolchain
169 meta-ide-support 170 meta-ide-support
170 171
171 You can also run generated qemu images with a command like 'runqemu qemux86-64' 172 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
172 173
173The default output of the ``oe-init-build-env`` script is from the 174The default output of the ``oe-init-build-env`` script is from the
174``conf-notes.txt`` file, which is found in the ``meta-poky`` directory 175``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the ``meta-poky`` directory
175within the :term:`Source Directory`. If you design a 176within the :term:`Source Directory`. If you design a
176custom distribution, you can include your own version of this 177custom distribution, you can include your own versions of these
177configuration file to mention the targets defined by your distribution. 178configuration files where you can provide a brief summary and detailed usage
179notes, such as a list of the targets defined by your distribution.
178See the 180See the
179":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" 181":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
180section in the Yocto Project Development Tasks Manual for more 182section in the Yocto Project Development Tasks Manual for more
181information. 183information.
182 184
183By default, running this script without a Build Directory argument 185By default, running this script without a :term:`Build Directory` argument
184creates the ``build/`` directory in your current working directory. If 186creates the ``build/`` directory in your current working directory. If
185you provide a Build Directory argument when you ``source`` the script, 187you provide a :term:`Build Directory` argument when you ``source`` the script,
186you direct the OpenEmbedded build system to create a Build Directory of 188you direct the OpenEmbedded build system to create a :term:`Build Directory` of
187your choice. For example, the following command creates a Build 189your choice. For example, the following command creates a
188Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: 190:term:`Build Directory` named ``mybuilds/`` that is outside of the
189:: 191:term:`Source Directory`::
190 192
191 $ source oe-init-build-env ~/mybuilds 193 $ source oe-init-build-env ~/mybuilds
192 194
193The OpenEmbedded build system uses the template configuration files, which 195The OpenEmbedded build system uses the template configuration files, which
194are found by default in the ``meta-poky/conf/`` directory in the Source 196are found by default in the ``meta-poky/conf/templates/default`` directory in the Source
195Directory. See the 197Directory. See the
196":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" 198":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
197section in the Yocto Project Development Tasks Manual for more 199section in the Yocto Project Development Tasks Manual for more
198information. 200information.
199 201
@@ -215,14 +217,13 @@ These files are standard top-level files.
215 217
216.. _structure-build: 218.. _structure-build:
217 219
218The Build Directory - ``build/`` 220The Build Directory --- ``build/``
219================================ 221==================================
220 222
221The OpenEmbedded build system creates the :term:`Build Directory` 223The OpenEmbedded build system creates the :term:`Build Directory` when you run
222when you run the build environment setup 224the build environment setup script :ref:`structure-core-script`. If you do not
223script :ref:`structure-core-script`. If you do not give the Build 225give the :term:`Build Directory` a specific name when you run the setup script,
224Directory a specific name when you run the setup script, the name 226the name defaults to ``build/``.
225defaults to ``build/``.
226 227
227For subsequent parsing and processing, the name of the Build directory 228For subsequent parsing and processing, the name of the Build directory
228is available via the :term:`TOPDIR` variable. 229is available via the :term:`TOPDIR` variable.
@@ -233,12 +234,24 @@ is available via the :term:`TOPDIR` variable.
233----------------------- 234-----------------------
234 235
235The OpenEmbedded build system creates this directory when you enable 236The OpenEmbedded build system creates this directory when you enable
236build history via the ``buildhistory`` class file. The directory 237build history via the :ref:`ref-classes-buildhistory` class file. The directory
237organizes build information into image, packages, and SDK 238organizes build information into image, packages, and SDK
238subdirectories. For information on the build history feature, see the 239subdirectories. For information on the build history feature, see the
239":ref:`dev-manual/common-tasks:maintaining build output quality`" 240":ref:`dev-manual/build-quality:maintaining build output quality`"
240section in the Yocto Project Development Tasks Manual. 241section in the Yocto Project Development Tasks Manual.
241 242
243.. _structure-build-cache:
244
245``build/cache/``
246----------------
247
248This directory contains several internal files used by the OpenEmbedded
249build system.
250
251It also contains ``sanity_info``, a text file keeping track of important
252build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`,
253as well as the name and version of the host distribution.
254
242.. _structure-build-conf-local.conf: 255.. _structure-build-conf-local.conf:
243 256
244``build/conf/local.conf`` 257``build/conf/local.conf``
@@ -253,9 +266,9 @@ variables are hard-coded for various reasons but such variables are
253relatively rare. 266relatively rare.
254 267
255At a minimum, you would normally edit this file to select the target 268At a minimum, you would normally edit this file to select the target
256``MACHINE``, which package types you wish to use 269:term:`MACHINE`, which package types you wish to use
257(:term:`PACKAGE_CLASSES`), and the location from 270(:term:`PACKAGE_CLASSES`), and the location from
258which you want to access downloaded files (``DL_DIR``). 271which you want to access downloaded files (:term:`DL_DIR`).
259 272
260If ``local.conf`` is not present when you start the build, the 273If ``local.conf`` is not present when you start the build, the
261OpenEmbedded build system creates it from ``local.conf.sample`` when you 274OpenEmbedded build system creates it from ``local.conf.sample`` when you
@@ -263,16 +276,15 @@ OpenEmbedded build system creates it from ``local.conf.sample`` when you
263:ref:`structure-core-script`. 276:ref:`structure-core-script`.
264 277
265The source ``local.conf.sample`` file used depends on the 278The source ``local.conf.sample`` file used depends on the
266``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` 279:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default``
267when you are building from the Yocto Project development environment, 280when you are building from the Yocto Project development environment,
268and to ``meta/conf/`` when you are building from the OpenEmbedded-Core 281and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core
269environment. Because the script variable points to the source of the 282environment. Because the script variable points to the source of the
270``local.conf.sample`` file, this implies that you can configure your 283``local.conf.sample`` file, this implies that you can configure your
271build environment from any layer by setting the variable in the 284build environment from any layer by setting the variable in the
272top-level build environment setup script as follows: 285top-level build environment setup script as follows::
273::
274 286
275 TEMPLATECONF=your_layer/conf 287 TEMPLATECONF=your_layer/conf/templates/your_template_name
276 288
277Once the build process gets the sample 289Once the build process gets the sample
278file, it uses ``sed`` to substitute final 290file, it uses ``sed`` to substitute final
@@ -281,10 +293,10 @@ file, it uses ``sed`` to substitute final
281 293
282.. note:: 294.. note::
283 295
284 You can see how the ``TEMPLATECONF`` variable is used by looking at the 296 You can see how the :term:`TEMPLATECONF` variable is used by looking at the
285 ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`. 297 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
286 You can find the Yocto Project version of the ``local.conf.sample`` file in 298 You can find the Yocto Project version of the ``local.conf.sample`` file in
287 the ``meta-poky/conf`` directory. 299 the ``meta-poky/conf/templates/default`` directory.
288 300
289.. _structure-build-conf-bblayers.conf: 301.. _structure-build-conf-bblayers.conf:
290 302
@@ -292,7 +304,7 @@ file, it uses ``sed`` to substitute final
292---------------------------- 304----------------------------
293 305
294This configuration file defines 306This configuration file defines
295:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`, 307:ref:`layers <dev-manual/layers:understanding and creating layers>`,
296which are directory trees, traversed (or walked) by BitBake. The 308which are directory trees, traversed (or walked) by BitBake. The
297``bblayers.conf`` file uses the :term:`BBLAYERS` 309``bblayers.conf`` file uses the :term:`BBLAYERS`
298variable to list the layers BitBake tries to find. 310variable to list the layers BitBake tries to find.
@@ -303,35 +315,26 @@ you ``source`` the top-level build environment setup script (i.e.
303:ref:`structure-core-script`). 315:ref:`structure-core-script`).
304 316
305As with the ``local.conf`` file, the source ``bblayers.conf.sample`` 317As with the ``local.conf`` file, the source ``bblayers.conf.sample``
306file used depends on the ``$TEMPLATECONF`` script variable, which 318file used depends on the :term:`TEMPLATECONF` script variable, which
307defaults to ``meta-poky/conf/`` when you are building from the Yocto 319defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto
308Project development environment, and to ``meta/conf/`` when you are 320Project development environment, and to ``meta/conf/templates/default`` when you are
309building from the OpenEmbedded-Core environment. Because the script 321building from the OpenEmbedded-Core environment. Because the script
310variable points to the source of the ``bblayers.conf.sample`` file, this 322variable points to the source of the ``bblayers.conf.sample`` file, this
311implies that you can base your build from any layer by setting the 323implies that you can base your build from any layer by setting the
312variable in the top-level build environment setup script as follows: 324variable in the top-level build environment setup script as follows::
313::
314 325
315 TEMPLATECONF=your_layer/conf 326 TEMPLATECONF=your_layer/conf/templates/your_template_name
316 327
317Once the build process gets the sample file, it uses ``sed`` to substitute final 328Once the build process gets the sample file, it uses ``sed`` to substitute final
318``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. 329``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
319 330
320.. note:: 331.. note::
321 332
322 You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir`` 333 You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir``
323 script in the :term:`Source Directory`. You can find the Yocto Project 334 script in the :term:`Source Directory`. You can find the Yocto Project
324 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/`` 335 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
325 directory. 336 directory.
326 337
327.. _structure-build-conf-sanity_info:
328
329``build/cache/sanity_info``
330---------------------------
331
332This file indicates the state of the sanity checks and is created during
333the build.
334
335.. _structure-build-downloads: 338.. _structure-build-downloads:
336 339
337``build/downloads/`` 340``build/downloads/``
@@ -340,7 +343,7 @@ the build.
340This directory contains downloaded upstream source tarballs. You can 343This directory contains downloaded upstream source tarballs. You can
341reuse the directory for multiple builds or move the directory to another 344reuse the directory for multiple builds or move the directory to another
342location. You can control the location of this directory through the 345location. You can control the location of this directory through the
343``DL_DIR`` variable. 346:term:`DL_DIR` variable.
344 347
345.. _structure-build-sstate-cache: 348.. _structure-build-sstate-cache:
346 349
@@ -350,7 +353,7 @@ location. You can control the location of this directory through the
350This directory contains the shared state cache. You can reuse the 353This directory contains the shared state cache. You can reuse the
351directory for multiple builds or move the directory to another location. 354directory for multiple builds or move the directory to another location.
352You can control the location of this directory through the 355You can control the location of this directory through the
353``SSTATE_DIR`` variable. 356:term:`SSTATE_DIR` variable.
354 357
355.. _structure-build-tmp: 358.. _structure-build-tmp:
356 359
@@ -370,14 +373,15 @@ remove the ``build/sstate-cache`` directory.
370.. _structure-build-tmp-buildstats: 373.. _structure-build-tmp-buildstats:
371 374
372``build/tmp/buildstats/`` 375``build/tmp/buildstats/``
373------------------------- 376~~~~~~~~~~~~~~~~~~~~~~~~~
374 377
375This directory stores the build statistics. 378This directory stores the build statistics as generated by the
379:ref:`ref-classes-buildstats` class.
376 380
377.. _structure-build-tmp-cache: 381.. _structure-build-tmp-cache:
378 382
379``build/tmp/cache/`` 383``build/tmp/cache/``
380-------------------- 384~~~~~~~~~~~~~~~~~~~~
381 385
382When BitBake parses the metadata (recipes and configuration files), it 386When BitBake parses the metadata (recipes and configuration files), it
383caches the results in ``build/tmp/cache/`` to speed up future builds. 387caches the results in ``build/tmp/cache/`` to speed up future builds.
@@ -393,7 +397,7 @@ cache is reused. If the file has changed, it is reparsed.
393.. _structure-build-tmp-deploy: 397.. _structure-build-tmp-deploy:
394 398
395``build/tmp/deploy/`` 399``build/tmp/deploy/``
396--------------------- 400~~~~~~~~~~~~~~~~~~~~~
397 401
398This directory contains any "end result" output from the OpenEmbedded 402This directory contains any "end result" output from the OpenEmbedded
399build process. The :term:`DEPLOY_DIR` variable points 403build process. The :term:`DEPLOY_DIR` variable points
@@ -406,7 +410,7 @@ Project Overview and Concepts Manual.
406.. _structure-build-tmp-deploy-deb: 410.. _structure-build-tmp-deploy-deb:
407 411
408``build/tmp/deploy/deb/`` 412``build/tmp/deploy/deb/``
409------------------------- 413^^^^^^^^^^^^^^^^^^^^^^^^^
410 414
411This directory receives any ``.deb`` packages produced by the build 415This directory receives any ``.deb`` packages produced by the build
412process. The packages are sorted into feeds for different architecture 416process. The packages are sorted into feeds for different architecture
@@ -415,7 +419,7 @@ types.
415.. _structure-build-tmp-deploy-rpm: 419.. _structure-build-tmp-deploy-rpm:
416 420
417``build/tmp/deploy/rpm/`` 421``build/tmp/deploy/rpm/``
418------------------------- 422^^^^^^^^^^^^^^^^^^^^^^^^^
419 423
420This directory receives any ``.rpm`` packages produced by the build 424This directory receives any ``.rpm`` packages produced by the build
421process. The packages are sorted into feeds for different architecture 425process. The packages are sorted into feeds for different architecture
@@ -424,27 +428,27 @@ types.
424.. _structure-build-tmp-deploy-ipk: 428.. _structure-build-tmp-deploy-ipk:
425 429
426``build/tmp/deploy/ipk/`` 430``build/tmp/deploy/ipk/``
427------------------------- 431^^^^^^^^^^^^^^^^^^^^^^^^^
428 432
429This directory receives ``.ipk`` packages produced by the build process. 433This directory receives ``.ipk`` packages produced by the build process.
430 434
431.. _structure-build-tmp-deploy-licenses: 435.. _structure-build-tmp-deploy-licenses:
432 436
433``build/tmp/deploy/licenses/`` 437``build/tmp/deploy/licenses/``
434------------------------------ 438^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
435 439
436This directory receives package licensing information. For example, the 440This directory receives package licensing information. For example, the
437directory contains sub-directories for ``bash``, ``busybox``, and 441directory contains sub-directories for ``bash``, ``busybox``, and
438``glibc`` (among others) that in turn contain appropriate ``COPYING`` 442``glibc`` (among others) that in turn contain appropriate ``COPYING``
439license files with other licensing information. For information on 443license files with other licensing information. For information on
440licensing, see the 444licensing, see the
441":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" 445":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`"
442section in the Yocto Project Development Tasks Manual. 446section in the Yocto Project Development Tasks Manual.
443 447
444.. _structure-build-tmp-deploy-images: 448.. _structure-build-tmp-deploy-images:
445 449
446``build/tmp/deploy/images/`` 450``build/tmp/deploy/images/``
447---------------------------- 451^^^^^^^^^^^^^^^^^^^^^^^^^^^^
448 452
449This directory is populated with the basic output objects of the build 453This directory is populated with the basic output objects of the build
450(think of them as the "generated artifacts" of the build process), 454(think of them as the "generated artifacts" of the build process),
@@ -463,8 +467,7 @@ image again.
463If you do accidentally delete files here, you will need to force them to 467If you do accidentally delete files here, you will need to force them to
464be re-created. In order to do that, you will need to know the target 468be re-created. In order to do that, you will need to know the target
465that produced them. For example, these commands rebuild and re-create 469that produced them. For example, these commands rebuild and re-create
466the kernel files: 470the kernel files::
467::
468 471
469 $ bitbake -c clean virtual/kernel 472 $ bitbake -c clean virtual/kernel
470 $ bitbake virtual/kernel 473 $ bitbake virtual/kernel
@@ -472,7 +475,7 @@ the kernel files:
472.. _structure-build-tmp-deploy-sdk: 475.. _structure-build-tmp-deploy-sdk:
473 476
474``build/tmp/deploy/sdk/`` 477``build/tmp/deploy/sdk/``
475------------------------- 478^^^^^^^^^^^^^^^^^^^^^^^^^
476 479
477The OpenEmbedded build system creates this directory to hold toolchain 480The OpenEmbedded build system creates this directory to hold toolchain
478installer scripts which, when executed, install the sysroot that matches 481installer scripts which, when executed, install the sysroot that matches
@@ -484,7 +487,7 @@ Software Development Kit (eSDK) manual.
484.. _structure-build-tmp-sstate-control: 487.. _structure-build-tmp-sstate-control:
485 488
486``build/tmp/sstate-control/`` 489``build/tmp/sstate-control/``
487----------------------------- 490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
488 491
489The OpenEmbedded build system uses this directory for the shared state 492The OpenEmbedded build system uses this directory for the shared state
490manifest files. The shared state code uses these files to record the 493manifest files. The shared state code uses these files to record the
@@ -497,7 +500,7 @@ another.
497.. _structure-build-tmp-sysroots-components: 500.. _structure-build-tmp-sysroots-components:
498 501
499``build/tmp/sysroots-components/`` 502``build/tmp/sysroots-components/``
500---------------------------------- 503~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
501 504
502This directory is the location of the sysroot contents that the task 505This directory is the location of the sysroot contents that the task
503:ref:`ref-tasks-prepare_recipe_sysroot` 506:ref:`ref-tasks-prepare_recipe_sysroot`
@@ -512,11 +515,11 @@ should be automatic, and recipes should not directly reference
512.. _structure-build-tmp-sysroots: 515.. _structure-build-tmp-sysroots:
513 516
514``build/tmp/sysroots/`` 517``build/tmp/sysroots/``
515----------------------- 518~~~~~~~~~~~~~~~~~~~~~~~
516 519
517Previous versions of the OpenEmbedded build system used to create a 520Previous versions of the OpenEmbedded build system used to create a
518global shared sysroot per machine along with a native sysroot. Beginning 521global shared sysroot per machine along with a native sysroot. Since
519with the 2.3 version of the Yocto Project, sysroots exist in 522the 2.3 version of the Yocto Project, there are sysroots in
520recipe-specific :term:`WORKDIR` directories. Thus, the 523recipe-specific :term:`WORKDIR` directories. Thus, the
521``build/tmp/sysroots/`` directory is unused. 524``build/tmp/sysroots/`` directory is unused.
522 525
@@ -530,13 +533,12 @@ recipe-specific :term:`WORKDIR` directories. Thus, the
530.. _structure-build-tmp-stamps: 533.. _structure-build-tmp-stamps:
531 534
532``build/tmp/stamps/`` 535``build/tmp/stamps/``
533--------------------- 536~~~~~~~~~~~~~~~~~~~~~
534 537
535This directory holds information that BitBake uses for accounting 538This directory holds information that BitBake uses for accounting
536purposes to track what tasks have run and when they have run. The 539purposes to track what tasks have run and when they have run. The
537directory is sub-divided by architecture, package name, and version. 540directory is sub-divided by architecture, package name, and version.
538Following is an example: 541Here is an example::
539::
540 542
541 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do 543 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
542 544
@@ -551,17 +553,17 @@ section in the Yocto Project Overview and Concepts Manual.
551.. _structure-build-tmp-log: 553.. _structure-build-tmp-log:
552 554
553``build/tmp/log/`` 555``build/tmp/log/``
554------------------ 556~~~~~~~~~~~~~~~~~~
555 557
556This directory contains general logs that are not otherwise placed using 558This directory contains general logs that are not otherwise placed using
557the package's ``WORKDIR``. Examples of logs are the output from the 559the package's :term:`WORKDIR`. Examples of logs are the output from the
558``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not 560``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
559necessarily mean this directory is created. 561necessarily mean this directory is created.
560 562
561.. _structure-build-tmp-work: 563.. _structure-build-tmp-work:
562 564
563``build/tmp/work/`` 565``build/tmp/work/``
564------------------- 566~~~~~~~~~~~~~~~~~~~
565 567
566This directory contains architecture-specific work sub-directories for 568This directory contains architecture-specific work sub-directories for
567packages built by BitBake. All tasks execute from the appropriate work 569packages built by BitBake. All tasks execute from the appropriate work
@@ -575,15 +577,15 @@ It is worth considering the structure of a typical work directory. As an
575example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` 577example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
576built within the Yocto Project. For this package, a work directory of 578built within the Yocto Project. For this package, a work directory of
577``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred 579``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
578to as the ``WORKDIR``, is created. Within this directory, the source is 580to as the :term:`WORKDIR`, is created. Within this directory, the source is
579unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. 581unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
580(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in 582(See the ":ref:`dev-manual/quilt:using quilt in your workflow`" section in
581the Yocto Project Development Tasks Manual for more information.) Within 583the Yocto Project Development Tasks Manual for more information.) Within
582the ``linux-qemux86-standard-build`` directory, standard Quilt 584the ``linux-qemux86-standard-build`` directory, standard Quilt
583directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and 585directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
584standard Quilt commands can be used. 586standard Quilt commands can be used.
585 587
586There are other directories generated within ``WORKDIR``. The most 588There are other directories generated within :term:`WORKDIR`. The most
587important directory is ``WORKDIR/temp/``, which has log files for each 589important directory is ``WORKDIR/temp/``, which has log files for each
588task (``log.do_*.pid``) and contains the scripts BitBake runs for each 590task (``log.do_*.pid``) and contains the scripts BitBake runs for each
589task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make 591task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
@@ -593,9 +595,9 @@ install" places its output that is then split into sub-packages within
593.. _structure-build-tmp-work-tunearch-recipename-version: 595.. _structure-build-tmp-work-tunearch-recipename-version:
594 596
595``build/tmp/work/tunearch/recipename/version/`` 597``build/tmp/work/tunearch/recipename/version/``
596----------------------------------------------- 598^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
597 599
598The recipe work directory - ``${WORKDIR}``. 600The recipe work directory --- ``${WORKDIR}``.
599 601
600As described earlier in the 602As described earlier in the
601":ref:`structure-build-tmp-sysroots`" section, 603":ref:`structure-build-tmp-sysroots`" section,
@@ -607,7 +609,7 @@ constructed using the architecture of the given build (e.g.
607name, and the version of the recipe (i.e. 609name, and the version of the recipe (i.e.
608:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). 610:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
609 611
610A number of key subdirectories exist within each recipe work directory: 612Here are key subdirectories within each recipe work directory:
611 613
612- ``${WORKDIR}/temp``: Contains the log files of each task executed for 614- ``${WORKDIR}/temp``: Contains the log files of each task executed for
613 this recipe, the "run" files for each executed task, which contain 615 this recipe, the "run" files for each executed task, which contain
@@ -629,8 +631,8 @@ A number of key subdirectories exist within each recipe work directory:
629 split into individual packages. 631 split into individual packages.
630 632
631- ``${WORKDIR}/packages-split``: Contains the output of the 633- ``${WORKDIR}/packages-split``: Contains the output of the
632 ``do_package`` task after the output has been split into individual 634 :ref:`ref-tasks-package` task after the output has been split into individual
633 packages. Subdirectories exist for each individual package created by 635 packages. There are subdirectories for each individual package created by
634 the recipe. 636 the recipe.
635 637
636- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target 638- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
@@ -651,7 +653,7 @@ A number of key subdirectories exist within each recipe work directory:
651.. _structure-build-work-shared: 653.. _structure-build-work-shared:
652 654
653``build/tmp/work-shared/`` 655``build/tmp/work-shared/``
654-------------------------- 656~~~~~~~~~~~~~~~~~~~~~~~~~~
655 657
656For efficiency, the OpenEmbedded build system creates and uses this 658For efficiency, the OpenEmbedded build system creates and uses this
657directory to hold recipes that share a work directory with other 659directory to hold recipes that share a work directory with other
@@ -660,29 +662,30 @@ recipes. In practice, this is only used for ``gcc`` and its variants
660 662
661.. _structure-meta: 663.. _structure-meta:
662 664
663The Metadata - ``meta/`` 665The Metadata --- ``meta/``
664======================== 666==========================
665 667
666As mentioned previously, :term:`Metadata` is the core of the 668As mentioned previously, :term:`Metadata` is the core of the
667Yocto Project. Metadata has several important subdivisions: 669Yocto Project. Metadata has several important subdivisions:
668 670
669.. _structure-meta-classes: 671.. _structure-meta-classes:
670 672
671``meta/classes/`` 673``meta/classes*/``
672----------------- 674------------------
673 675
674This directory contains the ``*.bbclass`` files. Class files are used to 676These directories contain the ``*.bbclass`` files. Class files are used to
675abstract common code so it can be reused by multiple packages. Every 677abstract common code so it can be reused by multiple packages. Every
676package inherits the ``base.bbclass`` file. Examples of other important 678package inherits the :ref:`ref-classes-base` file. Examples of other important
677classes are ``autotools.bbclass``, which in theory allows any 679classes are :ref:`ref-classes-autotools`, which in theory allows any
678Autotool-enabled package to work with the Yocto Project with minimal 680Autotool-enabled package to work with the Yocto Project with minimal
679effort. Another example is ``kernel.bbclass`` that contains common code 681effort. Another example is :ref:`ref-classes-kernel` that contains common code
680and functions for working with the Linux kernel. Functions like image 682and functions for working with the Linux kernel. Functions like image
681generation or packaging also have their specific class files such as 683generation or packaging also have their specific class files such as
682``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. 684:ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and
685:ref:`package*.bbclass <ref-classes-package>`.
683 686
684For reference information on classes, see the 687For reference information on classes, see the
685":ref:`ref-manual/classes:Classes`" chapter. 688":doc:`/ref-manual/classes`" chapter.
686 689
687.. _structure-meta-conf: 690.. _structure-meta-conf:
688 691
@@ -700,7 +703,7 @@ distribution configuration file.
700.. _structure-meta-conf-machine: 703.. _structure-meta-conf-machine:
701 704
702``meta/conf/machine/`` 705``meta/conf/machine/``
703---------------------- 706~~~~~~~~~~~~~~~~~~~~~~
704 707
705This directory contains all the machine configuration files. If you set 708This directory contains all the machine configuration files. If you set
706``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a 709``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a
@@ -711,11 +714,11 @@ support for a new machine to the Yocto Project, look in this directory.
711.. _structure-meta-conf-distro: 714.. _structure-meta-conf-distro:
712 715
713``meta/conf/distro/`` 716``meta/conf/distro/``
714--------------------- 717~~~~~~~~~~~~~~~~~~~~~
715 718
716The contents of this directory controls any distribution-specific 719The contents of this directory controls any distribution-specific
717configurations. For the Yocto Project, the ``defaultsetup.conf`` is the 720configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
718main file here. This directory includes the versions and the ``SRCDATE`` 721main file here. This directory includes the versions and the :term:`SRCDATE`
719definitions for applications that are configured here. An example of an 722definitions for applications that are configured here. An example of an
720alternative configuration might be ``poky-bleeding.conf``. Although this 723alternative configuration might be ``poky-bleeding.conf``. Although this
721file mainly inherits its configuration from Poky. 724file mainly inherits its configuration from Poky.
@@ -723,7 +726,7 @@ file mainly inherits its configuration from Poky.
723.. _structure-meta-conf-machine-sdk: 726.. _structure-meta-conf-machine-sdk:
724 727
725``meta/conf/machine-sdk/`` 728``meta/conf/machine-sdk/``
726-------------------------- 729~~~~~~~~~~~~~~~~~~~~~~~~~~
727 730
728The OpenEmbedded build system searches this directory for configuration 731The OpenEmbedded build system searches this directory for configuration
729files that correspond to the value of 732files that correspond to the value of
@@ -748,7 +751,9 @@ and lists of files and directories with known permissions.
748------------- 751-------------
749 752
750This directory contains OpenEmbedded Python library code used during the 753This directory contains OpenEmbedded Python library code used during the
751build process. 754build process. It is enabled via the ``addpylib`` directive in
755``meta/conf/local.conf``. For more information, see
756:ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`.
752 757
753.. _structure-meta-recipes-bsp: 758.. _structure-meta-recipes-bsp:
754 759
@@ -789,7 +794,7 @@ system. The tools, however, can also be used on targets.
789 794
790This directory contains non-essential applications that add features 795This directory contains non-essential applications that add features
791compared to the alternatives in core. You might need this directory for 796compared to the alternatives in core. You might need this directory for
792full tool functionality or for Linux Standard Base (LSB) compliance. 797full tool functionality.
793 798
794.. _structure-meta-recipes-gnome: 799.. _structure-meta-recipes-gnome:
795 800
@@ -815,14 +820,6 @@ libraries.
815This directory contains the kernel and generic applications and 820This directory contains the kernel and generic applications and
816libraries that have strong kernel dependencies. 821libraries that have strong kernel dependencies.
817 822
818.. _structure-meta-recipes-lsb4:
819
820``meta/recipes-lsb4/``
821----------------------
822
823This directory contains recipes specifically added to support the Linux
824Standard Base (LSB) version 4.x.
825
826.. _structure-meta-recipes-multimedia: 823.. _structure-meta-recipes-multimedia:
827 824
828``meta/recipes-multimedia/`` 825``meta/recipes-multimedia/``