1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************************** 4Source Directory Structure 5************************** 6 7The :term:`Source Directory` consists of numerous files, 8directories and subdirectories; understanding their locations and 9contents is key to using the Yocto Project effectively. This chapter 10describes the Source Directory and gives information about those files 11and directories. 12 13For information on how to establish a local Source Directory on your 14development system, see the 15":ref:`dev-manual/start:locating yocto project source files`" 16section in the Yocto Project Development Tasks Manual. 17 18.. note:: 19 20 The OpenEmbedded build system does not support file or directory 21 names that contain spaces. Be sure that the Source Directory you use 22 does not contain these types of names. 23 24.. _structure-core: 25 26Top-Level Core Components 27========================= 28 29This section describes the top-level components of the :term:`Source Directory`. 30 31.. _structure-core-bitbake: 32 33``bitbake/`` 34------------ 35 36This directory includes a copy of BitBake for ease of use. The copy 37usually matches the current stable BitBake release from the BitBake 38project. BitBake, a :term:`Metadata` interpreter, reads the 39Yocto Project Metadata and runs the tasks defined by that data. Failures 40are usually caused by errors in your Metadata and not from BitBake 41itself. 42 43When you run the ``bitbake`` command, the main BitBake executable (which 44resides in the ``bitbake/bin/`` directory) starts. Sourcing the 45environment setup script (i.e. :ref:`structure-core-script`) places 46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into 47the shell's ``PATH`` environment variable. 48 49For more information on BitBake, see the :doc:`BitBake User Manual 50<bitbake:index>`. 51 52.. _structure-core-build: 53 54``build/`` 55---------- 56 57This directory contains user configuration files and the output 58generated by the OpenEmbedded build system in its standard configuration 59where the source tree is combined with the output. The :term:`Build Directory` 60is created initially when you ``source`` the OpenEmbedded build environment 61setup script (i.e. :ref:`structure-core-script`). 62 63It is also possible to place output and configuration files in a 64directory separate from the :term:`Source Directory` by 65providing a directory name when you ``source`` the setup script. For 66information on separating output from your local Source Directory files 67(commonly described as an "out of tree" build), see the 68":ref:`structure-core-script`" section. 69 70See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details 71about the contents of the :term:`Build Directory`. 72 73.. _handbook: 74 75``documentation/`` 76------------------ 77 78This directory holds the source for the Yocto Project documentation as 79well as templates and tools that allow you to generate PDF and HTML 80versions of the manuals. Each manual is contained in its own sub-folder; 81for example, the files for this reference manual reside in the 82``ref-manual/`` directory. 83 84.. _structure-core-meta: 85 86``meta/`` 87--------- 88 89This directory contains the minimal, underlying OpenEmbedded-Core 90metadata. The directory holds recipes, common classes, and machine 91configuration for strictly emulated targets (``qemux86``, ``qemuarm``, 92and so forth.) 93 94.. _structure-core-meta-poky: 95 96``meta-poky/`` 97-------------- 98 99Designed above the ``meta/`` content, this directory adds just enough 100metadata to define the Poky reference distribution. 101 102.. _structure-core-meta-yocto-bsp: 103 104``meta-yocto-bsp/`` 105------------------- 106 107This directory contains the Yocto Project reference hardware Board 108Support Packages (BSPs). For more information on BSPs, see the 109:doc:`/bsp-guide/index`. 110 111.. _structure-meta-selftest: 112 113``meta-selftest/`` 114------------------ 115 116This directory adds additional recipes and append files used by the 117OpenEmbedded selftests to verify the behavior of the build system. You 118do not have to add this layer to your ``bblayers.conf`` file unless you 119want to run the selftests. 120 121.. _structure-meta-skeleton: 122 123``meta-skeleton/`` 124------------------ 125 126This directory contains template recipes for BSP and kernel development. 127 128.. _structure-core-scripts: 129 130``scripts/`` 131------------ 132 133This directory contains various integration scripts that implement extra 134functionality in the Yocto Project environment (e.g. QEMU scripts). The 135:ref:`structure-core-script` script prepends this directory to the 136shell's ``PATH`` environment variable. 137 138The ``scripts`` directory has useful scripts that assist in contributing 139back to the Yocto Project, such as ``create-pull-request`` and 140``send-pull-request``. 141 142.. _structure-core-script: 143 144``oe-init-build-env`` 145--------------------- 146 147This script sets up the OpenEmbedded build environment. Running this 148script with the ``source`` command in a shell makes changes to ``PATH`` 149and sets other core BitBake variables based on the current working 150directory. You need to run an environment setup script before running 151BitBake commands. The script uses other scripts within the ``scripts`` 152directory to do the bulk of the work. 153 154When you run this script, your Yocto Project environment is set up, a 155:term:`Build Directory` is created, your working directory becomes the 156:term:`Build Directory`, and you are presented with some simple 157suggestions as to what to do next, including a list of some possible 158targets to build. Here is an example:: 159 160 $ source oe-init-build-env 161 162 ### Shell environment set up for builds. ### 163 164 You can now run 'bitbake <target>' 165 166 Common targets are: 167 core-image-minimal 168 core-image-sato 169 meta-toolchain 170 meta-ide-support 171 172 You can also run generated QEMU images with a command like 'runqemu qemux86-64' 173 174The default output of the ``oe-init-build-env`` script is from the 175``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the ``meta-poky`` directory 176within the :term:`Source Directory`. If you design a 177custom distribution, you can include your own versions of these 178configuration files where you can provide a brief summary and detailed usage 179notes, such as a list of the targets defined by your distribution. 180See the 181":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`" 182section in the Yocto Project Development Tasks Manual for more 183information. 184 185By default, running this script without a :term:`Build Directory` argument 186creates the ``build/`` directory in your current working directory. If 187you provide a :term:`Build Directory` argument when you ``source`` the script, 188you direct the OpenEmbedded build system to create a :term:`Build Directory` of 189your choice. For example, the following command creates a 190:term:`Build Directory` named ``mybuilds/`` that is outside of the 191:term:`Source Directory`:: 192 193 $ source oe-init-build-env ~/mybuilds 194 195The OpenEmbedded build system uses the template configuration files, which 196are found by default in the ``meta-poky/conf/templates/default`` directory in the Source 197Directory. See the 198":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`" 199section in the Yocto Project Development Tasks Manual for more 200information. 201 202.. note:: 203 204 The OpenEmbedded build system does not support file or directory 205 names that contain spaces. If you attempt to run the ``oe-init-build-env`` 206 script from a Source Directory that contains spaces in either the 207 filenames or directory names, the script returns an error indicating 208 no such file or directory. Be sure to use a Source Directory free of 209 names containing spaces. 210 211.. _structure-basic-top-level: 212 213``LICENSE, README, and README.hardware`` 214---------------------------------------- 215 216These files are standard top-level files. 217 218.. _structure-build: 219 220The Build Directory --- ``build/`` 221================================== 222 223The OpenEmbedded build system creates the :term:`Build Directory` when you run 224the build environment setup script :ref:`structure-core-script`. If you do not 225give the :term:`Build Directory` a specific name when you run the setup script, 226the name defaults to ``build/``. 227 228For subsequent parsing and processing, the name of the Build directory 229is available via the :term:`TOPDIR` variable. 230 231.. _structure-build-buildhistory: 232 233``build/buildhistory/`` 234----------------------- 235 236The OpenEmbedded build system creates this directory when you enable 237build history via the :ref:`ref-classes-buildhistory` class file. The directory 238organizes build information into image, packages, and SDK 239subdirectories. For information on the build history feature, see the 240":ref:`dev-manual/build-quality:maintaining build output quality`" 241section in the Yocto Project Development Tasks Manual. 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 255.. _structure-build-conf-local.conf: 256 257``build/conf/local.conf`` 258------------------------- 259 260This configuration file contains all the local user configurations for 261your build environment. The ``local.conf`` file contains documentation 262on the various configuration options. Any variable set here overrides 263any variable set elsewhere within the environment unless that variable 264is hard-coded within a file (e.g. by using '=' instead of '?='). Some 265variables are hard-coded for various reasons but such variables are 266relatively rare. 267 268At a minimum, you would normally edit this file to select the target 269:term:`MACHINE`, which package types you wish to use 270(:term:`PACKAGE_CLASSES`), and the location from 271which you want to access downloaded files (:term:`DL_DIR`). 272 273If ``local.conf`` is not present when you start the build, the 274OpenEmbedded build system creates it from ``local.conf.sample`` when you 275``source`` the top-level build environment setup script 276:ref:`structure-core-script`. 277 278The source ``local.conf.sample`` file used depends on the 279:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default`` 280when you are building from the Yocto Project development environment, 281and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core 282environment. Because the script variable points to the source of the 283``local.conf.sample`` file, this implies that you can configure your 284build environment from any layer by setting the variable in the 285top-level build environment setup script as follows:: 286 287 TEMPLATECONF=your_layer/conf/templates/your_template_name 288 289Once the build process gets the sample 290file, it uses ``sed`` to substitute final 291``${``\ :term:`OEROOT`\ ``}`` values for all 292``##OEROOT##`` values. 293 294.. note:: 295 296 You can see how the :term:`TEMPLATECONF` variable is used by looking at the 297 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. 298 You can find the Yocto Project version of the ``local.conf.sample`` file in 299 the ``meta-poky/conf/templates/default`` directory. 300 301.. _structure-build-conf-bblayers.conf: 302 303``build/conf/bblayers.conf`` 304---------------------------- 305 306This configuration file defines 307:ref:`layers <dev-manual/layers:understanding and creating layers>`, 308which are directory trees, traversed (or walked) by BitBake. The 309``bblayers.conf`` file uses the :term:`BBLAYERS` 310variable to list the layers BitBake tries to find. 311 312If ``bblayers.conf`` is not present when you start the build, the 313OpenEmbedded build system creates it from ``bblayers.conf.sample`` when 314you ``source`` the top-level build environment setup script (i.e. 315:ref:`structure-core-script`). 316 317As with the ``local.conf`` file, the source ``bblayers.conf.sample`` 318file used depends on the :term:`TEMPLATECONF` script variable, which 319defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto 320Project development environment, and to ``meta/conf/templates/default`` when you are 321building from the OpenEmbedded-Core environment. Because the script 322variable points to the source of the ``bblayers.conf.sample`` file, this 323implies that you can base your build from any layer by setting the 324variable in the top-level build environment setup script as follows:: 325 326 TEMPLATECONF=your_layer/conf/templates/your_template_name 327 328Once the build process gets the sample file, it uses ``sed`` to substitute final 329``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. 330 331.. note:: 332 333 You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir`` 334 script in the :term:`Source Directory`. You can find the Yocto Project 335 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default`` 336 directory. 337 338.. _structure-build-conf-bblock.conf: 339 340``build/conf/bblock.conf`` 341-------------------------- 342 343This configuration file is generated by :doc:`bblock </dev-manual/bblock>` and 344contains the signatures locked by ``bblock``. By default, it does not exist 345and will be created upon the first invocation of ``bblock``. 346 347.. _structure-build-downloads: 348 349``build/downloads/`` 350-------------------- 351 352This directory contains downloaded upstream source tarballs. You can 353reuse the directory for multiple builds or move the directory to another 354location. You can control the location of this directory through the 355:term:`DL_DIR` variable. 356 357.. _structure-build-sstate-cache: 358 359``build/sstate-cache/`` 360----------------------- 361 362This directory contains the shared state cache. You can reuse the 363directory for multiple builds or move the directory to another location. 364You can control the location of this directory through the 365:term:`SSTATE_DIR` variable. 366 367.. _structure-build-tmp: 368 369``build/tmp/`` 370-------------- 371 372The OpenEmbedded build system creates and uses this directory for all 373the build system's output. The :term:`TMPDIR` variable 374points to this directory. 375 376BitBake creates this directory if it does not exist. As a last resort, 377to clean up a build and start it from scratch (other than the 378downloads), you can remove everything in the ``tmp`` directory or get 379rid of the directory completely. If you do, you should also completely 380remove the ``build/sstate-cache`` directory. 381 382.. _structure-build-tmp-buildstats: 383 384``build/tmp/buildstats/`` 385~~~~~~~~~~~~~~~~~~~~~~~~~ 386 387This directory stores the build statistics as generated by the 388:ref:`ref-classes-buildstats` class. 389 390.. _structure-build-tmp-cache: 391 392``build/tmp/cache/`` 393~~~~~~~~~~~~~~~~~~~~ 394 395When BitBake parses the metadata (recipes and configuration files), it 396caches the results in ``build/tmp/cache/`` to speed up future builds. 397The results are stored on a per-machine basis. 398 399During subsequent builds, BitBake checks each recipe (together with, for 400example, any files included or appended to it) to see if they have been 401modified. Changes can be detected, for example, through file 402modification time (mtime) changes and hashing of file contents. If no 403changes to the file are detected, then the parsed result stored in the 404cache is reused. If the file has changed, it is reparsed. 405 406.. _structure-build-tmp-deploy: 407 408``build/tmp/deploy/`` 409~~~~~~~~~~~~~~~~~~~~~ 410 411This directory contains any "end result" output from the OpenEmbedded 412build process. The :term:`DEPLOY_DIR` variable points 413to this directory. For more detail on the contents of the ``deploy`` 414directory, see the 415":ref:`overview-manual/concepts:images`" and 416":ref:`overview-manual/concepts:application development sdk`" sections in the Yocto 417Project Overview and Concepts Manual. 418 419.. _structure-build-tmp-deploy-deb: 420 421``build/tmp/deploy/deb/`` 422^^^^^^^^^^^^^^^^^^^^^^^^^ 423 424This directory receives any ``.deb`` packages produced by the build 425process. The packages are sorted into feeds for different architecture 426types. 427 428.. _structure-build-tmp-deploy-rpm: 429 430``build/tmp/deploy/rpm/`` 431^^^^^^^^^^^^^^^^^^^^^^^^^ 432 433This directory receives any ``.rpm`` packages produced by the build 434process. The packages are sorted into feeds for different architecture 435types. 436 437.. _structure-build-tmp-deploy-ipk: 438 439``build/tmp/deploy/ipk/`` 440^^^^^^^^^^^^^^^^^^^^^^^^^ 441 442This directory receives ``.ipk`` packages produced by the build process. 443 444.. _structure-build-tmp-deploy-licenses: 445 446``build/tmp/deploy/licenses/`` 447^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 448 449This directory receives package licensing information. For example, the 450directory contains sub-directories for ``bash``, ``busybox``, and 451``glibc`` (among others) that in turn contain appropriate ``COPYING`` 452license files with other licensing information. For information on 453licensing, see the 454":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" 455section in the Yocto Project Development Tasks Manual. 456 457.. _structure-build-tmp-deploy-images: 458 459``build/tmp/deploy/images/`` 460^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 461 462This directory is populated with the basic output objects of the build 463(think of them as the "generated artifacts" of the build process), 464including things like the boot loader image, kernel, root filesystem and 465more. If you want to flash the resulting image from a build onto a 466device, look here for the necessary components. 467 468Be careful when deleting files in this directory. You can safely delete 469old images from this directory (e.g. ``core-image-*``). However, the 470kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other 471supplementary files might be deployed here prior to building an image. 472Because these files are not directly produced from the image, if you 473delete them they will not be automatically re-created when you build the 474image again. 475 476If you do accidentally delete files here, you will need to force them to 477be re-created. In order to do that, you will need to know the target 478that produced them. For example, these commands rebuild and re-create 479the kernel files:: 480 481 $ bitbake -c clean virtual/kernel 482 $ bitbake virtual/kernel 483 484.. _structure-build-tmp-deploy-sdk: 485 486``build/tmp/deploy/sdk/`` 487^^^^^^^^^^^^^^^^^^^^^^^^^ 488 489The OpenEmbedded build system creates this directory to hold toolchain 490installer scripts which, when executed, install the sysroot that matches 491your target hardware. You can find out more about these installers in 492the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" 493section in the Yocto Project Application Development and the Extensible 494Software Development Kit (eSDK) manual. 495 496.. _structure-build-tmp-hosttools: 497 498``build/tmp/hosttools/`` 499~~~~~~~~~~~~~~~~~~~~~~~~ 500 501The OpenEmbedded build system uses this directory to create symbolic links to 502some of the host components that are allowed to be called within tasks. These 503are basic components listed in the :ref:`ref-manual/system-requirements:required 504packages for the build host` section. These components are also listed in the 505:term:`HOSTTOOLS` variable and are limited to this list to prevent host 506contamination. 507 508.. _structure-build-tmp-pkgdata: 509 510``build/tmp/pkgdata/`` 511~~~~~~~~~~~~~~~~~~~~~~ 512 513The OpenEmbedded build system uses this directory to store package metadata 514generated during the :ref:`ref-tasks-packagedata` task. The files stored in this 515directory contain information about each output package produced by the 516OpenEmbedded build system, and are used in different ways by the build system 517such as ":ref:`dev-manual/debugging:viewing package information with 518\`\`oe-pkgdata-util\`\``". 519 520.. _structure-build-tmp-sstate-control: 521 522``build/tmp/sstate-control/`` 523~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 524 525The OpenEmbedded build system uses this directory for the shared state 526manifest files. The shared state code uses these files to record the 527files installed by each sstate task so that the files can be removed 528when cleaning the recipe or when a newer version is about to be 529installed. The build system also uses the manifests to detect and 530produce a warning when files from one task are overwriting those from 531another. 532 533.. _structure-build-tmp-sysroots-components: 534 535``build/tmp/sysroots-components/`` 536~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 537 538This directory is the location of the sysroot contents that the task 539:ref:`ref-tasks-prepare_recipe_sysroot` 540links or copies into the recipe-specific sysroot for each recipe listed 541in :term:`DEPENDS`. Population of this directory is 542handled through shared state, while the path is specified by the 543:term:`COMPONENTS_DIR` variable. Apart from a few 544unusual circumstances, handling of the ``sysroots-components`` directory 545should be automatic, and recipes should not directly reference 546``build/tmp/sysroots-components``. 547 548.. _structure-build-tmp-sysroots: 549 550``build/tmp/sysroots/`` 551~~~~~~~~~~~~~~~~~~~~~~~ 552 553Previous versions of the OpenEmbedded build system used to create a 554global shared sysroot per machine along with a native sysroot. Since 555the 2.3 version of the Yocto Project, there are sysroots in 556recipe-specific :term:`WORKDIR` directories. Thus, the 557``build/tmp/sysroots/`` directory is unused. 558 559.. note:: 560 561 The ``build/tmp/sysroots/`` directory can still be populated using the 562 ``bitbake build-sysroots`` command and can be used for compatibility in some 563 cases. However, in general it is not recommended to populate this directory. 564 Individual recipe-specific sysroots should be used. 565 566.. _structure-build-tmp-stamps: 567 568``build/tmp/stamps/`` 569~~~~~~~~~~~~~~~~~~~~~ 570 571This directory holds information that BitBake uses for accounting 572purposes to track what tasks have run and when they have run. The 573directory is sub-divided by architecture, package name, and version. 574Here is an example:: 575 576 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do 577 578Although the files in the directory are empty of data, BitBake uses the filenames 579and timestamps for tracking purposes. 580 581For information on how BitBake uses stamp files to determine if a task 582should be rerun, see the 583":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`" 584section in the Yocto Project Overview and Concepts Manual. 585 586.. _structure-build-tmp-log: 587 588``build/tmp/log/`` 589~~~~~~~~~~~~~~~~~~ 590 591This directory contains general logs that are not otherwise placed using 592the package's :term:`WORKDIR`. Examples of logs are the output from the 593``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not 594necessarily mean this directory is created. 595 596.. _structure-build-tmp-work: 597 598``build/tmp/work/`` 599~~~~~~~~~~~~~~~~~~~ 600 601This directory contains architecture-specific work sub-directories for 602packages built by BitBake. All tasks execute from the appropriate work 603directory. For example, the source for a particular package is unpacked, 604patched, configured and compiled all within its own work directory. 605Within the work directory, organization is based on the package group 606and version for which the source is being compiled as defined by the 607:term:`WORKDIR`. 608 609It is worth considering the structure of a typical work directory. As an 610example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` 611built within the Yocto Project. For this package, a work directory of 612``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred 613to as the :term:`WORKDIR`, is created. Within this directory, the source is 614unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. 615(See the ":ref:`dev-manual/quilt:using quilt in your workflow`" section in 616the Yocto Project Development Tasks Manual for more information.) Within 617the ``linux-qemux86-standard-build`` directory, standard Quilt 618directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and 619standard Quilt commands can be used. 620 621There are other directories generated within :term:`WORKDIR`. The most 622important directory is ``WORKDIR/temp/``, which has log files for each 623task (``log.do_*.pid``) and contains the scripts BitBake runs for each 624task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make 625install" places its output that is then split into sub-packages within 626``WORKDIR/packages-split/``. 627 628.. _structure-build-tmp-work-tunearch-recipename-version: 629 630``build/tmp/work/tunearch/recipename/version/`` 631^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 632 633The recipe work directory --- ``${WORKDIR}``. 634 635As described earlier in the 636":ref:`structure-build-tmp-sysroots`" section, 637beginning with the 2.3 release of the Yocto Project, the OpenEmbedded 638build system builds each recipe in its own work directory (i.e. 639:term:`WORKDIR`). The path to the work directory is 640constructed using the architecture of the given build (e.g. 641:term:`TUNE_PKGARCH`, :term:`MACHINE_ARCH`, or "allarch"), the recipe 642name, and the version of the recipe (i.e. 643:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). 644 645Here are key subdirectories within each recipe work directory: 646 647- ``${WORKDIR}/temp``: Contains the log files of each task executed for 648 this recipe, the "run" files for each executed task, which contain 649 the code run, and a ``log.task_order`` file, which lists the order in 650 which tasks were executed. 651 652- ``${WORKDIR}/image``: Contains the output of the 653 :ref:`ref-tasks-install` task, which corresponds to 654 the ``${``\ :term:`D`\ ``}`` variable in that task. 655 656- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any 657 tasks executed under pseudo for the recipe. 658 659- ``${WORKDIR}/sysroot-destdir``: Contains the output of the 660 :ref:`ref-tasks-populate_sysroot` task. 661 662- ``${WORKDIR}/package``: Contains the output of the 663 :ref:`ref-tasks-package` task before the output is 664 split into individual packages. 665 666- ``${WORKDIR}/packages-split``: Contains the output of the 667 :ref:`ref-tasks-package` task after the output has been split into individual 668 packages. There are subdirectories for each individual package created by 669 the recipe. 670 671- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target 672 dependencies of the recipe. This directory looks like the target 673 filesystem and contains libraries that the recipe might need to link 674 against (e.g. the C library). 675 676- ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the 677 native dependencies of the recipe. This directory contains the tools 678 the recipe needs to build (e.g. the compiler, Autoconf, libtool, and 679 so forth). 680 681- ``${WORKDIR}/build``: This subdirectory applies only to recipes that 682 support builds where the source is separate from the build artifacts. 683 The OpenEmbedded build system uses this directory as a separate build 684 directory (i.e. ``${``\ :term:`B`\ ``}``). 685 686.. _structure-build-work-shared: 687 688``build/tmp/work-shared/`` 689~~~~~~~~~~~~~~~~~~~~~~~~~~ 690 691For efficiency, the OpenEmbedded build system creates and uses this 692directory to hold recipes that share a work directory with other 693recipes. This is for example used for ``gcc`` and its variants (e.g. 694``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth), or by the 695:ref:`ref-classes-kernel` class to make the kernel source code and kernel build 696artifacts available to out-of-tree kernel modules or other kernel-dependent 697recipes. 698 699In practice, only a few recipes make use of the ``work-shared`` directory. This 700directory is especially useful for recipes that would induce a lot of storage 701space if they were to be shared with the standard :term:`Sysroot` mechanism. 702 703.. _structure-meta: 704 705The Metadata --- ``meta/`` 706========================== 707 708As mentioned previously, :term:`Metadata` is the core of the 709Yocto Project. Metadata has several important subdivisions: 710 711.. _structure-meta-classes: 712 713``meta/classes*/`` 714------------------ 715 716These directories contain the ``*.bbclass`` files. Class files are used to 717abstract common code so it can be reused by multiple packages. Every 718package inherits the :ref:`ref-classes-base` file. Examples of other important 719classes are :ref:`ref-classes-autotools`, which in theory allows any 720Autotool-enabled package to work with the Yocto Project with minimal 721effort. Another example is :ref:`ref-classes-kernel` that contains common code 722and functions for working with the Linux kernel. Functions like image 723generation or packaging also have their specific class files such as 724:ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and 725:ref:`package*.bbclass <ref-classes-package>`. 726 727For reference information on classes, see the 728":doc:`/ref-manual/classes`" chapter. 729 730.. _structure-meta-conf: 731 732``meta/conf/`` 733-------------- 734 735This directory contains the core set of configuration files that start 736from ``bitbake.conf`` and from which all other configuration files are 737included. See the include statements at the end of the ``bitbake.conf`` 738file and you will note that even ``local.conf`` is loaded from there. 739While ``bitbake.conf`` sets up the defaults, you can often override 740these by using the (``local.conf``) file, machine file or the 741distribution configuration file. 742 743.. _structure-meta-conf-machine: 744 745``meta/conf/machine/`` 746~~~~~~~~~~~~~~~~~~~~~~ 747 748This directory contains all the machine configuration files. If you set 749``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a 750``qemux86.conf`` file in this directory. The ``include`` directory 751contains various data common to multiple machines. If you want to add 752support for a new machine to the Yocto Project, look in this directory. 753 754.. _structure-meta-conf-distro: 755 756``meta/conf/distro/`` 757~~~~~~~~~~~~~~~~~~~~~ 758 759The contents of this directory controls any distribution-specific 760configurations. For the Yocto Project, the ``defaultsetup.conf`` is the 761main file here. This directory includes the versions and the :term:`SRCDATE` 762definitions for applications that are configured here. An example of an 763alternative configuration might be ``poky-bleeding.conf``. Although this 764file mainly inherits its configuration from Poky. 765 766.. _structure-meta-conf-machine-sdk: 767 768``meta/conf/machine-sdk/`` 769~~~~~~~~~~~~~~~~~~~~~~~~~~ 770 771The OpenEmbedded build system searches this directory for configuration 772files that correspond to the value of 773:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86 774files ship with the Yocto Project that support some SDK hosts. However, 775it is possible to extend that support to other SDK hosts by adding 776additional configuration files in this subdirectory within another 777layer. 778 779.. _structure-meta-files: 780 781``meta/files/`` 782--------------- 783 784This directory contains common license files and several text files used 785by the build system. The text files contain minimal device information 786and lists of files and directories with known permissions. 787 788.. _structure-meta-lib: 789 790``meta/lib/`` 791------------- 792 793This directory contains OpenEmbedded Python library code used during the 794build process. It is enabled via the ``addpylib`` directive in 795``meta/conf/local.conf``. For more information, see 796:ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`. 797 798.. _structure-meta-recipes-bsp: 799 800``meta/recipes-bsp/`` 801--------------------- 802 803This directory contains anything linking to specific hardware or 804hardware configuration information such as "u-boot" and "grub". 805 806.. _structure-meta-recipes-connectivity: 807 808``meta/recipes-connectivity/`` 809------------------------------ 810 811This directory contains libraries and applications related to 812communication with other devices. 813 814.. _structure-meta-recipes-core: 815 816``meta/recipes-core/`` 817---------------------- 818 819This directory contains what is needed to build a basic working Linux 820image including commonly used dependencies. 821 822.. _structure-meta-recipes-devtools: 823 824``meta/recipes-devtools/`` 825-------------------------- 826 827This directory contains tools that are primarily used by the build 828system. The tools, however, can also be used on targets. 829 830.. _structure-meta-recipes-extended: 831 832``meta/recipes-extended/`` 833-------------------------- 834 835This directory contains non-essential applications that add features 836compared to the alternatives in core. You might need this directory for 837full tool functionality. 838 839.. _structure-meta-recipes-gnome: 840 841``meta/recipes-gnome/`` 842----------------------- 843 844This directory contains all things related to the GTK+ application 845framework. 846 847.. _structure-meta-recipes-graphics: 848 849``meta/recipes-graphics/`` 850-------------------------- 851 852This directory contains X and other graphically related system 853libraries. 854 855.. _structure-meta-recipes-kernel: 856 857``meta/recipes-kernel/`` 858------------------------ 859 860This directory contains the kernel and generic applications and 861libraries that have strong kernel dependencies. 862 863.. _structure-meta-recipes-multimedia: 864 865``meta/recipes-multimedia/`` 866---------------------------- 867 868This directory contains codecs and support utilities for audio, images 869and video. 870 871.. _structure-meta-recipes-rt: 872 873``meta/recipes-rt/`` 874-------------------- 875 876This directory contains package and image recipes for using and testing 877the ``PREEMPT_RT`` kernel. 878 879.. _structure-meta-recipes-sato: 880 881``meta/recipes-sato/`` 882---------------------- 883 884This directory contains the Sato demo/reference UI/UX and its associated 885applications and configuration data. 886 887.. _structure-meta-recipes-support: 888 889``meta/recipes-support/`` 890------------------------- 891 892This directory contains recipes used by other recipes, but that are not 893directly included in images (i.e. dependencies of other recipes). 894 895.. _structure-meta-site: 896 897``meta/site/`` 898-------------- 899 900This directory contains a list of cached results for various 901architectures. Because certain "autoconf" test results cannot be 902determined when cross-compiling due to the tests not able to run on a 903live system, the information in this directory is passed to "autoconf" 904for the various architectures. 905 906.. _structure-meta-recipes-txt: 907 908``meta/recipes.txt`` 909-------------------- 910 911This file is a description of the contents of ``recipes-*``. 912