import-layers/yocto-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; ] >

<chapter id='ref-structure'>

<title>Source Directory Structure</title>

<para>
    The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
    Understanding them and knowing where they are located is key to using the Yocto Project well.
    This chapter describes the Source Directory and gives information about the various
    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;#getting-setup'>Getting Set Up</ulink>"
    section in the Yocto Project Development 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
        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
    </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
            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
            interpreter, reads the Yocto Project Metadata and runs the tasks
            defined by that data.
            Failures are usually from the 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 an environment setup script (e.g.
            <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
            or
            <link linkend="structure-memres-core-script"><filename>oe-init-build-env-memres</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 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            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>
            or
            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
        </para>

        <para>
            It is also possible to place output and configuration
            files in a directory separate from the
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
            by providing a directory name when you <filename>source</filename>
            the setup script.
            For information on separating output from your local
            Source Directory files, see the
            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
            and
            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
            sections.
        </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 a sub-folder.
            For example, the files for this 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 OpenEmbedded Core metadata.
            The directory holds recipes, common classes, and machine
            configuration for 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>
            This directory contains the configuration for 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.
        </para>

        <para>
            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>
            and
            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
            scripts append 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 is one of two scripts that set up the OpenEmbedded build
            environment.
            For information on the other script, see the
            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
            section.
        </para>

        <para>
            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
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            is created, your working directory becomes the Build Directory,
            and you are presented with a list of common BitBake targets.
            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'
            </literallayout>
            The script gets its default list of common targets from the
            <filename>conf-notes.txt</filename> file, which is found in the
            <filename>meta-poky</filename> directory within the
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
            Should you have custom distributions, it is very easy to modify
            this configuration file to include your targets for 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 Manual for more
            information.
        </para>

        <para>
            By default, running this script without a
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            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
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
            <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
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
            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 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-memres-core-script'>
        <title><filename>oe-init-build-env-memres</filename></title>

        <para>
            This script is one of two scripts that set up the OpenEmbedded
            build environment.
            Aside from setting up the environment, this script starts a
            memory-resident BitBake server.
            For information on the other setup script, see the
            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
            section.
        </para>

        <para>
            Memory-resident BitBake resides in memory until you specifically
            remove it using the following BitBake command:
            <literallayout class='monospaced'>
     $ bitbake -m
            </literallayout>
        </para>

        <para>
            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.
            One of these variables is the
            <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
            variable, which allows the OpenEmbedded build system to locate
            the server that is running BitBake.
        </para>

        <para>
            You need to run an environment setup script before using BitBake
            commands.
            Following is the script syntax:
            <literallayout class='monospaced'>
     $ source oe-init-build-env-memres <replaceable>port_number</replaceable> <replaceable>build_dir</replaceable>
            </literallayout>
            Following are some considerations when sourcing this script:
            <itemizedlist>
                <listitem><para>
                    The script uses other scripts within the
                    <filename>scripts</filename> directory to do the bulk of
                    the work.
                    </para></listitem>
                <listitem><para>
                    If you do not provide a port number with the script, the
                    BitBake server starts at a randomly selected port.
                    </para></listitem>
                <listitem><para>
                    The script's parameters are positionally dependent.
                    Consequently, you cannot run the script and provide a
                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
                    name without also providing a port number.
                    In other words, the following syntax is illegal:
                    <literallayout class='monospaced'>
     $ source oe-initbuild-env-memres <replaceable>build_dir</replaceable>
                    </literallayout>
                    <note>
                        The previous restriction might be resolved in the
                        future.
                        See
                        <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=7555'>Bug 7555</ulink>
                        for more information.
                    </note>
                    </para></listitem>
            </itemizedlist>
        </para>

        <para>
            When you run this script, your Yocto Project environment is set
            up, a Build Directory is created, your working directory becomes
            the Build Directory, and you are presented with a list of common
            BitBake targets.
            Here is an example:
            <literallayout class='monospaced'>
     $ source oe-init-build-env-memres
     No port specified, using dynamically selected port

     ### 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'
     Bitbake server address: 127.0.0.1, server port: 53995
     Bitbake server started on demand as needed, use bitbake -m to shut it down
            </literallayout>
            The script gets its default list of common targets from the
            <filename>conf-notes.txt</filename> file, which is found in the
            <filename>meta-poky</filename> directory within the
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
            Should you have custom distributions, it is very easy to modify
            this configuration file to include your targets for 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 Manual for more
            information.
        </para>

        <para>
            By default, running this script without a
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
            argument creates a build directory named
            <filename>build</filename>.
            If you provide a Build Directory argument and port number when you
            <filename>source</filename> the script, the Build Directory is
            created using that name.
            For example, the following command starts the BitBake server using
            port 53995 and creates a Build Directory named
            <filename>mybuilds</filename> that is outside of the
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
            <literallayout class='monospaced'>
     $ source oe-init-build-env-memres 53995 ~/mybuilds
            </literallayout>
            The <filename>oe-init-build-env-memres</filename> script starts a
            memory resident BitBake server.
            This BitBake instance uses the
            <filename>bitbake-cookerdaemon.log</filename> file, which is
            located in the Build Directory.
        </para>

        <para>
            The OpenEmbedded build system uses the template configuration
            files, which are found by default in the
            <filename>meta-poky/conf</filename> directory in the
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
            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 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-build-env-memres</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
        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
        when you run one of the build environment setup scripts (i.e.
        <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
        or
        <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
    </para>

    <para>
        If you do not give the Build Directory a specific name when you run
        a setup script, the name defaults to <filename>build</filename>.
    </para>

    <para>
        The
        <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable
        points to the Build Directory.
    </para>

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

        <para>
            The OpenEmbedded build system creates this directory when you
            enable the build history feature.
            The directory tracks build information into image, packages, and
            SDK subdirectories.
            For information on the build history feature, see the
            "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
            section.
        </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 these
            variables are relatively rare.
        </para>

        <para>
            Edit this file to set the
            <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
            for which you want to build, 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 (i.e.
            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
            or
            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</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 defaults 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
                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
                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>
            or
            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
        </para>

        <para>
            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 defaults 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
                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
                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/conf/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
            "<link linkend='images-dev-environment'>Images</link>" and
            "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
            sections.
        </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.
        </para>
    </section>

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

        <para>
            This directory receives complete filesystem images.
            If you want to flash the resulting image from a build onto a device, look here for the image.
        </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 Software Development Kit (SDK) Developer's Guide.
        </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 <filename>COMPONENTS_DIR</filename>
            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
            "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
            section.
        </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><link linkend='var-WORKDIR'>WORKDIR</link></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 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,
        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> 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
-->