documentation/dev-manual/dev-manual-common-tasks.xml: Moved Layer section
The "BitBake Layers" section was grossly mis-positioned. It appeared in the "Making and Maintaining Changes" section. I have moved the layer section to the very front of this chapter. It is fundamental to know about layers and how to create your own custom layers. (From yocto-docs rev: 410154f6e0a1e1f3ebc05d3f45ed2ce6f71cc618) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
7018654853
commit
99d5ff0194
|
@ -14,6 +14,122 @@
|
|||
Yocto Project to achieve the best results.
|
||||
</para>
|
||||
|
||||
<section id="usingpoky-changes-layers">
|
||||
<title>BitBake Layers</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Yocto Project files include several additional layers such as
|
||||
<filename>meta-rt</filename> and <filename>meta-yocto</filename>
|
||||
that demonstrate this functionality.
|
||||
The <filename>meta-rt</filename> layer is not enabled by default.
|
||||
However, the <filename>meta-yocto</filename> layer is.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To enable a layer, you simply add the layer's path to the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename>
|
||||
variable in your
|
||||
<filename>conf/bblayers.conf</filename> file, which is found in the
|
||||
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>.
|
||||
The following example shows how to enable the <filename>meta-rt</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
LCONF_VERSION = "1"
|
||||
|
||||
BBFILES ?= ""
|
||||
BBLAYERS = " \
|
||||
/path/to/poky/meta \
|
||||
/path/to/poky/meta-yocto \
|
||||
/path/to/poky/meta-rt \
|
||||
"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
|
||||
<filename>BBLAYERS</filename>
|
||||
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 <filename>conf/layer.conf</filename> file and
|
||||
add the directory to your <filename>bblayers.conf</filename> file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>meta-yocto/conf/layer.conf</filename> file 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}/recipes-*/*/*.bb \
|
||||
${LAYERDIR}/recipes-*/*/*.bbappend"
|
||||
|
||||
BBFILE_COLLECTIONS += "yocto"
|
||||
BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
|
||||
BBFILE_PRIORITY_yocto = "5"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In the previous example, the recipes for the layers are added to
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
|
||||
variable is then appended with the layer name.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
|
||||
variable immediately expands with a regular expression used to match files from
|
||||
<filename>BBFILES</filename> into
|
||||
a particular layer, in this case by using the base pathname.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note the use of the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
|
||||
variable with the immediate expansion operator.
|
||||
The <filename>LAYERDIR</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BitBake can locate where other <filename>.bbclass</filename> and configuration files
|
||||
are applied through the <filename>BBPATH</filename> environment variable.
|
||||
For these cases, BitBake uses the first file with the matching name found in
|
||||
<filename>BBPATH</filename>.
|
||||
This is similar to the way the <filename>PATH</filename> variable is used for binaries.
|
||||
We recommend, therefore, that you use unique <filename>.bbclass</filename>
|
||||
and configuration file names in your custom layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We also recommend the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>Store custom layers in a Git repository that uses the
|
||||
<filename>meta-prvt-XXXX</filename> format.</para></listitem>
|
||||
<listitem><para>Clone the repository alongside other <filename>meta</filename>
|
||||
directories in the Yocto Project source files area.</para></listitem>
|
||||
</itemizedlist>
|
||||
Following these recommendations keeps your Yocto Project files area and
|
||||
its configuration entirely inside the Yocto Project's core base.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-extend-addpkg'>
|
||||
<title>Adding a Package</title>
|
||||
|
||||
|
@ -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.
|
||||
</para>
|
||||
|
||||
<section id="usingpoky-changes-layers">
|
||||
<title>BitBake Layers</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Yocto Project files include several additional layers such as
|
||||
<filename>meta-rt</filename> and <filename>meta-yocto</filename>
|
||||
that demonstrate this functionality.
|
||||
The <filename>meta-rt</filename> layer is not enabled by default.
|
||||
However, the <filename>meta-yocto</filename> layer is.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To enable a layer, you simply add the layer's path to the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename>
|
||||
variable in your
|
||||
<filename>conf/bblayers.conf</filename> file, which is found in the
|
||||
<link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>.
|
||||
The following example shows how to enable the <filename>meta-rt</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
LCONF_VERSION = "1"
|
||||
|
||||
BBFILES ?= ""
|
||||
BBLAYERS = " \
|
||||
/path/to/poky/meta \
|
||||
/path/to/poky/meta-yocto \
|
||||
/path/to/poky/meta-rt \
|
||||
"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
|
||||
<filename>BBLAYERS</filename>
|
||||
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 <filename>conf/layer.conf</filename> file and
|
||||
add the directory to your <filename>bblayers.conf</filename> file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>meta-yocto/conf/layer.conf</filename> file 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}/recipes-*/*/*.bb \
|
||||
${LAYERDIR}/recipes-*/*/*.bbappend"
|
||||
|
||||
BBFILE_COLLECTIONS += "yocto"
|
||||
BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
|
||||
BBFILE_PRIORITY_yocto = "5"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In the previous example, the recipes for the layers are added to
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
|
||||
variable is then appended with the layer name.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
|
||||
variable immediately expands with a regular expression used to match files from
|
||||
<filename>BBFILES</filename> into
|
||||
a particular layer, in this case by using the base pathname.
|
||||
The
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note the use of the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
|
||||
variable with the immediate expansion operator.
|
||||
The <filename>LAYERDIR</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
BitBake can locate where other <filename>.bbclass</filename> and configuration files
|
||||
are applied through the <filename>BBPATH</filename> environment variable.
|
||||
For these cases, BitBake uses the first file with the matching name found in
|
||||
<filename>BBPATH</filename>.
|
||||
This is similar to the way the <filename>PATH</filename> variable is used for binaries.
|
||||
We recommend, therefore, that you use unique <filename>.bbclass</filename>
|
||||
and configuration file names in your custom layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We also recommend the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>Store custom layers in a Git repository that uses the
|
||||
<filename>meta-prvt-XXXX</filename> format.</para></listitem>
|
||||
<listitem><para>Clone the repository alongside other <filename>meta</filename>
|
||||
directories in the Yocto Project source files area.</para></listitem>
|
||||
</itemizedlist>
|
||||
Following these recommendations keeps your Yocto Project files area and
|
||||
its configuration entirely inside the Yocto Project's core base.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-commits">
|
||||
<title>Committing Changes</title>
|
||||
|
||||
|
|
Loading…
Reference in New Issue