From 3a6948a2af25c1094b22a70c923dfecc296dad8b Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 8 Jun 2010 17:18:29 +0100 Subject: handbook: add documentation for layers Collections and overlays are deprecated in favour of layers, a much cleaner and non-intrusive way of extending Poky with custom recipes, classes and configuration. This patch updates the Extending Poky section of the handbook to show how to use layers to tailor Poky while dropping the existing section on using collections. Signed-off-by: Joshua Lock --- handbook/extendpoky.xml | 148 ++++++++++++++++++++++++---------------------- handbook/introduction.xml | 2 +- handbook/ref-bitbake.xml | 7 ++- 3 files changed, 83 insertions(+), 74 deletions(-) (limited to 'handbook') diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml index f072fe5032..b437c77fa3 100644 --- a/handbook/extendpoky.xml +++ b/handbook/extendpoky.xml @@ -518,85 +518,93 @@ bitbake poky-image-sato Poky supports the idea of "collections" which when used + linkend='usingpoky-changes-layers'>"layers" which when used properly can massively ease future upgrades and allow segregation between the Poky core and a given developer's changes. Some other advice on managing changes to Poky is also given in the following section. -
- Bitbake Collections +
+ Bitbake Layers - + Often, people want to extend Poky either through adding packages or overriding files contained within Poky to add their own functionality. Bitbake has a powerful mechanism called - collections which provide a way to handle this which is fully - supported and actively encouraged within Poky. - - - In the standard tree, meta-extras is an example of how you can - do this. As standard the data in meta-extras is not used on a - Poky build but local.conf.sample shows how to enable it: - - - -BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb" -BBFILE_COLLECTIONS = "normal extras" -BBFILE_PATTERN_normal = "^${OEROOT}/meta/" -BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/" -BBFILE_PRIORITY_normal = "5" -BBFILE_PRIORITY_extras = "5" - - - As can be seen, the extra recipes are added to BBFILES. The - BBFILE_COLLECTIONS variable is then set to contain a list of - collection names. The BBFILE_PATTERN variables are regular - expressions used to match files from BBFILES into a particular - collection in this case by using the base pathname. - The BBFILE_PRIORITY variable then assigns the different - priorities to the files in different collections. This is useful - in situations where the same package might appear in both - repositories and allows you to choose which collection should - 'win'. - - - This works well for recipes. For bbclasses and configuration - files, you can use the BBPATH environment variable. In this - case, the first file with the matching name found in BBPATH is - the one that is used, just like the PATH variable for binaries. - -
- -
- Supplementry Metadata Repositories - - - Often when developing a project based on Poky there will be components - that are not ready for public consumption for whatever reason. By making - use of the collections mechanism and other functionality within Poky, it - is possible to have a public repository which is supplemented by a private - one just containing the pieces that need to be kept private. - - - The usual approach with these is to create a separate git repository called - "meta-prvt-XXX" which is checked out alongside the other meta-* - directories included in Poky. Under this directory there can be several - different directories such as classes, conf and packages which all - function as per the usual Poky directory structure. - - - If extra meta-* directories are found, Poky will automatically add them - into the BBPATH variable so the conf and class files contained there - are found. If a file called poky-extra-environment is found within the - meta-* directory, this will be sourced as the environment is setup, - allowing certain configuration to be overridden such as the location of the - local.conf.sample file that is used. - - - Note that at present, BBFILES is not automatically changed and this needs - to be adjusted to find files in the packages/ directory. Usually a custom - local.conf.sample file will be used to handle this instead. + layers which provides a way to handle this extension in a fully + supported and non-invasive fashion. + + + + The Poky tree includes two additional layers which demonstrate + this functionality, meta-moblin and meta-extras. + The meta-extras repostory is not enabled by default but enabling + it is as easy as adding the layers path to the BBLAYERS variable in + your bblayers.conf, this is how all layers are enabled in Poky builds: + + + LCONF_VERSION = "1" + +BBFILES ?= "" +BBLAYERS = " \ + ${OEROOT}/meta \ + ${OEROOT}/meta-moblin \ + ${OEROOT}/meta-extras \ + " + + + + + Bitbake parses the conf/layer.conf of each of the layers in BBLAYERS + to add the layers packages, classes and configuration to Poky. + To create your own layer, independent of the main Poky repository, + you need only create a directory with a conf/layer.conf file and + add the directory to your bblayers.conf. + + + + The meta-extras layer.conf 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}/packages/*/*.bb" + +BBFILE_COLLECTIONS += "extras" +BBFILE_PATTERN_extras := "^${LAYERDIR}/" +BBFILE_PRIORITY_extras = "5" + +require conf/distro/include/poky-extras-src-revisions.inc + + + + + As can be seen, the layers recipes are added to BBFILES. The + BBFILE_COLLECTIONS variable is then appended to with the + layer name. The BBFILE_PATTERN variable is immediately expanded + 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. This is useful + in situations where the same package might appear in multiple + layers and allows you to choose which layer should 'win'. + + + + Extra bbclasses and configuration are added to the BBPATH + environment variable. In this case, the first file with the + matching name found in BBPATH is the one that is used, just + like the PATH variable for binaries. It is therefore recommended + that you use unique bbclass and configuration file names in your + custom layer. + + + + The recommended approach for custom layers is to store them in a + git repository of the format meta-prvt-XXXX and have this repository + cloned alongside the other meta directories in the Poky tree. + This way you can keep your Poky tree and it's configuration entirely + inside OEROOT.
diff --git a/handbook/introduction.xml b/handbook/introduction.xml index 1796abfdd7..a7ea20ff0d 100644 --- a/handbook/introduction.xml +++ b/handbook/introduction.xml @@ -117,7 +117,7 @@ build-essential - python + python (version 2.6 or later) diffstat diff --git a/handbook/ref-bitbake.xml b/handbook/ref-bitbake.xml index 8652424466..ddf3c760f2 100644 --- a/handbook/ref-bitbake.xml +++ b/handbook/ref-bitbake.xml @@ -81,9 +81,10 @@ default this specifies the meta/packages/ directory within Poky, but other directories such as meta-extras/ can be included - too. If multiple directories are specified a system referred to as - "collections" is used to - determine which files have priority. + too. Adding extra content to + BBFILES is best + acheived through the use of Bitbake + "layers". -- cgit 1.2.3-korg