summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--handbook/extendpoky.xml148
-rw-r--r--handbook/introduction.xml2
-rw-r--r--handbook/ref-bitbake.xml7
3 files changed, 83 insertions, 74 deletions
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index f072fe503..b437c77fa 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 1796abfdd..a7ea20ff0 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 865242446..ddf3c760f 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>