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 "Creating a New BSP Layer Using the yocto-bsp Script" section in the Yocto Project Board Support Package (BSP) Developer's Guide and the "Creating a General Layer Using the yocto-layer Script" section further down in this manual.
Follow these general steps to create your layer:
Check Existing Layers:
Before creating a new layer, you should be sure someone
has not already created a layer containing the Metadata
you need.
You can see the
OpenEmbedded Metadata Index
for a list of layers from the OpenEmbedded community
that can be used in the Yocto Project.
Create a Directory:
Create the directory for your layer.
While not strictly required, prepend the name of the
folder with the string meta-
.
For example:
meta-mylayer meta-GUI_xyz meta-mymachine
Create a Layer Configuration
File:
Inside your new layer folder, you need to create a
conf/layer.conf
file.
It is easiest to take an existing layer configuration
file and copy that to your layer's
conf
directory and then modify the
file as needed.
The
meta-yocto-bsp/conf/layer.conf
file
demonstrates the required syntax:
# We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" # We have recipes-* directories, add to BBFILES BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" BBFILE_COLLECTIONS += "yoctobsp" BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" BBFILE_PRIORITY_yoctobsp = "5"
Here is an explanation of the example:
The configuration and
classes directory is appended to
BBPATH
.
BBPATH
.
On the other hand, distro layers, such as
meta-yocto
, can choose
to enforce their own precedence over
BBPATH
.
For an example of that syntax, see the
layer.conf
file for
the meta-yocto
layer.
The recipes for the layers are
appended to
BBFILES
.
The
BBFILE_COLLECTIONS
variable is then appended with the layer name.
The
BBFILE_PATTERN
variable is set to a regular expression and is
used to match files from
BBFILES
into a particular
layer.
In this case,
LAYERDIR
is used to make BBFILE_PATTERN
match within the
layer's path.
The
BBFILE_PRIORITY
variable then assigns a priority to the layer.
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.
Note the use of the
LAYERDIR
variable, which expands to the directory of the current
layer.
Through the use of the BBPATH
variable, BitBake locates .bbclass
files, configuration files, and files that are included
with include
and
require
statements.
For these cases, BitBake uses the first file that
matches the name found in BBPATH
.
This is similar to the way the PATH
variable is used for binaries.
We recommend, therefore, that you use unique
.bbclass
and configuration
filenames in your custom layer.
Add Content: Depending
on the type of layer, add the content.
If the layer adds support for a machine, add the machine
configuration in a conf/machine/
file within the layer.
If the layer adds distro policy, add the distro
configuration in a conf/distro/
file with the layer.
If the layer introduces new recipes, put the recipes
you need in recipes-*
subdirectories within the layer.
To create layers that are easier to maintain, you should consider the following:
Avoid "overlaying" entire recipes from
other layers in your configuration.
In other words, do not copy an entire recipe into your
layer and then modify it.
Use .bbappend
files to override the
parts of the recipe you need to modify.
Avoid duplicating include files.
Use .bbappend
files for each recipe
that uses an include file.
Or, if you are introducing a new recipe that requires
the included file, use the path relative to the original
layer directory to refer to the file.
For example, use
require recipes-core/somepackage/somefile.inc
instead of require somefile.inc
.
If you're finding you have to overlay the include file,
it could indicate a deficiency in the include file in
the layer to which it originally belongs.
If this is the case, you need to address that deficiency
instead of overlaying the include file.
For example, consider how Qt 4 database support plug-ins
are configured.
The Source Directory does not have MySQL or PostgreSQL,
however OpenEmbedded's layer
meta-oe
does.
Consequently, meta-oe
uses
.bbappend
files to modify the
QT_SQL_DRIVER_FLAGS
variable to
enable the appropriate plugins.
This variable was added to the
qt4.inc
include file in the Source
Directory specifically to allow the
meta-oe
layer to be able to control
which plugins are built.
We also recommend the following:
Store custom layers in a Git repository
that uses the
meta-<layer_name>
format.
Clone the repository alongside other
meta
directories in the
Source Directory.
Following these recommendations keeps your Source Directory and its configuration entirely inside the Yocto Project's core base.