Gitiles
Code Review Sign In
gerrit.openbmc.org / openbmc / openbmc / 0ca19ccf045e022d8a24d26afbf346ab7f2f519f / . / poky / documentation / ref-manual / variables.rst
blob: 7aecda0174547db41eea72bdba21fe975cdad5b9 [file] [log] [blame]
.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
******************
Variables Glossary
******************
This chapter lists common variables used in the OpenEmbedded build
system and gives an overview of their function and contents.
:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>`
:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FEATURE_PACKAGES>`
:term:`G <GCCPIE>` :term:`H <HOMEPAGE>` :term:`I <ICECC_DISABLED>`
:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
:term:`R <RANLIB>` :term:`S` :term:`T`
:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>`
:term:`W <WARN_QA>` :term:`X <XSERVER>`
.. glossary::
:term:`ABIEXTENSION`
Extension to the Application Binary Interface (ABI) field of the GNU
canonical architecture name (e.g. "eabi").
ABI extensions are set in the machine include files. For example, the
``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
following extension::
ABIEXTENSION = "eabi"
:term:`ALLOW_EMPTY`
Specifies whether to produce an output package even if it is empty.
By default, BitBake does not produce empty packages. This default
behavior can cause issues when there is an
:term:`RDEPENDS` or some other hard runtime
requirement on the existence of the package.
Like all package-controlling variables, you must always use them in
conjunction with a package name override, as in::
ALLOW_EMPTY:${PN} = "1"
ALLOW_EMPTY:${PN}-dev = "1"
ALLOW_EMPTY:${PN}-staticdev = "1"
:term:`ALTERNATIVE`
Lists commands in a package that need an alternative binary naming
scheme. Sometimes the same command is provided in multiple packages.
When this occurs, the OpenEmbedded build system needs to use the
alternatives system to create a different binary naming scheme so the
commands can co-exist.
To use the variable, list out the package's commands that are also
provided by another package. For example, if the ``busybox`` package
has four such commands, you identify them as follows::
ALTERNATIVE:busybox = "sh sed test bracket"
For more information on the alternatives system, see the
":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
section.
:term:`ALTERNATIVE_LINK_NAME`
Used by the alternatives system to map duplicated commands to actual
locations. For example, if the ``bracket`` command provided by the
``busybox`` package is duplicated through another package, you must
use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
location::
ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
In this example, the binary for the ``bracket`` command (i.e. ``[``)
from the ``busybox`` package resides in ``/usr/bin/``.
.. note::
If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``.
For more information on the alternatives system, see the
":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
section.
:term:`ALTERNATIVE_PRIORITY`
Used by the alternatives system to create default priorities for
duplicated commands. You can use the variable to create a single
default regardless of the command name or package, a default for
specific duplicated commands regardless of the package, or a default
for specific commands tied to particular packages. Here are the
available syntax forms::
ALTERNATIVE_PRIORITY = "priority"
ALTERNATIVE_PRIORITY[name] = "priority"
ALTERNATIVE_PRIORITY_pkg[name] = "priority"
For more information on the alternatives system, see the
":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
section.
:term:`ALTERNATIVE_TARGET`
Used by the alternatives system to create default link locations for
duplicated commands. You can use the variable to create a single
default location for all duplicated commands regardless of the
command name or package, a default for specific duplicated commands
regardless of the package, or a default for specific commands tied to
particular packages. Here are the available syntax forms::
ALTERNATIVE_TARGET = "target"
ALTERNATIVE_TARGET[name] = "target"
ALTERNATIVE_TARGET_pkg[name] = "target"
.. note::
If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value
from the :term:`ALTERNATIVE_LINK_NAME` variable.
If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the
same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``"
appended to it.
Finally, if the file referenced has not been renamed, the
alternatives system will rename it to avoid the need to rename
alternative files in the :ref:`ref-tasks-install`
task while retaining support for the command if necessary.
For more information on the alternatives system, see the
":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
section.
:term:`ANY_OF_DISTRO_FEATURES`
When inheriting the
:ref:`features_check <ref-classes-features_check>`
class, this variable identifies a list of distribution features where
at least one must be enabled in the current configuration in order
for the OpenEmbedded build system to build the recipe. In other words,
if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES`
appear in :term:`DISTRO_FEATURES` within the current configuration, then
the recipe will be skipped, and if the build system attempts to build
the recipe then an error will be triggered.
:term:`APPEND`
An override list of append strings for each target specified with
:term:`LABELS`.
See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
information on how this variable is used.
:term:`AR`
The minimal command and arguments used to run ``ar``.
:term:`ARCHIVER_MODE`
When used with the :ref:`archiver <ref-classes-archiver>` class,
determines the type of information used to create a released archive.
You can use this variable to create archives of patched source,
original source, configured source, and so forth by employing the
following variable flags (varflags)::
ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
ARCHIVER_MODE[src] = "configured" # Uses configured source files.
ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
For information on how the variable works, see the
``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
:term:`AS`
Minimal command and arguments needed to run the assembler.
:term:`ASSUME_PROVIDED`
Lists recipe names (:term:`PN` values) BitBake does not
attempt to build. Instead, BitBake assumes these recipes have already
been built.
In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
tools that should not be built. An example is ``git-native``, which
when specified, allows for the Git binary from the host to be used
rather than building ``git-native``.
:term:`ASSUME_SHLIBS`
Provides additional ``shlibs`` provider mapping information, which
adds to or overwrites the information provided automatically by the
system. Separate multiple entries using spaces.
As an example, use the following form to add an ``shlib`` provider of
shlibname in packagename with the optional version::
shlibname:packagename[_version]
Here is an example that adds a shared library named ``libEGL.so.1``
as being provided by the ``libegl-implementation`` package::
ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
:term:`AUTHOR`
The email address used to contact the original author or authors in
order to send patches and forward bugs.
:term:`AUTO_LIBNAME_PKGS`
When the :ref:`debian <ref-classes-debian>` class is inherited,
which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which
packages should be checked for libraries and renamed according to
Debian library package naming.
The default value is "${PACKAGES}", which causes the debian class to
act on all packages that are explicitly generated by the recipe.
:term:`AUTO_SYSLINUXMENU`
Enables creating an automatic menu for the syslinux bootloader. You
must set this variable in your recipe. The
:ref:`syslinux <ref-classes-syslinux>` class checks this variable.
:term:`AUTOREV`
When :term:`SRCREV` is set to the value of this variable, it specifies to
use the latest source revision in the repository. Here is an example::
SRCREV = "${AUTOREV}"
If you use the previous statement to retrieve the latest version of
software, you need to be sure :term:`PV` contains
``${``\ :term:`SRCPV`\ ``}``. For example, suppose you
have a kernel recipe that inherits the
:ref:`kernel <ref-classes-kernel>` class and you use the previous
statement. In this example, ``${SRCPV}`` does not automatically get
into :term:`PV`. Consequently, you need to change :term:`PV` in your recipe
so that it does contain ``${SRCPV}``.
For more information see the
":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
section in the Yocto Project Development Tasks Manual.
:term:`AVAILABLE_LICENSES`
List of licenses found in the directories specified by
:term:`COMMON_LICENSE_DIR` and
:term:`LICENSE_PATH`.
.. note::
It is assumed that all changes to :term:`COMMON_LICENSE_DIR` and
:term:`LICENSE_PATH` have been done before :term:`AVAILABLE_LICENSES`
is defined (in :ref:`ref-classes-license`).
:term:`AVAILTUNES`
The list of defined CPU and Application Binary Interface (ABI)
tunings (i.e. "tunes") available for use by the OpenEmbedded build
system.
The list simply presents the tunes that are available. Not all tunes
may be compatible with a particular machine configuration, or with
each other in a
:ref:`Multilib <dev-manual/common-tasks:combining multiple versions of library files into one image>`
configuration.
To add a tune to the list, be sure to append it with spaces using the
"+=" BitBake operator. Do not simply replace the list by using the
"=" operator. See the
":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake
User Manual for more information.
:term:`AZ_SAS`
Azure Storage Shared Access Signature, when using the
:ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
This variable can be defined to be used by the fetcher to authenticate
and gain access to non-public artifacts.
::
AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
For more information see Microsoft's Azure Storage documentation at
https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
:term:`B`
The directory within the :term:`Build Directory` in
which the OpenEmbedded build system places generated objects during a
recipe's build process. By default, this directory is the same as the
:term:`S` directory, which is defined as::
S = "${WORKDIR}/${BP}"
You can separate the (:term:`S`) directory and the directory pointed to
by the :term:`B` variable. Most Autotools-based recipes support
separating these directories. The build system defaults to using
separate directories for ``gcc`` and some kernel recipes.
:term:`BAD_RECOMMENDATIONS`
Lists "recommended-only" packages to not install. Recommended-only
packages are packages installed only through the
:term:`RRECOMMENDS` variable. You can prevent any
of these "recommended" packages from being installed by listing them
with the :term:`BAD_RECOMMENDATIONS` variable::
BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
You can set this variable globally in your ``local.conf`` file or you
can attach it to a specific image recipe by using the recipe name
override::
BAD_RECOMMENDATIONS:pn-target_image = "package_name"
It is important to realize that if you choose to not install packages
using this variable and some other packages are dependent on them
(i.e. listed in a recipe's :term:`RDEPENDS`
variable), the OpenEmbedded build system ignores your request and
will install the packages to avoid dependency errors.
This variable is supported only when using the IPK and RPM
packaging backends. DEB is not supported.
See the :term:`NO_RECOMMENDATIONS` and the
:term:`PACKAGE_EXCLUDE` variables for related
information.
:term:`BASE_LIB`
The library directory name for the CPU or Application Binary
Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib
context. See the ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
section in the Yocto Project Development Tasks Manual for information
on Multilib.
The :term:`BASE_LIB` variable is defined in the machine include files in
the :term:`Source Directory`. If Multilib is not
being used, the value defaults to "lib".
:term:`BASE_WORKDIR`
Points to the base of the work directory for all recipes. The default
value is "${TMPDIR}/work".
:term:`BB_ALLOWED_NETWORKS`
Specifies a space-delimited list of hosts that the fetcher is allowed
to use to obtain the required source code. Following are
considerations surrounding this variable:
- This host list is only used if :term:`BB_NO_NETWORK` is either not set
or set to "0".
- There is limited support for wildcard matching against the beginning of
host names. For example, the following setting matches
``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
::
BB_ALLOWED_NETWORKS = "*.gnu.org"
.. note::
The use of the "``*``" character only works at the beginning of
a host name and it must be isolated from the remainder of the
host name. You cannot use the wildcard character in any other
location of the name or combined with the front part of the
name.
For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
is not.
- Mirrors not in the host list are skipped and logged in debug.
- Attempts to access networks not in the host list cause a failure.
Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
:term:`PREMIRRORS` is very useful. Adding the host
you want to use to :term:`PREMIRRORS` results in the source code being
fetched from an allowed location and avoids raising an error when a
host that is not allowed is in a :term:`SRC_URI`
statement. This is because the fetcher does not attempt to use the
host listed in :term:`SRC_URI` after a successful fetch from the
:term:`PREMIRRORS` occurs.
:term:`BB_DANGLINGAPPENDS_WARNONLY`
Defines how BitBake handles situations where an append file
(``.bbappend``) has no corresponding recipe file (``.bb``). This
condition often occurs when layers get out of sync (e.g. ``oe-core``
bumps a recipe version and the old recipe no longer exists and the
other layer has not been updated to the new version of the recipe
yet).
The default fatal behavior is safest because it is the sane reaction
given something is out of sync. It is important to realize when your
changes are no longer being applied.
You can change the default behavior by setting this variable to "1",
"yes", or "true" in your ``local.conf`` file, which is located in the
:term:`Build Directory`: Here is an example::
BB_DANGLINGAPPENDS_WARNONLY = "1"
:term:`BB_DISKMON_DIRS`
Monitors disk space and available inodes during the build and allows
you to control the build based on these parameters.
Disk space monitoring is disabled by default. To enable monitoring,
add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
found in the :term:`Build Directory`. Use the
following form:
.. code-block:: none
BB_DISKMON_DIRS = "action,dir,threshold [...]"
where:
action is:
ABORT: Immediately abort the build when
a threshold is broken.
STOPTASKS: Stop the build after the currently
executing tasks have finished when
a threshold is broken.
WARN: Issue a warning but continue the
build when a threshold is broken.
Subsequent warnings are issued as
defined by the BB_DISKMON_WARNINTERVAL
variable, which must be defined in
the conf/local.conf file.
dir is:
Any directory you choose. You can specify one or
more directories to monitor by separating the
groupings with a space. If two directories are
on the same device, only the first directory
is monitored.
threshold is:
Either the minimum available disk space,
the minimum number of free inodes, or
both. You must specify at least one. To
omit one or the other, simply omit the value.
Specify the threshold using G, M, K for Gbytes,
Mbytes, and Kbytes, respectively. If you do
not specify G, M, or K, Kbytes is assumed by
default. Do not use GB, MB, or KB.
Here are some examples::
BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
The first example works only if you also provide the
:term:`BB_DISKMON_WARNINTERVAL`
variable in the ``conf/local.conf``. This example causes the build
system to immediately abort when either the disk space in
``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
below 100 Kbytes. Because two directories are provided with the
variable, the build system also issue a warning when the disk space
in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
of free inodes drops below 100 Kbytes. Subsequent warnings are issued
during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL`
variable.
The second example stops the build after all currently executing
tasks complete when the minimum disk space in the ``${TMPDIR}``
directory drops below 1 Gbyte. No disk monitoring occurs for the free
inodes in this case.
The final example immediately aborts the build when the number of
free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
disk space monitoring for the directory itself occurs in this case.
:term:`BB_DISKMON_WARNINTERVAL`
Defines the disk space and free inode warning intervals. To set these
intervals, define the variable in your ``conf/local.conf`` file in
the :term:`Build Directory`.
If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
must also use the :term:`BB_DISKMON_DIRS`
variable and define its action as "WARN". During the build,
subsequent warnings are issued each time disk space or number of free
inodes further reduces by the respective interval.
If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
monitoring interval defaults to the following::
BB_DISKMON_WARNINTERVAL = "50M,5K"
When specifying the variable in your configuration file, use the
following form:
.. code-block:: none
BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"
where:
disk_space_interval is:
An interval of memory expressed in either
G, M, or K for Gbytes, Mbytes, or Kbytes,
respectively. You cannot use GB, MB, or KB.
disk_inode_interval is:
An interval of free inodes expressed in either
G, M, or K for Gbytes, Mbytes, or Kbytes,
respectively. You cannot use GB, MB, or KB.
Here is an example::
BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_WARNINTERVAL = "50M,5K"
These variables cause the
OpenEmbedded build system to issue subsequent warnings each time the
available disk space further reduces by 50 Mbytes or the number of
free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
directory. Subsequent warnings based on the interval occur each time
a respective interval is reached beyond the initial warning (i.e. 1
Gbytes and 100 Kbytes).
:term:`BB_GENERATE_MIRROR_TARBALLS`
Causes tarballs of the source control repositories (e.g. Git
repositories), including metadata, to be placed in the
:term:`DL_DIR` directory.
For performance reasons, creating and placing tarballs of these
repositories is not the default action by the OpenEmbedded build
system.
::
BB_GENERATE_MIRROR_TARBALLS = "1"
Set this variable in your
``local.conf`` file in the :term:`Build Directory`.
Once you have the tarballs containing your source files, you can
clean up your :term:`DL_DIR` directory by deleting any Git or other
source control work directories.
:term:`BB_NUMBER_THREADS`
The maximum number of tasks BitBake should run in parallel at any one
time. The OpenEmbedded build system automatically configures this
variable to be equal to the number of cores on the build system. For
example, a system with a dual core processor that also uses
hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default
to "4".
For single socket systems (i.e. one CPU), you should not have to
override this variable to gain optimal parallelism during builds.
However, if you have very large systems that employ multiple physical
CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable
is not set higher than "20".
For more information on speeding up builds, see the
":ref:`dev-manual/common-tasks:speeding up a build`"
section in the Yocto Project Development Tasks Manual.
:term:`BB_SERVER_TIMEOUT`
Specifies the time (in seconds) after which to unload the BitBake
server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
long the BitBake server stays resident between invocations.
For example, the following statement in your ``local.conf`` file
instructs the server to be unloaded after 20 seconds of inactivity::
BB_SERVER_TIMEOUT = "20"
If you want the server to never be unloaded,
set :term:`BB_SERVER_TIMEOUT` to "-1".
:term:`BBCLASSEXTEND`
Allows you to extend a recipe so that it builds variants of the
software. There are common variants for recipes as "natives" like
``quilt-native``, which is a copy of Quilt built to run on the build
system; "crosses" such as ``gcc-cross``, which is a compiler built to
run on the build machine but produces binaries that run on the target
:term:`MACHINE`; "nativesdk", which targets the SDK
machine instead of :term:`MACHINE`; and "mulitlibs" in the form
"``multilib:``\ multilib_name".
To build a different variant of the recipe with a minimal amount of
code, it usually is as simple as adding the following to your recipe::
BBCLASSEXTEND =+ "native nativesdk"
BBCLASSEXTEND =+ "multilib:multilib_name"
.. note::
Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
variants by rewriting variable values and applying overrides such
as ``:class-native``. For example, to generate a native version of
a recipe, a :term:`DEPENDS` on "foo" is rewritten
to a :term:`DEPENDS` on "foo-native".
Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Parsing once adds some limitations. For example, it is not
possible to include a different file depending on the variant,
since ``include`` statements are processed when the recipe is
parsed.
:term:`BBFILE_COLLECTIONS`
Lists the names of configured layers. These names are used to find
the other ``BBFILE_*`` variables. Typically, each layer will append
its name to this variable in its ``conf/layer.conf`` file.
:term:`BBFILE_PATTERN`
Variable that expands to match files from
:term:`BBFILES` in a particular layer. This variable
is used in the ``conf/layer.conf`` file and must be suffixed with the
name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
:term:`BBFILE_PRIORITY`
Assigns the priority for recipe files in each layer.
This variable is useful in situations where the same recipe appears
in more than one layer. Setting this variable allows you to
prioritize a layer against other layers that contain the same recipe
- effectively letting you control the precedence for the multiple
layers. The precedence established through this variable stands
regardless of a recipe's version (:term:`PV` variable). For
example, a layer that has a recipe with a higher :term:`PV` value but for
which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still
has a lower precedence.
A larger value for the :term:`BBFILE_PRIORITY` variable results in a
higher precedence. For example, the value 6 has a higher precedence
than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
for more information. The default priority, if unspecified for a
layer with no dependencies, is the lowest defined priority + 1 (or 1
if no priorities are defined).
.. tip::
You can use the command ``bitbake-layers show-layers``
to list all configured layers along with their priorities.
:term:`BBFILES`
A space-separated list of recipe files BitBake uses to build
software.
When specifying recipe files, you can pattern match using Python's
`glob <https://docs.python.org/3/library/glob.html>`_ syntax.
For details on the syntax, see the documentation by following the
previous link.
:term:`BBFILES_DYNAMIC`
Activates content when identified layers are present. You identify
the layers by the collections that the layers define.
Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files
whose corresponding ``.bb`` file is in a layer that attempts to
modify other layers through ``.bbappend`` but does not want to
introduce a hard dependency on those other layers.
Use the following form for :term:`BBFILES_DYNAMIC`:
collection_name:filename_pattern The following example identifies two
collection names and two filename patterns::
BBFILES_DYNAMIC += " \
clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
"
This next example shows an error message that occurs because invalid
entries are found, which cause parsing to abort:
.. code-block:: none
ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
/work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
/work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
:term:`BBINCLUDELOGS`
Variable that controls how BitBake displays logs on build failure.
:term:`BBINCLUDELOGS_LINES`
If :term:`BBINCLUDELOGS` is set, specifies the
maximum number of lines from the task log file to print when
reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
the entire log is printed.
:term:`BBLAYERS`
Lists the layers to enable during the build. This variable is defined
in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
Here is an example::
BBLAYERS = " \
/home/scottrif/poky/meta \
/home/scottrif/poky/meta-poky \
/home/scottrif/poky/meta-yocto-bsp \
/home/scottrif/poky/meta-mykernel \
"
This example enables four layers, one of which is a custom,
user-defined layer named ``meta-mykernel``.
:term:`BBMASK`
Prevents BitBake from processing recipes and recipe append files.
You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
``.bbappend`` files. BitBake ignores any recipe or recipe append
files that match any of the expressions. It is as if BitBake does not
see them at all. Consequently, matching files are not parsed or
otherwise used by BitBake.
The values you provide are passed to Python's regular expression
compiler. Consequently, the syntax follows Python's Regular
Expression (re) syntax. The expressions are compared against the full
paths to the files. For complete syntax information, see Python's
documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax.
The following example uses a complete regular expression to tell
BitBake to ignore all recipe and recipe append files in the
``meta-ti/recipes-misc/`` directory::
BBMASK = "meta-ti/recipes-misc/"
If you want to mask out multiple directories or recipes, you can
specify multiple regular expression fragments. This next example
masks out multiple directories and individual recipes::
BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
BBMASK += "/meta-oe/recipes-support/"
BBMASK += "/meta-foo/.*/openldap"
BBMASK += "opencv.*\.bbappend"
BBMASK += "lzma"
.. note::
When specifying a directory name, use the trailing slash character
to ensure you match just that directory name.
:term:`BBMULTICONFIG`
Specifies each additional separate configuration when you are
building targets with multiple configurations. Use this variable in
your ``conf/local.conf`` configuration file. Specify a
multiconfigname for each configuration file you are using. For
example, the following line specifies three configuration files::
BBMULTICONFIG = "configA configB configC"
Each configuration file you
use must reside in the :term:`Build Directory`
``conf/multiconfig`` directory (e.g.
build_directory\ ``/conf/multiconfig/configA.conf``).
For information on how to use :term:`BBMULTICONFIG` in an environment
that supports building targets with multiple configurations, see the
":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`"
section in the Yocto Project Development Tasks Manual.
:term:`BBPATH`
Used by BitBake to locate ``.bbclass`` and configuration files. This
variable is analogous to the ``PATH`` variable.
.. note::
If you run BitBake from a directory outside of the
:term:`Build Directory`, you must be sure to set :term:`BBPATH`
to point to the Build Directory. Set the variable as you would any
environment variable and then run BitBake::
$ BBPATH = "build_directory"
$ export BBPATH
$ bitbake target
:term:`BBSERVER`
If defined in the BitBake environment, :term:`BBSERVER` points to the
BitBake remote server.
Use the following format to export the variable to the BitBake
environment::
export BBSERVER=localhost:$port
By default, :term:`BBSERVER` also appears in :term:`BB_HASHBASE_WHITELIST`.
Consequently, :term:`BBSERVER` is excluded from checksum and dependency
data.
:term:`BINCONFIG`
When inheriting the
:ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class,
this variable specifies binary configuration scripts to disable in
favor of using ``pkg-config`` to query the information. The
``binconfig-disabled`` class will modify the specified scripts to
return an error so that calls to them can be easily found and
replaced.
To add multiple scripts, separate them by spaces. Here is an example
from the ``libpng`` recipe::
BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
:term:`BINCONFIG_GLOB`
When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
this variable specifies a wildcard for configuration scripts that
need editing. The scripts are edited to correct any paths that have
been set up during compilation so that they are correct for use when
installed into the sysroot and called by the build processes of other
recipes.
.. note::
The :term:`BINCONFIG_GLOB` variable uses
`shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__,
which is recognition and expansion of wildcards during pattern
matching. Shell globbing is very similar to
`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__
and `glob <https://docs.python.org/3/library/glob.html>`__.
For more information on how this variable works, see
``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`.
You can also find general
information on the class in the
":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
:term:`BP`
The base recipe name and version but without any special recipe name
suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is
comprised of the following::
${BPN}-${PV}
:term:`BPN`
This variable is a version of the :term:`PN` variable with
common prefixes and suffixes removed, such as ``nativesdk-``,
``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``.
The exact lists of prefixes and suffixes removed are specified by the
:term:`MLPREFIX` and
:term:`SPECIAL_PKGSUFFIX` variables,
respectively.
:term:`BUGTRACKER`
Specifies a URL for an upstream bug tracking website for a recipe.
The OpenEmbedded build system does not use this variable. Rather, the
variable is a useful pointer in case a bug in the software being
built needs to be manually reported.
:term:`BUILD_ARCH`
Specifies the architecture of the build host (e.g. ``i686``). The
OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
machine name reported by the ``uname`` command.
:term:`BUILD_AS_ARCH`
Specifies the architecture-specific assembler flags for the build
host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
:term:`BUILD_CC_ARCH`
Specifies the architecture-specific C compiler flags for the build
host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
:term:`BUILD_CCLD`
Specifies the linker command to be used for the build host when the C
compiler is being used as the linker. By default, :term:`BUILD_CCLD`
points to GCC and passes as arguments the value of
:term:`BUILD_CC_ARCH`, assuming
:term:`BUILD_CC_ARCH` is set.
:term:`BUILD_CFLAGS`
Specifies the flags to pass to the C compiler when building for the
build host. When building in the ``-native`` context,
:term:`CFLAGS` is set to the value of this variable by
default.
:term:`BUILD_CPPFLAGS`
Specifies the flags to pass to the C preprocessor (i.e. to both the C
and the C++ compilers) when building for the build host. When
building in the ``-native`` context, :term:`CPPFLAGS`
is set to the value of this variable by default.
:term:`BUILD_CXXFLAGS`
Specifies the flags to pass to the C++ compiler when building for the
build host. When building in the ``-native`` context,
:term:`CXXFLAGS` is set to the value of this variable
by default.
:term:`BUILD_FC`
Specifies the Fortran compiler command for the build host. By
default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
value of :term:`BUILD_CC_ARCH`, assuming
:term:`BUILD_CC_ARCH` is set.
:term:`BUILD_LD`
Specifies the linker command for the build host. By default,
:term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
the value of :term:`BUILD_LD_ARCH`, assuming
:term:`BUILD_LD_ARCH` is set.
:term:`BUILD_LD_ARCH`
Specifies architecture-specific linker flags for the build host. By
default, the value of :term:`BUILD_LD_ARCH` is empty.
:term:`BUILD_LDFLAGS`
Specifies the flags to pass to the linker when building for the build
host. When building in the ``-native`` context,
:term:`LDFLAGS` is set to the value of this variable
by default.
:term:`BUILD_OPTIMIZATION`
Specifies the optimization flags passed to the C compiler when
building for the build host or the SDK. The flags are passed through
the :term:`BUILD_CFLAGS` and
:term:`BUILDSDK_CFLAGS` default values.
The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2
-pipe".
:term:`BUILD_OS`
Specifies the operating system in use on the build host (e.g.
"linux"). The OpenEmbedded build system sets the value of
:term:`BUILD_OS` from the OS reported by the ``uname`` command - the
first word, converted to lower-case characters.
:term:`BUILD_PREFIX`
The toolchain binary prefix used for native recipes. The OpenEmbedded
build system uses the :term:`BUILD_PREFIX` value to set the
:term:`TARGET_PREFIX` when building for
``native`` recipes.
:term:`BUILD_STRIP`
Specifies the command to be used to strip debugging symbols from
binaries produced for the build host. By default, :term:`BUILD_STRIP`
points to
``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
:term:`BUILD_SYS`
Specifies the system, including the architecture and the operating
system, to use when building for the build host (i.e. when building
``native`` recipes).
The OpenEmbedded build system automatically sets this variable based
on :term:`BUILD_ARCH`,
:term:`BUILD_VENDOR`, and
:term:`BUILD_OS`. You do not need to set the
:term:`BUILD_SYS` variable yourself.
:term:`BUILD_VENDOR`
Specifies the vendor name to use when building for the build host.
The default value is an empty string ("").
:term:`BUILDDIR`
Points to the location of the :term:`Build Directory`.
You can define this directory indirectly through the
:ref:`structure-core-script` script by passing in a Build
Directory path when you run the script. If you run the script and do
not provide a Build Directory path, the :term:`BUILDDIR` defaults to
``build`` in the current directory.
:term:`BUILDHISTORY_COMMIT`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies whether or not to commit the build
history output in a local Git repository. If set to "1", this local
repository will be maintained automatically by the ``buildhistory``
class and a commit will be created on every build for changes to each
top-level subdirectory of the build history output (images, packages,
and sdk). If you want to track changes to build history over time,
you should set this value to "1".
By default, the ``buildhistory`` class does not commit the build
history output in a local Git repository::
BUILDHISTORY_COMMIT ?= "0"
:term:`BUILDHISTORY_COMMIT_AUTHOR`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies the author to use for each Git commit.
In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the
:term:`BUILDHISTORY_COMMIT` variable must
be set to "1".
Git requires that the value you provide for the
:term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name
email@host". Providing an email address or host that is not valid
does not produce an error.
By default, the ``buildhistory`` class sets the variable as follows::
BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
:term:`BUILDHISTORY_DIR`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies the directory in which build history
information is kept. For more information on how the variable works,
see the ``buildhistory.class``.
By default, the ``buildhistory`` class sets the directory as follows::
BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
:term:`BUILDHISTORY_FEATURES`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies the build history features to be
enabled. For more information on how build history works, see the
":ref:`dev-manual/common-tasks:maintaining build output quality`"
section in the Yocto Project Development Tasks Manual.
You can specify these features in the form of a space-separated list:
- *image:* Analysis of the contents of images, which includes the
list of installed packages among other things.
- *package:* Analysis of the contents of individual packages.
- *sdk:* Analysis of the contents of the software development kit
(SDK).
- *task:* Save output file signatures for
:ref:`shared state <overview-manual/concepts:shared state cache>`
(sstate) tasks.
This saves one file per task and lists the SHA-256 checksums for
each file staged (i.e. the output of the task).
By default, the ``buildhistory`` class enables the following
features::
BUILDHISTORY_FEATURES ?= "image package sdk"
:term:`BUILDHISTORY_IMAGE_FILES`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies a list of paths to files copied from
the image contents into the build history directory under an
"image-files" directory in the directory for the image, so that you
can track the contents of each file. The default is to copy
``/etc/passwd`` and ``/etc/group``, which allows you to monitor for
changes in user and group entries. You can modify the list to include
any file. Specifying an invalid path does not produce an error.
Consequently, you can include files that might not always be present.
By default, the ``buildhistory`` class provides paths to the
following files::
BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
:term:`BUILDHISTORY_PATH_PREFIX_STRIP`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable specifies a common path prefix that should be
stripped off the beginning of paths in the task signature list when the
``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be
useful when build history is populated from multiple sources that may not
all use the same top level directory.
By default, the ``buildhistory`` class sets the variable as follows::
BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
In this case, no prefixes will be stripped.
:term:`BUILDHISTORY_PUSH_REPO`
When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
class, this variable optionally specifies a remote repository to
which build history pushes Git changes. In order for
:term:`BUILDHISTORY_PUSH_REPO` to work,
:term:`BUILDHISTORY_COMMIT` must be set to
"1".
The repository should correspond to a remote address that specifies a
repository as understood by Git, or alternatively to a remote name
that you have set up manually using ``git remote`` within the local
repository.
By default, the ``buildhistory`` class sets the variable as follows::
BUILDHISTORY_PUSH_REPO ?= ""
:term:`BUILDSDK_CFLAGS`
Specifies the flags to pass to the C compiler when building for the
SDK. When building in the ``nativesdk-`` context,
:term:`CFLAGS` is set to the value of this variable by
default.
:term:`BUILDSDK_CPPFLAGS`
Specifies the flags to pass to the C pre-processor (i.e. to both the
C and the C++ compilers) when building for the SDK. When building in
the ``nativesdk-`` context, :term:`CPPFLAGS` is set
to the value of this variable by default.
:term:`BUILDSDK_CXXFLAGS`
Specifies the flags to pass to the C++ compiler when building for the
SDK. When building in the ``nativesdk-`` context,
:term:`CXXFLAGS` is set to the value of this variable
by default.
:term:`BUILDSDK_LDFLAGS`
Specifies the flags to pass to the linker when building for the SDK.
When building in the ``nativesdk-`` context,
:term:`LDFLAGS` is set to the value of this variable
by default.
:term:`BUILDSTATS_BASE`
Points to the location of the directory that holds build statistics
when you use and enable the
:ref:`buildstats <ref-classes-buildstats>` class. The
:term:`BUILDSTATS_BASE` directory defaults to
``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
:term:`BUSYBOX_SPLIT_SUID`
For the BusyBox recipe, specifies whether to split the output
executable file into two parts: one for features that require
``setuid root``, and one for the remaining features (i.e. those that
do not require ``setuid root``).
The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in
splitting the output executable file. Set the variable to "0" to get
a single output executable file.
:term:`CACHE`
Specifies the directory BitBake uses to store a cache of the
:term:`Metadata` so it does not need to be parsed every time
BitBake is started.
:term:`CC`
The minimal command and arguments used to run the C compiler.
:term:`CFLAGS`
Specifies the flags to pass to the C compiler. This variable is
exported to an environment variable and thus made visible to the
software being built during the compilation step.
Default initialization for :term:`CFLAGS` varies depending on what is
being built:
- :term:`TARGET_CFLAGS` when building for the
target
- :term:`BUILD_CFLAGS` when building for the
build host (i.e. ``-native``)
- :term:`BUILDSDK_CFLAGS` when building for
an SDK (i.e. ``nativesdk-``)
:term:`CLASSOVERRIDE`
An internal variable specifying the special class override that
should currently apply (e.g. "class-target", "class-native", and so
forth). The classes that use this variable (e.g.
:ref:`native <ref-classes-native>`,
:ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the
variable to appropriate values.
.. note::
:term:`CLASSOVERRIDE` gets its default "class-target" value from the
``bitbake.conf`` file.
As an example, the following override allows you to install extra
files, but only when building for the target::
do_install:append:class-target() {
install my-extra-file ${D}${sysconfdir}
}
Here is an example where ``FOO`` is set to
"native" when building for the build host, and to "other" when not
building for the build host::
FOO:class-native = "native"
FOO = "other"
The underlying mechanism behind :term:`CLASSOVERRIDE` is simply
that it is included in the default value of
:term:`OVERRIDES`.
:term:`CLEANBROKEN`
If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the
``make clean`` command does not work for the software being built.
Consequently, the OpenEmbedded build system will not try to run
``make clean`` during the :ref:`ref-tasks-configure`
task, which is the default behavior.
:term:`COMBINED_FEATURES`
Provides a list of hardware features that are enabled in both
:term:`MACHINE_FEATURES` and
:term:`DISTRO_FEATURES`. This select list of
features contains features that make sense to be controlled both at
the machine and distribution configuration level. For example, the
"bluetooth" feature requires hardware support but should also be
optional at the distribution level, in case the hardware supports
Bluetooth but you do not ever intend to use it.
:term:`COMMON_LICENSE_DIR`
Points to ``meta/files/common-licenses`` in the
:term:`Source Directory`, which is where generic license
files reside.
:term:`COMPATIBLE_HOST`
A regular expression that resolves to one or more hosts (when the
recipe is native) or one or more targets (when the recipe is
non-native) with which a recipe is compatible. The regular expression
is matched against :term:`HOST_SYS`. You can use the
variable to stop recipes from being built for classes of systems with
which the recipes are not compatible. Stopping these builds is
particularly useful with kernels. The variable also helps to increase
parsing speed since the build system skips parsing recipes not
compatible with the current system.
:term:`COMPATIBLE_MACHINE`
A regular expression that resolves to one or more target machines
with which a recipe is compatible. The regular expression is matched
against :term:`MACHINEOVERRIDES`. You can use
the variable to stop recipes from being built for machines with which
the recipes are not compatible. Stopping these builds is particularly
useful with kernels. The variable also helps to increase parsing
speed since the build system skips parsing recipes not compatible
with the current machine.
:term:`COMPLEMENTARY_GLOB`
Defines wildcards to match when installing a list of complementary
packages for all the packages explicitly (or implicitly) installed in
an image.
.. note::
The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching
(`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__),
which is similar to the Unix style pathname pattern expansion
(`glob <https://docs.python.org/3/library/glob.html>`__).
The resulting list of complementary packages is associated with an
item that can be added to
:term:`IMAGE_FEATURES`. An example usage of
this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES`
will install -dev packages (containing headers and other development
files) for every package in the image.
To add a new feature item pointing to a wildcard, use a variable flag
to specify the feature item name and use the value to specify the
wildcard. Here is an example::
COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
:term:`COMPONENTS_DIR`
Stores sysroot components for each recipe. The OpenEmbedded build
system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
sysroots for other recipes.
The default is
"``${``\ :term:`STAGING_DIR`\ ``}-components``."
(i.e.
"``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
:term:`CONF_VERSION`
Tracks the version of the local configuration file (i.e.
``local.conf``). The value for :term:`CONF_VERSION` increments each time
``build/conf/`` compatibility changes.
:term:`CONFFILES`
Identifies editable or configurable files that are part of a package.
If the Package Management System (PMS) is being used to update
packages on the target system, it is possible that configuration
files you have changed after the original installation and that you
now want to remain unchanged are overwritten. In other words,
editable files might exist in the package that you do not want reset
as part of the package update process. You can use the :term:`CONFFILES`
variable to list the files in the package that you wish to prevent
the PMS from overwriting during this update process.
To use the :term:`CONFFILES` variable, provide a package name override
that identifies the resulting package. Then, provide a
space-separated list of files. Here is an example::
CONFFILES:${PN} += "${sysconfdir}/file1 \
${sysconfdir}/file2 ${sysconfdir}/file3"
There is a relationship between the :term:`CONFFILES` and :term:`FILES`
variables. The files listed within :term:`CONFFILES` must be a subset of
the files listed within :term:`FILES`. Because the configuration files
you provide with :term:`CONFFILES` are simply being identified so that
the PMS will not overwrite them, it makes sense that the files must
already be included as part of the package through the :term:`FILES`
variable.
.. note::
When specifying paths as part of the :term:`CONFFILES` variable, it is
good practice to use appropriate path variables.
For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}``
rather than ``/usr/bin``. You can find a list of these variables at
the top of the ``meta/conf/bitbake.conf`` file in the
:term:`Source Directory`.
:term:`CONFIG_INITRAMFS_SOURCE`
Identifies the initial RAM filesystem (initramfs) source files. The
OpenEmbedded build system receives and uses this kernel Kconfig
variable as an environment variable. By default, the variable is set
to null ("").
The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
with a ``.cpio`` suffix or a space-separated list of directories and
files for building the initramfs image. A cpio archive should contain
a filesystem archive to be used as an initramfs image. Directories
should contain a filesystem layout to be included in the initramfs
image. Files should contain entries according to the format described
by the ``usr/gen_init_cpio`` program in the kernel tree.
If you specify multiple directories and files, the initramfs image
will be the aggregate of all of them.
For information on creating an initramfs, see the
":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
in the Yocto Project Development Tasks Manual.
:term:`CONFIG_SITE`
A list of files that contains ``autoconf`` test results relevant to
the current build. This variable is used by the Autotools utilities
when running ``configure``.
:term:`CONFIGURE_FLAGS`
The minimal arguments for GNU configure.
:term:`CONFLICT_DISTRO_FEATURES`
When inheriting the
:ref:`features_check <ref-classes-features_check>`
class, this variable identifies distribution features that would be
in conflict should the recipe be built. In other words, if the
:term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also
appears in :term:`DISTRO_FEATURES` within the current configuration, then
the recipe will be skipped, and if the build system attempts to build
the recipe then an error will be triggered.
:term:`COPYLEFT_LICENSE_EXCLUDE`
A space-separated list of licenses to exclude from the source
archived by the :ref:`archiver <ref-classes-archiver>` class. In
other words, if a license in a recipe's
:term:`LICENSE` value is in the value of
:term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the
class.
.. note::
The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the
:term:`COPYLEFT_LICENSE_INCLUDE` variable.
The default value, which is "CLOSED Proprietary", for
:term:`COPYLEFT_LICENSE_EXCLUDE` is set by the
:ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
is inherited by the ``archiver`` class.
:term:`COPYLEFT_LICENSE_INCLUDE`
A space-separated list of licenses to include in the source archived
by the :ref:`archiver <ref-classes-archiver>` class. In other
words, if a license in a recipe's :term:`LICENSE`
value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its
source is archived by the class.
The default value is set by the
:ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
is inherited by the ``archiver`` class. The default value includes
"GPL*", "LGPL*", and "AGPL*".
:term:`COPYLEFT_PN_EXCLUDE`
A list of recipes to exclude in the source archived by the
:ref:`archiver <ref-classes-archiver>` class. The
:term:`COPYLEFT_PN_EXCLUDE` variable overrides the license inclusion and
exclusion caused through the
:term:`COPYLEFT_LICENSE_INCLUDE` and
:term:`COPYLEFT_LICENSE_EXCLUDE`
variables, respectively.
The default value, which is "" indicating to not explicitly exclude
any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the
:ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
is inherited by the ``archiver`` class.
:term:`COPYLEFT_PN_INCLUDE`
A list of recipes to include in the source archived by the
:ref:`archiver <ref-classes-archiver>` class. The
:term:`COPYLEFT_PN_INCLUDE` variable overrides the license inclusion and
exclusion caused through the
:term:`COPYLEFT_LICENSE_INCLUDE` and
:term:`COPYLEFT_LICENSE_EXCLUDE`
variables, respectively.
The default value, which is "" indicating to not explicitly include
any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the
:ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
is inherited by the ``archiver`` class.
:term:`COPYLEFT_RECIPE_TYPES`
A space-separated list of recipe types to include in the source
archived by the :ref:`archiver <ref-classes-archiver>` class.
Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``,
``crosssdk``, and ``cross-canadian``.
The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES`
is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>`
class, which is inherited by the ``archiver`` class.
:term:`COPY_LIC_DIRS`
If set to "1" along with the
:term:`COPY_LIC_MANIFEST` variable, the
OpenEmbedded build system copies into the image the license files,
which are located in ``/usr/share/common-licenses``, for each
package. The license files are placed in directories within the image
itself during build time.
.. note::
The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for
newly installed packages to an image, which might be most suitable for
read-only filesystems that cannot be upgraded. See the
:term:`LICENSE_CREATE_PACKAGE` variable for additional information.
You can also reference the ":ref:`dev-manual/common-tasks:providing license text`"
section in the Yocto Project Development Tasks Manual for
information on providing license text.
:term:`COPY_LIC_MANIFEST`
If set to "1", the OpenEmbedded build system copies the license
manifest for the image to
``/usr/share/common-licenses/license.manifest`` within the image
itself during build time.
.. note::
The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for
newly installed packages to an image, which might be most suitable for
read-only filesystems that cannot be upgraded. See the
:term:`LICENSE_CREATE_PACKAGE` variable for additional information.
You can also reference the ":ref:`dev-manual/common-tasks:providing license text`"
section in the Yocto Project Development Tasks Manual for
information on providing license text.
:term:`CORE_IMAGE_EXTRA_INSTALL`
Specifies the list of packages to be added to the image. You should
only set this variable in the ``local.conf`` configuration file found
in the :term:`Build Directory`.
This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
supported.
:term:`COREBASE`
Specifies the parent directory of the OpenEmbedded-Core Metadata
layer (i.e. ``meta``).
It is an important distinction that :term:`COREBASE` points to the parent
of this layer and not the layer itself. Consider an example where you
have cloned the Poky Git repository and retained the ``poky`` name
for your local copy of the repository. In this case, :term:`COREBASE`
points to the ``poky`` folder because it is the parent directory of
the ``poky/meta`` layer.
:term:`COREBASE_FILES`
Lists files from the :term:`COREBASE` directory that
should be copied other than the layers listed in the
``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
to copy metadata from the OpenEmbedded build system
into the extensible SDK.
Explicitly listing files in :term:`COREBASE` is needed because it
typically contains build directories and other files that should not
normally be copied into the extensible SDK. Consequently, the value
of :term:`COREBASE_FILES` is used in order to only copy the files that
are actually needed.
:term:`CPP`
The minimal command and arguments used to run the C preprocessor.
:term:`CPPFLAGS`
Specifies the flags to pass to the C pre-processor (i.e. to both the
C and the C++ compilers). This variable is exported to an environment
variable and thus made visible to the software being built during the
compilation step.
Default initialization for :term:`CPPFLAGS` varies depending on what is
being built:
- :term:`TARGET_CPPFLAGS` when building for
the target
- :term:`BUILD_CPPFLAGS` when building for the
build host (i.e. ``-native``)
- :term:`BUILDSDK_CPPFLAGS` when building
for an SDK (i.e. ``nativesdk-``)
:term:`CROSS_COMPILE`
The toolchain binary prefix for the target tools. The
:term:`CROSS_COMPILE` variable is the same as the
:term:`TARGET_PREFIX` variable.
.. note::
The OpenEmbedded build system sets the :term:`CROSS_COMPILE`
variable only in certain contexts (e.g. when building for kernel
and kernel module recipes).
:term:`CVE_CHECK_PN_WHITELIST`
The list of package names (:term:`PN`) for which
CVEs (Common Vulnerabilities and Exposures) are ignored.
:term:`CVE_CHECK_WHITELIST`
The list of CVE IDs which are ignored. Here is
an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
# This is windows only issue.
CVE_CHECK_WHITELIST += "CVE-2020-15523"
:term:`CVE_PRODUCT`
In a recipe, defines the name used to match the recipe name
against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
The default is ${:term:`BPN`}. If it does not match the name in the NIST CVE
database or matches with multiple entries in the database, the default
value needs to be changed.
Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
:term:`CVSDIR`
The directory in which files checked out under the CVS system are
stored.
:term:`CXX`
The minimal command and arguments used to run the C++ compiler.
:term:`CXXFLAGS`
Specifies the flags to pass to the C++ compiler. This variable is
exported to an environment variable and thus made visible to the
software being built during the compilation step.
Default initialization for :term:`CXXFLAGS` varies depending on what is
being built:
- :term:`TARGET_CXXFLAGS` when building for
the target
- :term:`BUILD_CXXFLAGS` when building for the
build host (i.e. ``-native``)
- :term:`BUILDSDK_CXXFLAGS` when building
for an SDK (i.e. ``nativesdk-``)
:term:`D`
The destination directory. The location in the :term:`Build Directory`
where components are installed by the
:ref:`ref-tasks-install` task. This location defaults
to::
${WORKDIR}/image
.. note::
Tasks that read from or write to this directory should run under
:ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
:term:`DATE`
The date the build was started. Dates appear using the year, month,
and day (YMD) format (e.g. "20150209" for February 9th, 2015).
:term:`DATETIME`
The date and time on which the current build started. The format is
suitable for timestamps.
:term:`DEBIAN_NOAUTONAME`
When the :ref:`debian <ref-classes-debian>` class is inherited,
which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
particular package should not be renamed according to Debian library
package naming. You must use the package name as an override when you
set this variable. Here is an example from the ``fontconfig`` recipe::
DEBIAN_NOAUTONAME:fontconfig-utils = "1"
:term:`DEBIANNAME`
When the :ref:`debian <ref-classes-debian>` class is inherited,
which is the default behavior, :term:`DEBIANNAME` allows you to override
the library name for an individual package. Overriding the library
name in these cases is rare. You must use the package name as an
override when you set this variable. Here is an example from the
``dbus`` recipe::
DEBIANNAME:${PN} = "dbus-1"
:term:`DEBUG_BUILD`
Specifies to build packages with debugging information. This
influences the value of the :term:`SELECTED_OPTIMIZATION` variable.
:term:`DEBUG_OPTIMIZATION`
The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
compiling a system for debugging. This variable defaults to "-O
-fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
:term:`DEFAULT_PREFERENCE`
Specifies a weak bias for recipe selection priority.
The most common usage of this is variable is to set it to "-1" within
a recipe for a development version of a piece of software. Using the
variable in this way causes the stable version of the recipe to build
by default in the absence of :term:`PREFERRED_VERSION` being used to
build the development version.
.. note::
The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden
by :term:`BBFILE_PRIORITY` if that variable is different between two
layers that contain different versions of the same recipe.
:term:`DEFAULTTUNE`
The default CPU and Application Binary Interface (ABI) tunings (i.e.
the "tune") used by the OpenEmbedded build system. The
:term:`DEFAULTTUNE` helps define
:term:`TUNE_FEATURES`.
The default tune is either implicitly or explicitly set by the
machine (:term:`MACHINE`). However, you can override
the setting using available tunes as defined with
:term:`AVAILTUNES`.
:term:`DEPENDS`
Lists a recipe's build-time dependencies. These are dependencies on
other recipes whose contents (e.g. headers and shared libraries) are
needed by the recipe at build time.
As an example, consider a recipe ``foo`` that contains the following
assignment::
DEPENDS = "bar"
The practical effect of the previous
assignment is that all files installed by bar will be available in
the appropriate staging sysroot, given by the
:term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the
:ref:`ref-tasks-configure` task for ``foo`` runs.
This mechanism is implemented by having ``do_configure`` depend on
the :ref:`ref-tasks-populate_sysroot` task of
each recipe listed in :term:`DEPENDS`, through a
``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
declaration in the :ref:`base <ref-classes-base>` class.
.. note::
It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
explicitly. The standard classes and build-related variables are
configured to automatically use the appropriate staging sysroots.
As another example, :term:`DEPENDS` can also be used to add utilities
that run on the build machine during the build. For example, a recipe
that makes use of a code generator built by the recipe ``codegen``
might have the following::
DEPENDS = "codegen-native"
For more
information, see the :ref:`native <ref-classes-native>` class and
the :term:`EXTRANATIVEPATH` variable.
.. note::
- :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
it is a list of :term:`PROVIDES` names, which
usually match recipe names. Putting a package name such as
"foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
instead, as this will put files from all the packages that make
up ``foo``, which includes those from ``foo-dev``, into the
sysroot.
- One recipe having another recipe in :term:`DEPENDS` does not by
itself add any runtime dependencies between the packages
produced by the two recipes. However, as explained in the
":ref:`overview-manual/concepts:automatically added runtime dependencies`"
section in the Yocto Project Overview and Concepts Manual,
runtime dependencies will often be added automatically, meaning
:term:`DEPENDS` alone is sufficient for most recipes.
- Counterintuitively, :term:`DEPENDS` is often necessary even for
recipes that install precompiled components. For example, if
``libfoo`` is a precompiled library that links against
``libbar``, then linking against ``libfoo`` requires both
``libfoo`` and ``libbar`` to be available in the sysroot.
Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
to the recipe that installs ``libbar``, other recipes might
fail to link against ``libfoo``.
For information on runtime dependencies, see the
:term:`RDEPENDS` variable. You can also see the
":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
BitBake User Manual for additional information on tasks and
dependencies.
:term:`DEPLOY_DIR`
Points to the general area that the OpenEmbedded build system uses to
place images, packages, SDKs, and other output files that are ready
to be used outside of the build system. By default, this directory
resides within the :term:`Build Directory` as
``${TMPDIR}/deploy``.
For more information on the structure of the Build Directory, see
":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
For more detail on the contents of the ``deploy`` directory, see the
":ref:`overview-manual/concepts:images`",
":ref:`overview-manual/concepts:package feeds`", and
":ref:`overview-manual/concepts:application development sdk`" sections all in the
Yocto Project Overview and Concepts Manual.
:term:`DEPLOY_DIR_DEB`
Points to the area that the OpenEmbedded build system uses to place
Debian packages that are ready to be used outside of the build
system. This variable applies only when
:term:`PACKAGE_CLASSES` contains
"package_deb".
The BitBake configuration file initially defines the
:term:`DEPLOY_DIR_DEB` variable as a sub-folder of
:term:`DEPLOY_DIR`::
DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
The :ref:`package_deb <ref-classes-package_deb>` class uses the
:term:`DEPLOY_DIR_DEB` variable to make sure the
:ref:`ref-tasks-package_write_deb` task
writes Debian packages into the appropriate folder. For more
information on how packaging works, see the
":ref:`overview-manual/concepts:package feeds`" section
in the Yocto Project Overview and Concepts Manual.
:term:`DEPLOY_DIR_IMAGE`
Points to the area that the OpenEmbedded build system uses to place
images and other associated output files that are ready to be
deployed onto the target machine. The directory is machine-specific
as it contains the ``${MACHINE}`` name. By default, this directory
resides within the :term:`Build Directory` as
``${DEPLOY_DIR}/images/${MACHINE}/``.
It must not be used directly in recipes when deploying files. Instead,
it's only useful when a recipe needs to "read" a file already deployed
by a dependency. So, it should be filled with the contents of
:term:`DEPLOYDIR` by the :ref:`deploy <ref-classes-deploy>` class or
with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image
<ref-classes-image>` class.
For more information on the structure of the Build Directory, see
":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
For more detail on the contents of the ``deploy`` directory, see the
":ref:`overview-manual/concepts:images`" and
":ref:`overview-manual/concepts:application development sdk`" sections both in
the Yocto Project Overview and Concepts Manual.
:term:`DEPLOY_DIR_IPK`
Points to the area that the OpenEmbedded build system uses to place
IPK packages that are ready to be used outside of the build system.
This variable applies only when
:term:`PACKAGE_CLASSES` contains
"package_ipk".
The BitBake configuration file initially defines this variable as a
sub-folder of :term:`DEPLOY_DIR`::
DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
The :ref:`package_ipk <ref-classes-package_ipk>` class uses the
:term:`DEPLOY_DIR_IPK` variable to make sure the
:ref:`ref-tasks-package_write_ipk` task
writes IPK packages into the appropriate folder. For more information
on how packaging works, see the
":ref:`overview-manual/concepts:package feeds`" section
in the Yocto Project Overview and Concepts Manual.
:term:`DEPLOY_DIR_RPM`
Points to the area that the OpenEmbedded build system uses to place
RPM packages that are ready to be used outside of the build system.
This variable applies only when
:term:`PACKAGE_CLASSES` contains
"package_rpm".
The BitBake configuration file initially defines this variable as a
sub-folder of :term:`DEPLOY_DIR`::
DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
The :ref:`package_rpm <ref-classes-package_rpm>` class uses the
:term:`DEPLOY_DIR_RPM` variable to make sure the
:ref:`ref-tasks-package_write_rpm` task
writes RPM packages into the appropriate folder. For more information
on how packaging works, see the
":ref:`overview-manual/concepts:package feeds`" section
in the Yocto Project Overview and Concepts Manual.
:term:`DEPLOY_DIR_TAR`
Points to the area that the OpenEmbedded build system uses to place
tarballs that are ready to be used outside of the build system. This
variable applies only when
:term:`PACKAGE_CLASSES` contains
"package_tar".
The BitBake configuration file initially defines this variable as a
sub-folder of :term:`DEPLOY_DIR`::
DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
The :ref:`package_tar <ref-classes-package_tar>` class uses the
:term:`DEPLOY_DIR_TAR` variable to make sure the
:ref:`ref-tasks-package_write_tar` task
writes TAR packages into the appropriate folder. For more information
on how packaging works, see the
":ref:`overview-manual/concepts:package feeds`" section
in the Yocto Project Overview and Concepts Manual.
:term:`DEPLOYDIR`
When inheriting the :ref:`deploy <ref-classes-deploy>` class, the
:term:`DEPLOYDIR` points to a temporary work area for deployed files that
is set in the ``deploy`` class as follows::
DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
Recipes inheriting the ``deploy`` class should copy files to be
deployed into :term:`DEPLOYDIR`, and the class will take care of copying
them into :term:`DEPLOY_DIR_IMAGE`
afterwards.
:term:`DESCRIPTION`
The package description used by package managers. If not set,
:term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
variable.
:term:`DISTRO`
The short name of the distribution. For information on the long name
of the distribution, see the :term:`DISTRO_NAME`
variable.
The :term:`DISTRO` variable corresponds to a distribution configuration
file whose root name is the same as the variable's argument and whose
filename extension is ``.conf``. For example, the distribution
configuration file for the Poky distribution is named ``poky.conf``
and resides in the ``meta-poky/conf/distro`` directory of the
:term:`Source Directory`.
Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
follows::
DISTRO = "poky"
Distribution configuration files are located in a ``conf/distro``
directory within the :term:`Metadata` that contains the
distribution configuration. The value for :term:`DISTRO` must not contain
spaces, and is typically all lower-case.
.. note::
If the :term:`DISTRO` variable is blank, a set of default configurations
are used, which are specified within
``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
:term:`DISTRO_CODENAME`
Specifies a codename for the distribution being built.
:term:`DISTRO_EXTRA_RDEPENDS`
Specifies a list of distro-specific packages to add to all images.
This variable takes affect through ``packagegroup-base`` so the
variable only really applies to the more full-featured images that
include ``packagegroup-base``. You can use this variable to keep
distro policy out of generic images. As with all other distro
variables, you set this variable in the distro ``.conf`` file.
:term:`DISTRO_EXTRA_RRECOMMENDS`
Specifies a list of distro-specific packages to add to all images if
the packages exist. The packages might not exist or be empty (e.g.
kernel modules). The list of packages are automatically installed but
you can remove them.
:term:`DISTRO_FEATURES`
The software support you want in your distribution for various
features. You define your distribution features in the distribution
configuration file.
In most cases, the presence or absence of a feature in
:term:`DISTRO_FEATURES` is translated to the appropriate option supplied
to the configure script during the
:ref:`ref-tasks-configure` task for recipes that
optionally support the feature. For example, specifying "x11" in
:term:`DISTRO_FEATURES`, causes every piece of software built for the
target that can optionally support X11 to have its X11 support
enabled.
Two more examples are Bluetooth and NFS support. For a more complete
list of features that ships with the Yocto Project and that you can
provide with this variable, see the ":ref:`ref-features-distro`" section.
:term:`DISTRO_FEATURES_BACKFILL`
Features to be added to :term:`DISTRO_FEATURES` if not also present in
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
This variable is set in the ``meta/conf/bitbake.conf`` file. It is
not intended to be user-configurable. It is best to just reference
the variable to see which distro features are being backfilled for
all distro configurations. See the ":ref:`ref-features-backfill`" section
for more information.
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be
backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See
the ":ref:`ref-features-backfill`" section for more information.
:term:`DISTRO_FEATURES_DEFAULT`
A convenience variable that gives you the default list of distro
features with the exception of any features specific to the C library
(``libc``).
When creating a custom distribution, you might find it useful to be
able to reuse the default
:term:`DISTRO_FEATURES` options without the
need to write out the full set. Here is an example that uses
:term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
:term:`DISTRO_FEATURES_FILTER_NATIVE`
Specifies a list of features that if present in the target
:term:`DISTRO_FEATURES` value should be
included in :term:`DISTRO_FEATURES` when building native recipes. This
variable is used in addition to the features filtered using the
:term:`DISTRO_FEATURES_NATIVE`
variable.
:term:`DISTRO_FEATURES_FILTER_NATIVESDK`
Specifies a list of features that if present in the target
:term:`DISTRO_FEATURES` value should be
included in :term:`DISTRO_FEATURES` when building nativesdk recipes. This
variable is used in addition to the features filtered using the
:term:`DISTRO_FEATURES_NATIVESDK`
variable.
:term:`DISTRO_FEATURES_NATIVE`
Specifies a list of features that should be included in
:term:`DISTRO_FEATURES` when building native
recipes. This variable is used in addition to the features filtered
using the
:term:`DISTRO_FEATURES_FILTER_NATIVE`
variable.
:term:`DISTRO_FEATURES_NATIVESDK`
Specifies a list of features that should be included in
:term:`DISTRO_FEATURES` when building
nativesdk recipes. This variable is used in addition to the features
filtered using the
:term:`DISTRO_FEATURES_FILTER_NATIVESDK`
variable.
:term:`DISTRO_NAME`
The long name of the distribution. For information on the short name
of the distribution, see the :term:`DISTRO` variable.
The :term:`DISTRO_NAME` variable corresponds to a distribution
configuration file whose root name is the same as the variable's
argument and whose filename extension is ``.conf``. For example, the
distribution configuration file for the Poky distribution is named
``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
of the :term:`Source Directory`.
Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
as follows::
DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
Distribution configuration files are located in a ``conf/distro``
directory within the :term:`Metadata` that contains the
distribution configuration.
.. note::
If the :term:`DISTRO_NAME` variable is blank, a set of default
configurations are used, which are specified within
``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
:term:`DISTRO_VERSION`
The version of the distribution.
:term:`DISTROOVERRIDES`
A colon-separated list of overrides specific to the current
distribution. By default, this list includes the value of
:term:`DISTRO`.
You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
apply to the distribution.
The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
is included in the default value of
:term:`OVERRIDES`.
:term:`DISTUTILS_SETUP_PATH`
When used by recipes that inherit the
:ref:`distutils3 <ref-classes-distutils3>` or
:ref:`setuptools3 <ref-classes-setuptools3>` class, this variable should
be used to specify the directory in which the ``setup.py`` file is
located if it is not at the root of the source tree (as specified by
:term:`S`). For example, in a recipe where the sources are fetched from
a Git repository and ``setup.py`` is in a ``python/pythonmodule``
subdirectory, you would have this::
S = "${WORKDIR}/git"
DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
:term:`DL_DIR`
The central download directory used by the build process to store
downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
for everything except Git repositories. If you want tarballs of Git
repositories, use the
:term:`BB_GENERATE_MIRROR_TARBALLS`
variable.
You can set this directory by defining the :term:`DL_DIR` variable in the
``conf/local.conf`` file. This directory is self-maintaining and you
should not have to touch it. By default, the directory is
``downloads`` in the :term:`Build Directory`.
::
#DL_DIR ?= "${TOPDIR}/downloads"
To specify a different download directory,
simply remove the comment from the line and provide your directory.
During a first build, the system downloads many different source code
tarballs from various upstream projects. Downloading can take a
while, particularly if your network connection is slow. Tarballs are
all stored in the directory defined by :term:`DL_DIR` and the build
system looks there first to find source tarballs.
.. note::
When wiping and rebuilding, you can preserve this directory to
speed up this part of subsequent builds.
You can safely share this directory between multiple builds on the
same development machine. For additional information on how the build
process gets source files when working behind a firewall or proxy
server, see this specific question in the ":doc:`faq`"
chapter. You can also refer to the
":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Wiki page.
:term:`DOC_COMPRESS`
When inheriting the :ref:`compress_doc <ref-classes-compress_doc>`
class, this variable sets the compression policy used when the
OpenEmbedded build system compresses man pages and info pages. By
default, the compression method used is gz (gzip). Other policies
available are xz and bz2.
For information on policies and on how to use this variable, see the
comments in the ``meta/classes/compress_doc.bbclass`` file.
:term:`EFI_PROVIDER`
When building bootable images (i.e. where ``hddimg``, ``iso``, or
``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
:term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
default is "grub-efi", but "systemd-boot" can be used instead.
See the :ref:`systemd-boot <ref-classes-systemd-boot>` and
:ref:`image-live <ref-classes-image-live>` classes for more
information.
:term:`ENABLE_BINARY_LOCALE_GENERATION`
Variable that controls which locales for ``glibc`` are generated
during the build (useful if the target device has 64Mbytes of RAM or
less).
:term:`ERR_REPORT_DIR`
When used with the :ref:`report-error <ref-classes-report-error>`
class, specifies the path used for storing the debug files created by
the :ref:`error reporting
tool <dev-manual/common-tasks:using the error reporting tool>`, which
allows you to submit build errors you encounter to a central
database. By default, the value of this variable is
``${``\ :term:`LOG_DIR`\ ``}/error-report``.
You can set :term:`ERR_REPORT_DIR` to the path you want the error
reporting tool to store the debug files as follows in your
``local.conf`` file::
ERR_REPORT_DIR = "path"
:term:`ERROR_QA`
Specifies the quality assurance checks whose failures are reported as
errors by the OpenEmbedded build system. You set this variable in
your distribution configuration file. For a list of the checks you
can control with this variable, see the
":ref:`insane.bbclass <ref-classes-insane>`" section.
:term:`EXCLUDE_FROM_SHLIBS`
Triggers the OpenEmbedded build system's shared libraries resolver to
exclude an entire package when scanning for shared libraries.
.. note::
The shared libraries resolver's functionality results in part from
the internal function ``package_do_shlibs``, which is part of the
:ref:`ref-tasks-package` task. You should be aware that the shared
libraries resolver might implicitly define some dependencies between
packages.
The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
:term:`PRIVATE_LIBS` variable, which excludes a
package's particular libraries only and not the whole package.
Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
particular package::
EXCLUDE_FROM_SHLIBS = "1"
:term:`EXCLUDE_FROM_WORLD`
Directs BitBake to exclude a recipe from world builds (i.e.
``bitbake world``). During world builds, BitBake locates, parses and
builds all recipes found in every layer exposed in the
``bblayers.conf`` configuration file.
To exclude a recipe from a world build using this variable, set the
variable to "1" in the recipe.
.. note::
Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
world build in order to satisfy dependencies of other recipes. Adding
a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
explicitly added to the list of build targets in a world build.
:term:`EXTENDPE`
Used with file and pathnames to create a prefix for a recipe's
version based on the recipe's :term:`PE` value. If :term:`PE`
is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
If a recipe's :term:`PE` is not set (the default) or is equal to zero,
:term:`EXTENDPE` becomes "".
See the :term:`STAMP` variable for an example.
:term:`EXTENDPKGV`
The full package version specification as it appears on the final
packages produced by a recipe. The variable's value is normally used
to fix a runtime dependency to the exact same version of another
package in the same recipe::
RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
The dependency relationships are intended to force the package
manager to upgrade these types of packages in lock-step.
:term:`EXTERNAL_KERNEL_TOOLS`
When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
tools are not in the source tree.
When kernel tools are available in the tree, they are preferred over
any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
variable tells the OpenEmbedded build system to prefer the installed
external tools. See the
:ref:`kernel-yocto <ref-classes-kernel-yocto>` class in
``meta/classes`` to see how the variable is used.
:term:`EXTERNALSRC`
When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
class, this variable points to the source tree, which is outside of
the OpenEmbedded build system. When set, this variable sets the
:term:`S` variable, which is what the OpenEmbedded build
system uses to locate unpacked recipe source code.
For more information on ``externalsrc.bbclass``, see the
":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
can also find information on how to use this variable in the
":ref:`dev-manual/common-tasks:building software from an external source`"
section in the Yocto Project Development Tasks Manual.
:term:`EXTERNALSRC_BUILD`
When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
class, this variable points to the directory in which the recipe's
source code is built, which is outside of the OpenEmbedded build
system. When set, this variable sets the :term:`B` variable,
which is what the OpenEmbedded build system uses to locate the Build
Directory.
For more information on ``externalsrc.bbclass``, see the
":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
can also find information on how to use this variable in the
":ref:`dev-manual/common-tasks:building software from an external source`"
section in the Yocto Project Development Tasks Manual.
:term:`EXTRA_AUTORECONF`
For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
pass to the ``autoreconf`` command that is executed during the
:ref:`ref-tasks-configure` task.
The default value is "--exclude=autopoint".
:term:`EXTRA_IMAGE_FEATURES`
A list of additional features to include in an image. When listing
more than one feature, separate them with a space.
Typically, you configure this variable in your ``local.conf`` file,
which is found in the :term:`Build Directory`.
Although you can use this variable from within a recipe, best
practices dictate that you do not.
.. note::
To enable primary features from within the image recipe, use the
:term:`IMAGE_FEATURES` variable.
Here are some examples of features you can add:
- "dbg-pkgs" - Adds -dbg packages for all installed packages including
symbol information for debugging and profiling.
- "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and
enables post-installation logging. See the 'allow-empty-password' and
'post-install-logging' features in the ":ref:`ref-features-image`"
section for more information.
- "dev-pkgs" - Adds -dev packages for all installed packages. This is
useful if you want to develop against the libraries in the image.
- "read-only-rootfs" - Creates an image whose root filesystem is
read-only. See the
":ref:`dev-manual/common-tasks:creating a read-only root filesystem`"
section in the Yocto Project Development Tasks Manual for more
information
- "tools-debug" - Adds debugging tools such as gdb and strace.
- "tools-sdk" - Adds development tools such as gcc, make,
pkgconfig and so forth.
- "tools-testapps" - Adds useful testing tools
such as ts_print, aplay, arecord and so forth.
For a complete list of image features that ships with the Yocto
Project, see the ":ref:`ref-features-image`" section.
For an example that shows how to customize your image by using this
variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
section in the Yocto Project Development Tasks Manual.
:term:`EXTRA_IMAGECMD`
Specifies additional options for the image creation command that has
been specified in :term:`IMAGE_CMD`. When setting
this variable, use an override for the associated image type. Here is
an example::
EXTRA_IMAGECMD:ext3 ?= "-i 4096"
:term:`EXTRA_IMAGEDEPENDS`
A list of recipes to build that do not provide packages for
installing into the root filesystem.
Sometimes a recipe is required to build the final image but is not
needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
variable to list these recipes and thus specify the dependencies. A
typical example is a required bootloader in a machine configuration.
.. note::
To add packages to the root filesystem, see the various
:term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
:term:`EXTRANATIVEPATH`
A list of subdirectories of
``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
added to the beginning of the environment variable ``PATH``. As an
example, the following prepends
"${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
``PATH``::
EXTRANATIVEPATH = "foo bar"
:term:`EXTRA_OECMAKE`
Additional `CMake <https://cmake.org/overview/>`__ options. See the
:ref:`cmake <ref-classes-cmake>` class for additional information.
:term:`EXTRA_OECONF`
Additional ``configure`` script options. See
:term:`PACKAGECONFIG_CONFARGS` for
additional information on passing configure script options.
:term:`EXTRA_OEMAKE`
Additional GNU ``make`` options.
Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
variable to specify any required GNU options.
:term:`PARALLEL_MAKE` and
:term:`PARALLEL_MAKEINST` also make use of
:term:`EXTRA_OEMAKE` to pass the required flags.
:term:`EXTRA_OESCONS`
When inheriting the :ref:`scons <ref-classes-scons>` class, this
variable specifies additional configuration options you want to pass
to the ``scons`` command line.
:term:`EXTRA_USERS_PARAMS`
When inheriting the :ref:`extrausers <ref-classes-extrausers>`
class, this variable provides image level user and group operations.
This is a more global method of providing user and group
configuration as compared to using the
:ref:`useradd <ref-classes-useradd>` class, which ties user and
group configurations to a specific recipe.
The set list of commands you can configure using the
:term:`EXTRA_USERS_PARAMS` is shown in the ``extrausers`` class. These
commands map to the normal Unix commands of the same names::
# EXTRA_USERS_PARAMS = "\
# useradd -p '' tester; \
# groupadd developers; \
# userdel nobody; \
# groupdel -g video; \
# groupmod -g 1020 developers; \
# usermod -s /bin/sh tester; \
# "
Additionally there is a special ``passwd-expire`` command that will
cause the password for a user to be expired and thus force changing it
on first login, for example::
EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
.. note::
At present, ``passwd-expire`` may only work for remote logins when
using OpenSSH and not dropbear as an SSH server.
:term:`FEATURE_PACKAGES`
Defines one or more packages to include in an image when a specific
item is included in :term:`IMAGE_FEATURES`.
When setting the value, :term:`FEATURE_PACKAGES` should have the name of
the feature item as an override. Here is an example::
FEATURE_PACKAGES_widget = "package1 package2"
In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
package1 and package2 would be included in the image.
.. note::
Packages installed by features defined through :term:`FEATURE_PACKAGES`
are often package groups. While similarly named, you should not
confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
are discussed elsewhere in the documentation.
:term:`FEED_DEPLOYDIR_BASE_URI`
Points to the base URL of the server and location within the
document-root that provides the metadata and packages required by
OPKG to support runtime package management of IPK packages. You set
this variable in your ``local.conf`` file.
Consider the following example::
FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
This example assumes you are serving
your packages over HTTP and your databases are located in a directory
named ``BOARD-dir``, which is underneath your HTTP server's
document-root. In this case, the OpenEmbedded build system generates
a set of configuration files for you in your target that work with
the feed.
:term:`FILES`
The list of files and directories that are placed in a package. The
:term:`PACKAGES` variable lists the packages
generated by a recipe.
To use the :term:`FILES` variable, provide a package name override that
identifies the resulting package. Then, provide a space-separated
list of files or paths that identify the files you want included as
part of the resulting package. Here is an example::
FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
.. note::
- When specifying files or paths, you can pattern match using
Python's
`glob <https://docs.python.org/3/library/glob.html>`_
syntax. For details on the syntax, see the documentation by
following the previous link.
- When specifying paths as part of the :term:`FILES` variable, it is
good practice to use appropriate path variables. For example,
use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
rather than ``/usr/bin``. You can find a list of these
variables at the top of the ``meta/conf/bitbake.conf`` file in
the :term:`Source Directory`. You will also
find the default values of the various ``FILES:*`` variables in
this file.
If some of the files you provide with the :term:`FILES` variable are
editable and you know they should not be overwritten during the
package update process by the Package Management System (PMS), you
can identify these files so that the PMS will not overwrite them. See
the :term:`CONFFILES` variable for information on
how to identify these files to the PMS.
:term:`FILES_SOLIBSDEV`
Defines the file specification to match
:term:`SOLIBSDEV`. In other words,
:term:`FILES_SOLIBSDEV` defines the full path name of the development
symbolic link (symlink) for shared libraries on the target platform.
The following statement from the ``bitbake.conf`` shows how it is
set::
FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
:term:`FILESEXTRAPATHS`
Extends the search path the OpenEmbedded build system uses when
looking for files and patches as it processes recipes and append
files. The default directories BitBake uses when it processes recipes
are initially defined by the :term:`FILESPATH`
variable. You can extend :term:`FILESPATH` variable by using
:term:`FILESEXTRAPATHS`.
Best practices dictate that you accomplish this by using
:term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
prepend paths as follows::
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
In the above example, the build system first
looks for files in a directory that has the same name as the
corresponding append file.
.. note::
When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
expansion (``:=``) operator. Immediate expansion makes sure that
BitBake evaluates :term:`THISDIR` at the time the
directive is encountered rather than at some later time when
expansion might result in a directory that does not contain the
files you need.
Also, include the trailing separating colon character if you are
prepending. The trailing colon character is necessary because you
are directing BitBake to extend the path by prepending directories
to the search path.
Here is another common use::
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
In this example, the build system extends the
:term:`FILESPATH` variable to include a directory named ``files`` that is
in the same directory as the corresponding append file.
This next example specifically adds three paths::
FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
A final example shows how you can extend the search path and include
a :term:`MACHINE`-specific override, which is useful
in a BSP layer::
FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
The previous statement appears in the
``linux-yocto-dev.bbappend`` file, which is found in the
:ref:`overview-manual/development-environment:yocto project source repositories` in
``meta-intel/common/recipes-kernel/linux``. Here, the machine
override is a special :term:`PACKAGE_ARCH`
definition for multiple ``meta-intel`` machines.
.. note::
For a layer that supports a single BSP, the override could just be
the value of :term:`MACHINE`.
By prepending paths in ``.bbappend`` files, you allow multiple append
files that reside in different layers but are used for the same
recipe to correctly extend the path.
:term:`FILESOVERRIDES`
A subset of :term:`OVERRIDES` used by the
OpenEmbedded build system for creating
:term:`FILESPATH`. The :term:`FILESOVERRIDES` variable
uses overrides to automatically extend the
:term:`FILESPATH` variable. For an example of how
that works, see the :term:`FILESPATH` variable
description. Additionally, you find more information on how overrides
are handled in the
":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
section of the BitBake User Manual.
By default, the :term:`FILESOVERRIDES` variable is defined as::
FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
.. note::
Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
with expected overrides and are used in an expected manner by the
build system.
:term:`FILESPATH`
The default set of directories the OpenEmbedded build system uses
when searching for patches and files.
During the build process, BitBake searches each directory in
:term:`FILESPATH` in the specified order when looking for files and
patches specified by each ``file://`` URI in a recipe's
:term:`SRC_URI` statements.
The default value for the :term:`FILESPATH` variable is defined in the
``base.bbclass`` class found in ``meta/classes`` in the
:term:`Source Directory`::
FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
"${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
The
:term:`FILESPATH` variable is automatically extended using the overrides
from the :term:`FILESOVERRIDES` variable.
.. note::
- Do not hand-edit the :term:`FILESPATH` variable. If you want the
build system to look in directories other than the defaults,
extend the :term:`FILESPATH` variable by using the
:term:`FILESEXTRAPATHS` variable.
- Be aware that the default :term:`FILESPATH` directories do not map
to directories in custom layers where append files
(``.bbappend``) are used. If you want the build system to find
patches or files that reside with your append files, you need
to extend the :term:`FILESPATH` variable by using the
:term:`FILESEXTRAPATHS` variable.
You can take advantage of this searching behavior in useful ways. For
example, consider a case where there is the following directory structure
for general and machine-specific configurations::
files/defconfig
files/MACHINEA/defconfig
files/MACHINEB/defconfig
Also in the example, the :term:`SRC_URI` statement contains
"file://defconfig". Given this scenario, you can set
:term:`MACHINE` to "MACHINEA" and cause the build
system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
"MACHINEB" and the build system uses files from ``files/MACHINEB``.
Finally, for any machine other than "MACHINEA" and "MACHINEB", the
build system uses files from ``files/defconfig``.
You can find out more about the patching process in the
":ref:`overview-manual/concepts:patching`" section
in the Yocto Project Overview and Concepts Manual and the
":ref:`dev-manual/common-tasks:patching code`" section in
the Yocto Project Development Tasks Manual. See the
:ref:`ref-tasks-patch` task as well.
:term:`FILESYSTEM_PERMS_TABLES`
Allows you to define your own file permissions settings table as part
of your configuration for the packaging process. For example, suppose
you need a consistent set of custom permissions for a set of groups
and users across an entire work project. It is best to do this in the
packages themselves but this is not always possible.
By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
which is located in the ``meta/files`` folder in the :term:`Source Directory`.
If you create your own file
permissions setting table, you should place it in your layer or the
distro's layer.
You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
``conf/local.conf`` file, which is found in the :term:`Build Directory`,
to point to your custom
``fs-perms.txt``. You can specify more than a single file permissions
setting table. The paths you specify to these files must be defined
within the :term:`BBPATH` variable.
For guidance on how to create your own file permissions settings
table file, examine the existing ``fs-perms.txt``.
:term:`FIT_DESC`
Specifies the description string encoded into a fitImage. The default
value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
class as follows::
FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
:term:`FIT_GENERATE_KEYS`
Decides whether to generate the keys for signing fitImage if they
don't already exist. The keys are created in :term:`UBOOT_SIGN_KEYDIR`.
The default value is 0.
:term:`FIT_HASH_ALG`
Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
:term:`FIT_KERNEL_COMP_ALG`
Compression algorithm to use for the kernel image inside the FIT Image.
At present, the only supported values are "gzip" (default) or "none"
If you set this variable to anything other than "none" you may also need
to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
:term:`FIT_KERNEL_COMP_ALG_EXTENSION`
File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
value is ".gz".
:term:`FIT_KEY_GENRSA_ARGS`
Arguments to openssl genrsa for generating RSA private key for signing
fitImage. The default value is "-F4". i.e. the public exponent 65537 to
use.
:term:`FIT_KEY_REQ_ARGS`
Arguments to openssl req for generating certificate for signing fitImage.
The default value is "-batch -new". batch for non interactive mode
and new for generating new keys.
:term:`FIT_KEY_SIGN_PKCS`
Format for public key certificate used in signing fitImage.
The default value is "x509".
:term:`FIT_SIGN_ALG`
Specifies the signature algorithm used in creating the FIT Image.
For e.g. rsa2048.
:term:`FIT_SIGN_NUMBITS`
Size of private key in number of bits used in fitImage. The default
value is "2048".
:term:`FIT_SIGN_INDIVIDUAL`
If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
class will sign the kernel, dtb and ramdisk images individually in addition
to signing the fitImage itself. This could be useful if you are
intending to verify signatures in another context than booting via
U-Boot.
:term:`FONT_EXTRA_RDEPENDS`
When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
this variable specifies the runtime dependencies for font packages.
By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
:term:`FONT_PACKAGES`
When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
this variable identifies packages containing font files that need to
be cached by Fontconfig. By default, the ``fontcache`` class assumes
that fonts are in the recipe's main package (i.e.
``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
need are in a package other than that main package.
:term:`FORCE_RO_REMOVE`
Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
during the generation of the root filesystem.
Set the variable to "1" to force the removal of these packages.
:term:`FULL_OPTIMIZATION`
The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
compiling an optimized system. This variable defaults to "-O2 -pipe
${DEBUG_FLAGS}".
:term:`GCCPIE`
Enables Position Independent Executables (PIE) within the GNU C
Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
Programming (ROP) attacks much more difficult to execute.
By default the ``security_flags.inc`` file enables PIE by setting the
variable as follows::
GCCPIE ?= "--enable-default-pie"
:term:`GCCVERSION`
Specifies the default version of the GNU C Compiler (GCC) used for
compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
``meta/conf/distro/include/tcmode-default.inc`` include file::
GCCVERSION ?= "8.%"
You can override this value by setting it in a
configuration file such as the ``local.conf``.
:term:`GDB`
The minimal command and arguments to run the GNU Debugger.
:term:`GITDIR`
The directory in which a local copy of a Git repository is stored
when it is cloned.
:term:`GLIBC_GENERATE_LOCALES`
Specifies the list of GLIBC locales to generate should you not wish
to generate all LIBC locals, which can be time consuming.
.. note::
If you specifically remove the locale ``en_US.UTF-8``, you must set
:term:`IMAGE_LINGUAS` appropriately.
You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
By default, all locales are generated.
::
GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
:term:`GROUPADD_PARAM`
When inheriting the :ref:`useradd <ref-classes-useradd>` class,
this variable specifies for a package what parameters should be
passed to the ``groupadd`` command if you wish to add a group to the
system when the package is installed.
Here is an example from the ``dbus`` recipe::
GROUPADD_PARAM:${PN} = "-r netdev"
For information on the standard Linux shell command
``groupadd``, see https://linux.die.net/man/8/groupadd.
:term:`GROUPMEMS_PARAM`
When inheriting the :ref:`useradd <ref-classes-useradd>` class,
this variable specifies for a package what parameters should be
passed to the ``groupmems`` command if you wish to modify the members
of a group when the package is installed.
For information on the standard Linux shell command ``groupmems``,
see https://linux.die.net/man/8/groupmems.
:term:`GRUB_GFXSERIAL`
Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
and serial in the boot menu. Set this variable to "1" in your
``local.conf`` or distribution configuration file to enable graphics
and serial in the menu.
See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
information on how this variable is used.
:term:`GRUB_OPTS`
Additional options to add to the GNU GRand Unified Bootloader (GRUB)
configuration. Use a semi-colon character (``;``) to separate
multiple options.
The :term:`GRUB_OPTS` variable is optional. See the
:ref:`grub-efi <ref-classes-grub-efi>` class for more information
on how this variable is used.
:term:`GRUB_TIMEOUT`
Specifies the timeout before executing the default ``LABEL`` in the
GNU GRand Unified Bootloader (GRUB).
The :term:`GRUB_TIMEOUT` variable is optional. See the
:ref:`grub-efi <ref-classes-grub-efi>` class for more information
on how this variable is used.
:term:`GTKIMMODULES_PACKAGES`
When inheriting the
:ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
this variable specifies the packages that contain the GTK+ input
method modules being installed when the modules are in packages other
than the main package.
:term:`HOMEPAGE`
Website where more information about the software the recipe is
building can be found.
:term:`HOST_ARCH`
The name of the target architecture, which is normally the same as
:term:`TARGET_ARCH`. The OpenEmbedded build system
supports many architectures. Here is an example list of architectures
supported. This list is by no means complete as the architecture is
configurable:
- arm
- i586
- x86_64
- powerpc
- powerpc64
- mips
- mipsel
:term:`HOST_CC_ARCH`
Specifies architecture-specific compiler flags that are passed to the
C compiler.
Default initialization for :term:`HOST_CC_ARCH` varies depending on what
is being built:
- :term:`TARGET_CC_ARCH` when building for the
target
- :term:`BUILD_CC_ARCH` when building for the build host (i.e.
``-native``)
- ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
``nativesdk-``)
:term:`HOST_OS`
Specifies the name of the target operating system, which is normally
the same as the :term:`TARGET_OS`. The variable can
be set to "linux" for ``glibc``-based systems and to "linux-musl" for
``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
"linux-musleabi" values possible.
:term:`HOST_PREFIX`
Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
is normally the same as :term:`TARGET_PREFIX`.
:term:`HOST_SYS`
Specifies the system, including the architecture and the operating
system, for which the build is occurring in the context of the
current recipe.
The OpenEmbedded build system automatically sets this variable based
on :term:`HOST_ARCH`,
:term:`HOST_VENDOR`, and
:term:`HOST_OS` variables.
.. note::
You do not need to set the variable yourself.
Consider these two examples:
- Given a native recipe on a 32-bit x86 machine running Linux, the
value is "i686-linux".
- Given a recipe being built for a little-endian MIPS target running
Linux, the value might be "mipsel-linux".
:term:`HOSTTOOLS`
A space-separated list (filter) of tools on the build host that
should be allowed to be called from within build tasks. Using this
filter helps reduce the possibility of host contamination. If a tool
specified in the value of :term:`HOSTTOOLS` is not found on the build
host, the OpenEmbedded build system produces an error and the build
is not started.
For additional information, see
:term:`HOSTTOOLS_NONFATAL`.
:term:`HOSTTOOLS_NONFATAL`
A space-separated list (filter) of tools on the build host that
should be allowed to be called from within build tasks. Using this
filter helps reduce the possibility of host contamination. Unlike
:term:`HOSTTOOLS`, the OpenEmbedded build system
does not produce an error if a tool specified in the value of
:term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
:term:`HOST_VENDOR`
Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
same as :term:`TARGET_VENDOR`.
:term:`ICECC_DISABLED`
Disables or enables the ``icecc`` (Icecream) function. For more
information on this function and best practices for using this
variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`"
section.
Setting this variable to "1" in your ``local.conf`` disables the
function::
ICECC_DISABLED ??= "1"
To enable the function, set the variable as follows::
ICECC_DISABLED = ""
:term:`ICECC_ENV_EXEC`
Points to the ``icecc-create-env`` script that you provide. This
variable is used by the :ref:`icecc <ref-classes-icecc>` class. You
set this variable in your ``local.conf`` file.
If you do not point to a script that you provide, the OpenEmbedded
build system uses the default script provided by the
``icecc-create-env.bb`` recipe, which is a modified version and not
the one that comes with ``icecc``.
:term:`ICECC_PARALLEL_MAKE`
Extra options passed to the ``make`` command during the
:ref:`ref-tasks-compile` task that specify parallel
compilation. This variable usually takes the form of "-j x", where x
represents the maximum number of parallel threads ``make`` can run.
.. note::
The options passed affect builds on all enabled machines on the
network, which are machines running the ``iceccd`` daemon.
If your enabled machines support multiple cores, coming up with the
maximum number of parallel threads that gives you the best
performance could take some experimentation since machine speed,
network lag, available memory, and existing machine loads can all
affect build time. Consequently, unlike the
:term:`PARALLEL_MAKE` variable, there is no
rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
performance.
If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
use it (i.e. the system does not detect and assign the number of
cores as is done with :term:`PARALLEL_MAKE`).
:term:`ICECC_PATH`
The location of the ``icecc`` binary. You can set this variable in
your ``local.conf`` file. If your ``local.conf`` file does not define
this variable, the :ref:`icecc <ref-classes-icecc>` class attempts
to define it by locating ``icecc`` using ``which``.
:term:`ICECC_USER_CLASS_BL`
Identifies user classes that you do not want the Icecream distributed
compile support to consider. This variable is used by the
:ref:`icecc <ref-classes-icecc>` class. You set this variable in
your ``local.conf`` file.
When you list classes using this variable, you are "blacklisting"
them from distributed compilation across remote hosts. Any classes
you list will be distributed and compiled locally.
:term:`ICECC_USER_PACKAGE_BL`
Identifies user recipes that you do not want the Icecream distributed
compile support to consider. This variable is used by the
:ref:`icecc <ref-classes-icecc>` class. You set this variable in
your ``local.conf`` file.
When you list packages using this variable, you are "blacklisting"
them from distributed compilation across remote hosts. Any packages
you list will be distributed and compiled locally.
:term:`ICECC_USER_PACKAGE_WL`
Identifies user recipes that use an empty
:term:`PARALLEL_MAKE` variable that you want to
force remote distributed compilation on using the Icecream
distributed compile support. This variable is used by the
:ref:`icecc <ref-classes-icecc>` class. You set this variable in
your ``local.conf`` file.
:term:`IMAGE_BASENAME`
The base name of image output files. This variable defaults to the
recipe name (``${``\ :term:`PN`\ ``}``).
:term:`IMAGE_EFI_BOOT_FILES`
A space-separated list of files installed into the boot partition
when preparing an image using the Wic tool with the
``bootimg-efi`` source plugin. By default,
the files are
installed under the same name as the source files. To change the
installed name, separate it from the original name with a semi-colon
(;). Source files need to be located in
:term:`DEPLOY_DIR_IMAGE`. Here are two
examples::
IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
Alternatively, source files can be picked up using a glob pattern. In
this case, the destination file must have the same name as the base
name of the source file path. To install files into a directory
within the target location, pass its name after a semi-colon (;).
Here are two examples::
IMAGE_EFI_BOOT_FILES = "boot/loader/*"
IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
The first example
installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
into the root of the target partition. The second example installs
the same files into a ``boot`` directory within the target partition.
You can find information on how to use the Wic tool in the
":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
section of the Yocto Project Development Tasks Manual. Reference
material for Wic is located in the
":doc:`/ref-manual/kickstart`" chapter.
:term:`IMAGE_BOOT_FILES`
A space-separated list of files installed into the boot partition
when preparing an image using the Wic tool with the
``bootimg-partition`` source plugin. By default,
the files are
installed under the same name as the source files. To change the
installed name, separate it from the original name with a semi-colon
(;). Source files need to be located in
:term:`DEPLOY_DIR_IMAGE`. Here are two
examples::
IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
Alternatively, source files can be picked up using a glob pattern. In
this case, the destination file must have the same name as the base
name of the source file path. To install files into a directory
within the target location, pass its name after a semi-colon (;).
Here are two examples::
IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
The first example
installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
into the root of the target partition. The second example installs
the same files into a ``boot`` directory within the target partition.
You can find information on how to use the Wic tool in the
":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
section of the Yocto Project Development Tasks Manual. Reference
material for Wic is located in the
":doc:`/ref-manual/kickstart`" chapter.
:term:`IMAGE_CLASSES`
A list of classes that all images should inherit. You typically use
this variable to specify the list of classes that register the
different types of images the OpenEmbedded build system creates.
The default value for :term:`IMAGE_CLASSES` is ``image_types``. You can
set this variable in your ``local.conf`` or in a distribution
configuration file.
For more information, see ``meta/classes/image_types.bbclass`` in the
:term:`Source Directory`.
:term:`IMAGE_CMD`
Specifies the command to create the image file for a specific image
type, which corresponds to the value set in
:term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
``btrfs``, and so forth). When setting this variable, you should use
an override for the associated type. Here is an example::
IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
--output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
${EXTRA_IMAGECMD}"
You typically do not need to set this variable unless you are adding
support for a new image type. For more examples on how to set this
variable, see the :ref:`image_types <ref-classes-image_types>`
class file, which is ``meta/classes/image_types.bbclass``.
:term:`IMAGE_DEVICE_TABLES`
Specifies one or more files that contain custom device tables that
are passed to the ``makedevs`` command as part of creating an image.
These files list basic device nodes that should be created under
``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
``files/device_table-minimal.txt`` is used, which is located by
:term:`BBPATH`. For details on how you should write
device table files, see ``meta/files/device_table-minimal.txt`` as an
example.
:term:`IMAGE_FEATURES`
The primary list of features to include in an image. Typically, you
configure this variable in an image recipe. Although you can use this
variable from your ``local.conf`` file, which is found in the
:term:`Build Directory`, best practices dictate that you do
not.
.. note::
To enable extra features from outside the image recipe, use the
:term:`EXTRA_IMAGE_FEATURES` variable.
For a list of image features that ships with the Yocto Project, see
the ":ref:`ref-features-image`" section.
For an example that shows how to customize your image by using this
variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
section in the Yocto Project Development Tasks Manual.
:term:`IMAGE_FSTYPES`
Specifies the formats the OpenEmbedded build system uses during the
build when creating the root filesystem. For example, setting
:term:`IMAGE_FSTYPES` as follows causes the build system to create root
filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
IMAGE_FSTYPES = "ext3 tar.bz2"
For the complete list of supported image formats from which you can
choose, see :term:`IMAGE_TYPES`.
.. note::
- If an image recipe uses the "inherit image" line and you are
setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
:term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
- Due to the way the OpenEmbedded build system processes this
variable, you cannot update its contents by using ``:append``
or ``:prepend``. You must use the ``+=`` operator to add one or
more options to the :term:`IMAGE_FSTYPES` variable.
:term:`IMAGE_INSTALL`
Used by recipes to specify the packages to install into an image
through the :ref:`image <ref-classes-image>` class. Use the
:term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
install into an image through ``image.bbclass``. Additionally,
there are "helper" classes such as the
:ref:`core-image <ref-classes-core-image>` class which can
take lists used with :term:`IMAGE_FEATURES` and turn them into
auto-generated entries in :term:`IMAGE_INSTALL` in addition to its
default contents.
When you use this variable, it is best to use it as follows::
IMAGE_INSTALL:append = " package-name"
Be sure to include the space
between the quotation character and the start of the package name or
names.
.. note::
- When working with a
:ref:`core-image-minimal-initramfs <ref-manual/images:images>`
image, do not use the :term:`IMAGE_INSTALL` variable to specify
packages for installation. Instead, use the
:term:`PACKAGE_INSTALL` variable, which
allows the initial RAM filesystem (initramfs) recipe to use a
fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
For information on creating an initramfs, see the
":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`"
section in the Yocto Project Development Tasks Manual.
- Using :term:`IMAGE_INSTALL` with the
:ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
BitBake operator within the ``/conf/local.conf`` file or from
within an image recipe is not recommended. Use of this operator
in these ways can cause ordering issues. Since
``core-image.bbclass`` sets :term:`IMAGE_INSTALL` to a default
value using the
:ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
results in unexpected behavior when used within
``conf/local.conf``. Furthermore, the same operation from
within an image recipe may or may not succeed depending on the
specific situation. In both these cases, the behavior is
contrary to how most users expect the ``+=`` operator to work.
:term:`IMAGE_LINGUAS`
Specifies the list of locales to install into the image during the
root filesystem construction process. The OpenEmbedded build system
automatically splits locale files, which are used for localization,
into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
ensures that any locale packages that correspond to packages already
selected for installation into the image are also installed. Here is
an example::
IMAGE_LINGUAS = "pt-br de-de"
In this example, the build system ensures any Brazilian Portuguese
and German locale files that correspond to packages in the image are
installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
``*-locale-pt`` and ``*-locale-de``, since some software packages
only provide locale files by language and not by country-specific
language).
See the :term:`GLIBC_GENERATE_LOCALES`
variable for information on generating GLIBC locales.
:term:`IMAGE_LINK_NAME`
The name of the output image symlink (which does not include
the version part as :term:`IMAGE_NAME` does). The default value
is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE`
variables::
IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}"
:term:`IMAGE_MANIFEST`
The manifest file for the image. This file lists all the installed
packages that make up the image. The file contains package
information on a line-per-package basis as follows::
packagename packagearch version
The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
file as follows::
IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
The location is
derived using the :term:`IMGDEPLOYDIR`
and :term:`IMAGE_NAME` variables. You can find
information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
section in the Yocto Project Overview and Concepts Manual.
:term:`IMAGE_NAME`
The name of the output image files minus the extension. This variable
is derived using the :term:`IMAGE_BASENAME`,
:term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX`
variables::
IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
:term:`IMAGE_NAME_SUFFIX`
Suffix used for the image output filename - defaults to ``".rootfs"``
to distinguish the image file from other files created during image
building; however if this suffix is redundant or not desired you can
clear the value of this variable (set the value to ""). For example,
this is typically cleared in initramfs image recipes.
:term:`IMAGE_OVERHEAD_FACTOR`
Defines a multiplier that the build system applies to the initial
image size for cases when the multiplier times the returned disk
usage value for the image is greater than the sum of
:term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
the multiplier applied to the initial image size creates free disk
space in the image as overhead. By default, the build process uses a
multiplier of 1.3 for this variable. This default value results in
30% free disk space added to the image when this method is used to
determine the final generated image size. You should be aware that
post install scripts and the package management system uses disk
space inside this overhead area. Consequently, the multiplier does
not produce an image with all the theoretical free disk space. See
:term:`IMAGE_ROOTFS_SIZE` for information on how the build system
determines the overall image size.
The default 30% free disk space typically gives the image enough room
to boot and allows for basic post installs while still leaving a
small amount of free disk space. If 30% free space is inadequate, you
can increase the default value. For example, the following setting
gives you 50% free space added to the image::
IMAGE_OVERHEAD_FACTOR = "1.5"
Alternatively, you can ensure a specific amount of free disk space is
added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
variable.
:term:`IMAGE_PKGTYPE`
Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
OpenEmbedded build system. The variable is defined appropriately by
the :ref:`package_deb <ref-classes-package_deb>`,
:ref:`package_rpm <ref-classes-package_rpm>`,
:ref:`package_ipk <ref-classes-package_ipk>`, or
:ref:`package_tar <ref-classes-package_tar>` class.
.. note::
The ``package_tar`` class is broken and is not supported. It is
recommended that you do not use it.
The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
:ref:`image <ref-classes-image>` classes use the :term:`IMAGE_PKGTYPE`
for packaging up images and SDKs.
You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
variable is set indirectly through the appropriate
:ref:`package_* <ref-classes-package>` class using the
:term:`PACKAGE_CLASSES` variable. The
OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
or IPK) that appears with the variable
.. note::
Files using the ``.tar`` format are never used as a substitute
packaging format for DEB, RPM, and IPK formatted files for your image
or SDK.
:term:`IMAGE_POSTPROCESS_COMMAND`
Specifies a list of functions to call once the OpenEmbedded build
system creates the final image output files. You can specify
functions separated by semicolons::
IMAGE_POSTPROCESS_COMMAND += "function; ... "
If you need to pass the root filesystem path to a command within the
function, you can use ``${IMAGE_ROOTFS}``, which points to the
directory that becomes the root filesystem image. See the
:term:`IMAGE_ROOTFS` variable for more
information.
:term:`IMAGE_PREPROCESS_COMMAND`
Specifies a list of functions to call before the OpenEmbedded build
system creates the final image output files. You can specify
functions separated by semicolons::
IMAGE_PREPROCESS_COMMAND += "function; ... "
If you need to pass the root filesystem path to a command within the
function, you can use ``${IMAGE_ROOTFS}``, which points to the
directory that becomes the root filesystem image. See the
:term:`IMAGE_ROOTFS` variable for more
information.
:term:`IMAGE_ROOTFS`
The location of the root filesystem while it is under construction
(i.e. during the :ref:`ref-tasks-rootfs` task). This
variable is not configurable. Do not change it.
:term:`IMAGE_ROOTFS_ALIGNMENT`
Specifies the alignment for the output image file in Kbytes. If the
size of the image is not a multiple of this value, then the size is
rounded up to the nearest multiple of the value. The default value is
"1". See :term:`IMAGE_ROOTFS_SIZE` for
additional information.
:term:`IMAGE_ROOTFS_EXTRA_SPACE`
Defines additional free disk space created in the image in Kbytes. By
default, this variable is set to "0". This free disk space is added
to the image after the build system determines the image size as
described in :term:`IMAGE_ROOTFS_SIZE`.
This variable is particularly useful when you want to ensure that a
specific amount of free disk space is available on a device after an
image is installed and running. For example, to be sure 5 Gbytes of
free disk space is available, set the variable as follows::
IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
For example, the Yocto Project Build Appliance specifically requests
40 Gbytes of extra space with the line::
IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
:term:`IMAGE_ROOTFS_SIZE`
Defines the size in Kbytes for the generated image. The OpenEmbedded
build system determines the final size for the generated image using
an algorithm that takes into account the initial disk space used for
the generated image, a requested size for the image, and requested
additional free disk space to be added to the image. Programatically,
the build system determines the final size of the generated image as
follows::
if (image-du * overhead) < rootfs-size:
internal-rootfs-size = rootfs-size + xspace
else:
internal-rootfs-size = (image-du * overhead) + xspace
where:
image-du = Returned value of the du command on the image.
overhead = IMAGE_OVERHEAD_FACTOR
rootfs-size = IMAGE_ROOTFS_SIZE
internal-rootfs-size = Initial root filesystem size before any modifications.
xspace = IMAGE_ROOTFS_EXTRA_SPACE
See the :term:`IMAGE_OVERHEAD_FACTOR`
and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
variables for related information.
:term:`IMAGE_TYPEDEP`
Specifies a dependency from one image type on another. Here is an
example from the :ref:`image-live <ref-classes-image-live>` class::
IMAGE_TYPEDEP:live = "ext3"
In the previous example, the variable ensures that when "live" is
listed with the :term:`IMAGE_FSTYPES` variable,
the OpenEmbedded build system produces an ``ext3`` image first since
one of the components of the live image is an ``ext3`` formatted
partition containing the root filesystem.
:term:`IMAGE_TYPES`
Specifies the complete list of supported image types by default:
- btrfs
- container
- cpio
- cpio.gz
- cpio.lz4
- cpio.lzma
- cpio.xz
- cramfs
- erofs
- erofs-lz4
- erofs-lz4hc
- ext2
- ext2.bz2
- ext2.gz
- ext2.lzma
- ext3
- ext3.gz
- ext4
- ext4.gz
- f2fs
- hddimg
- iso
- jffs2
- jffs2.sum
- multiubi
- squashfs
- squashfs-lz4
- squashfs-lzo
- squashfs-xz
- tar
- tar.bz2
- tar.gz
- tar.lz4
- tar.xz
- tar.zst
- ubi
- ubifs
- wic
- wic.bz2
- wic.gz
- wic.lzma
For more information about these types of images, see
``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`.
:term:`IMAGE_VERSION_SUFFIX`
Version suffix that is part of the default :term:`IMAGE_NAME` and
:term:`KERNEL_ARTIFACT_NAME` values.
Defaults to ``"-${DATETIME}"``, however you could set this to a
version string that comes from your external build environment if
desired, and this suffix would then be used consistently across
the build artifacts.
:term:`IMGDEPLOYDIR`
When inheriting the :ref:`image <ref-classes-image>` class directly or
through the :ref:`core-image <ref-classes-core-image>` class, the
:term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
that is set in the ``image`` class as follows::
IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
Recipes inheriting the ``image`` class should copy files to be
deployed into :term:`IMGDEPLOYDIR`, and the class will take care of
copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
:term:`INC_PR`
Helps define the recipe revision for recipes that share a common
``include`` file. You can think of this variable as part of the
recipe revision as set from within an include file.
Suppose, for example, you have a set of recipes that are used across
several projects. And, within each of those recipes the revision (its
:term:`PR` value) is set accordingly. In this case, when
the revision of those recipes changes, the burden is on you to find
all those recipes and be sure that they get changed to reflect the
updated version of the recipe. In this scenario, it can get
complicated when recipes that are used in many places and provide
common functionality are upgraded to a new revision.
A more efficient way of dealing with this situation is to set the
:term:`INC_PR` variable inside the ``include`` files that the recipes
share and then expand the :term:`INC_PR` variable within the recipes to
help define the recipe revision.
The following provides an example that shows how to use the
:term:`INC_PR` variable given a common ``include`` file that defines the
variable. Once the variable is defined in the ``include`` file, you
can use the variable to set the :term:`PR` values in each recipe. You
will notice that when you set a recipe's :term:`PR` you can provide more
granular revisioning by appending values to the :term:`INC_PR` variable::
recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
The
first line of the example establishes the baseline revision to be
used for all recipes that use the ``include`` file. The remaining
lines in the example are from individual recipes and show how the
:term:`PR` value is set.
:term:`INCOMPATIBLE_LICENSE`
Specifies a space-separated list of license names (as they would
appear in :term:`LICENSE`) that should be excluded
from the build. Recipes that provide no alternatives to listed
incompatible licenses are not built. Packages that are individually
licensed with the specified incompatible licenses will be deleted.
.. note::
This functionality is only regularly tested using the following
setting::
INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
Although you can use other settings, you might be required to
remove dependencies on or provide alternatives to components that
are required to produce a functional system image.
.. note::
It is possible to define a list of licenses that are allowed to be
used instead of the licenses that are excluded. To do this, define
a variable ``COMPATIBLE_LICENSES`` with the names of the licenses
that are allowed. Then define :term:`INCOMPATIBLE_LICENSE` as::
INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
This will result in :term:`INCOMPATIBLE_LICENSE` containing the names of
all licenses from :term:`AVAILABLE_LICENSES` except the ones specified
in ``COMPATIBLE_LICENSES``, thus only allowing the latter licenses to
be used.
:term:`INHERIT`
Causes the named class or classes to be inherited globally. Anonymous
functions in the class or classes are not executed for the base
configuration and in each individual recipe. The OpenEmbedded build
system ignores changes to :term:`INHERIT` in individual recipes.
For more information on :term:`INHERIT`, see the
:ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
section in the Bitbake User Manual.
:term:`INHERIT_DISTRO`
Lists classes that will be inherited at the distribution level. It is
unlikely that you want to edit this variable.
The default value of the variable is set as follows in the
``meta/conf/distro/defaultsetup.conf`` file::
INHERIT_DISTRO ?= "debian devshell sstate license"
:term:`INHIBIT_DEFAULT_DEPS`
Prevents the default dependencies, namely the C compiler and standard
C library (libc), from being added to :term:`DEPENDS`.
This variable is usually used within recipes that do not require any
compilation using the C compiler.
Set the variable to "1" to prevent the default dependencies from
being added.
:term:`INHIBIT_PACKAGE_DEBUG_SPLIT`
Prevents the OpenEmbedded build system from splitting out debug
information during packaging. By default, the build system splits out
debugging information during the
:ref:`ref-tasks-package` task. For more information on
how debug information is split out, see the
:term:`PACKAGE_DEBUG_SPLIT_STYLE`
variable.
To prevent the build system from splitting out debug information
during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
follows::
INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
:term:`INHIBIT_PACKAGE_STRIP`
If set to "1", causes the build to not strip binaries in resulting
packages and prevents the ``-dbg`` package from containing the source
files.
By default, the OpenEmbedded build system strips binaries and puts
the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
plan to debug in general.
:term:`INHIBIT_SYSROOT_STRIP`
If set to "1", causes the build to not strip binaries in the
resulting sysroot.
By default, the OpenEmbedded build system strips binaries in the
resulting sysroot. When you specifically set the
:term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
this stripping.
If you want to use this variable, include the
:ref:`staging <ref-classes-staging>` class. This class uses a
``sys_strip()`` function to test for the variable and acts
accordingly.
.. note::
Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
special circumstances. For example, suppose you are building
bare-metal firmware by using an external GCC toolchain. Furthermore,
even if the toolchain's binaries are strippable, there are other files
needed for the build that are not strippable.
:term:`INITRAMFS_FSTYPES`
Defines the format for the output image of an initial RAM filesystem
(initramfs), which is used during boot. Supported formats are the
same as those supported by the
:term:`IMAGE_FSTYPES` variable.
The default value of this variable, which is set in the
``meta/conf/bitbake.conf`` configuration file in the
:term:`Source Directory`, is "cpio.gz". The Linux kernel's
initramfs mechanism, as opposed to the initial RAM filesystem
`initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
an optionally compressed cpio archive.
:term:`INITRAMFS_IMAGE`
Specifies the :term:`PROVIDES` name of an image
recipe that is used to build an initial RAM filesystem (initramfs)
image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
additional recipe to be built as a dependency to whatever root
filesystem recipe you might be using (e.g. ``core-image-sato``). The
initramfs image recipe you provide should set
:term:`IMAGE_FSTYPES` to
:term:`INITRAMFS_FSTYPES`.
An initramfs image provides a temporary root filesystem used for
early system initialization (e.g. loading of modules needed to locate
and mount the "real" root filesystem).
.. note::
See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
recipe in the :term:`Source Directory`
for an example initramfs recipe. To select this sample recipe as
the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE`
to "core-image-minimal-initramfs".
You can also find more information by referencing the
``meta-poky/conf/local.conf.sample.extended`` configuration file in
the Source Directory, the :ref:`image <ref-classes-image>` class,
and the :ref:`kernel <ref-classes-kernel>` class to see how to use
the :term:`INITRAMFS_IMAGE` variable.
If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
initramfs image is built.
For more information, you can also see the
:term:`INITRAMFS_IMAGE_BUNDLE`
variable, which allows the generated image to be bundled inside the
kernel image. Additionally, for information on creating an initramfs
image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
in the Yocto Project Development Tasks Manual.
:term:`INITRAMFS_IMAGE_BUNDLE`
Controls whether or not the image recipe specified by
:term:`INITRAMFS_IMAGE` is run through an
extra pass
(:ref:`ref-tasks-bundle_initramfs`) during
kernel compilation in order to build a single binary that contains
both the kernel image and the initial RAM filesystem (initramfs)
image. This makes use of the
:term:`CONFIG_INITRAMFS_SOURCE` kernel
feature.
.. note::
Using an extra compilation pass to bundle the initramfs avoids a
circular dependency between the kernel recipe and the initramfs
recipe should the initramfs include kernel modules. Should that be
the case, the initramfs recipe depends on the kernel for the