forked from brl/citadel
1125 lines
48 KiB
XML
1125 lines
48 KiB
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 <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;#working-with-yocto-project-source-files'>Working With 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 <target>'
|
|
|
|
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
|
|
<link linkend='build-directory'>Build Directory</link>
|
|
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
|
|
"<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>).
|
|
</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
|
|
"<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 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
|
|
"<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+<.....></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 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
|
|
-->
|