diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 80c47b0f64..9cdecb9f94 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -14,6 +14,122 @@
Yocto Project to achieve the best results.
+
+ BitBake Layers
+
+ Often, developers want to extend the Yocto Project either by adding packages
+ or by overriding files contained within the Yocto Project to add their own
+ functionality.
+ BitBake has a powerful mechanism called
+ "layers", which provides a way to handle this extension in a fully
+ supported and non-invasive fashion.
+
+
+
+ The Yocto Project files include several additional layers such as
+ meta-rt and meta-yocto
+ that demonstrate this functionality.
+ The meta-rt layer is not enabled by default.
+ However, the meta-yocto layer is.
+
+
+
+ To enable a layer, you simply add the layer's path to the
+ BBLAYERS
+ variable in your
+ conf/bblayers.conf file, which is found in the
+ Yocto Project Build Directory.
+ The following example shows how to enable the meta-rt:
+
+ LCONF_VERSION = "1"
+
+ BBFILES ?= ""
+ BBLAYERS = " \
+ /path/to/poky/meta \
+ /path/to/poky/meta-yocto \
+ /path/to/poky/meta-rt \
+ "
+
+
+
+
+ BitBake parses each conf/layer.conf file for each layer in
+ BBLAYERS
+ and adds the recipes, classes and configurations contained within the layer to
+ the Yocto Project.
+ To create your own layer, independent of the Yocto Project files,
+ simply create a directory with a conf/layer.conf file and
+ add the directory to your bblayers.conf file.
+
+
+
+ The meta-yocto/conf/layer.conf file demonstrates the
+ required syntax:
+
+ # We have a conf and classes directory, add to BBPATH
+ BBPATH := "${BBPATH}:${LAYERDIR}"
+
+ # We have a packages directory, add to BBFILES
+ BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
+ ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+ BBFILE_COLLECTIONS += "yocto"
+ BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
+ BBFILE_PRIORITY_yocto = "5"
+
+
+
+
+ In the previous example, the recipes for the layers are added to
+ BBFILES.
+ The
+ BBFILE_COLLECTIONS
+ variable is then appended with the layer name.
+ The
+ BBFILE_PATTERN
+ variable immediately expands with a regular expression used to match files from
+ BBFILES into
+ a particular layer, in this case by using the base pathname.
+ The
+ BBFILE_PRIORITY
+ variable
+ then assigns different priorities to the files in different layers.
+ Applying priorities is useful in situations where the same package might appear in multiple
+ layers and allows you to choose what layer should take precedence.
+
+
+
+ Note the use of the
+ LAYERDIR
+ variable with the immediate expansion operator.
+ The LAYERDIR variable expands to the directory of the current layer and
+ requires the immediate expansion operator so that BitBake does not wait to expand the variable
+ when it's parsing a different directory.
+
+
+
+ BitBake can locate where other .bbclass and configuration files
+ are applied through the BBPATH environment variable.
+ For these cases, BitBake uses the first file with the matching name found in
+ BBPATH.
+ This is similar to the way the PATH variable is used for binaries.
+ We recommend, therefore, that you use unique .bbclass
+ and configuration file names in your custom layer.
+
+
+
+ We also recommend the following:
+
+ Store custom layers in a Git repository that uses the
+ meta-prvt-XXXX format.
+ Clone the repository alongside other meta
+ directories in the Yocto Project source files area.
+
+ Following these recommendations keeps your Yocto Project files area and
+ its configuration entirely inside the Yocto Project's core base.
+
+
+
Adding a Package
@@ -1508,122 +1624,6 @@ so that there are some definite steps on how to do this. I need more detail her
The following section provides more advice on managing changes to the Yocto Project.
-
- BitBake Layers
-
- Often, developers want to extend the Yocto Project either by adding packages
- or by overriding files contained within the Yocto Project to add their own
- functionality.
- BitBake has a powerful mechanism called
- "layers", which provides a way to handle this extension in a fully
- supported and non-invasive fashion.
-
-
-
- The Yocto Project files include several additional layers such as
- meta-rt and meta-yocto
- that demonstrate this functionality.
- The meta-rt layer is not enabled by default.
- However, the meta-yocto layer is.
-
-
-
- To enable a layer, you simply add the layer's path to the
- BBLAYERS
- variable in your
- conf/bblayers.conf file, which is found in the
- Yocto Project Build Directory.
- The following example shows how to enable the meta-rt:
-
- LCONF_VERSION = "1"
-
- BBFILES ?= ""
- BBLAYERS = " \
- /path/to/poky/meta \
- /path/to/poky/meta-yocto \
- /path/to/poky/meta-rt \
- "
-
-
-
-
- BitBake parses each conf/layer.conf file for each layer in
- BBLAYERS
- and adds the recipes, classes and configurations contained within the layer to
- the Yocto Project.
- To create your own layer, independent of the Yocto Project files,
- simply create a directory with a conf/layer.conf file and
- add the directory to your bblayers.conf file.
-
-
-
- The meta-yocto/conf/layer.conf file demonstrates the
- required syntax:
-
- # We have a conf and classes directory, add to BBPATH
- BBPATH := "${BBPATH}:${LAYERDIR}"
-
- # We have a packages directory, add to BBFILES
- BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
- ${LAYERDIR}/recipes-*/*/*.bbappend"
-
- BBFILE_COLLECTIONS += "yocto"
- BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
- BBFILE_PRIORITY_yocto = "5"
-
-
-
-
- In the previous example, the recipes for the layers are added to
- BBFILES.
- The
- BBFILE_COLLECTIONS
- variable is then appended with the layer name.
- The
- BBFILE_PATTERN
- variable immediately expands with a regular expression used to match files from
- BBFILES into
- a particular layer, in this case by using the base pathname.
- The
- BBFILE_PRIORITY
- variable
- then assigns different priorities to the files in different layers.
- Applying priorities is useful in situations where the same package might appear in multiple
- layers and allows you to choose what layer should take precedence.
-
-
-
- Note the use of the
- LAYERDIR
- variable with the immediate expansion operator.
- The LAYERDIR variable expands to the directory of the current layer and
- requires the immediate expansion operator so that BitBake does not wait to expand the variable
- when it's parsing a different directory.
-
-
-
- BitBake can locate where other .bbclass and configuration files
- are applied through the BBPATH environment variable.
- For these cases, BitBake uses the first file with the matching name found in
- BBPATH.
- This is similar to the way the PATH variable is used for binaries.
- We recommend, therefore, that you use unique .bbclass
- and configuration file names in your custom layer.
-
-
-
- We also recommend the following:
-
- Store custom layers in a Git repository that uses the
- meta-prvt-XXXX format.
- Clone the repository alongside other meta
- directories in the Yocto Project source files area.
-
- Following these recommendations keeps your Yocto Project files area and
- its configuration entirely inside the Yocto Project's core base.
-
-
-
Committing Changes