blob: 541a47e55673eb0a84ef178fef428886065e4a40 [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 <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'>
<title><filename>build/tmp/sysroots/</filename></title>
<para>
This directory contains shared header files and libraries as well as other shared
data.
Packages that need to share output with other packages do so within this directory.
The directory is subdivided by architecture so multiple builds can run within
the one Build Directory.
</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-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
-->