diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index ab140207aa..ad4a7613a9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -16,58 +16,87 @@
Understanding and Creating 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 build system supports organizing metadata
+ into multiple layers.
+ Layers allow you to isolate different types of customizations from each other.
+ You might find it tempting to keep everything in one layer when working on a single project.
+ However, the more modular you organize your metadata, the easier it is to cope with future changes.
- 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 illustrate how layers are used to keep things modular, consider machine customizations.
+ These types of customizations typically reside in a BSP Layer.
+ Furthermore, the machine customizations should be isolated from recipes and metadata that support
+ a new GUI environment, for example.
+ This situation gives you a couple a layers: one for the machine configurations, and one for the
+ GUI environment.
+ It is important to understand, however, that the BSP layer can still make machine-specific
+ additions to recipes within the GUI environment layer without polluting the GUI layer itself
+ with those machine-specific changes.
+ You can accomplish this through an appending recipe (a .bbappend file),
+ which is described later in this section.
- 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.
-
+
+ Yocto Project Layers
-
- The meta-yocto/conf/layer.conf file demonstrates the
- required syntax:
-
+
+ The Yocto Project contains several layers right out of the box.
+ You can easily identify a layer in the Yocto Project by the name of its folder.
+ Folders that are layers begin with the string meta.
+ For example, when you set up the Yocto Project Files
+ structure, you will see several layers: meta, meta-demoapps,
+ meta-skeleton, and meta-yocto.
+ Each of these folders is a layer.
+
+
+
+ Furthermore, if you set up a local copy of the meta-intel Git repository
+ and then explore that folder, you will discover many BSP layers within the
+ meta-intel layer.
+ For more information on BSP layers, see the
+ "BSP Layers"
+ section in the Yocto Project Development Manual.
+
+
+
+
+ Creating Your Own Layer
+
+
+ It is very easy to create your own layer to use with the Yocto Project.
+ Follow these general steps to create your layer:
+
+ Check Existing Layers: Before creating a new layer,
+ you should be sure someone has not already created a layer containing the metadata
+ you need.
+ You can see the
+ LayerIndex
+ to determine what types of layers already exist in the Yocto Project.
+ Create a Directory: Create the directory
+ for your layer.
+ Traditionally, prepend the name of the folder with the string
+ meta.
+ For example:
+
+ meta-mylayer
+ meta-GUI_xyz
+ meta-mymachine
+
+ Create a Layer Configuration File: Inside your new
+ layer folder, you need to create a conf/layer.conf file.
+ It is easiest to take an existing layer configuration file and copy that to your
+ layer's conf directory and then modify the file as needed.
+ The meta-yocto/conf/layer.conf file demonstrates the
+ required syntax:
+
# We have a conf and classes directory, add to BBPATH
- BBPATH := "${BBPATH}:${LAYERDIR}"
+ BBPATH := "${LAYERDIR}:${BBPATH}"
# We have a packages directory, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
@@ -76,58 +105,243 @@
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.
+ Add Content: Depending on the type of layer,
+ add the content.
+ If the layer adds support for a machine, add the machine configuration in
+ a conf/machine/ file within the layer.
+ If the layer adds distro policy, add the distro configuration in a
+ conf/distro/ file with the layer.
+ If the layer introduces new recipes, put the recipes you need in
+ recipes-* subdirectories within the layer.
+
+
-
- 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.
-
+
+ To create layers that are easier to maintain, you should consider the following:
+
+ Avoid "overlaying" entire recipes from other layers in your
+ configuration.
+ In other words, don't copy an entire recipe into your layer and then modify it.
+ Use .bbappend files to override the parts of the
+ recipe you need to modify.
+ Avoid duplicating include files.
+ Use .bbappend files for each recipe that uses an include
+ file.
+ Or, if you are introducing a new recipe that requires the inc file, use the
+ full path to refer to the original.
+ For example, use require recipes-core/somepackage/somefile.inc
+ instead of require somefile.inc.
+ If you're finding you have to overlay the include file, it could indicate a
+ deficiency in the include file in the layer to which it originally belongs.
+ If this is the case, you need to address that deficiency instead of overlaying
+ the include file.
+ For example, consider how Qt 4 database support plugins are configured.
+ The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's
+ layer meta-oe does.
+ Consequently, meta-oe uses .bbappend
+ files to modify the QT_SQL_DRIVER_FLAGS variable to enable
+ the appropriate plugins.
+ This variable was added to the qt4.inc include file in
+ The Yocto Project specifically to allow the meta-oe layer
+ to be able to control which plugins are built.
+
+
-
- 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.
-
+
+ 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.
+
+
-
- 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.
-
+
+ Enabling Your 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.
-
+
+ Before the Yocto Project build system can use your new layer, you need to enable it.
+ To enable your layer, simply add your 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 a layer named meta-mylayer:
+
+ LCONF_VERSION = "1"
+
+ BBFILES ?= ""
+ BBLAYERS = " \
+ /path/to/poky/meta \
+ /path/to/poky/meta-yocto \
+ /path/to/poky/meta-mylayer \
+ "
+
+
+
+
+ BitBake parses each conf/layer.conf file as specified in the
+ BBLAYERS variable within the conf/bblayers.conf
+ file.
+ During the processing of each conf/layer.conf file, BitBake adds the
+ recipes, classes and configurations contained within the particular 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.
+
+
+
+
+ Using .bbappend Files
+
+
+ Recipe append files (.bbappend type) allow your layer to make additions or
+ changes to the content of another layer's recipe without having to copy the other recipe into
+ your layer.
+ Your .bbappend file resides in your layer, while the underlying recipe
+ to which you are appending resides in a different layer.
+
+
+
+ Append files files must have the same name as the underlying recipe.
+ For example, the append file someapp_1.1.bbappend must
+ apply to someapp_1.1.bb.
+ This means the original recipe and append file names are version number specific.
+ If the underlying recipe is renamed to update to a newer version, the
+ corresponding .bbappend file must be renamed as well.
+ During the build process, BitBake displays warnings on starting if it detects a
+ .bbappend file that does not have an underlying recipe
+ with the proper name.
+
+
+
+ Being able to append information to an existing recipe not only avoids duplication,
+ but also automatically applies recipe changes in a different layer to your layer.
+ If you were copying recipes, you would have to manually merge changes as they occur.
+
+
+
+ As an example, consider the main formfactor recipe and a corresponding formfactor
+ append file both from the Yocto Project Files.
+ Here is the main formfactor recipe, which is named formfactor_0.0.bb and
+ located in the meta layer at meta/bsp-recipes/formfactor:
+
+ DESCRIPTION = "Device formfactor information"
+ SECTION = "base"
+ LICENSE = "MIT"
+ LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
+ file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+ PR = "r19"
+
+ SRC_URI = "file://config file://machconfig"
+ S = "${WORKDIR}"
+
+ PACKAGE_ARCH = "${MACHINE_ARCH}"
+ INHIBIT_DEFAULT_DEPS = "1"
+
+ do_install() {
+ # Only install file if it has a contents
+ install -d ${D}${sysconfdir}/formfactor/
+ install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
+ if [ -s "${S}/machconfig" ]; then
+ install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
+ fi
+ }
+
+ Here is the append file, which is named formfactor_0.0.bbappend and is from the
+ Crown Bay BSP Layer named meta-intel/meta-crownbay:
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+ PRINC = "1"
+
+ This example adds or overrides files in
+ SRC_URI
+ within a bbappend by extending the path BitBake uses to search for files.
+ The most reliable way to do this is by prepending the
+ FILESEXTRAPATHS variable.
+ For example, if you have your files in a directory that is named the same as your package
+ (PN),
+ you can add this directory by adding the following to your bbappend file:
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+ Using the immediate expansion assignment operator := and the trailing colon
+ are important so that the resulting list of pathnames is syntactically correct.
+ BitBake automatically defines the THISDIR variable.
+ You should never set this variable yourself.
+ Using _prepend ensures your path will be searched prior to other
+ paths in the final list.
+
+
+
+
+
+ Prioritizing Your Layer
+
+
+ Each layer is assigned a priority value.
+ Priority values control which layer takes precedence if there are recipe files with
+ the same name in multiple layers.
+ For these cases, the recipe file from the layer with a higher priority number taking precedence.
+ Priority values also affect the order in which multiple .bbappend files
+ for the same recipe are applied.
+ You can either specify the priority manually, or allow the build system to calculate it
+ based on the layer's dependencies.
+
+
+
+ To specify the layer's priority manually, use the
+ BBFILE_PRIORITY
+ variable.
+ For example:
+
+ BBFILE_PRIORITY := "1"
+
+
+
+
+ It is possible for a recipe with a lower version number
+ PV
+ in a layer that has a higher priority to take precedence.
+ Also, the layer priority does not currently affect the precedence order of
+ .conf or .bbclass files.
+ Future versions of BitBake might address this.
+
+
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index e076c8ff02..6df59983e7 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -177,12 +177,13 @@
For a list of the supported image types that the Yocto Project provides, see the
"Reference: Images"
appendix in The Yocto Project Reference Manual.
- Layer: A collection of recipes representing the core,
+ Layer: A collection of recipes representing the core,
a BSP, or an application stack.
For a discussion on BSP Layers, see the
"BSP Layers"
section in the Yocto Project Board Support Packages (BSP) Developer's Guide.
- Metadata: The files that BitBake parses when building an image.
+ Metadata: The files that BitBake parses when
+ building an image.
Metadata includes recipes, classes, and configuration files.OE-Core: A core set of metadata originating
with OpenEmbedded (OE) that is shared between OE and the Yocto Project.