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 <josh@linux.intel.com>
This commit is contained in:
parent
6a9312cccc
commit
3a6948a2af
|
@ -518,85 +518,93 @@ bitbake poky-image-sato
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Poky supports the idea of <link
|
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
|
properly can massively ease future upgrades and allow segregation
|
||||||
between the Poky core and a given developer's changes. Some other advice on
|
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.
|
managing changes to Poky is also given in the following section.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section id="usingpoky-changes-collections">
|
<section id="usingpoky-changes-layers">
|
||||||
<title>Bitbake Collections</title>
|
<title>Bitbake Layers</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Often, people want to extend Poky either through adding packages
|
Often, people want to extend Poky either through adding packages
|
||||||
or overriding files contained within Poky to add their own
|
or overriding files contained within Poky to add their own
|
||||||
functionality. Bitbake has a powerful mechanism called
|
functionality. Bitbake has a powerful mechanism called
|
||||||
collections which provide a way to handle this which is fully
|
layers which provides a way to handle this extension in a fully
|
||||||
supported and actively encouraged within Poky.
|
supported and non-invasive fashion.
|
||||||
</para>
|
</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">
|
<para>
|
||||||
<title>Supplementry Metadata Repositories</title>
|
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>
|
<para>
|
||||||
Often when developing a project based on Poky there will be components
|
Extra bbclasses and configuration are added to the BBPATH
|
||||||
that are not ready for public consumption for whatever reason. By making
|
environment variable. In this case, the first file with the
|
||||||
use of the collections mechanism and other functionality within Poky, it
|
matching name found in BBPATH is the one that is used, just
|
||||||
is possible to have a public repository which is supplemented by a private
|
like the PATH variable for binaries. It is therefore recommended
|
||||||
one just containing the pieces that need to be kept private.
|
that you use unique bbclass and configuration file names in your
|
||||||
|
custom layer.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The usual approach with these is to create a separate git repository called
|
The recommended approach for custom layers is to store them in a
|
||||||
"meta-prvt-XXX" which is checked out alongside the other meta-*
|
git repository of the format meta-prvt-XXXX and have this repository
|
||||||
directories included in Poky. Under this directory there can be several
|
cloned alongside the other meta directories in the Poky tree.
|
||||||
different directories such as classes, conf and packages which all
|
This way you can keep your Poky tree and it's configuration entirely
|
||||||
function as per the usual Poky directory structure.
|
inside OEROOT.
|
||||||
</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.
|
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
|
@ -117,7 +117,7 @@
|
||||||
<para>build-essential</para>
|
<para>build-essential</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>python</para>
|
<para>python (version 2.6 or later)</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>diffstat</para>
|
<para>diffstat</para>
|
||||||
|
|
|
@ -81,9 +81,10 @@
|
||||||
default this specifies the <filename class="directory">meta/packages/
|
default this specifies the <filename class="directory">meta/packages/
|
||||||
</filename> directory within Poky, but other directories such as
|
</filename> directory within Poky, but other directories such as
|
||||||
<filename class="directory">meta-extras/</filename> can be included
|
<filename class="directory">meta-extras/</filename> can be included
|
||||||
too. If multiple directories are specified a system referred to as
|
too. Adding extra content to
|
||||||
<link linkend='usingpoky-changes-collections'>"collections"</link> is used to
|
<glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> is best
|
||||||
determine which files have priority.
|
acheived through the use of Bitbake
|
||||||
|
<link linkend='usingpoky-changes-layers'>"layers"</link>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
|
Loading…
Reference in New Issue