diff --git a/documentation/ref-manual/figures/layer-input.png b/documentation/ref-manual/figures/layer-input.png
index f06c9ba6b6..1e22bd713b 100644
Binary files a/documentation/ref-manual/figures/layer-input.png and b/documentation/ref-manual/figures/layer-input.png differ
diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png
index b4dafe60a2..5f49e2fccf 100644
Binary files a/documentation/ref-manual/figures/user-configuration.png and b/documentation/ref-manual/figures/user-configuration.png differ
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 664c4f7986..77c1ba84e4 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -157,25 +157,18 @@
A Closer Look at the Yocto Project Development Environment
- This section is a work-in-progress for an expanded discussion of the
- Yocto Project Development Environment.
- The section is rooted in the figure found in the
- "Introducing the Yocto Project Development Environment"
- section of the Yocto Project Quick Start.
- This expanded discussion presents a deeper level of detail regarding
- input, output, and
- Metadata.
+ This section takes a more detailed look at the Yocto Project
+ development environment.
+ The following diagram represents the development environment at a
+ high level.
+ The remainder of this section expands on the fundamental input, output,
+ process, and
+ Metadata) blocks
+ in the Yocto Project development environment.
- I will either replicate the exact figure from the YP Quick Start here
- or I will create a more simplified version that can be used as the
- top-level diagram from which to base subsequent sections and expanded
- illustrations.
-
-
-
- [NEED REPEATED FIGURE HERE OR A NEW FIGURE]
+
@@ -222,7 +215,9 @@
environment:
-
+
+
+
BitBake needs some basic configuration files in order to complete
@@ -232,15 +227,21 @@
Source Directory.
For simplicity, this section refers to the Source Directory as
the "Poky Directory."
-
- Poky is primarily an aggregation of existing repositories and
- is not actual canonical upstream source for anything.
-
+
+
+
When you clone the poky Git repository or you
download and unpack a Yocto Project release, you can set up the
Source Directory to be named anything you want.
For this discussion, the cloned repository uses the default
name poky.
+ Within the figure, layers appear inside the Source Directory using
+ a bold typeface.
+
+ The Poky repository is primarily an aggregation of existing
+ repositories.
+ It is not a canonical upstream source.
+
@@ -250,35 +251,50 @@
These example files are used as a basis for creating actual
configuration files when you source the build environment
script oe-init-build-env.
-
- The oe-init-build-env script also exists
- in the meta directory of the OE-Core
- root directory.
- Both scripts look for sample configuration files through
- a $TEMPLATECONF variable.
- When using the Yocto Project Development Environment,
- that location resolves to the samples found in the
- poky/meta-yocto/conf directory.
-
- When you source the build environment script, it creates a
+ Sourcing the build environment script creates a
Build Directory
if one does not already exist.
BitBake uses the Build Directory for all its work during builds.
The Build Directory has a conf directory that
contains default versions of your local.conf
and bblayers.conf configuration files.
- These default configuration files are created by
- oe-init-build-env only if versions of these
- files do not already exist in the Build Directory you specify
- when you run the script.
+ These default configuration files are created only if versions
+ do not already exist in the Build Directory at the time you
+ source the oe-init-build-env script.
+
+
+
+ Because the Poky repository is fundamentally an aggregation of
+ existing repositories, some users might be familiar with running
+ the oe-init-build-env script in the context
+ of the OpenEmbedded development environment, which is outside
+ of the Yocto Project development environment.
+ This discussion assumes the script is executed from within a
+ cloned or unpacked version of Poky (i.e. within the Yocto Project
+ environment).
+
+
+
+ Depending on where the script is sourced, different sub-scripts
+ are called to set up the Build Directory (Yocto or OpenEmbedded).
+ Specifically, the script
+ scripts/oe-setup-builddir inside the
+ poky directory sets up the Build Directory and seeds the directory
+ (if necessary) with configuration files appropriate for the
+ Yocto Project development environment.
+
+ The scripts/oe-setup-builddir script
+ uses the $TEMPLATECONF variable to
+ determine which sample configuration files to locate.
+
The local.conf file provides many
- basic variables that define your build.
+ basic variables that define a build environment.
Here is a list of a few.
To see the default configurations in a local.conf
file created by the build environment script, see the
@@ -308,14 +324,20 @@
TMPDIR
variable.
+
+ Configurations set in the conf/local.conf
+ file can also be set in the
+ conf/site.conf and
+ conf/auto.conf configuration files.
+
The bblayers.conf file tells BitBake what
- layers you want it to consider during the build.
- The list of layers includes default layers needed by the build
- system.
- You have to manually add any custom layers that you have created.
+ layers you want considered during the build.
+ By default, the layers listed in this file include layers
+ minimally needed by the build system.
+ However, you must manually add any custom layers you have created.
You can find more information on working with the
bblayers.conf file in the
"Enabling Your Layer"
@@ -330,24 +352,44 @@
yourself:
site.conf:
- I don't really know what this does.
- All I know is that if you want it, you need to hand-create
- it.
- I need some information on it.
+ You can use the conf/site.conf
+ configuration file to configure multiple build directories.
+ For example, suppose you had several build environments and
+ they shared some common features.
+ You can set these default build properties here.
+ A good example is perhaps the level of parallelism you want
+ to use through the
+ BB_NUMBER_THREADS
+ and
+ PARALLEL_MAKE
+ variables.
+ One useful scenario for using the
+ conf/site.conf file is to extend your
+ BBPATH
+ variable to include the path to a
+ conf/site.conf.
+ Then, when BitBake looks for Metadata using
+ BBPATH, it finds the
+ conf/site.conf file and applies your
+ common configurations found in the file.
+ To override configurations in a particular build directory,
+ alter the similar configurations within that build
+ directory's conf/local.conf file.
+ auto.conf:
This file is not hand-created.
Rather, the file is usually created and written to by
an autobuilder.
The settings put into the file are typically the same as
- you would find in the local.conf
- or site.conf files.
+ you would find in the conf/local.conf
+ or the conf/site.conf files.
You can edit all configuration files to further define
- the build.
+ any particular build environment.
This process is represented by the "User Configuration Edits"
box in the figure.
@@ -355,8 +397,8 @@
When you launch your build with the
bitbake <target> command, BitBake
- draws on the user configurations you have provided in your
- Build Directory.
+ sorts out the configurations to ultimately define your build
+ environment.
@@ -372,159 +414,174 @@
policy.
-
- In general, three types of layer input exist:
-
- Metadata:
- Software layers contain user-supplied recipe files,
- patches, and append files.
-
- Machine Configuration:
- Board Support Package (BSP) layers provide machine
- configurations.
- This type of information is specific to a particular
- target architecture.
- Policy Configuration:
- Distribution Layers provide top-level or general
- policies for the image or SDK being built.
- For example, this layer would dictate whether BitBake
- produces RPM or IPK packages.
-
-
+
+ In general, three types of layer input exist:
+
+ Policy Configuration:
+ Distribution Layers provide top-level or general
+ policies for the image or SDK being built.
+ For example, this layer would dictate whether BitBake
+ produces RPM or IPK packages.
+ Machine Configuration:
+ Board Support Package (BSP) layers provide machine
+ configurations.
+ This type of information is specific to a particular
+ target architecture.
+ Metadata:
+ Software layers contain user-supplied recipe files,
+ patches, and append files.
+
+
+
-
+
The following figure shows an expanded representation of the
Metadata, Machine Configuration, and Policy Configuration input
- boxes of the Yocto Project development environment:
-
+ (layers) boxes of the Yocto Project development environment:
+
-
+
+
+
-
- The Yocto Project has many layers that can be used.
- You can see a web-interface listing of them on the
- Source Repositories
- page.
- The layers are shown at the bottom categorized under
- "Yocto Metadata Layers."
- These layers are fundamentally a subset of the
- OpenEmbedded Metadata Index,
- which shows all layers supported by OpenEmbedded.
-
+
+ In general, all layers have a similar structure.
+ They all contain a licensing file
+ (e.g. COPYING) if the layer is to be
+ distributed, a README file as good practice
+ and especially if the layer is to be distributed, a
+ configuration directory, and recipe directories.
+
-
- Layers exist in the Yocto Project Source Repositories that cannot
- be found in the OpenEmbedded Metadata Index.
- These layers are either deprecated or experimental in nature.
-
+
+ The Yocto Project has many layers that can be used.
+ You can see a web-interface listing of them on the
+ Source Repositories
+ page.
+ The layers are shown at the bottom categorized under
+ "Yocto Metadata Layers."
+ These layers are fundamentally a subset of the
+ OpenEmbedded Metadata Index,
+ which lists all layers provided by the OpenEmbedded community.
+
+ Layers exist in the Yocto Project Source Repositories that
+ cannot be found in the OpenEmbedded Metadata Index.
+ These layers are either deprecated or experimental in nature.
+
+
-
- BitBake uses the bblayers.conf file that is
- part of the user configuration to find what layers it should be
- using as part of the build.
-
+
+ BitBake uses the conf/bblayers.conf file,
+ which is part of the user configuration, to find what layers it
+ should be using as part of the build.
+
-
- For more information on layers, see the
- "Understanding and Creating Layers"
- section in the Yocto Project Development Manual.
-
+
+ For more information on layers, see the
+ "Understanding and Creating Layers"
+ section in the Yocto Project Development Manual.
+
-
- Software Layer
+
+ Distro Layer
-
- The software layer provides the Metadata for your source
- code used during the build.
- This general layer minimally contains license
- information; a README file; a layer
- configuration file named layer.conf;
- and recipe files (.bb), append files
- (.bbappend), and patches
- (.patch).
-
+
+ The distribution layer provides policy configurations for your
+ distribution.
+ Best practices dictate that you isolate these types of
+ configurations into their own layer.
+ Settings you provide in
+ conf/<distro>.conf override similar
+ settings that BitBake finds in your
+ conf/local.conf file in the Build
+ Directory.
+
-
- You provide any new recipes that your project needs in the
- form of recipe files.
- If you are modifying any existing recipes from other layers,
- rather than duplicate them here with the modifcations, you can
- provide a recipe append file that just has the modifications.
- Patch files are stored in the files
- directory.
-
-
+
+ The following list provides some explanation and references
+ for what you typically find in the distribution layer:
+
+ classes:
+ Class files (.bbclass) holds
+ common functionality that can be shared among
+ recipes in the distribution.
+ When your recipes inherit a class, they take on the
+ settings and functions for that class.
+ You can read more about class files in the
+ "Classes" section.
+
+ conf:
+ This area holds configuration files for the
+ layer (conf/layer.conf),
+ the distribution
+ (conf/distro/<distro<.conf),
+ and any distribution-wide include files.
+
+ recipes-*:
+ Recipes and append files that affect common
+ functionality across the distribution.
+ This area also can hold common distribution headers,
+ initialization files, and
+ <recipe>/files/defconfig
+ files for the distribution.
+
+
+
-
- Distro Layer
+
+ BSP Layer
-
- The distribution layer provides policy configurations for your
- distribution.
- Best practices dictate that you isolate these types of
- configurations into their own layer.
- Metadata you provide in this layer overrides similar settings
- that BitBake finds in your local.conf
- file in the Build Directory.
-
+
+ The BSP Layer provides machine configurations.
+ Everything in this layer is specific to the machine for which
+ you are building the image or the SDK.
+ BSP Layers have a structure that is followed if they are
+ considered to be compatible with the Yocto Project.
+ For information on the structure, see the
+ Yocto Project Board Support Package (BSP) Developer's Guide.
+
-
- The following list provides some explanation and references
- for what you typically find in the distribution layer:
-
- classes:
- Class files (.bbclass) hold
- common functionality that can be shared among
- recipes in the distribution.
- When your recipes inherit a class, they take on the
- settings and functions for that class.
- You can read more about class files in the
- "Classes" section.
-
- conf:
- This area holds configuration information for the
- distribution.
- Any distribution-wide include files and, of course, the
- layer.conf configuration
- file that every layer must have.
- recipes-core:
- Recipes and append files that affect common
- functionality across the distribution.
- This area also can hold common distribution headers,
- initialization files, and
- defconfig files for the
- distribution.
-
-
-
+
+ The BSP Layer's configuration directory contains
+ configuration files for the machine
+ (conf/machine/<machine>.conf) and,
+ of course, the layer (conf/layer.conf).
+
-
- BSP Layer
+
+ The remainder of the layer is dedicated to specific recipes
+ by function: recipes-bsp,
+ recipes-core,
+ recipes-graphics, and
+ recipes-kernel.
+ Metadata can exist for multiple formfactors, graphics
+ support systems, and so forth.
+
+ While the figure shows several recipe-*
+ directories, not all these directories appear in all
+ BSP layers.
+
+
+
-
- The BSP Layer provides machine configurations.
- Everything in this layer is specific to the machine for which
- you are building the image or the SDK.
- BSP Layer's have a structure that is followed if they are
- considered to be compatible with the Yocto Project.
- For information on the structure, see the
- Yocto Project Board Support Package (BSP) Developer's Guide.
-
+
+ Software Layer
-
- The BSP Layer contains a configuration directory that has
- configuration files for the machine
- (<machine>.conf) and, of course,
- the layer (layer.conf).
-
+
+ The software layer provides the Metadata for your source
+ code used during the build.
+ This layer does not include Metadata that is specific to the
+ distribution or the machine, which are found in their
+ respective layers.
+
-
- The remainder of the layer is dedicated to specific recipes
- by function: bsp, core, graphics, and kernel.
- Metadata can exist for multiple formfactors, graphics
- support systems, and so forth.
-
-
+
+ This layer contains any new recipes that your project needs
+ in the form of recipe files.
+ Patch files are stored in the files
+ directory.
+
+