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