blob: 8e0c9f5b6261242d8e0be99776f3dc909b55a864 [file] [log] [blame]
<!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 <link linkend='source-directory'>Source Directory</link>
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;#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 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 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, 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 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>
script appends 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 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
<link linkend='source-directory'>Source Directory</link>.
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 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 scripts (i.e.
<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</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
"<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 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>).
</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
<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>
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
<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/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
"<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 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 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
-->