diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png
index 2c81dae08c..b4dafe60a2 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 79d16549c3..664c4f7986 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -222,147 +222,309 @@
environment:
-
-
-
-
-
+
+
+
+ BitBake needs some basic configuration files in order to complete
+ a build.
+ These files are *.conf files.
+ The minimally necessary ones reside as example files in the
+ 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.
+
+
+
+ The meta-yocto layer inside Poky contains
+ a conf directory that has example
+ configuration files.
+ 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
+ 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.
+
+
+
+ The local.conf file provides many
+ basic variables that define your build.
+ 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
+ local.conf.sample in the
+ meta-yocto layer:
+
+ Parallelism Options:
+ Controlled by the
+ BB_NUMBER_THREADS
+ and
+ PARALLEL_MAKE
+ variables.
+ Target Machine Selection:
+ Controlled by the
+ MACHINE
+ variable.
+ Download Directory:
+ Controlled by the
+ DL_DIR
+ variable.
+ Shared State Directory:
+ Controlled by the
+ SSTATE_DIR
+ variable.
+ Build Output:
+ Controlled by the
+ TMPDIR
+ variable.
+
+
+
+
+ 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.
+ You can find more information on working with the
+ bblayers.conf file in the
+ "Enabling Your Layer"
+ section in the Yocto Project Development Manual.
+
+
+
+ The files site.conf and
+ auto.conf are not created by the environment
+ initialization script.
+ If you want these configuration files, you must create them
+ 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.
+ 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 can edit all configuration files to further define
+ the build.
+ This process is represented by the "User Configuration Edits"
+ box in the figure.
+
+
+
+ When you launch your build with the
+ bitbake <target> command, BitBake
+ draws on the user configurations you have provided in your
+ Build Directory.
+
+
+
+
+ Metadata, Machine Configuration, and Policy Configuration
+
+
+ The previous section described the user configurations that
+ define the BitBake's global behavior.
+ This section takes a closer look at the layers the build system
+ uses to further control the build.
+ These layers provide Metadata for the software, machine, and
+ policy.
+
- BitBake needs some basic configuration files in order to complete
- a build.
- These files are *.conf files.
- The minimally necessary ones reside as example files in the
- 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.
- Here, though, we will assume that you have a cloned repository that
- has the default name poky.
-
-
-
- The meta-yocto layer inside Poky contains
- a conf directory that has example
- configuration files.
- 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
- Build Directory
- that BitBake uses as the area in which it does 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.
-
-
-
- The local.conf file provides many
- basic variables that define your build.
- 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
- local.conf.sample in the
- meta-yocto layer:
+ In general, three types of layer input exist:
- Parallelism Options:
- Controlled by the
- BB_NUMBER_THREADS
- and
- PARALLEL_MAKE
- variables.
- Target Machine Selection:
- Controlled by the
- MACHINE
- variable.
- Download Directory:
- Controlled by the
- DL_DIR
- variable.
- Shared State Directory:
- Controlled by the
- SSTATE_DIR
- variable.
- Build Output:
- Controlled by the
- TMPDIR
- variable.
+ 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.
- 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.
- You can find more information on working with the
- bblayers.conf file in the
- "Enabling Your Layer"
+ The following figure shows an expanded representation of the
+ Metadata, Machine Configuration, and Policy Configuration input
+ 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.
+
+
+
+ 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.
+
+
+
+ For more information on layers, see the
+ "Understanding and Creating Layers"
section in the Yocto Project Development Manual.
-
- The files site.conf and
- auto.conf are not created by the environment
- initialization script.
- If you want these configuration files, you must create them
- 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.
- 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.
-
-
-
+
+ Software Layer
-
- You can edit all configuration files to further define
- the build.
- This process is represented by the "User Configuration Edits"
- box in the figure.
-
+
+ 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).
+
-
- When you launch your build with the
- bitbake <target> command, BitBake
- draws on the user configurations you have provided in your
- 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.
+
+
+
+
+ Distro 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 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.
+
+
+
+
+
+ BSP Layer
+
+
+ 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.
+
+
+
+ The BSP Layer contains a configuration directory that has
+ configuration files for the machine
+ (<machine>.conf) and, of course,
+ the layer (layer.conf).
+
+
+
+ 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.
+
+