poky/documentation/ref-manual/ref-structure.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->

<chapter id='ref-structure'>

<title>Source Directory Structure</title>

<para>
    The <link linkend='source-directory'>Source Directory</link>
    consists of numerous files, directories and subdirectories;
    understanding their locations and contents is key to using the
    Yocto Project effectively.
    This chapter describes the Source Directory and gives information about
    those files and directories.
</para>

<para>
    For information on how to establish a local Source Directory on your
    development system, see the
    "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
    section in the Yocto Project Development Tasks Manual.
</para>

    <note>
        The OpenEmbedded build system does not support file or directory names that
        contain spaces.
        Be sure that the Source Directory you use does not contain these types
        of names.
    </note>

<section id='structure-core'>
    <title>Top-Level Core Components</title>

    <para>
        This section describes the top-level components of the
        <link linkend='source-directory'>Source Directory</link>.
    </para>

    <section id='structure-core-bitbake'>
        <title><filename>bitbake/</filename></title>

        <para>
            This directory includes a copy of BitBake for ease of use.
            The copy usually matches the current stable BitBake release from
            the BitBake project.
            BitBake, a
            <link linkend='metadata'>Metadata</link>
            interpreter, reads the Yocto Project Metadata and runs the tasks
            defined by that data.
            Failures are usually caused by errors in your Metadata and not from BitBake itself;
            consequently, most users do not need to worry about BitBake.
        </para>

        <para>
            When you run the <filename>bitbake</filename> command, the
            main BitBake executable (which resides in the
            <filename>bitbake/bin/</filename> directory) starts.
            Sourcing the environment setup script (i.e.
            <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>)
            places the <filename>scripts/</filename> and
            <filename>bitbake/bin/</filename> directories (in that order) into
            the shell's <filename>PATH</filename> environment variable.
        </para>

        <para>
            For more information on BitBake, see the
            <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
        </para>
    </section>

    <section id='structure-core-build'>
        <title><filename>build/</filename></title>

        <para>
            This directory contains user configuration files and the output
            generated by the OpenEmbedded build system in its standard configuration where
            the source tree is combined with the output.
            The
            <link linkend='build-directory'>Build Directory</link>
            is created initially when you <filename>source</filename>
            the OpenEmbedded build environment setup script
            (i.e.
            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
        </para>

        <para>
            It is also possible to place output and configuration
            files in a directory separate from the
            <link linkend='source-directory'>Source Directory</link>
            by providing a directory name when you <filename>source</filename>
            the setup script.
            For information on separating output from your local
            Source Directory files (commonly described as an "out of tree" build), see the
            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
            section.
        </para>
    </section>

    <section id='handbook'>
        <title><filename>documentation/</filename></title>

        <para>
            This directory holds the source for the Yocto Project documentation
            as well as templates and tools that allow you to generate PDF and HTML
            versions of the manuals.
            Each manual is contained in its own sub-folder;
            for example, the files for this reference manual reside in
            the <filename>ref-manual/</filename> directory.
        </para>
    </section>

    <section id='structure-core-meta'>
        <title><filename>meta/</filename></title>

        <para>
            This directory contains the minimal, underlying OpenEmbedded-Core metadata.
            The directory holds recipes, common classes, and machine
            configuration for strictly emulated targets (<filename>qemux86</filename>,
            <filename>qemuarm</filename>, and so forth.)
        </para>
    </section>

    <section id='structure-core-meta-poky'>
        <title><filename>meta-poky/</filename></title>

        <para>
            Designed above the <filename>meta/</filename> content, this directory
            adds just enough metadata to define the Poky reference distribution.
        </para>
    </section>

    <section id='structure-core-meta-yocto-bsp'>
        <title><filename>meta-yocto-bsp/</filename></title>

        <para>
            This directory contains the Yocto Project reference
            hardware Board Support Packages (BSPs).
            For more information on BSPs, see the
            <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
        </para>
    </section>

    <section id='structure-meta-selftest'>
        <title><filename>meta-selftest/</filename></title>

        <para>
            This directory adds additional recipes and append files
            used by the OpenEmbedded selftests to verify the behavior
            of the build system.
            You do not have to add this layer to your
            <filename>bblayers.conf</filename> file unless you want to run the
            selftests.
        </para>
    </section>

    <section id='structure-meta-skeleton'>
        <title><filename>meta-skeleton/</filename></title>

        <para>
            This directory contains template recipes for BSP and kernel development.
        </para>
    </section>

    <section id='structure-core-scripts'>
        <title><filename>scripts/</filename></title>

        <para>
            This directory contains various integration scripts that implement
            extra functionality in the Yocto Project environment (e.g. QEMU scripts).
            The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
            script prepends this directory to the shell's
            <filename>PATH</filename> environment variable.
        </para>

        <para>
            The <filename>scripts</filename> directory has useful scripts that assist in contributing
            back to the Yocto Project, such as <filename>create-pull-request</filename> and
            <filename>send-pull-request</filename>.
        </para>
    </section>

    <section id='structure-core-script'>
        <title><filename>&OE_INIT_FILE;</filename></title>

        <para>
            This script sets up the OpenEmbedded build environment.
            Running this script with the <filename>source</filename> command in
            a shell makes changes to <filename>PATH</filename> and sets other
            core BitBake variables based on the current working directory.
            You need to run an environment setup script before running BitBake
            commands.
            The script uses other scripts within the
            <filename>scripts</filename> directory to do the bulk of the work.
        </para>

        <para>
            When you run this script, your Yocto Project environment is set
            up, a
            <link linkend='build-directory'>Build Directory</link>
            is created, your working directory becomes the Build Directory,
            and you are presented with some simple suggestions as to what to do
            next, including a list of some possible targets to build.
            Here is an example:
            <literallayout class='monospaced'>
     $ source oe-init-build-env

     ### Shell environment set up for builds. ###

     You can now run 'bitbake &lt;target&gt;'

     Common targets are:
         core-image-minimal
         core-image-sato
         meta-toolchain
         meta-ide-support

     You can also run generated qemu images with a command like 'runqemu qemux86-64'
            </literallayout>
            The default output of the <filename>oe-init-build-env</filename> script
            is from the <filename>conf-notes.txt</filename> file, which is found in the
            <filename>meta-poky</filename> directory within the
            <link linkend='source-directory'>Source Directory</link>.
            If you design a custom distribution, you can include your own version
            of this configuration file to mention the targets defined by your
            distribution.
            See the
            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
            section in the Yocto Project Development Tasks Manual for more
            information.
        </para>

        <para>
            By default, running this script without a Build Directory
            argument creates the <filename>build/</filename> directory
            in your current working directory.
            If you provide a Build Directory argument when you
            <filename>source</filename> the script, you direct the OpenEmbedded
            build system to create a Build Directory of your choice.
            For example, the following command creates a Build Directory named
            <filename>mybuilds/</filename> that is outside of the
            <link linkend='source-directory'>Source Directory</link>:
            <literallayout class='monospaced'>
     $ source &OE_INIT_FILE; ~/mybuilds
            </literallayout>
            The OpenEmbedded build system uses the template configuration
            files, which are found by default in the
            <filename>meta-poky/conf/</filename> directory in the
            Source Directory.
            See the
            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
            section in the Yocto Project Development Tasks Manual for more
            information.
            <note>
                The OpenEmbedded build system does not support file or directory names that
                contain spaces.
                If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
                from a Source Directory that contains spaces in either the filenames
                or directory names, the script returns an error indicating no such
                file or directory.
                Be sure to use a Source Directory free of names containing spaces.
            </note>
        </para>
    </section>

    <section id='structure-basic-top-level'>
        <title><filename>LICENSE, README, and README.hardware</filename></title>

        <para>
            These files are standard top-level files.
        </para>
    </section>
</section>

<section id='structure-build'>
    <title>The Build Directory - <filename>build/</filename></title>

    <para>
        The OpenEmbedded build system creates the
        <link linkend='build-directory'>Build Directory</link>
        when you run the build environment setup script
        <link
linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
        If you do not give the Build Directory a specific name when you run
        the setup script, the name defaults to <filename>build/</filename>.
    </para>

    <para>
        For subsequent parsing and processing, the name of the Build
        directory is available via the
        <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable.
    </para>

    <section id='structure-build-buildhistory'>
        <title><filename>build/buildhistory/</filename></title>

        <para>
            The OpenEmbedded build system creates this directory when you
            enable build history via the <filename>buildhistory</filename> class file.
            The directory organizes build information into image, packages, and
            SDK subdirectories.
            For information on the build history feature, see the
            "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
            section in the Yocto Project Development Tasks Manual.
        </para>
    </section>

    <section id='structure-build-conf-local.conf'>
        <title><filename>build/conf/local.conf</filename></title>

        <para>
            This configuration file contains all the local user configurations
            for your build environment.
            The <filename>local.conf</filename> file contains documentation on
            the various configuration options.
            Any variable set here overrides any variable set elsewhere within
            the environment unless that variable is hard-coded within a file
            (e.g. by using '=' instead of '?=').
            Some variables are hard-coded for various reasons but such
            variables are relatively rare.
        </para>

        <para>
            At a minimum, you would normally edit this file to select the target
            <filename><link linkend='var-MACHINE'>MACHINE</link></filename>,
            which package types you wish to use
            (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
            and the location from which you want to access downloaded files
            (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>).
        </para>

        <para>
            If <filename>local.conf</filename> is not present when you
            start the build, the OpenEmbedded build system creates it from
            <filename>local.conf.sample</filename> when
            you <filename>source</filename> the top-level build environment
            setup script
            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
        </para>

        <para>
            The source <filename>local.conf.sample</filename> file used
            depends on the <filename>$TEMPLATECONF</filename> script variable,
            which defaults to <filename>meta-poky/conf/</filename>
            when you are building from the Yocto Project development
            environment, and to <filename>meta/conf/</filename> when
            you are building from the OpenEmbedded-Core environment.
            Because the script variable points to the source of the
            <filename>local.conf.sample</filename> file, this implies that
            you can configure your build environment from any layer by setting
            the variable in the top-level build environment setup script as
            follows:
            <literallayout class='monospaced'>
     TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
            </literallayout>
            Once the build process gets the sample file, it uses
            <filename>sed</filename> to substitute final
            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
            values for all <filename>##OEROOT##</filename> values.
            <note>
                You can see how the <filename>TEMPLATECONF</filename> variable
                is used by looking at the
                <filename>scripts/oe-setup-builddir</filename> script in the
                <link linkend='source-directory'>Source Directory</link>.
                You can find the Yocto Project version of the
                <filename>local.conf.sample</filename> file in the
                <filename>meta-poky/conf</filename> directory.
            </note>
        </para>
    </section>

    <section id='structure-build-conf-bblayers.conf'>
        <title><filename>build/conf/bblayers.conf</filename></title>

        <para>
            This configuration file defines
            <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
            which are directory trees, traversed (or walked) by BitBake.
            The <filename>bblayers.conf</filename> file uses the
            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
            variable to list the layers BitBake tries to find.
        </para>

        <para>
            If <filename>bblayers.conf</filename> is not present when you
            start the build, the OpenEmbedded build system creates it from
            <filename>bblayers.conf.sample</filename> when
            you <filename>source</filename> the top-level build environment
            setup script (i.e.
            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
        </para>

        <para>
            As with the <filename>local.conf</filename> file,
            the source <filename>bblayers.conf.sample</filename> file used
            depends on the <filename>$TEMPLATECONF</filename> script variable,
            which defaults to <filename>meta-poky/conf/</filename>
            when you are building from the Yocto Project development
            environment, and to <filename>meta/conf/</filename> when
            you are building from the OpenEmbedded-Core environment.
            Because the script variable points to the source of the
            <filename>bblayers.conf.sample</filename> file, this implies that
            you can base your build from any layer by setting the variable in
            the top-level build environment setup script as follows:
            <literallayout class='monospaced'>
     TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
            </literallayout>
            Once the build process gets the sample file, it uses
            <filename>sed</filename> to substitute final
            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
            values for all <filename>##OEROOT##</filename> values.
            <note>
                You can see how the <filename>TEMPLATECONF</filename> variable
                <filename>scripts/oe-setup-builddir</filename> script in the
                <link linkend='source-directory'>Source Directory</link>.
                You can find the Yocto Project version of the
                <filename>bblayers.conf.sample</filename> file in the
                <filename>meta-poky/conf/</filename> directory.
            </note>
        </para>
    </section>

    <section id='structure-build-conf-sanity_info'>
        <title><filename>build/cache/sanity_info</filename></title>

        <para>
            This file indicates the state of the sanity checks and is created
            during the build.
        </para>
    </section>

    <section id='structure-build-downloads'>
        <title><filename>build/downloads/</filename></title>

        <para>
            This directory contains downloaded upstream source tarballs.
            You can reuse the directory for multiple builds or move
            the directory to another location.
            You can control the location of this directory through the
            <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
        </para>
    </section>

    <section id='structure-build-sstate-cache'>
        <title><filename>build/sstate-cache/</filename></title>

        <para>
            This directory contains the shared state cache.
            You can reuse the directory for multiple builds or move
            the directory to another location.
            You can control the location of this directory through the
            <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
        </para>
    </section>

    <section id='structure-build-tmp'>
        <title><filename>build/tmp/</filename></title>

        <para>
            The OpenEmbedded build system creates and uses this directory
            for all the build system's output.
            The
            <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
            variable points to this directory.
        </para>

        <para>
            BitBake creates this directory if it does not exist.
            As a last resort, to clean up a build and start it from scratch
            (other than the downloads), you can remove everything in the
            <filename>tmp</filename> directory or get rid of the
            directory completely.
            If you do, you should also completely remove the
            <filename>build/sstate-cache</filename> directory.
        </para>
    </section>

    <section id='structure-build-tmp-buildstats'>
        <title><filename>build/tmp/buildstats/</filename></title>

        <para>
            This directory stores the build statistics.
        </para>
    </section>

    <section id='structure-build-tmp-cache'>
        <title><filename>build/tmp/cache/</filename></title>

        <para>
            When BitBake parses the metadata (recipes and configuration files),
            it caches the results in <filename>build/tmp/cache/</filename>
            to speed up future builds.
            The results are stored on a per-machine basis.
        </para>

        <para>
            During subsequent builds, BitBake checks each recipe (together
            with, for example, any files included or appended to it) to see
            if they have been modified.
            Changes can be detected, for example, through file modification
            time (mtime) changes and hashing of file contents.
            If no changes to the file are detected, then the parsed result
            stored in the cache is reused.
            If the file has changed, it is reparsed.
        </para>
    </section>

    <section id='structure-build-tmp-deploy'>
        <title><filename>build/tmp/deploy/</filename></title>

        <para>
            This directory contains any "end result" output from the
            OpenEmbedded build process.
            The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
            variable points to this directory.
            For more detail on the contents of the <filename>deploy</filename>
            directory, see the
            "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
            and
            "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
            sections in the Yocto Project Overview and Concepts Manual.
        </para>
    </section>

    <section id='structure-build-tmp-deploy-deb'>
        <title><filename>build/tmp/deploy/deb/</filename></title>

        <para>
            This directory receives any <filename>.deb</filename> packages produced by
            the build process.
            The packages are sorted into feeds for different architecture types.
        </para>
    </section>

    <section id='structure-build-tmp-deploy-rpm'>
        <title><filename>build/tmp/deploy/rpm/</filename></title>

        <para>
            This directory receives any <filename>.rpm</filename> packages produced by
            the build process.
            The packages are sorted into feeds for different architecture types.
        </para>
    </section>

    <section id='structure-build-tmp-deploy-ipk'>
        <title><filename>build/tmp/deploy/ipk/</filename></title>

        <para>
            This directory receives <filename>.ipk</filename> packages produced by
            the build process.
        </para>
    </section>

    <section id='structure-build-tmp-deploy-licenses'>
        <title><filename>build/tmp/deploy/licenses/</filename></title>

        <para>
            This directory receives package licensing information.
            For example, the directory contains sub-directories for <filename>bash</filename>,
            <filename>busybox</filename>, and <filename>glibc</filename> (among others) that in turn
            contain appropriate <filename>COPYING</filename> license files with other licensing information.
            For information on licensing, see the
            "<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>"
            section in the Yocto Project Development Tasks Manual.
        </para>
    </section>

    <section id='structure-build-tmp-deploy-images'>
        <title><filename>build/tmp/deploy/images/</filename></title>

        <para>
            This directory is populated with the basic output objects of the
            build (think of them as the "generated artifacts" of the build process),
            including things like the boot loader image, kernel, root filesystem and more.
            If you want to flash the resulting image from a build onto a device,
            look here for the necessary components.
        </para>

        <para>
            Be careful when deleting files in this directory.
            You can safely delete old images from this directory (e.g.
            <filename>core-image-*</filename>).
            However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
            bootloader and other supplementary files might be deployed here prior to building an
            image.
            Because these files are not directly produced from the image, if you
            delete them they will not be automatically re-created when you build the image again.
        </para>

        <para>
            If you do accidentally delete files here, you will need to force them to be
            re-created.
            In order to do that, you will need to know the target that produced them.
            For example, these commands rebuild and re-create the kernel files:
            <literallayout class='monospaced'>
     $ bitbake -c clean virtual/kernel
     $ bitbake virtual/kernel
            </literallayout>
        </para>
    </section>

    <section id='structure-build-tmp-deploy-sdk'>
        <title><filename>build/tmp/deploy/sdk/</filename></title>

        <para>
            The OpenEmbedded build system creates this directory to hold
            toolchain installer scripts which, when executed, install the
            sysroot that matches your target hardware.
            You can find out more about these installers in the
            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
            section in the Yocto Project Application Development and the
            Extensible Software Development Kit (eSDK) manual.
        </para>
    </section>

    <section id='structure-build-tmp-sstate-control'>
        <title><filename>build/tmp/sstate-control/</filename></title>

        <para>
            The OpenEmbedded build system uses this directory for the
            shared state manifest files.
            The shared state code uses these files to record the files
            installed by each sstate task so that the files can be removed
            when cleaning the recipe or when a newer version is about to
            be installed.
            The build system also uses the manifests to detect and produce
            a warning when files from one task are overwriting those from
            another.
        </para>
    </section>

    <section id='structure-build-tmp-sysroots-components'>
        <title><filename>build/tmp/sysroots-components/</filename></title>

        <para>
            This directory is the location of the sysroot contents that the
            task
            <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
            links or copies into the recipe-specific sysroot for each
            recipe listed in
            <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
            Population of this directory is handled through shared state, while
            the path is specified by the
            <link linkend='var-COMPONENTS_DIR'><filename>COMPONENTS_DIR</filename></link>
            variable. Apart from a few unusual circumstances, handling of the
            <filename>sysroots-components</filename> directory should be
            automatic, and recipes should not directly reference
            <filename>build/tmp/sysroots-components</filename>.
        </para>
    </section>

    <section id='structure-build-tmp-sysroots'>
        <title><filename>build/tmp/sysroots/</filename></title>

        <para>
            Previous versions of the OpenEmbedded build system used to
            create a global shared sysroot per machine along with a native
            sysroot.
            Beginning with the &DISTRO; version of the Yocto Project,
            sysroots exist in recipe-specific
            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
            directories.
            Thus, the <filename>build/tmp/sysroots/</filename> directory
            is unused.
            <note>
                The <filename>build/tmp/sysroots/</filename> directory
                can still be populated using the
                <filename>bitbake build-sysroots</filename> command and can
                be used for compatibility in some cases.
                However, in general it is not recommended to populate
                this directory.
                Individual recipe-specific sysroots should be used.
            </note>
        </para>
    </section>

    <section id='structure-build-tmp-stamps'>
        <title><filename>build/tmp/stamps/</filename></title>

        <para>
            This directory holds information that BitBake uses for
            accounting purposes to track what tasks have run and when they
            have run.
            The directory is sub-divided by architecture, package name, and
            version.
            Following is an example:
            <literallayout class='monospaced'>
     stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
            </literallayout>
            Although the files in the directory are empty of data,
            BitBake uses the filenames and timestamps for tracking purposes.
        </para>

        <para>
            For information on how BitBake uses stamp files to determine if
            a task should be rerun, see the
            "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
            section in the Yocto Project Overview and Concepts Manual.
        </para>
    </section>

    <section id='structure-build-tmp-log'>
        <title><filename>build/tmp/log/</filename></title>

        <para>
            This directory contains general logs that are not otherwise placed using the
            package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
            Examples of logs are the output from the
            <filename>do_check_pkg</filename> or
            <filename>do_distro_check</filename> tasks.
            Running a build does not necessarily mean this directory is created.
        </para>
    </section>

    <section id='structure-build-tmp-work'>
        <title><filename>build/tmp/work/</filename></title>

        <para>
            This directory contains architecture-specific work sub-directories
            for packages built by BitBake.
            All tasks execute from the appropriate work directory.
            For example, the source for a particular package is unpacked,
            patched, configured and compiled all within its own work directory.
            Within the work directory, organization is based on the package group
            and version for which the source is being compiled
            as defined by the
            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
        </para>

        <para>
            It is worth considering the structure of a typical work directory.
            As an example, consider <filename>linux-yocto-kernel-3.0</filename>
            on the machine <filename>qemux86</filename>
            built within the Yocto Project.
            For this package, a work directory of
            <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
            referred to as the <filename>WORKDIR</filename>, is created.
            Within this directory, the source is unpacked to
            <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
            (See the
            "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using Quilt in Your Workflow</ulink>"
            section in the Yocto Project Development Tasks Manual for more
            information.)
            Within the <filename>linux-qemux86-standard-build</filename> directory,
            standard Quilt directories <filename>linux-3.0/patches</filename>
            and <filename>linux-3.0/.pc</filename> are created,
            and standard Quilt commands can be used.
        </para>

        <para>
            There are other directories generated within <filename>WORKDIR</filename>.
            The most important directory is <filename>WORKDIR/temp/</filename>,
            which has log files for each task (<filename>log.do_*.pid</filename>)
            and contains the scripts BitBake runs for each task
            (<filename>run.do_*.pid</filename>).
            The <filename>WORKDIR/image/</filename> directory is where "make
            install" places its output that is then split into sub-packages
            within <filename>WORKDIR/packages-split/</filename>.
        </para>
    </section>

    <section id='structure-build-tmp-work-tunearch-recipename-version'>
        <title><filename>build/tmp/work/<replaceable>tunearch</replaceable>/<replaceable>recipename</replaceable>/<replaceable>version</replaceable>/</filename></title>

        <para>
            The recipe work directory - <filename>${WORKDIR}</filename>.
        </para>

        <para>
            As described earlier in the
            "<link linkend='structure-build-tmp-sysroots'><filename>build/tmp/sysroots/</filename></link>"
            section, beginning with the &DISTRO; release of the Yocto
            Project, the OpenEmbedded build system builds each recipe in its
            own work directory (i.e.
            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
            The path to the work directory is constructed using the
            architecture of the given build (e.g.
            <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>,
            <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>,
            or "allarch"), the recipe name, and the version of the recipe (i.e.
            <link linkend='var-PE'><filename>PE</filename></link><filename>:</filename><link linkend='var-PV'><filename>PV</filename></link><filename>-</filename><link linkend='var-PR'><filename>PR</filename></link>).
        </para>

        <para>
            A number of key subdirectories exist within each recipe
            work directory:
            <itemizedlist>
                <listitem><para>
                    <filename>${WORKDIR}/temp</filename>:
                    Contains the log files of each task executed for this
                    recipe, the "run" files for each executed task, which
                    contain the code run, and a
                    <filename>log.task_order</filename> file, which lists the
                    order in which tasks were executed.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/image</filename>:
                    Contains the output of the
                    <link linkend='ref-tasks-install'><filename>do_install</filename></link>
                    task, which corresponds to the
                    <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
                    variable in that task.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/pseudo</filename>:
                    Contains the pseudo database and log for any tasks executed
                    under pseudo for the recipe.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/sysroot-destdir</filename>:
                    Contains the output of the
                    <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
                    task.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/package</filename>:
                    Contains the output of the
                    <link linkend='ref-tasks-package'><filename>do_package</filename></link>
                    task before the output is split into individual packages.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/packages-split</filename>:
                    Contains the output of the <filename>do_package</filename>
                    task after the output has been split into individual
                    packages.
                    Subdirectories exist for each individual package created
                    by the recipe.
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/recipe-sysroot</filename>:
                    A directory populated with the target dependencies of the
                    recipe.
                    This directory looks like the target filesystem and
                    contains libraries that the recipe might need to link
                    against (e.g. the C library).
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/recipe-sysroot-native</filename>:
                    A directory populated with the native dependencies of the
                    recipe.
                    This directory contains the tools the recipe needs to build
                    (e.g. the compiler, Autoconf, libtool, and so forth).
                   </para></listitem>
                <listitem><para>
                    <filename>${WORKDIR}/build</filename>:
                    This subdirectory applies only to recipes that support
                    builds where the source is separate from the
                    build artifacts.
                    The OpenEmbedded build system uses this directory as a
                    separate build directory (i.e.
                    <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>).
                   </para></listitem>
            </itemizedlist>
        </para>
    </section>

    <section id='structure-build-work-shared'>
        <title><filename>build/tmp/work-shared/</filename></title>

        <para>
            For efficiency, the OpenEmbedded build system creates and uses
            this directory to hold recipes that share a work directory with
            other recipes.
            In practice, this is only used for <filename>gcc</filename>
            and its variants (e.g. <filename>gcc-cross</filename>,
            <filename>libgcc</filename>, <filename>gcc-runtime</filename>,
            and so forth).
        </para>
    </section>
</section>

<section id='structure-meta'>
    <title>The Metadata - <filename>meta/</filename></title>

    <para>
        As mentioned previously,
        <link linkend='metadata'>Metadata</link> is the core
        of the Yocto Project.
        Metadata has several important subdivisions:
    </para>

    <section id='structure-meta-classes'>
        <title><filename>meta/classes/</filename></title>

        <para>
            This directory contains the <filename>*.bbclass</filename> files.
            Class files are used to abstract common code so it can be reused by multiple
            packages.
            Every package inherits the <filename>base.bbclass</filename> file.
            Examples of other important classes are <filename>autotools.bbclass</filename>, which
            in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
            Another example is <filename>kernel.bbclass</filename> that contains common code and functions
            for working with the Linux kernel.
            Functions like image generation or packaging also have their specific class files
            such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
            <filename>package*.bbclass</filename>.
        </para>

        <para>
            For reference information on classes, see the
            "<link linkend='ref-classes'>Classes</link>" chapter.
        </para>
    </section>

    <section id='structure-meta-conf'>
        <title><filename>meta/conf/</filename></title>

        <para>
            This directory contains the core set of configuration files that start from
            <filename>bitbake.conf</filename> and from which all other configuration
            files are included.
            See the include statements at the end of the
            <filename>bitbake.conf</filename> file and you will note that even
            <filename>local.conf</filename> is loaded from there.
            While <filename>bitbake.conf</filename> sets up the defaults, you can often override
            these by using the (<filename>local.conf</filename>) file, machine file or
            the distribution configuration file.
        </para>
    </section>

    <section id='structure-meta-conf-machine'>
        <title><filename>meta/conf/machine/</filename></title>

        <para>
            This directory contains all the machine configuration files.
            If you set <filename>MACHINE = "qemux86"</filename>,
            the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
            directory.
            The <filename>include</filename> directory contains various data common to multiple machines.
            If you want to add support for a new machine to the Yocto Project, look in this directory.
        </para>
    </section>

    <section id='structure-meta-conf-distro'>
        <title><filename>meta/conf/distro/</filename></title>

        <para>
            The contents of this directory controls any distribution-specific
            configurations.
            For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
            This directory includes the versions and the
            <filename>SRCDATE</filename> definitions for applications that are configured here.
            An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
            Although this file mainly inherits its configuration from Poky.
        </para>
    </section>

    <section id='structure-meta-conf-machine-sdk'>
        <title><filename>meta/conf/machine-sdk/</filename></title>

        <para>
            The OpenEmbedded build system searches this directory for
            configuration files that correspond to the value of
            <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
            By default, 32-bit and 64-bit x86 files ship with the Yocto
            Project that support some SDK hosts.
            However, it is possible to extend that support to other SDK hosts
            by adding additional configuration files in this subdirectory
            within another layer.
        </para>
    </section>

    <section id='structure-meta-files'>
        <title><filename>meta/files/</filename></title>

        <para>
            This directory contains common license files and several text files
            used by the build system.
            The text files contain minimal device information and
            lists of files and directories with known permissions.
        </para>
    </section>

    <section id='structure-meta-lib'>
        <title><filename>meta/lib/</filename></title>

        <para>
            This directory contains OpenEmbedded Python library code
            used during the build process.
        </para>
    </section>

    <section id='structure-meta-recipes-bsp'>
        <title><filename>meta/recipes-bsp/</filename></title>

        <para>
            This directory contains anything linking to specific hardware or hardware
            configuration information such as "u-boot" and "grub".
        </para>
    </section>

    <section id='structure-meta-recipes-connectivity'>
        <title><filename>meta/recipes-connectivity/</filename></title>

        <para>
            This directory contains libraries and applications related to communication with other devices.
        </para>
    </section>

    <section id='structure-meta-recipes-core'>
        <title><filename>meta/recipes-core/</filename></title>

        <para>
            This directory contains what is needed to build a basic working Linux image
            including commonly used dependencies.
        </para>
    </section>

    <section id='structure-meta-recipes-devtools'>
        <title><filename>meta/recipes-devtools/</filename></title>

        <para>
            This directory contains tools that are primarily used by the build system.
            The tools, however, can also be used on targets.
        </para>
    </section>

    <section id='structure-meta-recipes-extended'>
        <title><filename>meta/recipes-extended/</filename></title>

        <para>
            This directory contains non-essential applications that add features compared to the
            alternatives in core.
            You might need this directory for full tool functionality or for Linux Standard Base (LSB)
            compliance.
        </para>
    </section>

    <section id='structure-meta-recipes-gnome'>
        <title><filename>meta/recipes-gnome/</filename></title>

        <para>
            This directory contains all things related to the GTK+ application framework.
        </para>
    </section>

    <section id='structure-meta-recipes-graphics'>
        <title><filename>meta/recipes-graphics/</filename></title>

        <para>
            This directory contains X and other graphically related system libraries.
        </para>
    </section>

    <section id='structure-meta-recipes-kernel'>
        <title><filename>meta/recipes-kernel/</filename></title>

        <para>
            This directory contains the kernel and generic applications and libraries that
            have strong kernel dependencies.
        </para>
    </section>

    <section id='structure-meta-recipes-lsb4'>
        <title><filename>meta/recipes-lsb4/</filename></title>

        <para>
            This directory contains recipes specifically added to support
            the Linux Standard Base (LSB) version 4.x.
        </para>
    </section>

    <section id='structure-meta-recipes-multimedia'>
        <title><filename>meta/recipes-multimedia/</filename></title>

        <para>
            This directory contains codecs and support utilities for audio, images and video.
        </para>
    </section>

    <section id='structure-meta-recipes-rt'>
        <title><filename>meta/recipes-rt/</filename></title>

        <para>
            This directory contains package and image recipes for using and testing
            the <filename>PREEMPT_RT</filename> kernel.
        </para>
    </section>

    <section id='structure-meta-recipes-sato'>
        <title><filename>meta/recipes-sato/</filename></title>

        <para>
            This directory contains the Sato demo/reference UI/UX and its associated applications
            and configuration data.
        </para>
    </section>

    <section id='structure-meta-recipes-support'>
        <title><filename>meta/recipes-support/</filename></title>

        <para>
            This directory contains recipes used by other recipes, but that are
            not directly included in images (i.e. dependencies of other
            recipes).
        </para>
    </section>

    <section id='structure-meta-site'>
        <title><filename>meta/site/</filename></title>

        <para>
            This directory contains a list of cached results for various architectures.
            Because certain "autoconf" test results cannot be determined when cross-compiling due to
            the tests not able to run on a live system, the information in this directory is
            passed to "autoconf" for the various architectures.
        </para>
    </section>

    <section id='structure-meta-recipes-txt'>
        <title><filename>meta/recipes.txt</filename></title>

        <para>
            This file is a description of the contents of <filename>recipes-*</filename>.
        </para>
    </section>
</section>

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->