A recipe that appends Metadata to another recipe is called a
BitBake append file.
A BitBake append file uses the .bbappend
file type suffix, while the corresponding recipe to which
Metadata is being appended uses the .bb
file type suffix.
You can use a .bbappend
file in your
layer to make additions or changes to the content of another
layer's recipe without having to copy the other layer's
recipe into your layer.
Your .bbappend
file resides in your layer,
while the main .bb
recipe file to
which you are appending Metadata resides in a different layer.
Being able to append information to an existing recipe not only avoids duplication, but also automatically applies recipe changes from a different layer into your layer. If you were copying recipes, you would have to manually merge changes as they occur.
When you create an append file, you must use the same root
name as the corresponding recipe file.
For example, the append file
someapp_2.5.bbappend
must apply to
someapp_2.5.bb
.
This means the original recipe and append file names are
version number-specific.
If the corresponding recipe is renamed to update to a newer
version, you must also rename and possibly update
the corresponding .bbappend
as well.
During the build process, BitBake displays an error on starting
if it detects a .bbappend
file that does
not have a corresponding recipe with a matching name.
See the
BB_DANGLINGAPPENDS_WARNONLY
variable for information on how to handle this error.
As an example, consider the main formfactor recipe and a
corresponding formfactor append file both from the
Source Directory.
Here is the main formfactor recipe, which is named
formfactor_0.0.bb
and located in the
"meta" layer at
meta/recipes-bsp/formfactor
:
SUMMARY = "Device formfactor information" SECTION = "base" LICENSE = "MIT" LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" PR = "r45" SRC_URI = "file://config file://machconfig" S = "${WORKDIR}" PACKAGE_ARCH = "${MACHINE_ARCH}" INHIBIT_DEFAULT_DEPS = "1" do_install() { # Install file only if it has contents install -d ${D}${sysconfdir}/formfactor/ install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ if [ -s "${S}/machconfig" ]; then install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ fi }
In the main recipe, note the
SRC_URI
variable, which tells the OpenEmbedded build system where to
find files during the build.
Following is the append file, which is named
formfactor_0.0.bbappend
and is from the
Raspberry Pi BSP Layer named
meta-raspberrypi
.
The file is in the layer at
recipes-bsp/formfactor
:
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
By default, the build system uses the
FILESPATH
variable to locate files.
This append file extends the locations by setting the
FILESEXTRAPATHS
variable.
Setting this variable in the .bbappend
file is the most reliable and recommended method for adding
directories to the search path used by the build system
to find files.
The statement in this example extends the directories to
include
${
THISDIR
}/${
PN
}
,
which resolves to a directory named
formfactor
in the same directory
in which the append file resides (i.e.
meta-raspberrypi/recipes-bsp/formfactor
.
This implies that you must have the supporting directory
structure set up that will contain any files or patches you
will be including from the layer.
Using the immediate expansion assignment operator
:=
is important because of the reference
to THISDIR
.
The trailing colon character is important as it ensures that
items in the list remain colon-separated.
BitBake automatically defines the
THISDIR
variable.
You should never set this variable yourself.
Using "_prepend" as part of the
FILESEXTRAPATHS
ensures your path
will be searched prior to other paths in the final
list.
Also, not all append files add extra files.
Many append files simply exist to add build options
(e.g. systemd
).
For these cases, your append file would not even
use the FILESEXTRAPATHS
statement.