diff options
| -rw-r--r-- | handbook/extendpoky.xml | 148 | ||||
| -rw-r--r-- | handbook/introduction.xml | 2 | ||||
| -rw-r--r-- | handbook/ref-bitbake.xml | 7 |
3 files changed, 83 insertions, 74 deletions
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 </para> <para> Poky supports the idea of <link - linkend='usingpoky-changes-collections'>"collections"</link> which when used + linkend='usingpoky-changes-layers'>"layers"</link> 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. </para> - <section id="usingpoky-changes-collections"> - <title>Bitbake Collections</title> + <section id="usingpoky-changes-layers"> + <title>Bitbake Layers</title> - <para> + <para> 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. - </para> - <para> - 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: - </para> - <para> - <literallayout class='monospaced'> -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"</literallayout> - </para> - <para> - 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'. - </para> - <para> - 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. - </para> - </section> - - <section id="usingpoky-changes-supplement"> - <title>Supplementry Metadata Repositories</title> - - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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. + </para> + + <para> + 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: + </para> + <para> + <literallayout class='monospaced'>LCONF_VERSION = "1" + +BBFILES ?= "" +BBLAYERS = " \ + ${OEROOT}/meta \ + ${OEROOT}/meta-moblin \ + ${OEROOT}/meta-extras \ + " +</literallayout> + </para> + + <para> + 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. + </para> + + <para> + The meta-extras layer.conf demonstrates the required syntax: + <literallayout class='monospaced'># 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 + </literallayout> + </para> + + <para> + 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'. + </para> + + <para> + 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. + </para> + + <para> + 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. </para> </section> 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 @@ <para>build-essential</para> </listitem> <listitem> - <para>python</para> + <para>python (version 2.6 or later)</para> </listitem> <listitem> <para>diffstat</para> 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 <filename class="directory">meta/packages/ </filename> directory within Poky, but other directories such as <filename class="directory">meta-extras/</filename> can be included - too. If multiple directories are specified a system referred to as - <link linkend='usingpoky-changes-collections'>"collections"</link> is used to - determine which files have priority. + too. Adding extra content to + <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> is best + acheived through the use of Bitbake + <link linkend='usingpoky-changes-layers'>"layers"</link>. </para> <para> |