2102 lines
104 KiB
XML
2102 lines
104 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
|
|
|
<!-- Dummy chapter -->
|
|
<chapter id='ref-variables-glos'>
|
|
|
|
<title>Variables Glossary</title>
|
|
|
|
<para>
|
|
This chapter lists common variables used in the OpenEmbedded build system and gives an overview
|
|
of their function and contents.
|
|
</para>
|
|
|
|
<glossary id='ref-variables-glossary'>
|
|
|
|
|
|
<para>
|
|
<link linkend='var-ALLOW_EMPTY'>A</link>
|
|
<link linkend='var-B'>B</link>
|
|
<link linkend='var-CFLAGS'>C</link>
|
|
<link linkend='var-D'>D</link>
|
|
<link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
|
|
<link linkend='var-FILES'>F</link>
|
|
<!-- <link linkend='var-glossary-g'>G</link> -->
|
|
<link linkend='var-HOMEPAGE'>H</link>
|
|
<link linkend='var-IMAGE_FEATURES'>I</link>
|
|
<!-- <link linkend='var-glossary-j'>J</link> -->
|
|
<link linkend='var-KBRANCH'>K</link>
|
|
<link linkend='var-LAYERDIR'>L</link>
|
|
<link linkend='var-MACHINE'>M</link>
|
|
<!-- <link linkend='var-glossary-n'>N</link> -->
|
|
<!-- <link linkend='var-glossary-o'>O</link> -->
|
|
<link linkend='var-PACKAGE_ARCH'>P</link>
|
|
<!-- <link linkend='var-glossary-q'>Q</link> -->
|
|
<link linkend='var-RCONFLICTS'>R</link>
|
|
<link linkend='var-S'>S</link>
|
|
<link linkend='var-TARGET_ARCH'>T</link>
|
|
<!-- <link linkend='var-glossary-u'>U</link> -->
|
|
<!-- <link linkend='var-glossary-v'>V</link> -->
|
|
<link linkend='var-WORKDIR'>W</link>
|
|
<!-- <link linkend='var-glossary-x'>X</link> -->
|
|
<!-- <link linkend='var-glossary-y'>Y</link> -->
|
|
<!-- <link linkend='var-glossary-z'>Z</link>-->
|
|
</para>
|
|
|
|
<glossdiv id='var-glossary-a'><title>A</title>
|
|
|
|
<glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies if an output package should still be produced if it is empty.
|
|
By default, BitBake does not produce empty packages.
|
|
This default behavior can cause issues when there is an
|
|
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
|
|
some other runtime hard-requirement on the existence of the package.
|
|
</para>
|
|
|
|
<para>
|
|
Like all package-controlling variables, you must always use them in
|
|
conjunction with a package name override.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
ALLOW_EMPTY_${PN} = "1"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
|
|
<glossdef>
|
|
<para>The email address used to contact the original author or authors in
|
|
order to send patches, forward bugs, etc.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
|
|
<glossdef>
|
|
<para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
|
|
is set to the value of this variable, it specifies that the latest
|
|
source revision in the repository should be used. Here is an example:
|
|
<literallayout class='monospaced'>
|
|
SRCREV = "${AUTOREV}"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-b'><title>B</title>
|
|
|
|
<glossentry id='var-B'><glossterm>B</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The 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 <link linkend='var-S'><filename>S</filename></link>
|
|
directory:
|
|
<literallayout class='monospaced'>
|
|
B = ${WORKDIR}/${BPN}-{PV}/
|
|
</literallayout>
|
|
You can separate the source directory (<filename>S</filename>) and the directory pointed to
|
|
by the <filename>B</filename> variable.
|
|
Most autotools-based recipes support separating these directories.
|
|
The build system defaults to using separate directories for <filename>gcc</filename>
|
|
and some kernel recipes.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of packages not to install despite being recommended by a recipe.
|
|
Support for this variable exists only for images that use the
|
|
<filename>ipkg</filename> packaging system.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Allows you to extend a recipe so that it builds variants of the software.
|
|
Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
|
|
which is a copy of quilt built to run on the build system;
|
|
"crosses" such as <filename>gcc-cross</filename>,
|
|
which is a compiler built to run on the build machine but produces binaries
|
|
that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
|
|
"nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
|
|
and "mulitlibs" in the form "<filename>multilib:<multilib_name></filename>".
|
|
</para>
|
|
|
|
<para>
|
|
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:
|
|
<literallayout class='monospaced'>
|
|
BBCLASSEXTEND =+ "native nativesdk"
|
|
BBCLASSEXTEND =+ "multilib:<multilib_name>"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
|
|
<glossdef>
|
|
<para>Prevents BitBake from processing recipes and recipe append files.
|
|
You can use the <filename>BBMASK</filename> variable to "hide"
|
|
these <filename>.bb</filename> and <filename>.bbappend</filename> files.
|
|
BitBake ignores any recipe or recipe append files that match the expression.
|
|
It is as if BitBake does not see them at all.
|
|
Consequently, matching files are not parsed or otherwise used by
|
|
BitBake.</para>
|
|
<para>The value you provide is passed to python's regular expression compiler.
|
|
For complete syntax information, see python's documentation at
|
|
<ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
|
|
The expression is compared against the full paths to the files.
|
|
For example, the following uses a complete regular expression to tell
|
|
BitBake to ignore all recipe and recipe append files in the
|
|
<filename>.*/meta-ti/recipes-misc/</filename> directory:
|
|
<literallayout class='monospaced'>
|
|
BBMASK = ".*/meta-ti/recipes-misc/"
|
|
</literallayout></para>
|
|
<para>Use the <filename>BBMASK</filename> variable from within the
|
|
<filename>conf/local.conf</filename> file found
|
|
in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
|
|
<glossdef>
|
|
<para>The maximum number of tasks BitBake should run in parallel at any one time.
|
|
If your host development system supports multiple cores a good rule of thumb
|
|
is to set this variable to twice the number of cores.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
|
|
<glossdef>
|
|
<para>Lists the names of configured layers.
|
|
These names are used to find the other <filename>BBFILE_*</filename>
|
|
variables.
|
|
Typically, each layer will append its name to this variable in its
|
|
<filename>conf/layer.conf</filename> file.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
|
|
<glossdef>
|
|
<para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer.
|
|
This variable is used in the <filename>conf/layer.conf</filename> file and must
|
|
be suffixed with the name of the specific layer (e.g.
|
|
<filename>BBFILE_PATTERN_emenlow</filename>).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
|
|
<glossdef>
|
|
<para>Assigns the priority for recipe files in each layer.</para>
|
|
<para>This variable is useful in situations where the same package appears in
|
|
more than one layer.
|
|
Setting this variable allows you to prioritize a
|
|
layer against other layers that contain the same package - effectively
|
|
letting you control the precedence for the multiple layers.
|
|
The precedence established through this variable stands regardless of a
|
|
layer's package version (<filename>PV</filename> variable).
|
|
For example, a layer that has a package with a higher <filename>PV</filename> value but for
|
|
which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
|
|
lower precedence.</para>
|
|
<para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
|
|
precedence.
|
|
For example, the value 6 has a higher precedence than the value 5.
|
|
If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
|
|
dependencies (see the
|
|
<filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> 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).</para>
|
|
<tip>
|
|
You can use the command <filename>bitbake-layers show_layers</filename> to list
|
|
all configured layers along with their priorities.
|
|
</tip>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
|
|
<glossdef>
|
|
<para>List of recipe files used by BitBake to build software</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
|
|
<glossdef>
|
|
<para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files.
|
|
This variable is analogous to the <filename>PATH</filename> variable.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
|
|
<glossdef>
|
|
<para>Variable that controls how BitBake displays logs on build failure.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
|
|
<glossdef>
|
|
<para>Lists the layers to enable during the build.
|
|
This variable is defined in the <filename>bblayers.conf</filename> configuration
|
|
file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
BBLAYERS = " \
|
|
/home/scottrif/poky/meta \
|
|
/home/scottrif/poky/meta-yocto \
|
|
/home/scottrif/poky/meta-mykernel \
|
|
"
|
|
</literallayout>
|
|
This example enables three layers, one of which is a custom, user-defined layer
|
|
named <filename>meta-mykernel</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-BPN'><glossterm>BPN</glossterm>
|
|
<glossdef>
|
|
<para>Bare name of package with any suffixes like -cross -native removed.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-c'><title>C</title>
|
|
|
|
<glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Flags passed to C compiler for the target system.
|
|
This variable evaluates to the same as
|
|
<filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
|
|
<glossdef>
|
|
<para>A regular expression which evaluates to match the machines the recipe
|
|
works with.
|
|
It stops recipes being run on machines for which they are not compatible.
|
|
This is particularly useful with kernels.
|
|
It also helps to increase parsing speed as further parsing of the recipe is skipped
|
|
if it is found the current machine is not compatible.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
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 <filename>CONFFILES</filename> variable to list the files in the
|
|
package that you wish to prevent the PMS from overwriting during this update process.
|
|
</para>
|
|
|
|
<para>
|
|
To use the <filename>CONFFILES</filename> variable, provide a package name
|
|
override that identifies the package.
|
|
Then, provide a space-separated list of files.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
CONFFILES_${PN} += "${sysconfdir}/file1 \
|
|
${sysconfdir}/file2 ${sysconfdir}/file3"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
A relationship exists between the <filename>CONFFILES</filename> and
|
|
<filename><link linkend='var-FILES'>FILES</link></filename> variables.
|
|
The files listed within <filename>CONFFILES</filename> must be a subset of
|
|
the files listed within <filename>FILES</filename>.
|
|
Because the configuration files you provide with <filename>CONFFILES</filename>
|
|
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
|
|
<filename>FILES</filename> variable.
|
|
</para>
|
|
|
|
<note>
|
|
When specifying paths as part of the <filename>CONFFILES</filename> variable,
|
|
it is good practice to use appropriate path variables.
|
|
For example, <filename>${sysconfdir}</filename> rather than
|
|
<filename>/etc</filename> or <filename>${bindir}</filename> rather
|
|
than <filename>/usr/bin</filename>.
|
|
You can find a list of these variables at the top of the
|
|
<filename>/meta/conf/bitbake.conf</filename> file in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
|
|
</note>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of files that contains <filename>autoconf</filename> test results relevant
|
|
to the current build.
|
|
This variable is used by the Autotools utilities when running
|
|
<filename>configure</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies the list of packages to be added to the image.
|
|
This variable should only be set in the <filename>local.conf</filename>
|
|
configuration file found in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-d'><title>D</title>
|
|
|
|
<glossentry id='var-D'><glossterm>D</glossterm>
|
|
<glossdef>
|
|
<para>The destination directory.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies to build packages with debugging information.
|
|
This influences the value of the
|
|
<filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
|
|
variable.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The options to pass in
|
|
<filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
|
|
and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
|
|
a system for debugging.
|
|
This variable defaults to "-O -fno-omit-frame-pointer -g".
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the priority of recipes.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of build-time dependencies for a given recipe.
|
|
The variable indicates recipes that must have been staged before a
|
|
particular recipe can configure.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
|
|
<glossdef>
|
|
<para>The package description used by package managers.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
|
|
<glossdef>
|
|
<para>the destination directory.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
|
|
<glossdef>
|
|
<para>The short name of the distribution.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>The list of packages which extend usability of the image.
|
|
Those packages will automatically be installed but can be removed by user.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
|
|
<glossdef>
|
|
<para>The features of the distribution.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
|
|
<glossdef>
|
|
<para>The long name of the distribution.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
|
|
<glossdef>
|
|
<para>Alias names used for the recipe in various Linux distributions.</para>
|
|
<para>See the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
|
|
a Package Name Alias</ulink>" section in the Yocto Project Development
|
|
Manual for more information.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
|
|
<glossdef>
|
|
<para>the version of the distribution.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The central download directory used by the build process to store downloads.
|
|
You can set this directory by defining the <filename>DL_DIR</filename>
|
|
variable in the <filename>/conf/local.conf</filename> file.
|
|
This directory is self-maintaining and you should not have
|
|
to touch it.
|
|
By default, the directory is <filename>downloads</filename> in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
|
|
<literallayout class='monospaced'>
|
|
#DL_DIR ?= "${TOPDIR}/downloads"
|
|
</literallayout>
|
|
To specify a different download directory, simply uncomment the line
|
|
and provide your directory.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
<filename>DL_DIR</filename> 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.
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
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 the
|
|
"<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
|
|
chapter.
|
|
</para>
|
|
</glossdef>
|
|
|
|
</glossentry>
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-e'><title>E</title>
|
|
|
|
<glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>Variable that controls which locales for <filename>eglibc</filename> are
|
|
to be generated during the build (useful if the target device has 64Mbytes
|
|
of RAM or less).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
|
|
<glossdef>
|
|
<para>Allows extra packages to be added to the generated images.
|
|
You set this variable in the <filename>local.conf</filename>
|
|
configuration file.
|
|
Note that some image features are also added using the
|
|
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
|
|
variable generally configured in image recipes.
|
|
You can use this variable to add more features in addition to those.
|
|
Here are some examples of features you can add:</para>
|
|
<literallayout class='monospaced'>
|
|
"dbg-pkgs" - Adds -dbg packages for all installed packages
|
|
including symbol information for debugging and
|
|
profiling.
|
|
|
|
"dev-pkgs" - Adds -dev packages for all installed packages.
|
|
This is useful if you want to develop against
|
|
the libraries in the image.
|
|
|
|
"tools-sdk" - Adds development tools such as gcc, make,
|
|
pkgconfig and so forth.
|
|
|
|
"tools-debug" - Adds debugging tools such as gdb and
|
|
strace.
|
|
|
|
"tools-profile" - Adds profiling tools such as oprofile,
|
|
exmap, lttng and valgrind (x86 only).
|
|
|
|
"tools-testapps" - Adds useful testing tools such as
|
|
ts_print, aplay, arecord and so
|
|
forth.
|
|
|
|
"debug-tweaks" - Makes an image suitable for development.
|
|
For example, ssh root access has a blank
|
|
password. You should remove this feature
|
|
before you produce a production image.
|
|
</literallayout>
|
|
|
|
<para>There are other valid features too, see the
|
|
<link linkend='ref-features-image'>Images</link>
|
|
section for more details.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
|
|
<glossdef>
|
|
<para>A list of recipes to be built that do not provide packages to be installed in
|
|
the root filesystem.
|
|
</para>
|
|
<para>Sometimes a recipe is required to build the final image but is not
|
|
needed in the root filesystem.
|
|
You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
|
|
list these recipes and thus, specify the dependencies.
|
|
A typical example is a required bootloader in a machine configuration.
|
|
</para>
|
|
<note>
|
|
To add packages to the root filesystem, see the various
|
|
<filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename>
|
|
variables.
|
|
</note>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
|
|
<glossdef>
|
|
<para>Additional <filename>cmake</filename> options.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
|
|
<glossdef>
|
|
<para>Additional <filename>configure</filename> script options.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
|
|
<glossdef>
|
|
<para>Additional GNU <filename>make</filename> options.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-f'><title>F</title>
|
|
|
|
<glossentry id='var-FILES'><glossterm>FILES</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The list of directories or files that are placed in packages.
|
|
</para>
|
|
|
|
<para>
|
|
To use the <filename>FILES</filename> variable, provide a package name
|
|
override that identifies the package.
|
|
Then, provide a space-separated list of files or paths that identifies the
|
|
files you want included as part of the package.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<note>
|
|
When specifying paths as part of the <filename>FILES</filename> variable,
|
|
it is good practice to use appropriate path variables.
|
|
For example, <filename>${sysconfdir}</filename> rather than
|
|
<filename>/etc</filename> or <filename>${bindir}</filename> rather
|
|
than <filename>/usr/bin</filename>.
|
|
You can find a list of these variables at the top of the
|
|
<filename>/meta/conf/bitbake.conf</filename> file in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
|
|
</note>
|
|
|
|
<para>
|
|
If some of the files you provide with the <filename>FILES</filename> 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 <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
|
|
variable for information on how to identify these files to the PMS.
|
|
</para>
|
|
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Extends the search path the OpenEmbedded build system uses when
|
|
looking for files and patches as it processes recipes.
|
|
The directories BitBake uses when it processes recipes is defined by the
|
|
<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
|
|
You can add directories to the search path by defining the
|
|
<filename>FILESEXTRAPATHS</filename> variable.
|
|
</para>
|
|
|
|
<para>
|
|
To add paths to the search order, provide a list of directories and separate
|
|
each path using a colon character as follows:
|
|
<literallayout class='monospaced'>
|
|
FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
|
|
</literallayout>
|
|
Typically, you want your directories search first.
|
|
To make sure that happens, use <filename>_prepend</filename> and
|
|
the immediate expansion (<filename>:=</filename>) operator as shown in the
|
|
previous example.
|
|
Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable,
|
|
you must include the appropriate beginning or ending (as needed) colon character.
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>FILESEXTRAPATHS</filename> variable is intended for use in
|
|
<filename>.bbappend</filename> files to include any additional files provided in that layer.
|
|
You typically accomplish this with the following:
|
|
<literallayout class='monospaced'>
|
|
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
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
|
|
<filename>FILESPATH</filename> in the specified order when looking for
|
|
files and patches specified by each <filename>file://</filename> URI in a recipe.
|
|
</para>
|
|
|
|
<para>
|
|
The default value for the <filename>FILESPATH</filename> variable is defined
|
|
in the <filename>base.bbclass</filename> class found in
|
|
<filename>meta/classes</filename> in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>:
|
|
<literallayout class='monospaced'>
|
|
FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
|
|
"${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
|
|
"${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
|
|
"${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
|
|
</literallayout>
|
|
Do not hand-edit the <filename>FILESPATH</filename> variable.
|
|
If you want to extend the set of pathnames that BitBake uses when searching for
|
|
files and patches, use the
|
|
<link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
|
|
<glossdef>
|
|
<para>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.
|
|
</para>
|
|
<para>
|
|
By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
|
|
is located in the <filename>meta/files</filename> folder in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
|
|
If you create your own file permissions setting table, you should place it in your
|
|
layer or the distros layer.
|
|
</para>
|
|
<para>
|
|
You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
|
|
<filename>conf/local.conf</filename> file, which is found in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>, to
|
|
point to your custom <filename>fs-perms.txt</filename>.
|
|
You can specify more than a single file permissions setting table.
|
|
The paths you specify to these files must be defined within the
|
|
<filename>BBPATH</filename> variable.
|
|
</para>
|
|
<para>
|
|
For guidance on how to create your own file permissions settings table file,
|
|
examine the existing <filename>fs-perms.txt</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The options to pass in
|
|
<filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
|
|
and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
|
|
when compiling an optimized system.
|
|
This variable defaults to
|
|
"-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<glossdiv id='var-glossary-h'><title>H</title>
|
|
|
|
<glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
|
|
<glossdef>
|
|
<para>Website where more info about package can be found</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-i'><title>I</title>
|
|
|
|
<glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
|
|
<glossdef>
|
|
<para>The list of features present in images.
|
|
Typically, you configure this variable in image recipes.
|
|
Note that you can add extra features to the image by using the
|
|
<filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
|
|
See the "<link linkend="ref-features-image">Images</link>" section for the
|
|
list of features present in images built by the OpenEmbedded build system.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
|
|
<glossdef>
|
|
<para>Formats of root filesystem images that you want to have created.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies the packages to install into an image.
|
|
The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
|
|
recipe and you should use it with care to avoid ordering issues.
|
|
</para>
|
|
|
|
<para>
|
|
Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
|
|
packages to install into an image through <filename>image.bbclass</filename>.
|
|
Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
|
|
that can take
|
|
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
|
|
and turn these into auto-generated entries in
|
|
<filename>IMAGE_INSTALL</filename> in addition to its default contents.
|
|
</para>
|
|
|
|
<para>
|
|
Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
|
|
operator from the <filename>/conf/local.conf</filename> file or from within
|
|
an image recipe is not recommended as it can cause ordering issues.
|
|
Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
|
|
to a default value using the <filename>?=</filename> operator, using a
|
|
<filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
|
|
will result in unexpected behavior when used in
|
|
<filename>/conf/local.conf</filename>.
|
|
Furthermore, the same operation from with 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 <filename>+=</filename> operator to work.
|
|
</para>
|
|
|
|
<para>
|
|
When you use this variable, it is best to use it as follows:
|
|
<literallayout class='monospaced'>
|
|
IMAGE_INSTALL_append = " package-name"
|
|
</literallayout>
|
|
Be sure to include the space between the quotation character and the start of the
|
|
package name.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
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
|
|
<filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
|
|
and
|
|
<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
|
|
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 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
|
|
for information on how the build system determines the overall image size.
|
|
</para>
|
|
|
|
<para>
|
|
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:
|
|
<literallayout class='monospaced'>
|
|
IMAGE_OVERHEAD_FACTOR = "1.5"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, you can ensure a specific amount of free disk space is added
|
|
to the image by using
|
|
<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
|
|
the variable.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
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
|
|
<filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
|
|
</para>
|
|
|
|
<para>
|
|
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:
|
|
<literallayout class='monospaced'>
|
|
IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
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:
|
|
<literallayout class='monospaced'>
|
|
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
|
|
</literallayout>
|
|
<!-- In the above example, <filename>overhead</filename> is defined by the
|
|
<filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
|
|
variable, <filename>xspace</filename> is defined by the
|
|
<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
|
|
variable, and <filename>du</filename> is the results of the disk usage command
|
|
on the initially generated image. -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
|
|
<glossdef>
|
|
<para>Defines the Package revision.
|
|
You manually combine values for <filename>INC_PR</filename> into the
|
|
<link linkend='var-PR'><filename>PR</filename></link> field of the parent recipe.
|
|
When you change this variable, you change the <filename>PR</filename>
|
|
value for every person that includes the file.</para>
|
|
<para>
|
|
The following example shows how to use the <filename>INC_PR</filename> variable
|
|
given a common <filename>.inc</filename> file that defines the variable.
|
|
Once defined, you can use the variable to set the
|
|
<filename>PR</filename> value:
|
|
</para>
|
|
<literallayout class='monospaced'>
|
|
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"
|
|
recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
|
|
</literallayout>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Causes the build to not strip binaries in resulting packages.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
|
|
<glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Causes the named class to be inherited at
|
|
this point during parsing.
|
|
The variable is only valid in configuration files.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
|
|
<glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of the packages that contain initscripts.
|
|
If multiple packages are specified, you need to append the package name
|
|
to the other <filename>INITSCRIPT_*</filename> as an override.</para>
|
|
<para>
|
|
This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
|
|
The variable is optional and defaults to the <filename>PN</filename> variable.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The filename of the initscript (as installed to <filename>${etcdir}/init.d)</filename>.
|
|
</para>
|
|
<para>
|
|
This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
|
|
The variable is Mandatory.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies the options to pass to <filename>update-rc.d</filename>.
|
|
An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a
|
|
runlevel of 99, starts the script in initlevels 2 and 5, and
|
|
stops the script in levels 0, 1 and 6.
|
|
</para>
|
|
<para>
|
|
The variable is mandatory and is used in recipes when using
|
|
<filename>update-rc.d.bbclass</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<glossdiv id='var-glossary-k'><title>K</title>
|
|
|
|
<glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A regular expression used by the build process to explicitly identify the kernel
|
|
branch that is validated, patched and configured during a build.
|
|
The <filename>KBRANCH</filename> variable is optional.
|
|
You can use it to trigger checks to ensure the exact kernel branch you want is
|
|
being used by the build process.
|
|
</para>
|
|
|
|
<para>
|
|
Values for this variable are set in the kernel's recipe file and the kernel's
|
|
append file.
|
|
For example, if you are using the Yocto Project kernel that is based on the
|
|
Linux 3.2 kernel, the kernel recipe file is the
|
|
<filename>meta/recipes-kernel/linux/linux-yocto_3.2.bb</filename> file.
|
|
Following is the default value for <filename>KBRANCH</filename> and the five overrides
|
|
for the architectures the Yocto Project supports:
|
|
<literallayout class='monospaced'>
|
|
KBRANCH = "standard/default/base"
|
|
KBRANCH_qemux86 = "standard/default/common-pc/base"
|
|
KBRANCH_qemux86-64 = "standard/default/common-pc-64/base"
|
|
KBRANCH_qemuppc = "standard/default/qemu-ppc32"
|
|
KBRANCH_qemumips = "standard/default/mti-malta32-be"
|
|
KBRANCH_qemuarm = "standard/default/arm-versatile-926ejs"
|
|
</literallayout>
|
|
Each of the above branches exist in the <filename>linux-yocto-3.2</filename> kernel Git
|
|
repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.2/refs/heads'></ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
This variable is also used from the kernel's append file to identify the kernel
|
|
branch specific to a particular machine or target hardware.
|
|
The kernel's append file is located in the BSP layer for a given machine.
|
|
For example, the kernel append file for the Crown Bay BSP is in the
|
|
<filename>meta-intel</filename> Git repository and is named
|
|
<filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend</filename>.
|
|
Here are the related statements from the append file:
|
|
<literallayout class='monospaced'>
|
|
COMPATIBLE_MACHINE_crownbay = "crownbay"
|
|
KMACHINE_crownbay = "crownbay"
|
|
KBRANCH_crownbay = "standard/default/crownbay"
|
|
|
|
COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
|
|
KMACHINE_crownbay-noemgd = "crownbay"
|
|
KBRANCH_crownbay-noemgd = "standard/default/crownbay"
|
|
</literallayout>
|
|
The <filename>KBRANCH_*</filename> statements identify the kernel branch to
|
|
use when building for the Crown Bay BSP.
|
|
In this case there are two identical statements: one for each type of
|
|
Crown Bay machine.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
|
|
<glossdef>
|
|
<para>Includes additional metadata from the Yocto Project kernel Git repository.
|
|
In the OpenEmbedded build system, the default Board Support Packages (BSPs)
|
|
metadata is provided through
|
|
the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables.
|
|
You can use the <filename>KERNEL_FEATURES</filename> variable to further
|
|
add metadata for all BSPs.</para>
|
|
<para>The metadata you add through this variable includes config fragments and
|
|
features descriptions,
|
|
which usually includes patches as well as config fragments.
|
|
You typically override the <filename>KERNEL_FEATURES</filename> variable
|
|
for a specific machine.
|
|
In this way, you can provide validated, but optional, sets of kernel
|
|
configurations and features.</para>
|
|
<para>For example, the following adds <filename>netfilter</filename> to all
|
|
the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
|
|
machine:
|
|
<literallayout class='monospaced'>
|
|
# Add netfilter to all linux-yocto kernels
|
|
KERNEL_FEATURES="features/netfilter"
|
|
|
|
# Add sound support to the qemux86 machine
|
|
KERNEL_FEATURES_append_qemux86="cfg/sound"
|
|
</literallayout></para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
|
|
<glossdef>
|
|
<para>The type of kernel to build for a device, usually set by the
|
|
machine configuration files and defaults to "zImage".
|
|
This variable is used
|
|
when building the kernel and is passed to <filename>make</filename> as the target to
|
|
build.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The machine as known by the kernel.
|
|
Sometimes the machine name used by the kernel does not match the machine name
|
|
used by the OpenEmbedded build system.
|
|
For example, the machine name that the OpenEmbedded build system understands as
|
|
<filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
|
|
The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
|
|
For cases like these, the <filename>KMACHINE</filename> variable maps the
|
|
kernel machine name to the OpenEmbedded build system machine name.
|
|
</para>
|
|
|
|
<para>
|
|
Kernel machine names are initially defined in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink> in
|
|
the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file.
|
|
For example, in the <filename>linux-yocto-3.4</filename> kernel in the
|
|
<filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file,
|
|
has the following:
|
|
<literallayout class='monospaced'>
|
|
define KMACHINE cedartrail
|
|
define KTYPE standard
|
|
define KARCH i386
|
|
|
|
include ktypes/standard
|
|
branch cedartrail
|
|
|
|
include cedartrail.scc
|
|
</literallayout>
|
|
You can see that the kernel understands the machine name for the Cedar Trail BSP as
|
|
<filename>cedartrail</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source
|
|
repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
|
|
you will find the following statements among others:
|
|
<literallayout class='monospaced'>
|
|
COMPATIBLE_MACHINE_cedartrail = "cedartrail"
|
|
KMACHINE_cedartrail = "cedartrail"
|
|
KBRANCH_cedartrail = "yocto/standard/cedartrail"
|
|
KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
|
|
KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
|
|
|
|
COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
|
|
KMACHINE_cedartrail-nopvr = "cedartrail"
|
|
KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
|
|
KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
|
|
</literallayout>
|
|
The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
|
|
the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
|
|
names.
|
|
</para>
|
|
|
|
<para>
|
|
This append file uses two <filename>KMACHINE</filename> statements.
|
|
The first is not really necessary but does ensure that the machine known to the
|
|
OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
|
|
in the kernel also known as <filename>cedartrail</filename>:
|
|
<literallayout class='monospaced'>
|
|
KMACHINE_cedartrail = "cedartrail"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
The second statement is a good example of why the <filename>KMACHINE</filename> variable
|
|
is needed.
|
|
In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
|
|
machine name to refer to the Cedar Trail BSP that does not support the propriatory
|
|
PowerVR driver.
|
|
The kernel, however, uses the machine name <filename>cedartrail</filename>.
|
|
Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
|
|
the kernel's <filename>cedartrail</filename> name:
|
|
<literallayout class='monospaced'>
|
|
KMACHINE_cedartrail-nopvr = "cedartrail"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
BSPs that ship with the Yocto Project release provide all mappings between the Yocto
|
|
Project kernel machine names and the OpenEmbedded machine names.
|
|
Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
|
|
name you use is different than that used in the kernel.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-l'><title>L</title>
|
|
|
|
<glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
|
|
<glossdef>
|
|
<para>Lists the layers that this recipe depends upon, separated by spaces.
|
|
Optionally, you can specify a specific layer version for a dependency
|
|
by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
|
|
to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case).
|
|
An error will be produced if any dependency is missing or
|
|
the version numbers do not match exactly (if specified).
|
|
This variable is used in the <filename>conf/layer.conf</filename> file
|
|
and must be suffixed with the name of the specific layer (e.g.
|
|
<filename>LAYERDEPENDS_mylayer</filename>).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
|
|
<glossdef>
|
|
<para>When used inside the <filename>layer.conf</filename> configuration
|
|
file, this variable provides the path of the current layer.
|
|
This variable requires immediate expansion
|
|
(see the BitBake manual) as lazy expansion can result in
|
|
the expansion happening in the wrong directory and therefore
|
|
giving the wrong value.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
|
|
<glossdef>
|
|
<para>Optionally specifies the version of a layer as a single number.
|
|
You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to
|
|
depend on a specific version of the layer.
|
|
This variable is used in the <filename>conf/layer.conf</filename> file
|
|
and must be suffixed with the name of the specific layer (e.g.
|
|
<filename>LAYERVERSION_mylayer</filename>).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
|
|
<glossdef>
|
|
<para>Checksums of the license text in the recipe source code.</para>
|
|
<para>This variable tracks changes in license text of the source
|
|
code files.
|
|
If the license text is changed, it will trigger a build
|
|
failure, which gives the developer an opportunity to review any
|
|
license change.</para>
|
|
<para>
|
|
This variable must be defined for all recipes (unless <filename>LICENSE</filename>
|
|
is set to "CLOSED")</para>
|
|
<para>For more information, see the
|
|
<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
|
|
Tracking License Changes</link> section</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
|
|
<glossdef>
|
|
<para>The list of package source licenses.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-LICENSE_DIR'><glossterm>LICENSE_DIR</glossterm>
|
|
<glossdef>
|
|
<para>Path to additional licenses used during the build.
|
|
By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
|
|
to define the directory that holds common license text used during the build.
|
|
The <filename>LICENSE_DIR</filename> variable allows you to extend that
|
|
location to other areas that have additional licenses:
|
|
<literallayout class='monospaced'>
|
|
LICENSE_DIR += "/path/to/additional/common/licenses"
|
|
</literallayout></para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-m'><title>M</title>
|
|
|
|
<glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the target device.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>
|
|
A list of required packages to install as part of the package being
|
|
built.
|
|
The build process depends on these packages being present.
|
|
Furthermore, because this is a "machine essential" variable, the list of
|
|
packages are essential for the machine to boot.
|
|
The impact of this variable affects images based on <filename>packagegroup-core-boot</filename>,
|
|
including the <filename>core-image-minimal</filename> image.
|
|
</para>
|
|
<para>
|
|
This variable is similar to the
|
|
<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
|
|
variable with the exception that the package being built has a build
|
|
dependency on the variable's list of packages.
|
|
In other words, the image will not build if a file in this list is not found.
|
|
</para>
|
|
<para>
|
|
For example, suppose you are building a runtime package that depends
|
|
on a certain disk driver.
|
|
In this case, you would use the following:
|
|
<literallayout class='monospaced'>
|
|
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>
|
|
A list of recommended packages to install as part of the package being
|
|
built.
|
|
The build process does not depend on these packages being present.
|
|
Furthermore, because this is a "machine essential" variable, the list of
|
|
packages are essential for the machine to boot.
|
|
The impact of this variable affects images based on <filename>packagegroup-core-boot</filename>,
|
|
including the <filename>core-image-minimal</filename> image.
|
|
</para>
|
|
<para>
|
|
This variable is similar to the
|
|
<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
|
|
variable with the exception that the package being built does not have a build
|
|
dependency on the variable's list of packages.
|
|
In other words, the image will build if a file in this list is not found.
|
|
However, because this is one of the "essential" variables, the resulting image
|
|
might not boot on the machine.
|
|
Or, if the machine does boot using the image, the machine might not be fully
|
|
functional.
|
|
</para>
|
|
<para>
|
|
Consider an example where you have a custom kernel with a disk driver
|
|
built into the kernel itself, rather than using the driver built as a module.
|
|
If you include the package that has the driver module as part of
|
|
the variable's list, the
|
|
build process will not find that package.
|
|
However, because these packages are "recommends" packages, the build will
|
|
not fail due to the missing package.
|
|
Not accounting for any other problems, the custom kernel would still boot the machine.
|
|
</para>
|
|
<para>
|
|
Some example packages of these machine essentials are flash, screen, keyboard, mouse,
|
|
or touchscreen drivers (depending on the machine).
|
|
</para>
|
|
<para>
|
|
For example, suppose you are building a runtime package that depends
|
|
on a mouse driver.
|
|
In this case, you would use the following:
|
|
<literallayout class='monospaced'>
|
|
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of optional but non-machine essential packages to install as
|
|
part of the package being built.
|
|
Even though these packages are not essential for the machine to boot,
|
|
the build process depends on them being present.
|
|
The impact of this variable affects all images based on
|
|
<filename>packagegroup-base</filename>, which does not include the
|
|
<filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
|
|
images.
|
|
</para>
|
|
<para>
|
|
This variable is similar to the
|
|
<filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
|
|
variable with the exception that the package being built has a build
|
|
dependency on the variable's list of packages.
|
|
In other words, the image will not build if a file in this list is not found.
|
|
</para>
|
|
<para>
|
|
An example is a machine that might or might not have a WiFi card.
|
|
The package containing the WiFi support is not essential for the
|
|
machine to boot the image.
|
|
If it is not there, the machine will boot but not be able to use the
|
|
WiFi functionality.
|
|
However, if you include the package with the WiFi support as part of the
|
|
variable's package list, the build
|
|
process depends on finding the package.
|
|
In this case, you would use the following:
|
|
<literallayout class='monospaced'>
|
|
MACHINE_EXTRA_RDEPENDS += "<wifi_driver>"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>
|
|
A list of optional but non-machine essential packages to install as
|
|
part of the package being built.
|
|
The package being built has no build dependency on the list of packages
|
|
with this variable.
|
|
The impact of this variable affects only images based on
|
|
<filename>packagegroup-base</filename>, which does not include the
|
|
<filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
|
|
images.
|
|
</para>
|
|
<para>
|
|
This variable is similar to the
|
|
<filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
|
|
variable with the exception that the package being built does not have a build
|
|
dependency on the variable's list of packages.
|
|
In other words, the image will build if a file in this list is not found.
|
|
</para>
|
|
<para>
|
|
An example is a machine that might or might not have a WiFi card.
|
|
The package containing the WiFi support is not essential for the
|
|
machine to boot the image.
|
|
If it is not there, the machine will boot but not be able to use the
|
|
WiFi functionality.
|
|
You are free to either include or not include the
|
|
the package with the WiFi support as part of the
|
|
variable's package list, the build
|
|
process does not depend on finding the package.
|
|
If you include the package, you would use the following:
|
|
<literallayout class='monospaced'>
|
|
MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the list of device features.
|
|
See the <link linkend='ref-features-machine'>Machine</link> section for
|
|
more information.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
|
|
<glossdef>
|
|
<para>The email address of the distribution maintainer.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<!-- <glossdiv id='var-glossary-o'><title>O</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<glossdiv id='var-glossary-p'><title>P</title>
|
|
|
|
<glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
|
|
<glossdef>
|
|
<para>The architecture of the resulting package or packages.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
|
|
<glossdef>
|
|
<para>Enables easily adding packages to
|
|
<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
|
|
before <filename>${PN}</filename> so that the packages can pick
|
|
up files that would normally be included in the default package.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
|
|
<glossdef>
|
|
<para>This variable, which is set in the <filename>local.conf</filename> configuration
|
|
file found in the <filename>conf</filename> folder of the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>,
|
|
specifies the package manager to use when packaging data.
|
|
You can provide one or more arguments for the variable with the first
|
|
argument being the package manager used to create images:
|
|
<literallayout class='monospaced'>
|
|
PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
|
|
</literallayout>
|
|
For information on build performance effects as a result of the
|
|
package manager use, see
|
|
<link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
|
|
in this manual.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the list of architectures compatible with the device CPU.
|
|
This variable is useful when you build for several different devices that use
|
|
miscellaneous processors such as XScale and ARM926-EJS).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
|
|
<glossdef>
|
|
<para>The list of packages to be created from the recipe.
|
|
The default value is the following:
|
|
<literallayout class='monospaced'>
|
|
${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
|
|
</literallayout></para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
|
|
<glossdef>
|
|
<para>Specifies extra options that are passed to the <filename>make</filename> command during the
|
|
compile tasks.
|
|
This variable is usually in the form <filename>-j 4</filename>, where the number
|
|
represents the maximum number of parallel threads make can run.
|
|
If you development host supports multiple cores a good rule of thumb is to set
|
|
this variable to twice the number of cores on the host.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PN'><glossterm>PN</glossterm>
|
|
<glossdef>
|
|
<para>The name of the recipe. The name is normally extracted from the recipe file name.
|
|
For example, if the recipe is named
|
|
<filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
|
|
will be "expat".
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PR'><glossterm>PR</glossterm>
|
|
<glossdef>
|
|
<para>The revision of the recipe.
|
|
The default value for this variable is "r0".
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PV'><glossterm>PV</glossterm>
|
|
<glossdef>
|
|
<para>The version of the recipe.
|
|
The version is normally extracted from the recipe filename.
|
|
For example, if the recipe is named
|
|
<filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
|
|
will be "2.0.1".
|
|
<filename>PV</filename> is generally not overridden within
|
|
a recipe unless it is building an unstable (i.e. development) version from a source code repository
|
|
(e.g. Git or Subversion).
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PE'><glossterm>PE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
the epoch of the recipe.
|
|
The default value is "0".
|
|
The field is used to make upgrades possible when the versioning scheme changes in
|
|
some backwards incompatible way.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
If multiple recipes provide an item, this variable
|
|
determines which recipe should be given preference.
|
|
The variable must always be suffixed with the name of the
|
|
provided item, and should be set to the
|
|
<filename>PN</filename> of the recipe
|
|
to which you want to give precedence.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
If there are multiple versions of recipes available, this
|
|
variable determines which recipe should be given preference.
|
|
The variable must always be suffixed with the <filename>PN</filename>
|
|
for which to select, and should be set to the
|
|
<filename>PV</filename> to which you want to give precedence.
|
|
You can use the "<filename>%</filename>" character as a wildcard
|
|
to match any number of characters, which can be useful when
|
|
specifying versions that contain long revision number that could
|
|
potentially change.
|
|
Here are two examples:
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_VERSION_python = "2.6.6"
|
|
PREFERRED_VERSION_linux-yocto = "3.0+git%"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<glossdiv id='var-glossary-r'><title>R</title>
|
|
|
|
<glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
|
|
<glossdef>
|
|
<para>The list of packages that conflict with a package.
|
|
Note that the package will not be installed if the conflicting packages are not
|
|
first removed.</para>
|
|
<para>
|
|
Like all package-controlling variables, you must always use them in
|
|
conjunction with a package name override.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
RCONFLICTS_${PN} = "another-conflicting-package-name"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of packages that must be installed as part of a package being built.
|
|
The package being built has a runtime dependency on the packages in the
|
|
variable's list.
|
|
In other words, in order for the package being built to run correctly,
|
|
it depends on these listed packages.
|
|
If a package in this list cannot be found during the build, the build
|
|
will not complete.
|
|
</para>
|
|
<para>
|
|
Because the <filename>RDEPENDS</filename> variable applies to packages
|
|
being built, you should
|
|
always attach an override to the variable to specify the particular runtime package
|
|
that has the dependency.
|
|
For example, suppose you are building a development package that depends
|
|
on the <filename>perl</filename> package.
|
|
In this case, you would use the following <filename>RDEPENDS</filename>
|
|
statement:
|
|
<literallayout class='monospaced'>
|
|
RDEPENDS_${PN}-dev += "perl"
|
|
</literallayout>
|
|
In the example, the package name (<filename>${PN}-dev</filename>) must
|
|
appear as it would in the
|
|
<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
|
|
renaming of the output package by classes like <filename>debian.bbclass</filename>.
|
|
</para>
|
|
<para>
|
|
Some automatic handling occurs around the <filename>RDEPENDS</filename>
|
|
variable:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If a runtime
|
|
package contains a shared library (<filename>.so</filename>), the build
|
|
processes the library in order to determine other libraries to which it
|
|
is dynamically linked.
|
|
The build process adds these libraries to <filename>RDEPENDS</filename>
|
|
to create the runtime package.</para></listitem>
|
|
<listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If the package
|
|
ships a <filename>pkg-config</filename> information file, the build process
|
|
uses this file to add items to the <filename>RDEPENDS</filename>
|
|
variable to create the runtime packages.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A list of packages that extend the usability of a package being
|
|
built.
|
|
The package being built does not depend on this list of packages in
|
|
order to successfully build, but needs them for the extended usability.
|
|
To specify runtime dependencies for packages, see the
|
|
<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable.
|
|
</para>
|
|
<para>
|
|
The OpenEmbedded build process automatically installs the list of packages
|
|
as part of the built package.
|
|
However, you can remove them later if you want.
|
|
If, during the build, a package from the list cannot be found, the build
|
|
process continues without an error.
|
|
</para>
|
|
<para>
|
|
Because the <filename>RRECOMMENDS</filename> variable applies to packages
|
|
being built, you should
|
|
always attach an override to the variable to specify the particular package
|
|
whose usability is being extended.
|
|
For example, suppose you are building a development package that is extended
|
|
to support wireless functionality.
|
|
In this case, you would use the following:
|
|
<literallayout class='monospaced'>
|
|
RRECOMMENDS_${PN}-dev += "<wireless_package_name>"
|
|
</literallayout>
|
|
In the example, the package name (<filename>${PN}-dev</filename>) must
|
|
appear as it would in the
|
|
<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
|
|
renaming of the output package by classes like <filename>debian.bbclass</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
|
|
<glossdef>
|
|
<para>The list of packages that are replaced with this package.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-s'><title>S</title>
|
|
|
|
<glossentry id='var-S'><glossterm>S</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
|
|
where unpacked package source code resides.
|
|
This location is within the working directory
|
|
(<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which
|
|
is not static.
|
|
The unpacked source location depends on the package name
|
|
(<filename><link linkend='var-PN'>PN</link></filename>) and
|
|
package version (<filename><link linkend='var-PV'>PV</link></filename>) as
|
|
follows:
|
|
<literallayout class='monospaced'>
|
|
${WORKDIR}/${PN}-${PV}
|
|
</literallayout>
|
|
As an example, assume a
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> top-level
|
|
folder named <filename>poky</filename>
|
|
and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
|
|
at <filename>poky/build</filename>.
|
|
In this case, the working directory the build system uses to build
|
|
the <filename>db</filename> package is the following:
|
|
<literallayout class='monospaced'>
|
|
~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
|
|
<glossdef>
|
|
<para>The section where package should be put.
|
|
Package managers use this variable.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The variable takes the value of
|
|
<filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
|
|
unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
|
|
In this case the value of
|
|
<filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
|
|
<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
|
|
<glossdef>
|
|
<para>The speed and device for the serial port used to attach the serial console.
|
|
This variable is given to the kernel as the "console"
|
|
parameter and after booting occurs <filename>getty</filename> is started on that port
|
|
so remote login is possible.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
|
|
<glossdef>
|
|
<para>The directory for the shared state.</para>
|
|
</glossdef>
|
|
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies the endian byte order of the target system.
|
|
The variable is either "le" for little-endian or "be" for big-endian.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies the number of bits for the target system CPU.
|
|
The variable is either "32" or "64".
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
|
|
<glossdef>
|
|
<para>The list of source files - local or remote.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
|
|
<glossdef>
|
|
<para></para>
|
|
<para>
|
|
By default, the OpenEmbedded build system automatically detects whether
|
|
<filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
|
|
contains files that are machine-specific.
|
|
If so, the build system automatically changes
|
|
<filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
|
|
Setting this variable to "0" disables this behavior.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The date of the source code used to build the package.
|
|
This variable applies only if the source was fetched from a Source Code Manager (SCM).
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The revision of the source code used to build the package.
|
|
This variable applies to Subversion, Git, Mercurial and Bazaar
|
|
only.
|
|
Note that if you wish to build a fixed revision and you wish
|
|
to avoid performing a query on the remote repository every time
|
|
BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
|
|
full revision identifier and not just a tag.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The directory with kernel headers that are required to build out-of-tree
|
|
modules.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The directory (usually <filename>TMPDIR/stamps</filename>) with timestamps of
|
|
executed tasks.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
|
|
<glossdef>
|
|
<para>The short (72 characters or less) summary of the binary package for packaging
|
|
systems such as <filename>ipkg</filename>, <filename>rpm</filename> or
|
|
<filename>debian</filename>.
|
|
By default, this variable inherits <filename>DESCRIPTION</filename>.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<glossdiv id='var-glossary-t'><title>T</title>
|
|
|
|
<glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
|
|
<glossdef>
|
|
<para>The architecture of the device being built.
|
|
While a number of values are possible, the OpenEmbedded build system primarily supports
|
|
<filename>arm</filename> and <filename>i586</filename>.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Flags passed to the C compiler for the target system.
|
|
This variable evaluates to the same as
|
|
<filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
|
|
<glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the method for handling FPU code.
|
|
For FPU-less targets, which include most ARM CPUs, the variable must be
|
|
set to "soft".
|
|
If not, the kernel emulation gets used, which results in a performance penalty.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
|
|
<glossdef>
|
|
<para>Specifies the target's operating system.
|
|
The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
|
|
to "linux-uclibc" for <filename>uclibc</filename>.
|
|
For ARM/EABI targets, there are also "linux-gnueabi" and
|
|
"linux-uclibc-gnueabi" values possible.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Specifies which variant of the GNU standard C library (<filename>libc</filename>)
|
|
to use during the build process.
|
|
This variable replaces <filename>POKYLIBC</filename>, which is no longer
|
|
supported.
|
|
</para>
|
|
<para>
|
|
You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
|
|
<note>
|
|
This release of the Yocto Project does not support the
|
|
<filename>glibc</filename> implementation of <filename>libc</filename>.
|
|
</note>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The toolchain selector.
|
|
This variable replaces <filename>POKYMODE</filename>, which is no longer
|
|
supported.
|
|
</para>
|
|
<para>
|
|
The <filename>TCMODE</filename> variable selects the external toolchain
|
|
built using the OpenEmbedded build system or a few supported combinations of
|
|
the upstream GCC or CodeSourcery Labs toolchain.
|
|
The variable identifies the <filename>tcmode-*</filename> files used in
|
|
the <filename>meta/conf/distro/include</filename> directory, which is found in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
|
|
</para>
|
|
<para>
|
|
By default, <filename>TCMODE</filename> is set to "default", which
|
|
chooses the <filename>tcmode-default.inc</filename> file.
|
|
The variable is similar to
|
|
<link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
|
|
the variant of the GNU standard C library (<filename>libc</filename>)
|
|
used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
This variable is the temporary directory the OpenEmbedded build system
|
|
uses when it does its work building images.
|
|
By default, the <filename>TMPDIR</filename> variable is named
|
|
<filename>tmp</filename> within the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
If you want to establish this directory in a location other than the
|
|
default, you can uncomment the following statement in the
|
|
<filename>conf/local.conf</filename> file in the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>:
|
|
<literallayout class='monospaced'>
|
|
#TMPDIR = "${TOPDIR}/tmp"
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
This variable is the
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
|
|
BitBake automatically sets this variable.
|
|
The OpenEmbedded build system uses the build directory when building images.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<glossdiv id='var-glossary-w'><title>W</title>
|
|
|
|
<glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The pathname of the working directory in which the OpenEmbedded build system
|
|
builds packages.
|
|
This directory is located within the
|
|
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
|
|
as different packages are built.
|
|
</para>
|
|
|
|
<para>
|
|
The actual <filename>WORKDIR</filename> directory depends on several things:
|
|
<itemizedlist>
|
|
<listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
|
|
<listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
|
|
<listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
|
|
<listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
|
|
<listitem>The package name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
|
|
<listitem>The package version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
|
|
<listitem>The package revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
For packages that are not dependent on a particular machine,
|
|
<filename>WORKDIR</filename> is defined as follows:
|
|
<literallayout class='monospaced'>
|
|
${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
|
|
</literallayout>
|
|
As an example, assume a
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> top-level
|
|
folder name <filename>poky</filename> and a default
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
|
|
at <filename>poky/build</filename>.
|
|
In this case, the working directory the build system uses to build
|
|
the <filename>v86d</filename> package is the following:
|
|
<literallayout class='monospaced'>
|
|
~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
|
|
is defined slightly different:
|
|
<literallayout class='monospaced'>
|
|
${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
|
|
</literallayout>
|
|
As an example, again assume a source directory top-level folder
|
|
named <filename>poky</filename> and a default build directory
|
|
at <filename>poky/build</filename>.
|
|
In this case, the working directory the build system uses to build
|
|
the <filename>acl</filename> package, which is dependent on a
|
|
MIPS-based device, is the following:
|
|
<literallayout class='monospaced'>
|
|
~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
|
|
</literallayout>
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossdiv>
|
|
|
|
<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
|
|
<!-- </glossdiv>-->
|
|
|
|
</glossary>
|
|
</chapter>
|
|
<!--
|
|
vim: expandtab tw=80 ts=4
|
|
-->
|