sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: Initial draft of the new yocto-layer section 

Rough text for a section within the layer section that
introduces and describes a bit how the new yocto-layer
script works.

(From yocto-docs rev: ee56a264600df9fe250e73b60c8dadd6f8e55009)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-04-05 15:03:39 -07:00 committed by Richard Purdie
parent 7f21c57770
commit 64a5bec850
1 changed files with 402 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

575
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -17,25 +17,34 @@
<title>Understanding and Creating Layers</title> <title>Understanding and Creating Layers</title>
<para> <para>
The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link> The OpenEmbedded build system supports organizing
into multiple layers. <link linkend='metadata'>Metadata</link> into multiple layers.
Layers allow you to isolate different types of customizations from each other. Layers allow you to isolate different types of customizations from
You might find it tempting to keep everything in one layer when working on a single project. each other.
However, the more modular you organize your metadata, the easier it is to cope with future changes. You might find it tempting to keep everything in one layer when
working on a single project.
However, the more modular you organize your Metadata, the easier
it is to cope with future changes.
</para> </para>
<para> <para>
To illustrate how layers are used to keep things modular, consider machine customizations. To illustrate how layers are used to keep things modular, consider
These types of customizations typically reside in a BSP Layer. machine customizations.
Furthermore, the machine customizations should be isolated from recipes and metadata that support These types of customizations typically reside in a special layer,
a new GUI environment, for example. rather than a general layer, called a Board Specific Package (BSP)
This situation gives you a couple of layers: one for the machine configurations, and one for the Layer.
GUI environment. Furthermore, the machine customizations should be isolated from
It is important to understand, however, that the BSP layer can still make machine-specific recipes and Metadata that support a new GUI environment,
additions to recipes within the GUI environment layer without polluting the GUI layer itself for example.
This situation gives you a couple of layers: one for the machine
configurations, and one for the GUI environment.
It is important to understand, however, that the BSP layer can
still make machine-specific additions to recipes within the GUI
environment layer without polluting the GUI layer itself
with those machine-specific changes. with those machine-specific changes.
You can accomplish this through a recipe that is a BitBake append You can accomplish this through a recipe that is a BitBake append
(<filename>.bbappend</filename>) file, which is described later in this section. (<filename>.bbappend</filename>) file, which is described later
in this section.
</para> </para>
<para> <para>
@ -45,8 +54,8 @@
<title>Layers</title> <title>Layers</title>
<para> <para>
The Source Directory contains several layers right out of the The Source Directory contains both general layers and BSP
box. layers right out of the box.
You can easily identify layers that ship with a You can easily identify layers that ship with a
Yocto Project release in the Source Directory by their Yocto Project release in the Source Directory by their
folder names. folder names.
@ -56,20 +65,25 @@
It is not a requirement that a layer begins with the It is not a requirement that a layer begins with the
string <filename>meta</filename>. string <filename>meta</filename>.
</note> </note>
For example, when you set up the <link linkend='source-directory'>Source Directory</link> For example, when you set up the
structure, you will see several layers: <filename>meta</filename>, <link linkend='source-directory'>Source Directory</link>
<filename>meta-hob</filename>, <filename>meta-skeleton</filename>, structure, you will see several layers:
<filename>meta-yocto</filename>, and <filename>meta-yocto-bsp</filename>. <filename>meta</filename>, <filename>meta-hob</filename>,
<filename>meta-skeleton</filename>,
<filename>meta-yocto</filename>, and
<filename>meta-yocto-bsp</filename>.
Each of these folders is a layer. Each of these folders is a layer.
</para> </para>
<para> <para>
Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository Furthermore, if you set up a local copy of the
and then explore that folder, you will discover many BSP layers within the <filename>meta-intel</filename> Git repository
<filename>meta-intel</filename> layer. and then explore the folder of that general layer,
you will discover many BSP layers inside.
For more information on BSP layers, see the For more information on BSP layers, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
section in the Yocto Project Board Support Package (BSP) Developer's Guide. section in the Yocto Project Board Support Package (BSP)
Developer's Guide.
</para> </para>
</section> </section>
@ -77,32 +91,54 @@
<title>Creating Your Own Layer</title> <title>Creating Your Own Layer</title>
<para> <para>
It is very easy to create your own layer to use with the OpenEmbedded build system. It is very easy to create your own layers to use with the
OpenEmbedded build system.
The Yocto Project ships with scripts that speed up creating
general layers and BSP layers.
This section describes the steps you perform by hand to create
a layer so that you can better understand them.
For information about the layer-creation scripts, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
section in the Yocto Project Board Support Package (BSP)
Developer's Guide and the
"<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
section further down in this manual.
</para>
<para>
Follow these general steps to create your layer: Follow these general steps to create your layer:
<orderedlist> <orderedlist>
<listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, <listitem><para><emphasis>Check Existing Layers:</emphasis>
you should be sure someone has not already created a layer containing the metadata Before creating a new layer, you should be sure someone
has not already created a layer containing the Metadata
you need. you need.
You can see the You can see the
<ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded metadata index</filename></ulink> <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
for a list of layers from the OpenEmbedded community that can be used in the for a list of layers from the OpenEmbedded community
Yocto Project.</para></listitem> that can be used in the Yocto Project.
</para></listitem>
<listitem><para><emphasis>Create a Directory:</emphasis> <listitem><para><emphasis>Create a Directory:</emphasis>
Create the directory for your layer. Create the directory for your layer.
While not strictly required, prepend the name of the While not strictly required, prepend the name of the
folder with the string <filename>meta</filename>. folder with the string <filename>meta-</filename>.
For example: For example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
meta-mylayer meta-mylayer
meta-GUI_xyz meta-GUI_xyz
meta-mymachine meta-mymachine
</literallayout></para></listitem> </literallayout>
<listitem><para><emphasis>Create a Layer Configuration File:</emphasis> Inside your new </para></listitem>
layer folder, you need to create a <filename>conf/layer.conf</filename> file. <listitem><para><emphasis>Create a Layer Configuration
It is easiest to take an existing layer configuration file and copy that to your File:</emphasis>
layer's <filename>conf</filename> directory and then modify the file as needed.</para> Inside your new layer folder, you need to create a
<para>The <filename>meta-yocto-bsp/conf/layer.conf</filename> file demonstrates the <filename>conf/layer.conf</filename> file.
required syntax: It is easiest to take an existing layer configuration
file and copy that to your layer's
<filename>conf</filename> directory and then modify the
file as needed.</para>
<para>The
<filename>meta-yocto-bsp/conf/layer.conf</filename> file
demonstrates the required syntax:
<literallayout class='monospaced'> <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH # We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}" BBPATH .= ":${LAYERDIR}"
@ -161,73 +197,95 @@
</itemizedlist></para> </itemizedlist></para>
<para>Note the use of the <para>Note the use of the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
variable, which expands to the directory of the current layer.</para> variable, which expands to the directory of the current
<para>Through the use of the <filename>BBPATH</filename> variable, layer.</para>
BitBake locates <filename>.bbclass</filename> files, configuration <para>Through the use of the <filename>BBPATH</filename>
files, and files that are included with <filename>include</filename> variable, BitBake locates <filename>.bbclass</filename>
and <filename>require</filename> statements. files, configuration files, and files that are included
For these cases, BitBake uses the first file with the matching name found in with <filename>include</filename> and
<filename>BBPATH</filename>. <filename>require</filename> statements.
This is similar to the way the <filename>PATH</filename> variable is used for binaries. For these cases, BitBake uses the first file that
We recommend, therefore, that you use unique <filename>.bbclass</filename> matches the name found in <filename>BBPATH</filename>.
and configuration file names in your custom layer.</para></listitem> This is similar to the way the <filename>PATH</filename>
<listitem><para><emphasis>Add Content:</emphasis> Depending on the type of layer, variable is used for binaries.
add the content. We recommend, therefore, that you use unique
If the layer adds support for a machine, add the machine configuration in <filename>.bbclass</filename> and configuration
a <filename>conf/machine/</filename> file within the layer. filenames in your custom layer.</para></listitem>
If the layer adds distro policy, add the distro configuration in a <listitem><para><emphasis>Add Content:</emphasis> Depending
<filename>conf/distro/</filename> file with the layer. on the type of layer, add the content.
If the layer introduces new recipes, put the recipes you need in If the layer adds support for a machine, add the machine
<filename>recipes-*</filename> subdirectories within the layer. configuration in a <filename>conf/machine/</filename>
<note>In order to be compliant with the Yocto Project, a layer must contain file within the layer.
a <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> If the layer adds distro policy, add the distro
configuration in a <filename>conf/distro/</filename>
file with the layer.
If the layer introduces new recipes, put the recipes
you need in <filename>recipes-*</filename>
subdirectories within the layer.
<note>In order to be compliant with the Yocto Project,
a layer must contain a
<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
</note></para></listitem> </note></para></listitem>
</orderedlist> </orderedlist>
</para> </para>
<para> <para>
To create layers that are easier to maintain, you should consider the following: To create layers that are easier to maintain, you should
consider the following:
<itemizedlist> <itemizedlist>
<listitem><para>Avoid "overlaying" entire recipes from other layers in your <listitem><para>Avoid "overlaying" entire recipes from
configuration. other layers in your configuration.
In other words, don't copy an entire recipe into your layer and then modify it. In other words, don't copy an entire recipe into your
Use <filename>.bbappend</filename> files to override the parts of the layer and then modify it.
recipe you need to modify.</para></listitem> Use <filename>.bbappend</filename> files to override the
parts of the recipe you need to modify.
</para></listitem>
<listitem><para>Avoid duplicating include files. <listitem><para>Avoid duplicating include files.
Use <filename>.bbappend</filename> files for each recipe that uses an include Use <filename>.bbappend</filename> files for each recipe
file. that uses an include file.
Or, if you are introducing a new recipe that requires the included file, use the Or, if you are introducing a new recipe that requires
path relative to the original layer directory to refer to the file. the included file, use the path relative to the original
For example, use <filename>require recipes-core/somepackage/somefile.inc</filename> layer directory to refer to the file.
For example, use
<filename>require recipes-core/somepackage/somefile.inc</filename>
instead of <filename>require somefile.inc</filename>. instead of <filename>require somefile.inc</filename>.
If you're finding you have to overlay the include file, it could indicate a If you're finding you have to overlay the include file,
deficiency in the include file in the layer to which it originally belongs. it could indicate a deficiency in the include file in
If this is the case, you need to address that deficiency instead of overlaying the layer to which it originally belongs.
the include file. If this is the case, you need to address that deficiency
For example, consider how Qt 4 database support plug-ins are configured. instead of overlaying the include file.
The Source Directory does not have For example, consider how Qt 4 database support plug-ins
MySQL or PostgreSQL, however OpenEmbedded's are configured.
layer <filename>meta-oe</filename> does. The Source Directory does not have MySQL or PostgreSQL,
Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> however OpenEmbedded's layer
files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable <filename>meta-oe</filename> does.
the appropriate plugins. Consequently, <filename>meta-oe</filename> uses
This variable was added to the <filename>qt4.inc</filename> include file in <filename>.bbappend</filename> files to modify the
the Source Directory specifically to allow the <filename>meta-oe</filename> layer <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
to be able to control which plugins are built.</para></listitem> enable the appropriate plugins.
This variable was added to the
<filename>qt4.inc</filename> include file in the Source
Directory specifically to allow the
<filename>meta-oe</filename> layer to be able to control
which plugins are built.</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
We also recommend the following: We also recommend the following:
<itemizedlist> <itemizedlist>
<listitem><para>Store custom layers in a Git repository that uses the <listitem><para>Store custom layers in a Git repository
<filename>meta-&lt;layer_name&gt;</filename> format.</para></listitem> that uses the
<listitem><para>Clone the repository alongside other <filename>meta</filename> <filename>meta-&lt;layer_name&gt;</filename> format.
directories in the </para></listitem>
<link linkend='source-directory'>Source Directory</link>.</para></listitem> <listitem><para>Clone the repository alongside other
<filename>meta</filename> directories in the
<link linkend='source-directory'>Source Directory</link>.
</para></listitem>
</itemizedlist> </itemizedlist>
Following these recommendations keeps your Source Directory and Following these recommendations keeps your Source Directory and
its configuration entirely inside the Yocto Project's core base. its configuration entirely inside the Yocto Project's core
base.
</para> </para>
</section> </section>
@ -235,12 +293,15 @@
<title>Enabling Your Layer</title> <title>Enabling Your Layer</title>
<para> <para>
Before the OpenEmbedded build system can use your new layer, you need to enable it. Before the OpenEmbedded build system can use your new layer,
you need to enable it.
To enable your layer, simply add your layer's path to the To enable your layer, simply add your layer's path to the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
variable in your <filename>conf/bblayers.conf</filename> file, which is found in the variable in your <filename>conf/bblayers.conf</filename> file,
which is found in the
<link linkend='build-directory'>Build Directory</link>. <link linkend='build-directory'>Build Directory</link>.
The following example shows how to enable a layer named <filename>meta-mylayer</filename>: The following example shows how to enable a layer named
<filename>meta-mylayer</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
LCONF_VERSION = "6" LCONF_VERSION = "6"
@ -262,12 +323,13 @@
</para> </para>
<para> <para>
BitBake parses each <filename>conf/layer.conf</filename> file as specified in the BitBake parses each <filename>conf/layer.conf</filename> file
<filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> as specified in the <filename>BBLAYERS</filename> variable
file. within the <filename>conf/bblayers.conf</filename> file.
During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the During the processing of each
recipes, classes and configurations contained within the particular layer to the source <filename>conf/layer.conf</filename> file, BitBake adds the
directory. recipes, classes and configurations contained within the
particular layer to the source directory.
</para> </para>
</section> </section>
@ -275,48 +337,58 @@
<title>Using .bbappend Files</title> <title>Using .bbappend Files</title>
<para> <para>
Recipes used to append metadata to other recipes are called BitBake append files. Recipes used to append Metadata to other recipes are called
BitBake append files use the <filename>.bbappend</filename> file type suffix, while BitBake append files.
the corresponding recipes to which metadata is being appended use the BitBake append files use the <filename>.bbappend</filename> file
<filename>.bb</filename> file type suffix. type suffix, while the corresponding recipes to which Metadata
is being appended use the <filename>.bb</filename> file type
suffix.
</para> </para>
<para> <para>
A <filename>.bbappend</filename> file allows your layer to make additions or A <filename>.bbappend</filename> file allows your layer to make
changes to the content of another layer's recipe without having to copy the other additions or changes to the content of another layer's recipe
recipe into your layer. without having to copy the other recipe into your layer.
Your <filename>.bbappend</filename> file resides in your layer, while the underlying Your <filename>.bbappend</filename> file resides in your layer,
<filename>.bb</filename> recipe file to which you are appending metadata while the main <filename>.bb</filename> recipe file to
resides in a different layer. which you are appending Metadata resides in a different layer.
</para> </para>
<para> <para>
Append files must have the same root name as the corresponding recipe. Append files must have the same root name as the corresponding
For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must recipe.
apply to <filename>someapp_&DISTRO;.bb</filename>. For example, the append file
This means the original recipe and append file names are version number-specific. <filename>someapp_&DISTRO;.bbappend</filename> must apply to
If the corresponding recipe is renamed to update to a newer version, the <filename>someapp_&DISTRO;.bb</filename>.
underlying <filename>.bbappend</filename> file must be renamed as well. This means the original recipe and append file names are version
During the build process, BitBake displays an error on starting if it detects a number-specific.
<filename>.bbappend</filename> file that does not have a corresponding recipe If the corresponding recipe is renamed to update to a newer
with a matching name. version, the underlying <filename>.bbappend</filename> file must
be renamed as well.
During the build process, BitBake displays an error on starting
if it detects a <filename>.bbappend</filename> file that does
not have a corresponding recipe with a matching name.
See the See the
<ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
variable for information on how to handle this error. variable for information on how to handle this error.
</para> </para>
<para> <para>
Being able to append information to an existing recipe not only avoids duplication, Being able to append information to an existing recipe not only
but also automatically applies recipe changes in a different layer to your layer. avoids duplication, but also automatically applies recipe
If you were copying recipes, you would have to manually merge changes as they occur. changes in a different layer to your layer.
If you were copying recipes, you would have to manually merge
changes as they occur.
</para> </para>
<para> <para>
As an example, consider the main formfactor recipe and a corresponding formfactor As an example, consider the main formfactor recipe and a
append file both from the corresponding formfactor append file both from the
<link linkend='source-directory'>Source Directory</link>. <link linkend='source-directory'>Source Directory</link>.
Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and Here is the main formfactor recipe, which is named
located in the "meta" layer at <filename>meta/recipes-bsp/formfactor</filename>: <filename>formfactor_0.0.bb</filename> and located in the
"meta" layer at
<filename>meta/recipes-bsp/formfactor</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
DESCRIPTION = "Device formfactor information" DESCRIPTION = "Device formfactor information"
SECTION = "base" SECTION = "base"
@ -340,8 +412,10 @@
fi fi
} }
</literallayout> </literallayout>
Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the Here is the append file, which is named
Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>. <filename>formfactor_0.0.bbappend</filename> and is from the
Crown Bay BSP Layer named
<filename>meta-intel/meta-crownbay</filename>.
The file is in <filename>recipes-bsp/formfactor</filename>: The file is in <filename>recipes-bsp/formfactor</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@ -350,20 +424,24 @@
</literallayout> </literallayout>
This example adds or overrides files in This example adds or overrides files in
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
within a <filename>.bbappend</filename> by extending the path BitBake uses to search for files. within a <filename>.bbappend</filename> by extending the path
BitBake uses to search for files.
The most reliable way to do this is by prepending the The most reliable way to do this is by prepending the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
variable. variable.
For example, if you have your files in a directory that is named the same as your package For example, if you have your files in a directory that is named
the same as your package
(<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>), (<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>),
you can add this directory by adding the following to your <filename>.bbappend</filename> file: you can add this directory by adding the following to your
<filename>.bbappend</filename> file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
</literallayout> </literallayout>
Using the immediate expansion assignment operator <filename>:=</filename> is important because Using the immediate expansion assignment operator
of the reference to <filename>THISDIR</filename>. <filename>:=</filename> is important because of the reference to
The trailing colon character is important as it ensures that items in the list remain <filename>THISDIR</filename>.
colon-separated. The trailing colon character is important as it ensures that
items in the list remain colon-separated.
<note><para>BitBake automatically defines the <note><para>BitBake automatically defines the
<filename>THISDIR</filename> variable. <filename>THISDIR</filename> variable.
You should never set this variable yourself. You should never set this variable yourself.
@ -383,13 +461,15 @@
<para> <para>
Each layer is assigned a priority value. Each layer is assigned a priority value.
Priority values control which layer takes precedence if there are recipe files with Priority values control which layer takes precedence if there
the same name in multiple layers. are recipe files with the same name in multiple layers.
For these cases, the recipe file from the layer with a higher priority number takes precedence. For these cases, the recipe file from the layer with a higher
Priority values also affect the order in which multiple <filename>.bbappend</filename> files priority number takes precedence.
for the same recipe are applied. Priority values also affect the order in which multiple
You can either specify the priority manually, or allow the build system to calculate it <filename>.bbappend</filename> files for the same recipe are
based on the layer's dependencies. applied.
You can either specify the priority manually, or allow the
build system to calculate it based on the layer's dependencies.
</para> </para>
<para> <para>
@ -406,8 +486,9 @@
<para>It is possible for a recipe with a lower version number <para>It is possible for a recipe with a lower version number
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
in a layer that has a higher priority to take precedence.</para> in a layer that has a higher priority to take precedence.</para>
<para>Also, the layer priority does not currently affect the precedence order of <para>Also, the layer priority does not currently affect the
<filename>.conf</filename> or <filename>.bbclass</filename> files. precedence order of <filename>.conf</filename>
or <filename>.bbclass</filename> files.
Future versions of BitBake might address this.</para> Future versions of BitBake might address this.</para>
</note> </note>
</section> </section>
@ -416,11 +497,12 @@
<title>Managing Layers</title> <title>Managing Layers</title>
<para> <para>
You can use the BitBake layer management tool to provide a view into the structure of You can use the BitBake layer management tool to provide a view
recipes across a multi-layer project. into the structure of recipes across a multi-layer project.
Being able to generate output that reports on configured layers with their paths and Being able to generate output that reports on configured layers
priorities and on <filename>.bbappend</filename> files and their applicable recipes with their paths and priorities and on
can help to reveal potential problems. <filename>.bbappend</filename> files and their applicable
recipes can help to reveal potential problems.
</para> </para>
<para> <para>
@ -431,46 +513,64 @@
The following list describes the available commands: The following list describes the available commands:
<itemizedlist> <itemizedlist>
<listitem><para><filename><emphasis>help:</emphasis></filename> <listitem><para><filename><emphasis>help:</emphasis></filename>
Displays general help or help on a specified command.</para></listitem> Displays general help or help on a specified command.
</para></listitem>
<listitem><para><filename><emphasis>show-layers:</emphasis></filename> <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
Show the current configured layers.</para></listitem> Show the current configured layers.
</para></listitem>
<listitem><para><filename><emphasis>show-recipes:</emphasis></filename> <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
Lists available recipes and the layers that provide them. Lists available recipes and the layers that provide them.
</para></listitem> </para></listitem>
<listitem><para><filename><emphasis>show-overlayed:</emphasis></filename> <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
Lists overlayed recipes. Lists overlayed recipes.
A recipe is overlayed when a recipe with the same name exists in another layer A recipe is overlayed when a recipe with the same name
that has a higher layer priority. exists in another layer that has a higher layer
priority.
</para></listitem> </para></listitem>
<listitem><para><filename><emphasis>show-appends:</emphasis></filename> <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
Lists <filename>.bbappend</filename> files and the recipe files to which Lists <filename>.bbappend</filename> files and the
they apply.</para></listitem> recipe files to which they apply.
</para></listitem>
<listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename> <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
Lists dependency relationships between recipes that cross layer boundaries. Lists dependency relationships between recipes that
cross layer boundaries.
</para></listitem> </para></listitem>
<listitem><para><filename><emphasis>flatten:</emphasis></filename> <listitem><para><filename><emphasis>flatten:</emphasis></filename>
Flattens the layer configuration into a separate output directory. Flattens the layer configuration into a separate output
Flattening your layer configuration builds a "flattened" directory that contains directory.
the contents of all layers, with any overlayed recipes removed and any Flattening your layer configuration builds a "flattened"
<filename>.bbappend</filename> files appended to the corresponding recipes. directory that contains the contents of all layers,
You might have to perform some manual cleanup of the flattened layer as follows: with any overlayed recipes removed and any
<filename>.bbappend</filename> files appended to the
corresponding recipes.
You might have to perform some manual cleanup of the
flattened layer as follows:
<itemizedlist> <itemizedlist>
<listitem><para>Non-recipe files (such as patches) are overwritten. <listitem><para>Non-recipe files (such as patches)
The flatten command shows a warning for these files.</para></listitem> are overwritten.
<listitem><para>Anything beyond the normal layer setup has been added to The flatten command shows a warning for these
the <filename>layer.conf</filename> file. files.
Only the lowest priority layer's <filename>layer.conf</filename> is used.
</para></listitem> </para></listitem>
<listitem><para>Overridden and appended items from <filename>.bbappend</filename> <listitem><para>Anything beyond the normal layer
files need to be cleaned up. setup has been added to the
The contents of each <filename>.bbappend</filename> end up in the <filename>layer.conf</filename> file.
Only the lowest priority layer's
<filename>layer.conf</filename> is used.
</para></listitem>
<listitem><para>Overridden and appended items from
<filename>.bbappend</filename> files need to be
cleaned up.
The contents of each
<filename>.bbappend</filename> end up in the
flattened recipe. flattened recipe.
However, if there are appended or changed variable values, you need to tidy However, if there are appended or changed
these up yourself. variable values, you need to tidy these up
yourself.
Consider the following example. Consider the following example.
Here, the <filename>bitbake-layers</filename> command adds the line Here, the <filename>bitbake-layers</filename>
<filename>#### bbappended ...</filename> so that you know where the following command adds the line
lines originate: <filename>#### bbappended ...</filename> so that
you know where the following lines originate:
<literallayout class='monospaced'> <literallayout class='monospaced'>
... ...
DESCRIPTION = "A useful utility" DESCRIPTION = "A useful utility"
@ -483,7 +583,8 @@
DESCRIPTION = "Customized utility" DESCRIPTION = "Customized utility"
EXTRA_OECONF += "--enable-somethingelse" EXTRA_OECONF += "--enable-somethingelse"
</literallayout> </literallayout>
Ideally, you would tidy up these utilities as follows: Ideally, you would tidy up these utilities as
follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
... ...
DESCRIPTION = "Customized utility" DESCRIPTION = "Customized utility"
@ -495,6 +596,134 @@
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
<section id='creating-a-general-layer-using-the-yocto-layer-script'>
<title>Creating a General Layer Using the yocto-layer Script</title>
<para>
The <filename>yocto-layer</filename> script simplifies
creating a new general layer.
<note>
For information on BSP layers, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
section in the Yocto Project Board Specific (BSP)
Developer's Guide.
</note>
The default mode of the script's operation is to prompt you for
information needed to generate the layer:
<itemizedlist>
<listitem><para>The layer priority
</para></listitem>
<listitem><para>Whether or not to create a sample recipe.
</para></listitem>
<listitem><para>Whether or not to create a sample
append file.
</para></listitem>
</itemizedlist>
</para>
<para>
You use the <filename>yocto-layer create</filename> sub-command
to create a new general layer.
In its simplest form, you can create a layer as follows:
<literallayout class='monospaced'>
$ yocto-layer create mylayer
</literallayout>
The previous example creates a layer named
<filename>meta-mylayer</filename> in the current directory.
</para>
<para>
As the <filename>yocto-layer create</filename> command runs,
default values for the prompts appear in brackets.
Pressing enter without supplying anything on the command line
or pressing enter and providing an invalid response causes the
script to accept the default value.
Once the script completes, the new layer
is created in the current working directory.
The script names the layer according to the string you provide
and the prepended <filename>meta-</filename> string.
</para>
<para>
If you choose to not generate a sample recipe or append file,
the script creates the following within the layer:
<itemizedlist>
<listitem><para><emphasis>The <filename>conf</filename>
directory:</emphasis>
This directory contains the layers
<filename>.conf</filename>.
The root name for the file is the same as the root name
your provided for the layer.
</para></listitem>
<listitem><para><emphasis>The
<filename>COPYING.MIT</filename>:</emphasis>
The copyright and use notice for the software.
</para></listitem>
<listitem><para><emphasis>The <filename>README</filename>
file:</emphasis>
A file describing the contents of your new layer.
</para></listitem>
</itemizedlist>
</para>
<para>
If you choose to generate a sample recipe file, the script
prompts you for the name for the recipe and then creates it
in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
in a directory named <filename>recipes-example</filename>.
The script creates a <filename>.bb</filename> file and a
directory, which contains a sample
<filename>helloworld.c</filename>source file and along with
a sample patch file.
If you do not provide a recipe name, the script uses
"example".
</para>
<para>
If you choose to generate a sample append file, the script
prompts you for the name for the file and then creates it
in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
The script creates a <filename>.bbappend</filename> file and a
directory, which contains a sample patch file.
If you do not provide a recipe name, the script uses
"example".
The script also prompts you for the version of the append file.
The version should match the recipe to which the append file
is associated.
</para>
<para>
The easiest way to see how the <filename>yocto-layer</filename>
script works is to experiment with the script.
You can also read the usage information by entering the
following:
<literallayout class='monospaced'>
$ yocto-layer help
</literallayout>
</para>
<para>
Once you create your general layer, you must add it to your
<filename>bblayers.conf</filename> file.
Here is an example:
<literallayout class='monospaced'>
BBLAYERS = ?" \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-yocto \
/usr/local/src/yocto/meta-yocto-bsp \
/usr/local/src/yocto/meta-mylayer \
"
BBLAYERS_NON_REMOVABLE ?= " \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-yocto \
"
</literallayout>
Adding the layer to this file enables the build system to
the layer during the build.
</para>
</section>
</section> </section>
<section id='usingpoky-extend-customimage'> <section id='usingpoky-extend-customimage'>