mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-01-29 21:08:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

bitbake: sphinx: last manual round of fixes/improvements

Browse Source 
Review all pages, and fix up for formatting which was not covered by
pandoc, such as some links and code block sections.

(Bitbake rev: d99760cc687cc9c24d6d9a1c49fa094574476e0c)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Nicolas Dechesne
2020-07-31 10:00:02 +02:00
committed by Richard Purdie
parent 4324c6e071
commit e3b76c8fc3
6 changed files with 1727 additions and 1164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
View File

@@ -16,9 +16,13 @@ data, or simply return information about the execution environment.
This chapter describes BitBake's execution process from start to finish
when you use it to create an image. The execution process is launched
using the following command form: $ bitbake target For information on
the BitBake command and its options, see "`The BitBake
Command <#bitbake-user-manual-command>`__" section.
using the following command form: ::
$ bitbake target
For information on
the BitBake command and its options, see ":ref:`The BitBake Command
<bitbake-user-manual-command>`" section.
.. note::
@@ -28,7 +32,11 @@ Command <#bitbake-user-manual-command>`__" section.
your project's ``local.conf`` configuration file.
A common method to determine this value for your build host is to run
the following: $ grep processor /proc/cpuinfo This command returns
the following: ::
$ grep processor /proc/cpuinfo
This command returns
the number of processors, which takes into account hyper-threading.
Thus, a quad-core build host with hyper-threading most likely shows
eight processors, which is the value you would then assign to
@@ -46,12 +54,12 @@ to determine what layers BitBake needs to recognize, all necessary
``layer.conf`` files (one from each layer), and ``bitbake.conf``. The
data itself is of various types:
- *Recipes:* Details about particular pieces of software.
- **Recipes:** Details about particular pieces of software.
- *Class Data:* An abstraction of common build information (e.g. how to
- **Class Data:** An abstraction of common build information (e.g. how to
build a Linux kernel).
- *Configuration Data:* Machine-specific settings, policy decisions,
- **Configuration Data:** Machine-specific settings, policy decisions,
and so forth. Configuration data acts as the glue to bind everything
together.
@@ -72,13 +80,9 @@ Prior to parsing configuration files, BitBake looks at certain
variables, including:
- :term:`BB_ENV_WHITELIST`
- :term:`BB_ENV_EXTRAWHITE`
- :term:`BB_PRESERVE_ENV`
- :term:`BB_ORIGENV`
- :term:`BITBAKE_UI`
The first four variables in this list relate to how BitBake treats shell
@@ -87,8 +91,8 @@ the environment variables and provides tight control over the shell
execution environment. However, through the use of these first four
variables, you can apply your control regarding the environment
variables allowed to be used by BitBake in the shell during execution of
tasks. See the "`Passing Information Into the Build Task
Environment <#passing-information-into-the-build-task-environment>`__"
tasks. See the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:Passing Information Into the Build Task Environment`"
section and the information about these variables in the variable
glossary for more information on how they work and on how to use them.
@@ -118,8 +122,8 @@ Only variable definitions and include directives are allowed in BitBake
``.conf`` files. Some variables directly influence BitBake's behavior.
These variables might have been set from the environment depending on
the environment variables previously mentioned or set in the
configuration files. The "`Variables
Glossary <#ref-bb-variables-glos>`__" chapter presents a full list of
configuration files. The ":ref:`bitbake-user-manual/bitbake-user-manual-ref-variables:Variables Glossary`"
chapter presents a full list of
variables.
After parsing configuration files, BitBake uses its rudimentary
@@ -135,7 +139,11 @@ in ``BBPATH`` in the same way as configuration files.
A good way to get an idea of the configuration files and the class files
used in your execution environment is to run the following BitBake
command: $ bitbake -e > mybb.log Examining the top of the ``mybb.log``
command: ::
$ bitbake -e > mybb.log
Examining the top of the ``mybb.log``
shows you the many configuration files and class files used in your
execution environment.
@@ -147,15 +155,28 @@ execution environment.
pair of curly braces in a shell function, the closing curly brace
must not be located at the start of the line without leading spaces.
Here is an example that causes BitBake to produce a parsing error:
fakeroot create_shar() { cat << "EOF" >
${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh usage() { echo "test" ######
The following "}" at the start of the line causes a parsing error
###### } EOF } Writing the recipe this way avoids the error: fakeroot
create_shar() { cat << "EOF" >
${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh usage() { echo "test"
######The following "}" with a leading space at the start of the line
avoids the error ###### } EOF }
Here is an example that causes BitBake to produce a parsing error: ::
fakeroot create_shar() {
cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
###### The following "}" at the start of the line causes a parsing error ######
}
EOF
}
Writing the recipe this way avoids the error:
fakeroot create_shar() {
cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
###### The following "}" with a leading space at the start of the line avoids the error ######
}
EOF
}
Locating and Parsing Recipes
============================
@@ -164,16 +185,17 @@ During the configuration phase, BitBake will have set
:term:`BBFILES`. BitBake now uses it to construct a
list of recipes to parse, along with any append files (``.bbappend``) to
apply. ``BBFILES`` is a space-separated list of available files and
supports wildcards. An example would be: BBFILES =
"/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" BitBake parses each
supports wildcards. An example would be: ::
BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
BitBake parses each
recipe and append file located with ``BBFILES`` and stores the values of
various variables into the datastore.
.. note::
Append files are applied in the order they are encountered in
BBFILES
.
Append files are applied in the order they are encountered in BBFILES.
For each file, a fresh copy of the base configuration is made, then the
recipe is parsed line by line. Any inherit statements cause BitBake to
@@ -184,11 +206,12 @@ parses in order any append files found in ``BBFILES``.
One common convention is to use the recipe filename to define pieces of
metadata. For example, in ``bitbake.conf`` the recipe name and version
are used to set the variables :term:`PN` and
:term:`PV`: PN =
"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or
'defaultpkgname'}" PV =
"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or
'1.0'}" In this example, a recipe called "something_1.2.3.bb" would set
:term:`PV`: ::
PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
In this example, a recipe called "something_1.2.3.bb" would set
``PN`` to "something" and ``PV`` to "1.2.3".
By the time parsing is complete for a recipe, BitBake has a list of
@@ -215,11 +238,13 @@ Recipe file collections exist to allow the user to have multiple
repositories of ``.bb`` files that contain the same exact package. For
example, one could easily use them to make one's own local copy of an
upstream repository, but with custom modifications that one does not
want upstream. Here is an example: BBFILES = "/stuff/openembedded/*/*.bb
/stuff/openembedded.modified/*/*.bb" BBFILE_COLLECTIONS = "upstream
local" BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10"
want upstream. Here is an example: ::
BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10"
.. note::
@@ -244,7 +269,11 @@ variable, which is optional.
When a recipe uses ``PROVIDES``, that recipe's functionality can be
found under an alternative name or names other than the implicit ``PN``
name. As an example, suppose a recipe named ``keyboard_1.0.bb``
contained the following: PROVIDES += "fullkeyboard" The ``PROVIDES``
contained the following: ::
PROVIDES += "fullkeyboard"
The ``PROVIDES``
list for this recipe becomes "keyboard", which is implicit, and
"fullkeyboard", which is explicit. Consequently, the functionality found
in ``keyboard_1.0.bb`` can be found under two different names.
@@ -261,9 +290,11 @@ needs to prioritize providers by determining provider preferences.
A common example in which a target has multiple providers is
"virtual/kernel", which is on the ``PROVIDES`` list for each kernel
recipe. Each machine often selects the best kernel provider by using a
line similar to the following in the machine configuration file:
PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" The default
:term:`PREFERRED_PROVIDER` is the provider
line similar to the following in the machine configuration file: ::
PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
The default :term:`PREFERRED_PROVIDER` is the provider
with the same name as the target. BitBake iterates through each target
it needs to build and resolves them and their dependencies using this
process.
@@ -299,8 +330,9 @@ If the first recipe is named ``a_1.1.bb``, then the
Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by
default. However, if you define the following variable in a ``.conf``
file that BitBake parses, you can change that preference:
PREFERRED_VERSION_a = "1.1"
file that BitBake parses, you can change that preference: ::
PREFERRED_VERSION_a = "1.1"
.. note::
@@ -312,7 +344,11 @@ PREFERRED_VERSION_a = "1.1"
For example, in the OpenEmbedded codebase, there is a standard,
versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
is also a Git-based version, ``busybox_git.bb``, which explicitly
contains the line DEFAULT_PREFERENCE = "-1" to ensure that the
contains the line ::
DEFAULT_PREFERENCE = "-1"
to ensure that the
numbered, stable version is always preferred unless the developer
selects otherwise.
@@ -327,15 +363,16 @@ performance on multi-core systems, BitBake considers each task as an
independent entity with its own set of dependencies.
Dependencies are defined through several variables. You can find
information about variables BitBake uses in the `Variables
Glossary <#ref-bb-variables-glos>`__ near the end of this manual. At a
information about variables BitBake uses in the
:doc:`bitbake-user-manual-ref-variables` near the end of this manual. At a
basic level, it is sufficient to know that BitBake uses the
:term:`DEPENDS` and
:term:`RDEPENDS` variables when calculating
dependencies.
For more information on how BitBake handles dependencies, see the
"`Dependencies <#dependencies>`__" section.
:ref:`bitbake-user-manual/bitbake-user-manual-metadata:Dependencies`
section.
.. _ref-bitbake-tasklist:
@@ -344,7 +381,8 @@ The Task List
Based on the generated list of providers and the dependency information,
BitBake can now calculate exactly what tasks it needs to run and in what
order it needs to run them. The "`Executing Tasks <#executing-tasks>`__"
order it needs to run them. The
:ref:`bitbake-user-manual/bitbake-user-manual-execution:executing tasks`
section has more information on how BitBake chooses which task to
execute next.
@@ -371,8 +409,9 @@ The exact format of the stamps is partly configurable. In modern
versions of BitBake, a hash is appended to the stamp so that if the
configuration changes, the stamp becomes invalid and the task is
automatically rerun. This hash, or signature used, is governed by the
signature policy that is configured (see the "`Checksums
(Signatures) <#checksums>`__" section for information). It is also
signature policy that is configured (see the
:ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`
section for information). It is also
possible to append extra metadata to the stamp using the
``[stamp-extra-info]`` task flag. For example, OpenEmbedded uses this
flag to make some tasks machine-specific.
@@ -383,7 +422,8 @@ flag to make some tasks machine-specific.
created when these tasks are run. Consequently, "nostamp" tasks are
always rerun.
For more information on tasks, see the "`Tasks <#tasks>`__" section.
For more information on tasks, see the
:ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks` section.
Executing Tasks
===============
@@ -457,14 +497,21 @@ to the task.
Like the working directory case, situations exist where dependencies
should be ignored. For these cases, you can instruct the build process
to ignore a dependency by using a line like the following:
PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the
to ignore a dependency by using a line like the following: ::
PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
This example ensures that the
``PACKAGE_ARCHS`` variable does not depend on the value of ``MACHINE``,
even if it does reference it.
Equally, there are cases where we need to add dependencies BitBake is
not able to find. You can accomplish this by using a line like the
following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly
following: ::
PACKAGE_ARCHS[vardeps] = "MACHINE"
This example explicitly
adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
Consider a case with in-line Python, for example, where BitBake is not
@@ -488,13 +535,15 @@ configuration file, we can give BitBake some extra information to help
it construct the basehash. The following statement effectively results
in a list of global variable dependency excludes - variables never
included in any checksum. This example uses variables from OpenEmbedded
to help illustrate the concept: BB_HASHBASE_WHITELIST ?= "TMPDIR FILE
PATH PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS
FILE_DIRNAME HOME LOGNAME SHELL \\ USER FILESPATH STAGING_DIR_HOST
STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR
PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR
EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The
previous example excludes the work directory, which is part of
to help illustrate the concept: ::
BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL \
USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
The previous example excludes the work directory, which is part of
``TMPDIR``.
The rules for deciding which hashes of dependent tasks to include
@@ -507,8 +556,11 @@ OpenEmbedded-Core uses: "OEBasic" and "OEBasicHash". By default, there
is a dummy "noop" signature handler enabled in BitBake. This means that
behavior is unchanged from previous versions. ``OE-Core`` uses the
"OEBasicHash" signature handler by default through this setting in the
``bitbake.conf`` file: BB_SIGNATURE_HANDLER ?= "OEBasicHash" The
"OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic"
``bitbake.conf`` file: ::
BB_SIGNATURE_HANDLER ?= "OEBasicHash"
The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic"
version but adds the task hash to the stamp files. This results in any
metadata change that changes the task hash, automatically causing the
task to be run again. This removes the need to bump
@@ -519,13 +571,13 @@ It is also worth noting that the end result of these signature
generators is to make some dependency and hash information available to
the build. This information includes:
- ``BB_BASEHASH_task-``\ taskname: The base hashes for each task in the
- ``BB_BASEHASH_task-``\ *taskname*: The base hashes for each task in the
recipe.
- ``BB_BASEHASH_``\ filename\ ``:``\ taskname: The base hashes for each
- ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each
dependent task.
- ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for
- ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for
each task.
- ``BB_TASKHASH``: The hash of the currently running task.
@@ -547,8 +599,9 @@ where these two stamp trees diverge.
It is likely that future versions of BitBake will provide other
signature handlers triggered through additional "-S" parameters.
You can find more information on checksum metadata in the "`Task
Checksums and Setscene <#task-checksums-and-setscene>`__" section.
You can find more information on checksum metadata in the
:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
section.
Setscene
========
@@ -601,8 +654,9 @@ with the list of tasks BitBake thinks has been "covered". The metadata
can then ensure that this list is correct and can inform BitBake that it
wants specific tasks to be run regardless of the setscene result.
You can find more information on setscene metadata in the "`Task
Checksums and Setscene <#task-checksums-and-setscene>`__" section.
You can find more information on setscene metadata in the
:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
section.
Logging
=======
@@ -648,11 +702,32 @@ logging configuration is merged using the following rules:
As an example, consider the following user logging configuration file
which logs all Hash Equivalence related messages of VERBOSE or higher to
a file called ``hashequiv.log`` { "version": 1, "handlers": {
"autobuilderlog": { "class": "logging.FileHandler", "formatter":
"logfileFormatter", "level": "DEBUG", "filename": "hashequiv.log",
"mode": "w" } }, "formatters": { "logfileFormatter": { "format":
"%(name)s: %(levelname)s: %(message)s" } }, "loggers": {
"BitBake.SigGen.HashEquiv": { "level": "VERBOSE", "handlers":
["autobuilderlog"] }, "BitBake.RunQueue.HashEquiv": { "level":
"VERBOSE", "handlers": ["autobuilderlog"] } } }
a file called ``hashequiv.log`` ::
{
"version": 1,
"handlers": {
"autobuilderlog": {
"class": "logging.FileHandler",
"formatter": "logfileFormatter",
"level": "DEBUG",
"filename": "hashequiv.log",
"mode": "w"
}
},
"formatters": {
"logfileFormatter": {
"format": "%(name)s: %(levelname)s: %(message)s"
}
},
"loggers": {
"BitBake.SigGen.HashEquiv": {
"level": "VERBOSE",
"handlers": ["autobuilderlog"]
},
"BitBake.RunQueue.HashEquiv": {
"level": "VERBOSE",
"handlers": ["autobuilderlog"]
}
}
}

239
bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
View File

@@ -27,22 +27,28 @@ and unpacking the files is often optionally followed by patching.
Patching, however, is not covered by this module.
The code to execute the first part of this process, a fetch, looks
something like the following: src_uri = (d.getVar('SRC_URI') or
"").split() fetcher = bb.fetch2.Fetch(src_uri, d) fetcher.download()
something like the following: ::
src_uri = (d.getVar('SRC_URI') or "").split()
fetcher = bb.fetch2.Fetch(src_uri, d)
fetcher.download()
This code sets up an instance of the fetch class. The instance uses a
space-separated list of URLs from the :term:`SRC_URI`
variable and then calls the ``download`` method to download the files.
The instantiation of the fetch class is usually followed by: rootdir =
l.getVar('WORKDIR') fetcher.unpack(rootdir) This code unpacks the
downloaded files to the specified by ``WORKDIR``.
The instantiation of the fetch class is usually followed by: ::
rootdir = l.getVar('WORKDIR')
fetcher.unpack(rootdir)
This code unpacks the downloaded files to the specified by ``WORKDIR``.
.. note::
For convenience, the naming in these examples matches the variables
used by OpenEmbedded. If you want to see the above code in action,
examine the OpenEmbedded class file
base.bbclass
examine the OpenEmbedded class file ``base.bbclass``
.
The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the
@@ -61,30 +67,37 @@ URLs by looking for source files in a specific search order:
from ``SRC_URI``).
- *Mirror Sites:* If fetch failures occur, BitBake next uses mirror
locations as defined by the :term:`MIRRORS`
variable.
locations as defined by the :term:`MIRRORS` variable.
For each URL passed to the fetcher, the fetcher calls the submodule that
handles that particular URL type. This behavior can be the source of
some confusion when you are providing URLs for the ``SRC_URI`` variable.
Consider the following two URLs:
http://git.yoctoproject.org/git/poky;protocol=git
git://git.yoctoproject.org/git/poky;protocol=http In the former case,
the URL is passed to the ``wget`` fetcher, which does not understand
"git". Therefore, the latter case is the correct form since the Git
Consider the following two URLs: ::
http://git.yoctoproject.org/git/poky;protocol=git
git://git.yoctoproject.org/git/poky;protocol=http
In the former case, the URL is passed to the ``wget`` fetcher, which does not
understand "git". Therefore, the latter case is the correct form since the Git
fetcher does know how to use HTTP as a transport.
Here are some examples that show commonly used mirror definitions:
PREMIRRORS ?= "\\ bzr://.*/.\* http://somemirror.org/sources/ \\n \\
cvs://.*/.\* http://somemirror.org/sources/ \\n \\ git://.*/.\*
http://somemirror.org/sources/ \\n \\ hg://.*/.\*
http://somemirror.org/sources/ \\n \\ osc://.*/.\*
http://somemirror.org/sources/ \\n \\ p4://.*/.\*
http://somemirror.org/sources/ \\n \\ svn://.*/.\*
http://somemirror.org/sources/ \\n" MIRRORS =+ "\\ ftp://.*/.\*
http://somemirror.org/sources/ \\n \\ http://.*/.\*
http://somemirror.org/sources/ \\n \\ https://.*/.\*
http://somemirror.org/sources/ \\n" It is useful to note that BitBake
Here are some examples that show commonly used mirror definitions: ::
PREMIRRORS ?= "\
bzr://.*/.\* http://somemirror.org/sources/ \\n \
cvs://.*/.\* http://somemirror.org/sources/ \\n \
git://.*/.\* http://somemirror.org/sources/ \\n \
hg://.*/.\* http://somemirror.org/sources/ \\n \
osc://.*/.\* http://somemirror.org/sources/ \\n \
p4://.*/.\* http://somemirror.org/sources/ \\n \
svn://.*/.\* http://somemirror.org/sources/ \\n"
MIRRORS =+ "\
ftp://.*/.\* http://somemirror.org/sources/ \\n \
http://.*/.\* http://somemirror.org/sources/ \\n \
https://.*/.\* http://somemirror.org/sources/ \\n"
It is useful to note that BitBake
supports cross-URLs. It is possible to mirror a Git repository on an
HTTP server as a tarball. This is what the ``git://`` mapping in the
previous example does.
@@ -98,15 +111,24 @@ File integrity is of key importance for reproducing builds. For
non-local archive downloads, the fetcher code can verify SHA-256 and MD5
checksums to ensure the archives have been downloaded correctly. You can
specify these checksums by using the ``SRC_URI`` variable with the
appropriate varflags as follows: SRC_URI[md5sum] = "value"
SRC_URI[sha256sum] = "value" You can also specify the checksums as
parameters on the ``SRC_URI`` as shown below: SRC_URI =
"http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
appropriate varflags as follows: ::
SRC_URI[md5sum] = "value"
SRC_URI[sha256sum] = "value"
You can also specify the checksums as
parameters on the ``SRC_URI`` as shown below: ::
SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
If multiple URIs exist, you can specify the checksums either directly as
in the previous example, or you can name the URLs. The following syntax
shows how you name the URIs: SRC_URI =
"http://example.com/foobar.tar.bz2;name=foo" SRC_URI[foo.md5sum] =
4a8e0f237e961fd7785d19d07fdb994d After a file has been downloaded and
shows how you name the URIs: ::
SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
After a file has been downloaded and
has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``.
BitBake uses this stamp during subsequent builds to avoid downloading or
comparing a checksum for the file again.
@@ -182,8 +204,10 @@ time the ``download()`` method is called.
If you specify a directory, the entire directory is unpacked.
Here are a couple of example URLs, the first relative and the second
absolute: SRC_URI = "file://relativefile.patch" SRC_URI =
"file:///Users/ich/very_important_software"
absolute: ::
SRC_URI = "file://relativefile.patch"
SRC_URI = "file:///Users/ich/very_important_software"
.. _http-ftp-fetcher:
@@ -201,10 +225,11 @@ downloaded file is useful for avoiding collisions in
:term:`DL_DIR` when dealing with multiple files that
have the same name.
Some example URLs are as follows: SRC_URI =
"http://oe.handhelds.org/not_there.aac" SRC_URI =
"ftp://oe.handhelds.org/not_there_as_well.aac" SRC_URI =
"ftp://you@oe.handhelds.org/home/you/secret.plan"
Some example URLs are as follows: ::
SRC_URI = "http://oe.handhelds.org/not_there.aac"
SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
.. note::
@@ -214,14 +239,14 @@ Some example URLs are as follows: SRC_URI =
::
SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
Such URLs should should be modified by replacing semi-colons with '&'
characters:
::
SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
In most cases this should work. Treating semi-colons and '&' in
queries identically is recommended by the World Wide Web Consortium
@@ -230,7 +255,7 @@ Some example URLs are as follows: SRC_URI =
::
SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"
.. _cvs-fetcher:
@@ -240,20 +265,20 @@ CVS fetcher (``(cvs://``)
This submodule handles checking out files from the CVS version control
system. You can configure it using a number of different variables:
- *``FETCHCMD_cvs``:* The name of the executable to use when running
- :term:`FETCHCMD_cvs <FETCHCMD>`: The name of the executable to use when running
the ``cvs`` command. This name is usually "cvs".
- *``SRCDATE``:* The date to use when fetching the CVS source code. A
- :term:`SRCDATE`: The date to use when fetching the CVS source code. A
special value of "now" causes the checkout to be updated on every
build.
- :term:`CVSDIR`\ *:* Specifies where a temporary
- :term:`CVSDIR`: Specifies where a temporary
checkout is saved. The location is often ``DL_DIR/cvs``.
- *``CVS_PROXY_HOST``:* The name to use as a "proxy=" parameter to the
- CVS_PROXY_HOST: The name to use as a "proxy=" parameter to the
``cvs`` command.
- *``CVS_PROXY_PORT``:* The port number to use as a "proxyport="
- CVS_PROXY_PORT: The port number to use as a "proxyport="
parameter to the ``cvs`` command.
As well as the standard username and password URL syntax, you can also
@@ -282,7 +307,7 @@ The supported parameters are as follows:
are forcing the module into a special directory relative to
:term:`CVSDIR`.
- *"rsh"* Used in conjunction with the "method" parameter.
- *"rsh":* Used in conjunction with the "method" parameter.
- *"scmdata":* Causes the CVS metadata to be maintained in the tarball
the fetcher creates when set to "keep". The tarball is expanded into
@@ -296,9 +321,10 @@ The supported parameters are as follows:
- *"port":* The port to which the CVS server connects.
Some example URLs are as follows: SRC_URI =
"cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" SRC_URI =
"cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
Some example URLs are as follows: ::
SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
.. _svn-fetcher:
@@ -337,10 +363,11 @@ The supported parameters are as follows:
username is different than the username used in the main URL, which
is passed to the subversion command.
Following are three examples using svn: SRC_URI =
"svn://myrepos/proj1;module=vip;protocol=http;rev=667" SRC_URI =
"svn://myrepos/proj1;module=opie;protocol=svn+ssh" SRC_URI =
"svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
Following are three examples using svn: ::
SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
.. _git-fetcher:
@@ -409,20 +436,22 @@ This fetcher supports the following parameters:
parameter implies no branch and only works when the transfer protocol
is ``file://``.
Here are some example URLs: SRC_URI =
"git://git.oe.handhelds.org/git/vip.git;tag=version-1" SRC_URI =
"git://git.oe.handhelds.org/git/vip.git;protocol=http"
Here are some example URLs: ::
SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
.. _gitsm-fetcher:
Git Submodule Fetcher (``gitsm://``)
------------------------------------
This fetcher submodule inherits from the `Git fetcher <#git-fetcher>`__
and extends that fetcher's behavior by fetching a repository's
submodules. :term:`SRC_URI` is passed to the Git
fetcher as described in the "`Git Fetcher
(``git://``) <#git-fetcher>`__" section.
This fetcher submodule inherits from the :ref:`Git
fetcher<bitbake-user-manual/bitbake-user-manual-fetching:git fetcher
(\`\`git://\`\`)>` and extends that fetcher's behavior by fetching a
repository's submodules. :term:`SRC_URI` is passed to the Git fetcher as
described in the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git
fetcher (\`\`git://\`\`)` section.
.. note::
@@ -446,42 +475,33 @@ repository.
To use this fetcher, make sure your recipe has proper
:term:`SRC_URI`, :term:`SRCREV`, and
:term:`PV` settings. Here is an example: SRC_URI =
"ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
SRCREV = "EXAMPLE_CLEARCASE_TAG" PV = "${@d.getVar("SRCREV",
False).replace("/", "+")}" The fetcher uses the ``rcleartool`` or
:term:`PV` settings. Here is an example: ::
SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
SRCREV = "EXAMPLE_CLEARCASE_TAG"
PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
The fetcher uses the ``rcleartool`` or
``cleartool`` remote client, depending on which one is available.
Following are options for the ``SRC_URI`` statement:
- *``vob``*: The name, which must include the prepending "/" character,
- *vob*: The name, which must include the prepending "/" character,
of the ClearCase VOB. This option is required.
- *``module``*: The module, which must include the prepending "/"
- *module*: The module, which must include the prepending "/"
character, in the selected VOB.
.. note::
The
module
and
vob
options are combined to create the
load
rule in the view config spec. As an example, consider the
vob
and
module
values from the
SRC_URI
statement at the start of this section. Combining those values
results in the following:
::
The module and vob options are combined to create the load rule in the
view config spec. As an example, consider the vob and module values from
the SRC_URI statement at the start of this section. Combining those values
results in the following: ::
load /example_vob/example_module
load /example_vob/example_module
- *``proto``*: The protocol, which can be either ``http`` or ``https``.
- *proto*: The protocol, which can be either ``http`` or ``https``.
By default, the fetcher creates a configuration specification. If you
want this specification written to an area other than the default, use
@@ -490,11 +510,8 @@ the specification is written.
.. note::
the
SRCREV
loses its functionality if you specify this variable. However,
SRCREV
is still used to label the archive after a fetch even though it does
the SRCREV loses its functionality if you specify this variable. However,
SRCREV is still used to label the archive after a fetch even though it does
not define what is fetched.
Here are a couple of other behaviors worth mentioning:
@@ -532,34 +549,36 @@ the server's URL and port number, and you can specify a username and
password directly in your recipe within ``SRC_URI``.
Here is an example that relies on ``P4CONFIG`` to specify the server URL
and port, username, and password, and fetches the Head Revision: SRC_URI
= "p4://example-depot/main/source/..." SRCREV = "${AUTOREV}" PV =
"p4-${SRCPV}" S = "${WORKDIR}/p4"
and port, username, and password, and fetches the Head Revision: ::
SRC_URI = "p4://example-depot/main/source/..."
SRCREV = "${AUTOREV}"
PV = "p4-${SRCPV}"
S = "${WORKDIR}/p4"
Here is an example that specifies the server URL and port, username, and
password, and fetches a Revision based on a Label: P4PORT =
"tcp:p4server.example.net:1666" SRC_URI =
"p4://user:passwd@example-depot/main/source/..." SRCREV = "release-1.0"
PV = "p4-${SRCPV}" S = "${WORKDIR}/p4"
password, and fetches a Revision based on a Label: ::
P4PORT = "tcp:p4server.example.net:1666"
SRC_URI = "p4://user:passwd@example-depot/main/source/..."
SRCREV = "release-1.0"
PV = "p4-${SRCPV}"
S = "${WORKDIR}/p4"
.. note::
You should always set
S
to
"${WORKDIR}/p4"
in your recipe.
You should always set S to "${WORKDIR}/p4" in your recipe.
By default, the fetcher strips the depot location from the local file paths. In
the above example, the content of ``example-depot/main/source/`` will be placed
in ``${WORKDIR}/p4``. For situations where preserving parts of the remote depot
paths locally is desirable, the fetcher supports two parameters:
- **"module":**
- *"module":*
The top-level depot location or directory to fetch. The value of this
parameter can also point to a single file within the depot, in which case
the local file path will include the module path.
- **"remotepath":**
- *"remotepath":*
When used with the value "``keep``", the fetcher will mirror the full depot
paths locally for the specified location, even in combination with the
``module`` parameter.
@@ -589,7 +608,7 @@ Repo Fetcher (``repo://``)
This fetcher submodule fetches code from ``google-repo`` source control
system. The fetcher works by initiating and syncing sources of the
repository into :term:`REPODIR`, which is usually
:term:`DL_DIR`\ ``/repo``.
``${DL_DIR}/repo``.
This fetcher supports the following parameters:
@@ -600,10 +619,10 @@ This fetcher supports the following parameters:
- *"manifest":* Name of the manifest file (default: ``default.xml``).
Here are some example URLs: SRC_URI =
"repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
SRC_URI =
"repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"
Here are some example URLs: ::
SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"
Other Fetchers
--------------

417
bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
View File

@@ -18,21 +18,28 @@ it.
Obtaining BitBake
=================
See the "`Obtaining BitBake <#obtaining-bitbake>`__" section for
See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for
information on how to obtain BitBake. Once you have the source code on
your machine, the BitBake directory appears as follows: $ ls -al total
100 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . drwxrwxr-x. 3 wmat wmat
4096 Feb 4 10:45 .. -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin drwxrwxr-x. 4 wmat wmat
4096 Jan 31 13:44 build -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55
ChangeLog drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes drwxrwxr-x.
2 wmat wmat 4096 Nov 26 04:55 conf drwxrwxr-x. 3 wmat wmat 4096 Nov 26
04:55 contrib -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc -rw-rw-r--. 1 wmat wmat 69
Nov 26 04:55 .gitignore -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib -rw-rw-r--. 1 wmat wmat
195 Nov 26 04:55 MANIFEST.in -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55
TODO
your machine, the BitBake directory appears as follows: ::
$ ls -al
total 100
drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
-rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
-rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
-rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
-rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
-rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
-rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
-rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
At this point, you should have BitBake cloned to a directory that
matches the previous listing except for dates and user names.
@@ -42,18 +49,29 @@ Setting Up the BitBake Environment
First, you need to be sure that you can run BitBake. Set your working
directory to where your local BitBake files are and run the following
command: $ ./bin/bitbake --version BitBake Build Tool Core version
1.23.0, bitbake version 1.23.0 The console output tells you what version
command: ::
$ ./bin/bitbake --version
BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
The console output tells you what version
you are running.
The recommended method to run BitBake is from a directory of your
choice. To be able to run BitBake from any directory, you need to add
the executable binary to your binary to your shell's environment
``PATH`` variable. First, look at your current ``PATH`` variable by
entering the following: $ echo $PATH Next, add the directory location
entering the following: ::
$ echo $PATH
Next, add the directory location
for the BitBake binary to the ``PATH``. Here is an example that adds the
``/home/scott-lenovo/bitbake/bin`` directory to the front of the
``PATH`` variable: $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
``PATH`` variable: ::
$ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
You should now be able to enter the ``bitbake`` command from the command
line while working from any directory.
@@ -74,8 +92,7 @@ example.
While every attempt is made to explain what is happening during the
example, the descriptions cannot cover everything. You can find further
information throughout this manual. Also, you can actively participate
in the
http://lists.openembedded.org/mailman/listinfo/bitbake-devel
in the :oe_lists:`/g/bitbake-devel`
discussion mailing list about the BitBake build tool.
.. note::
@@ -87,36 +104,46 @@ discussion mailing list about the BitBake build tool.
As stated earlier, the goal of this example is to eventually compile
"Hello World". However, it is unknown what BitBake needs and what you
have to provide in order to achieve that goal. Recall that BitBake
utilizes three types of metadata files: `Configuration
Files <#configuration-files>`__, `Classes <#classes>`__, and
`Recipes <#recipes>`__. But where do they go? How does BitBake find
utilizes three types of metadata files:
:ref:`bitbake-user-manual/bitbake-user-manual-intro:configuration files`,
:ref:`bitbake-user-manual/bitbake-user-manual-intro:classes`, and
:ref:`bitbake-user-manual/bitbake-user-manual-intro:recipes`.
But where do they go? How does BitBake find
them? BitBake's error messaging helps you answer these types of
questions and helps you better understand exactly what is going on.
Following is the complete "Hello World" example.
1. *Create a Project Directory:* First, set up a directory for the
#. **Create a Project Directory:** First, set up a directory for the
"Hello World" project. Here is how you can do so in your home
directory: $ mkdir ~/hello $ cd ~/hello This is the directory that
directory: ::
$ mkdir ~/hello
$ cd ~/hello
This is the directory that
BitBake will use to do all of its work. You can use this directory
to keep all the metafiles needed by BitBake. Having a project
directory is a good way to isolate your project.
2. *Run BitBake:* At this point, you have nothing but a project
directory. Run the ``bitbake`` command and see what it does: $
bitbake The BBPATH variable is not set and bitbake did not find a
conf/bblayers.conf file in the expected location. Maybe you
accidentally invoked bitbake from the wrong directory? DEBUG:
Removed the following variables from the environment:
GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
\_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS The
majority of this output is specific to environment variables that
#. **Run BitBake:** At this point, you have nothing but a project
directory. Run the ``bitbake`` command and see what it does: ::
$ bitbake
The BBPATH variable is not set and bitbake did not
find a conf/bblayers.conf file in the expected location.
Maybe you accidentally invoked bitbake from the wrong directory?
DEBUG: Removed the following variables from the environment:
GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
The majority of this output is specific to environment variables that
are not directly relevant to BitBake. However, the very first
message regarding the ``BBPATH`` variable and the
``conf/bblayers.conf`` file is relevant.
@@ -128,14 +155,18 @@ Following is the complete "Hello World" example.
(``.conf``) or recipe files (``.bb``) at all. BitBake also cannot
find the ``bitbake.conf`` file.
3. *Setting ``BBPATH``:* For this example, you can set ``BBPATH`` in
#. **Setting BBPATH:** For this example, you can set ``BBPATH`` in
the same manner that you set ``PATH`` earlier in the appendix. You
should realize, though, that it is much more flexible to set the
``BBPATH`` variable up in a configuration file for each project.
From your shell, enter the following commands to set and export the
``BBPATH`` variable: $ BBPATH="projectdirectory" $ export BBPATH Use
your actual project directory in the command. BitBake uses that
``BBPATH`` variable: ::
$ BBPATH="projectdirectory"
$ export BBPATH
Use your actual project directory in the command. BitBake uses that
directory to find the metadata it needs for your project.
.. note::
@@ -144,28 +175,32 @@ Following is the complete "Hello World" example.
("~") character as BitBake does not expand that character as the
shell would.
4. *Run BitBake:* Now that you have ``BBPATH`` defined, run the
``bitbake`` command again: $ bitbake ERROR: Traceback (most recent
call last): File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py",
line 163, in wrapped return func(fn, \*args) File
"/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in
parse_config_file return bb.parse.handle(fn, data, include) File
"/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in
handle return h['handle'](fn, data, include) File
"/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py",
line 120, in handle abs_fn = resolve_file(fn, data) File
"/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in
resolve_file raise IOError("file %s not found in %s" % (fn, bbpath))
IOError: file conf/bitbake.conf not found in
/home/scott-lenovo/hello ERROR: Unable to parse conf/bitbake.conf:
file conf/bitbake.conf not found in /home/scott-lenovo/hello This
sample output shows that BitBake could not find the
#. **Run BitBake:** Now that you have ``BBPATH`` defined, run the
``bitbake`` command again: ::
$ bitbake
ERROR: Traceback (most recent call last):
File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
return func(fn, *args)
File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
return bb.parse.handle(fn, data, include)
File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
return h['handle'](fn, data, include)
File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
abs_fn = resolve_file(fn, data)
File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
raise IOError("file %s not found in %s" % (fn, bbpath))
IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
This sample output shows that BitBake could not find the
``conf/bitbake.conf`` file in the project directory. This file is
the first thing BitBake must find in order to build a target. And,
since the project directory for this example is empty, you need to
provide a ``conf/bitbake.conf`` file.
5. *Creating ``conf/bitbake.conf``:* The ``conf/bitbake.conf`` includes
#. **Creating conf/bitbake.conf:** The ``conf/bitbake.conf`` includes
a number of configuration variables BitBake uses for metadata and
recipe files. For this example, you need to create the file in your
project directory and define some key BitBake variables. For more
@@ -173,106 +208,100 @@ Following is the complete "Hello World" example.
http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
Use the following commands to create the ``conf`` directory in the
project directory: $ mkdir conf From within the ``conf`` directory,
project directory: ::
$ mkdir conf
From within the ``conf`` directory,
use some editor to create the ``bitbake.conf`` so that it contains
the following: :term:`PN` =
"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0]
or 'defaultpkgname'}" TMPDIR = "${:term:`TOPDIR`}/tmp"
:term:`CACHE` = "${TMPDIR}/cache"
:term:`STAMP` = "${TMPDIR}/${PN}/stamps"
:term:`T` = "${TMPDIR}/${PN}/work" :term:`B` =
"${TMPDIR}/${PN}"
the following: ::
PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
TMPDIR = "${TOPDIR}/tmp"
CACHE = "${TMPDIR}/cache"
STAMP = "${TMPDIR}/${PN}/stamps"
T = "${TMPDIR}/${PN}/work"
B = "${TMPDIR}/${PN}"
.. note::
Without a value for
PN
, the variables
STAMP
,
T
, and
B
, prevent more than one recipe from working. You can fix this by
either setting
PN
to have a value similar to what OpenEmbedded and BitBake use in
the default
bitbake.conf
file (see previous example). Or, by manually updating each recipe
to set
PN
. You will also need to include
PN
as part of the
STAMP
,
T
, and
B
variable definitions in the
local.conf
file.
Without a value for PN , the variables STAMP , T , and B , prevent more
than one recipe from working. You can fix this by either setting PN to
have a value similar to what OpenEmbedded and BitBake use in the default
bitbake.conf file (see previous example). Or, by manually updating each
recipe to set PN . You will also need to include PN as part of the STAMP
, T , and B variable definitions in the local.conf file.
The ``TMPDIR`` variable establishes a directory that BitBake uses
for build output and intermediate files other than the cached
information used by the `Setscene <#setscene>`__ process. Here, the
``TMPDIR`` directory is set to ``hello/tmp``.
information used by the
:ref:`bitbake-user-manual/bitbake-user-manual-execution:setscene`
process. Here, the ``TMPDIR`` directory is set to ``hello/tmp``.
.. note::
.. tip::
You can always safely delete the
tmp
directory in order to rebuild a BitBake target. The build process
creates the directory for you when you run BitBake.
You can always safely delete the tmp directory in order to rebuild a
BitBake target. The build process creates the directory for you when you
run BitBake.
For information about each of the other variables defined in this
example, click on the links to take you to the definitions in the
example, check :term:`PN`, :term:`TOPDIR`, :term:`CACHE`, :term:`STAMP`,
:term:`T` or :term:`B` to take you to the definitions in the
glossary.
6. *Run BitBake:* After making sure that the ``conf/bitbake.conf`` file
exists, you can run the ``bitbake`` command again: $ bitbake ERROR:
Traceback (most recent call last): File
"/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in
wrapped return func(fn, \*args) File
"/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in
\_inherit bb.parse.BBHandler.inherit(bbclass, "configuration
INHERITs", 0, data) File
"/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py",
line 92, in inherit include(fn, file, lineno, d, "inherit") File
"/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py",
line 100, in include raise ParseError("Could not %(error_out)s file
%(fn)s" % vars(), oldfn, lineno) ParseError: ParseError in
configuration INHERITs: Could not inherit file classes/base.bbclass
ERROR: Unable to parse base: ParseError in configuration INHERITs:
Could not inherit file classes/base.bbclass In the sample output,
#. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file
exists, you can run the ``bitbake`` command again: ::
$ bitbake
ERROR: Traceback (most recent call last):
File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
return func(fn, *args)
File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
include(fn, file, lineno, d, "inherit")
File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
In the sample output,
BitBake could not find the ``classes/base.bbclass`` file. You need
to create that file next.
7. *Creating ``classes/base.bbclass``:* BitBake uses class files to
#. **Creating classes/base.bbclass:** BitBake uses class files to
provide common code and functionality. The minimally required class
for BitBake is the ``classes/base.bbclass`` file. The ``base`` class
is implicitly inherited by every recipe. BitBake looks for the class
in the ``classes`` directory of the project (i.e ``hello/classes``
in this example).
Create the ``classes`` directory as follows: $ cd $HOME/hello $
mkdir classes Move to the ``classes`` directory and then create the
Create the ``classes`` directory as follows: ::
$ cd $HOME/hello
$ mkdir classes
Move to the ``classes`` directory and then create the
``base.bbclass`` file by inserting this single line: addtask build
The minimal task that BitBake runs is the ``do_build`` task. This is
all the example needs in order to build the project. Of course, the
``base.bbclass`` can have much more depending on which build
environments BitBake is supporting.
8. *Run BitBake:* After making sure that the ``classes/base.bbclass``
file exists, you can run the ``bitbake`` command again: $ bitbake
Nothing to do. Use 'bitbake world' to build everything, or run
'bitbake --help' for usage information. BitBake is finally reporting
#. **Run BitBake:** After making sure that the ``classes/base.bbclass``
file exists, you can run the ``bitbake`` command again: ::
$ bitbake
Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
BitBake is finally reporting
no errors. However, you can see that it really does not have
anything to do. You need to create a recipe that gives BitBake
something to do.
9. *Creating a Layer:* While it is not really necessary for such a
#. **Creating a Layer:** While it is not really necessary for such a
small example, it is good practice to create a layer in which to
keep your code separate from the general metadata used by BitBake.
Thus, this example creates and uses a layer called "mylayer".
@@ -285,78 +314,102 @@ Following is the complete "Hello World" example.
Minimally, you need a recipe file and a layer configuration file in
your layer. The configuration file needs to be in the ``conf``
directory inside the layer. Use these commands to set up the layer
and the ``conf`` directory: $ cd $HOME $ mkdir mylayer $ cd mylayer
$ mkdir conf Move to the ``conf`` directory and create a
``layer.conf`` file that has the following: BBPATH .=
":${:term:`LAYERDIR`}" :term:`BBFILES`
+= "${LAYERDIR}/\*.bb"
:term:`BBFILE_COLLECTIONS` += "mylayer"
`BBFILE_PATTERN_mylayer <#var-bb-BBFILE_PATTERN>`__ :=
"^${LAYERDIR_RE}/" For information on these variables, click the
links to go to the definitions in the glossary.
and the ``conf`` directory: ::
$ cd $HOME
$ mkdir mylayer
$ cd mylayer
$ mkdir conf
Move to the ``conf`` directory and create a ``layer.conf`` file that has the
following: ::
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/\*.bb"
BBFILE_COLLECTIONS += "mylayer"
`BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
For information on these variables, click on :term:`BBFILES`,
:term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
to go to the definitions in the glossary.
You need to create the recipe file next. Inside your layer at the
top-level, use an editor and create a recipe file named
``printhello.bb`` that has the following:
:term:`DESCRIPTION` = "Prints Hello World"
:term:`PN` = 'printhello' :term:`PV` = '1' python
do_build() { bb.plain("********************"); bb.plain("\* \*");
bb.plain("\* Hello, World! \*"); bb.plain("\* \*");
bb.plain("********************"); } The recipe file simply provides
``printhello.bb`` that has the following: ::
DESCRIPTION = "Prints Hello World"
PN = 'printhello'
PV = '1'
python do_build() {
bb.plain("********************");
bb.plain("* *");
bb.plain("* Hello, World! *");
bb.plain("* *");
bb.plain("********************");
}
The recipe file simply provides
a description of the recipe, the name, version, and the ``do_build``
task, which prints out "Hello World" to the console. For more
information on these variables, follow the links to the glossary.
information on :term:`DESCRIPTION`, :term:`PN` or :term:`PV`
follow the links to the glossary.
10. *Run BitBake With a Target:* Now that a BitBake target exists, run
the command and provide that target: $ cd $HOME/hello $ bitbake
printhello ERROR: no recipe files to build, check your BBPATH and
BBFILES? Summary: There was 1 ERROR message shown, returning a
non-zero exit code. We have created the layer with the recipe and
#. **Run BitBake With a Target:** Now that a BitBake target exists, run
the command and provide that target: ::
$ cd $HOME/hello
$ bitbake printhello
ERROR: no recipe files to build, check your BBPATH and BBFILES?
Summary: There was 1 ERROR message shown, returning a non-zero exit code.
We have created the layer with the recipe and
the layer configuration file but it still seems that BitBake cannot
find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists
the layers for the project. Without this file, BitBake cannot find
the recipe.
11. *Creating ``conf/bblayers.conf``:* BitBake uses the
#. **Creating conf/bblayers.conf:** BitBake uses the
``conf/bblayers.conf`` file to locate layers needed for the project.
This file must reside in the ``conf`` directory of the project (i.e.
``hello/conf`` for this example).
Set your working directory to the ``hello/conf`` directory and then
create the ``bblayers.conf`` file so that it contains the following:
BBLAYERS ?= " \\ /home/<you>/mylayer \\ " You need to provide your
own information for ``you`` in the file.
create the ``bblayers.conf`` file so that it contains the following: ::
12. *Run BitBake With a Target:* Now that you have supplied the
BBLAYERS ?= " \
/home/<you>/mylayer \
"
You need to provide your own information for ``you`` in the file.
#. **Run BitBake With a Target:** Now that you have supplied the
``bblayers.conf`` file, run the ``bitbake`` command and provide the
target: $ bitbake printhello Parsing recipes: 100%
\|##################################################################################\|
Time: 00:00:00 Parsing of 1 .bb files complete (0 cached, 1 parsed).
1 targets, 0 skipped, 0 masked, 0 errors. NOTE: Resolving any
missing task queue dependencies NOTE: Preparing RunQueue NOTE:
Executing RunQueue Tasks \*******************\* \* \* \* Hello,
World! \* \* \* \*******************\* NOTE: Tasks Summary:
Attempted 1 tasks of which 0 didn't need to be rerun and all
succeeded. BitBake finds the ``printhello`` recipe and successfully
runs the task.
target: ::
$ bitbake printhello
Parsing recipes: 100% |##################################################################################|
Time: 00:00:00
Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Executing RunQueue Tasks
********************
* *
* Hello, World! *
* *
********************
NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
.. note::
After the first execution, re-running
bitbake printhello
again will not result in a BitBake run that prints the same
console output. The reason for this is that the first time the
printhello.bb
recipe's
do_build
task executes successfully, BitBake writes a stamp file for the
task. Thus, the next time you attempt to run the task using that
same
bitbake
command, BitBake notices the stamp and therefore determines that
the task does not need to be re-run. If you delete the
tmp
directory or run
bitbake -c clean printhello
and then re-run the build, the "Hello, World!" message will be
printed again.
After the first execution, re-running bitbake printhello again will not
result in a BitBake run that prints the same console output. The reason
for this is that the first time the printhello.bb recipe's do_build task
executes successfully, BitBake writes a stamp file for the task. Thus,
the next time you attempt to run the task using that same bitbake
command, BitBake notices the stamp and therefore determines that the task
does not need to be re-run. If you delete the tmp directory or run
bitbake -c clean printhello and then re-run the build, the "Hello,
World!" message will be printed again.

316
bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
View File

@@ -248,19 +248,23 @@ underlying, similarly-named recipe files.
When you name an append file, you can use the "``%``" wildcard character
to allow for matching recipe names. For example, suppose you have an
append file named as follows: busybox_1.21.%.bbappend That append file
append file named as follows: ::
busybox_1.21.%.bbappend
That append file
would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
the append file would match the following recipe names:
busybox_1.21.1.bb busybox_1.21.2.bb busybox_1.21.3.bb
the append file would match the following recipe names: ::
busybox_1.21.1.bb
busybox_1.21.2.bb
busybox_1.21.3.bb
.. note::
The use of the "
%
" character is limited in that it only works directly in front of the
.bbappend
portion of the append file's name. You cannot use the wildcard
character in any other location of the name.
The use of the " % " character is limited in that it only works directly in
front of the .bbappend portion of the append file's name. You cannot use the
wildcard character in any other location of the name.
If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
append name would not match. However, if you named the append file
@@ -274,7 +278,7 @@ Obtaining BitBake
You can obtain BitBake several different ways:
- *Cloning BitBake:* Using Git to clone the BitBake source code
- **Cloning BitBake:** Using Git to clone the BitBake source code
repository is the recommended method for obtaining BitBake. Cloning
the repository makes it easy to get bug fixes and have access to
stable branches and the master branch. Once you have cloned BitBake,
@@ -286,36 +290,42 @@ You can obtain BitBake several different ways:
are using. The metadata is generally backwards compatible but not
forward compatible.
Here is an example that clones the BitBake repository: $ git clone
git://git.openembedded.org/bitbake This command clones the BitBake
Here is an example that clones the BitBake repository: ::
$ git clone git://git.openembedded.org/bitbake
This command clones the BitBake
Git repository into a directory called ``bitbake``. Alternatively,
you can designate a directory after the ``git clone`` command if you
want to call the new directory something other than ``bitbake``. Here
is an example that names the directory ``bbdev``: $ git clone
git://git.openembedded.org/bitbake bbdev
is an example that names the directory ``bbdev``: ::
- *Installation using your Distribution Package Management System:*
$ git clone git://git.openembedded.org/bitbake bbdev
- **Installation using your Distribution Package Management System:**
This method is not recommended because the BitBake version that is
provided by your distribution, in most cases, is several releases
behind a snapshot of the BitBake repository.
- *Taking a snapshot of BitBake:* Downloading a snapshot of BitBake
- **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake
from the source code repository gives you access to a known branch or
release of BitBake.
.. note::
.. note::
Cloning the Git repository, as described earlier, is the preferred
method for getting BitBake. Cloning the repository makes it easier
to update as patches are added to the stable branches.
Cloning the Git repository, as described earlier, is the preferred
method for getting BitBake. Cloning the repository makes it easier
to update as patches are added to the stable branches.
The following example downloads a snapshot of BitBake version 1.17.0:
$ wget
http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz $
tar zxpvf bitbake-1.17.0.tar.gz After extraction of the tarball using
The following example downloads a snapshot of BitBake version 1.17.0: ::
$ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
$ tar zxpvf bitbake-1.17.0.tar.gz
After extraction of the tarball using
the tar utility, you have a directory entitled ``bitbake-1.17.0``.
- *Using the BitBake that Comes With Your Build Checkout:* A final
- **Using the BitBake that Comes With Your Build Checkout:** A final
possibility for getting a copy of BitBake is that it already comes
with your checkout of a larger BitBake-based build system, such as
Poky. Rather than manually checking out individual layers and gluing
@@ -337,75 +347,108 @@ execution examples.
Usage and syntax
----------------
Following is the usage and syntax for BitBake: $ bitbake -h Usage:
bitbake [options] [recipename/target recipe:do_task ...] Executes the
specified task (default is 'build') for a given set of target recipes
(.bb files). It is assumed there is a conf/bblayers.conf available in
cwd or in BBPATH which will provide the layer, BBFILES and other
configuration information. Options: --version show program's version
number and exit -h, --help show this help message and exit -b BUILDFILE,
--buildfile=BUILDFILE Execute tasks from a specific .bb recipe directly.
WARNING: Does not handle any dependencies from other recipes. -k,
--continue Continue as much as possible after an error. While the target
that failed and anything depending on it cannot be built, as much as
possible will be built before stopping. -f, --force Force the specified
targets/task to run (invalidating any existing stamp file). -c CMD,
--cmd=CMD Specify the task to execute. The exact options available
depend on the metadata. Some examples might be 'compile' or
'populate_sysroot' or 'listtasks' may give a list of the tasks
available. -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
Invalidate the stamp for the specified task such as 'compile' and then
run the default task for the specified target(s). -r PREFILE,
--read=PREFILE Read the specified file before bitbake.conf. -R POSTFILE,
--postread=POSTFILE Read the specified file after bitbake.conf. -v,
--verbose Enable tracing of shell tasks (with 'set -x'). Also print
bb.note(...) messages to stdout (in addition to writing them to
${T}/log.do_<task>). -D, --debug Increase the debug level. You can
specify this more than once. -D sets the debug level to 1, where only
bb.debug(1, ...) messages are printed to stdout; -DD sets the debug
level to 2, where both bb.debug(1, ...) and bb.debug(2, ...) messages
are printed; etc. Without -D, no debug messages are printed. Note that
-D only affects output to stdout. All debug messages are written to
${T}/log.do_taskname, regardless of the debug level. -q, --quiet Output
less log message data to the terminal. You can specify this more than
once. -n, --dry-run Don't execute, just go through the motions. -S
SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER Dump out the
signature construction information, with no task execution. The
SIGNATURE_HANDLER parameter is passed to the handler. Two common values
are none and printdiff but the handler may define more/less. none means
only dump the signature, printdiff means compare the dumped signature
with the cached one. -p, --parse-only Quit after parsing the BB recipes.
-s, --show-versions Show current and preferred versions of all recipes.
-e, --environment Show the global or per-recipe environment complete
with information about where variables were set/changed. -g, --graphviz
Save dependency tree information for the specified targets in the dot
syntax. -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
Assume these dependencies don't exist and are already provided
(equivalent to ASSUME_PROVIDED). Useful to make dependency graphs more
appealing -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug
logging for the specified logging domains -P, --profile Profile the
command and save reports. -u UI, --ui=UI The user interface to use
(knotty, ncurses or taskexp - default knotty). --token=XMLRPCTOKEN
Specify the connection token to be used when connecting to a remote
server. --revisions-changed Set the exit code depending on whether
upstream floating revisions have changed or not. --server-only Run
bitbake without a UI, only starting a server (cooker) process. -B BIND,
--bind=BIND The name/address for the bitbake xmlrpc server to bind to.
-T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT Set timeout to unload
bitbake server due to inactivity, set to -1 means no unload, default:
Environment variable BB_SERVER_TIMEOUT. --no-setscene Do not run any
setscene tasks. sstate will be ignored and everything needed, built.
--setscene-only Only run setscene tasks, don't run any real tasks.
--remote-server=REMOTE_SERVER Connect to the specified server. -m,
--kill-server Terminate any running bitbake server. --observe-only
Connect to a server as an observing-only client. --status-only Check the
status of the remote bitbake server. -w WRITEEVENTLOG,
--write-log=WRITEEVENTLOG Writes the event log of the build to a bitbake
event json file. Use '' (empty string) to assign the name automatically.
--runall=RUNALL Run the specified task for any recipe in the taskgraph
of the specified target (even if it wouldn't otherwise have run).
--runonly=RUNONLY Run only the specified task within the taskgraph of
the specified targets (and any task dependencies those tasks may have).
Following is the usage and syntax for BitBake: ::
$ bitbake -h
Usage: bitbake [options] [recipename/target recipe:do_task ...]
Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
will provide the layer, BBFILES and other configuration information.
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-b BUILDFILE, --buildfile=BUILDFILE
Execute tasks from a specific .bb recipe directly.
WARNING: Does not handle any dependencies from other
recipes.
-k, --continue Continue as much as possible after an error. While the
target that failed and anything depending on it cannot
be built, as much as possible will be built before
stopping.
-f, --force Force the specified targets/task to run (invalidating
any existing stamp file).
-c CMD, --cmd=CMD Specify the task to execute. The exact options
available depend on the metadata. Some examples might
be 'compile' or 'populate_sysroot' or 'listtasks' may
give a list of the tasks available.
-C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
Invalidate the stamp for the specified task such as
'compile' and then run the default task for the
specified target(s).
-r PREFILE, --read=PREFILE
Read the specified file before bitbake.conf.
-R POSTFILE, --postread=POSTFILE
Read the specified file after bitbake.conf.
-v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
print bb.note(...) messages to stdout (in addition to
writing them to ${T}/log.do_&lt;task&gt;).
-D, --debug Increase the debug level. You can specify this more
than once. -D sets the debug level to 1, where only
bb.debug(1, ...) messages are printed to stdout; -DD
sets the debug level to 2, where both bb.debug(1, ...)
and bb.debug(2, ...) messages are printed; etc.
Without -D, no debug messages are printed. Note that
-D only affects output to stdout. All debug messages
are written to ${T}/log.do_taskname, regardless of the
debug level.
-q, --quiet Output less log message data to the terminal. You can
specify this more than once.
-n, --dry-run Don't execute, just go through the motions.
-S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
Dump out the signature construction information, with
no task execution. The SIGNATURE_HANDLER parameter is
passed to the handler. Two common values are none and
printdiff but the handler may define more/less. none
means only dump the signature, printdiff means compare
the dumped signature with the cached one.
-p, --parse-only Quit after parsing the BB recipes.
-s, --show-versions Show current and preferred versions of all recipes.
-e, --environment Show the global or per-recipe environment complete
with information about where variables were
set/changed.
-g, --graphviz Save dependency tree information for the specified
targets in the dot syntax.
-I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
Assume these dependencies don't exist and are already
provided (equivalent to ASSUME_PROVIDED). Useful to
make dependency graphs more appealing
-l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
Show debug logging for the specified logging domains
-P, --profile Profile the command and save reports.
-u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
- default knotty).
--token=XMLRPCTOKEN Specify the connection token to be used when
connecting to a remote server.
--revisions-changed Set the exit code depending on whether upstream
floating revisions have changed or not.
--server-only Run bitbake without a UI, only starting a server
(cooker) process.
-B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
to.
-T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
Set timeout to unload bitbake server due to
inactivity, set to -1 means no unload, default:
Environment variable BB_SERVER_TIMEOUT.
--no-setscene Do not run any setscene tasks. sstate will be ignored
and everything needed, built.
--setscene-only Only run setscene tasks, don't run any real tasks.
--remote-server=REMOTE_SERVER
Connect to the specified server.
-m, --kill-server Terminate any running bitbake server.
--observe-only Connect to a server as an observing-only client.
--status-only Check the status of the remote bitbake server.
-w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
Writes the event log of the build to a bitbake event
json file. Use '' (empty string) to assign the name
automatically.
--runall=RUNALL Run the specified task for any recipe in the taskgraph
of the specified target (even if it wouldn't otherwise
have run).
--runonly=RUNONLY Run only the specified task within the taskgraph of
the specified targets (and any task dependencies those
tasks may have).
.. _bitbake-examples:
@@ -426,9 +469,13 @@ default task, which is "build”. BitBake obeys inter-task dependencies
when doing so.
The following command runs the build task, which is the default task, on
the ``foo_1.0.bb`` recipe file: $ bitbake -b foo_1.0.bb The following
command runs the clean task on the ``foo.bb`` recipe file: $ bitbake -b
foo.bb -c clean
the ``foo_1.0.bb`` recipe file: ::
$ bitbake -b foo_1.0.bb
The following command runs the clean task on the ``foo.bb`` recipe file: ::
$ bitbake -b foo.bb -c clean
.. note::
@@ -450,9 +497,15 @@ functionality, or when there are multiple versions of a recipe.
The ``bitbake`` command, when not using "--buildfile" or "-b" only
accepts a "PROVIDES". You cannot provide anything else. By default, a
recipe file generally "PROVIDES" its "packagename" as shown in the
following example: $ bitbake foo This next example "PROVIDES" the
following example: ::
$ bitbake foo
This next example "PROVIDES" the
package name and also uses the "-c" option to tell BitBake to just
execute the ``do_clean`` task: $ bitbake -c clean foo
execute the ``do_clean`` task: ::
$ bitbake -c clean foo
Executing a List of Task and Recipe Combinations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -461,8 +514,9 @@ The BitBake command line supports specifying different tasks for
individual targets when you specify multiple targets. For example,
suppose you had two targets (or recipes) ``myfirstrecipe`` and
``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first
recipe and ``taskB`` for the second recipe: $ bitbake
myfirstrecipe:do_taskA mysecondrecipe:do_taskB
recipe and ``taskB`` for the second recipe: ::
$ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
Generating Dependency Graphs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -474,10 +528,10 @@ You can convert these graphs into images using the ``dot`` tool from
When you generate a dependency graph, BitBake writes two files to the
current working directory:
- *``task-depends.dot``:* Shows dependencies between tasks. These
- ``task-depends.dot``: Shows dependencies between tasks. These
dependencies match BitBake's internal task execution list.
- *``pn-buildlist``:* Shows a simple list of targets that are to be
- ``pn-buildlist``: Shows a simple list of targets that are to be
built.
To stop depending on common depends, use the "-I" depend option and
@@ -486,8 +540,11 @@ produce more readable graphs. This way, you can remove from the graph
``DEPENDS`` from inherited classes such as ``base.bbclass``.
Here are two examples that create dependency graphs. The second example
omits depends common in OpenEmbedded from the graph: $ bitbake -g foo $
bitbake -g -I virtual/kernel -I eglibc foo
omits depends common in OpenEmbedded from the graph: ::
$ bitbake -g foo
$ bitbake -g -I virtual/kernel -I eglibc foo
Executing a Multiple Configuration Build
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -504,6 +561,9 @@ files is specific. They must reside in the current build directory in a
sub-directory of ``conf`` named ``multiconfig``. Following is an example
for two separate targets:
.. image:: figures/bb_multiconfig_files.png
:align: center
The reason for this required file hierarchy is because the ``BBPATH``
variable is not constructed until the layers are parsed. Consequently,
using the configuration file as a pre-configuration file is not possible
@@ -522,14 +582,19 @@ accomplished by setting the
configuration files for ``target1`` and ``target2`` defined in the build
directory. The following statement in the ``local.conf`` file both
enables BitBake to perform multiple configuration builds and specifies
the two extra multiconfigs: BBMULTICONFIG = "target1 target2"
the two extra multiconfigs: ::
BBMULTICONFIG = "target1 target2"
Once the target configuration files are in place and BitBake has been
enabled to perform multiple configuration builds, use the following
command form to start the builds: $ bitbake [mc:multiconfigname:]target
[[[mc:multiconfigname:]target] ... ] Here is an example for two extra
multiconfigs: ``target1`` and ``target2``: $ bitbake mc::target
mc:target1:target mc:target2:target
command form to start the builds: ::
$ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
Here is an example for two extra multiconfigs: ``target1`` and ``target2``: ::
$ bitbake mc::target mc:target1:target mc:target2:target
.. _bb-enabling-multiple-configuration-build-dependencies:
@@ -548,26 +613,37 @@ multiconfig.
To enable dependencies in a multiple configuration build, you must
declare the dependencies in the recipe using the following statement
form: task_or_package[mcdepends] =
"mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
form: ::
task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
To better show how to use this statement, consider an example with two
multiconfigs: ``target1`` and ``target2``: image_task[mcdepends] =
"mc:target1:target2:image2:rootfs_task" In this example, the
from_multiconfig is "target1" and the to_multiconfig is "target2". The
multiconfigs: ``target1`` and ``target2``: ::
image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task"
In this example, the
``from_multiconfig`` is "target1" and the ``to_multiconfig`` is "target2". The
task on which the image whose recipe contains image_task depends on the
completion of the rootfs_task used to build out image2, which is
associated with the "target2" multiconfig.
Once you set up this dependency, you can build the "target1" multiconfig
using a BitBake command as follows: $ bitbake mc:target1:image1 This
command executes all the tasks needed to create image1 for the "target1"
using a BitBake command as follows: ::
$ bitbake mc:target1:image1
This command executes all the tasks needed to create ``image1`` for the "target1"
multiconfig. Because of the dependency, BitBake also executes through
the rootfs_task for the "target2" multiconfig build.
the ``rootfs_task`` for the "target2" multiconfig build.
Having a recipe depend on the root filesystem of another build might not
seem that useful. Consider this change to the statement in the image1
recipe: image_task[mcdepends] = "mc:target1:target2:image2:image_task"
In this case, BitBake must create image2 for the "target2" build since
recipe: ::
image_task[mcdepends] = "mc:target1:target2:image2:image_task"
In this case, BitBake must create ``image2`` for the "target2" build since
the "target1" build depends on it.
Because "target1" and "target2" are enabled for multiple configuration

1227
bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
View File

File diff suppressed because it is too large Load Diff

455
bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
View File

@@ -55,9 +55,11 @@ overview of their function and contents.
- Limited support for the "``*``" wildcard character for matching
against the beginning of host names exists. For example, the
following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and
``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "\*.gnu.org"
``foo.git.gnu.org``. ::
.. note::
BB_ALLOWED_NETWORKS = "\*.gnu.org"
.. important::
The use of the "``*``" character only works at the beginning of
a host name and it must be isolated from the remainder of the
@@ -111,26 +113,48 @@ overview of their function and contents.
you to control the build based on these parameters.
Disk space monitoring is disabled by default. When setting this
variable, use the following form: 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 :term:`BB_DISKMON_WARNINTERVAL`
variable, which must be defined. <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.
variable, use the following form: ::
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.
<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"
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 set the
:term:`BB_DISKMON_WARNINTERVAL`
variable. This example causes the build system to immediately abort
@@ -166,16 +190,28 @@ overview of their function and contents.
BB_DISKMON_WARNINTERVAL = "50M,5K"
When specifying the variable in your configuration file, use the
following form: 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.
following form: ::
Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause BitBake to
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 BitBake 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
@@ -186,10 +222,8 @@ overview of their function and contents.
Specifies the internal whitelist of variables to allow through from
the external environment into BitBake's datastore. If the value of
this variable is not specified (which is the default), the following
list is used: :term:`BBPATH`,
:term:`BB_PRESERVE_ENV`,
:term:`BB_ENV_WHITELIST`, and
:term:`BB_ENV_EXTRAWHITE`.
list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`,
:term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`.
.. note::
@@ -264,8 +298,9 @@ overview of their function and contents.
wishing to create a source mirror would want to enable this variable.
For performance reasons, creating and placing tarballs of the Git
repositories is not the default action by BitBake.
BB_GENERATE_MIRROR_TARBALLS = "1"
repositories is not the default action by BitBake. ::
BB_GENERATE_MIRROR_TARBALLS = "1"
BB_HASHCONFIG_WHITELIST
Lists variables that are excluded from base configuration checksum,
@@ -308,21 +343,25 @@ overview of their function and contents.
BB_LOGCONFIG
Specifies the name of a config file that contains the user logging
configuration. See `Logging <#logging>`__ for additional information
configuration. See
:ref:`bitbake-user-manual/bitbake-user-manual-execution:logging`
for additional information
BB_LOGFMT
Specifies the name of the log files saved into
``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT``
variable is undefined and the log file names get created using the
following form: log.{task}.{pid} If you want to force log files to
take a specific name, you can set this variable in a configuration
file.
following form: ::
log.{task}.{pid}
If you want to force log files to take a specific name, you can set this
variable in a configuration file.
BB_NICE_LEVEL
Allows BitBake to run at a specific priority (i.e. nice level).
System permissions usually mean that BitBake can reduce its priority
but not raise it again. See
:term:`BB_TASK_NICE_LEVEL` for
but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for
additional information.
BB_NO_NETWORK
@@ -366,9 +405,12 @@ overview of their function and contents.
Specifies the name of the executable script files (i.e. run files)
saved into ``${``\ :term:`T`\ ``}``. By default, the
``BB_RUNFMT`` variable is undefined and the run file names get
created using the following form: run.{task}.{pid} If you want to
force run files to take a specific name, you can set this variable in
a configuration file.
created using the following form: ::
run.{task}.{pid}
If you want to force run files to take a specific name, you can set this
variable in a configuration file.
BB_RUNTASK
Contains the name of the currently executing task. The value includes
@@ -423,8 +465,9 @@ overview of their function and contents.
generating checksum or dependency data for keys in the datastore, the
flags set against that key are normally included in the checksum.
For more information on varflags, see the "`Variable
Flags <#variable-flags>`__" section.
For more information on varflags, see the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`"
section.
BB_SIGNATURE_HANDLER
Defines the name of the signature handler BitBake uses. The signature
@@ -487,32 +530,30 @@ overview of their function and contents.
.. note::
This variable works similarly to the
:term:`BB_TASK_NICE_LEVEL`
This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
variable except with a task's I/O priorities.
Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For
class, the default value is "2", which is a best effort. You can use
Set the variable as follows: ::
BB_TASK_IONICE_LEVEL = "class.prio"
For *class*, the default value is "2", which is a best effort. You can use
"1" for realtime and "3" for idle. If you want to use realtime, you
must have superuser privileges.
For prio, you can use any value from "0", which is the highest
For *prio*, you can use any value from "0", which is the highest
priority, to "7", which is the lowest. The default value is "4". You
do not need any special privileges to use this range of priority
values.
.. note::
In order for your I/O priority settings to take effect, you need
the Completely Fair Queuing (CFQ) Scheduler selected for the
backing block device. To select the scheduler, use the following
command form where
device
is the device (e.g. sda, sdb, and so forth):
::
$ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
In order for your I/O priority settings to take effect, you need the
Completely Fair Queuing (CFQ) Scheduler selected for the backing block
device. To select the scheduler, use the following command form where
device is the device (e.g. sda, sdb, and so forth): ::
$ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
BB_TASK_NICE_LEVEL
Allows specific tasks to change their priority (i.e. nice level).
@@ -551,8 +592,10 @@ overview of their function and contents.
To build a different variant of the recipe with a minimal amount of
code, it usually is as simple as adding the variable to your recipe.
Here are two examples. The "native" variants are from the
OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk"
BBCLASSEXTEND =+ "multilib:multilib_name"
OpenEmbedded-Core metadata: ::
BBCLASSEXTEND =+ "native nativesdk"
BBCLASSEXTEND =+ "multilib:multilib_name"
.. note::
@@ -612,9 +655,8 @@ overview of their function and contents.
.. tip::
You can use the command
bitbake-layers show-layers
to list all configured layers along with their priorities.
You can use the command bitbake-layers show-layers to list all
configured layers along with their priorities.
BBFILES
A space-separated list of recipe files BitBake uses to build
@@ -642,11 +684,17 @@ overview of their function and contents.
BBLAYERS
Lists the layers to enable during the build. This variable is defined
in the ``bblayers.conf`` configuration file in the build directory.
Here is an example: BBLAYERS = " \\ /home/scottrif/poky/meta \\
/home/scottrif/poky/meta-yocto \\ /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``.
Here is an example: ::
BBLAYERS = " \
/home/scottrif/poky/meta \
/home/scottrif/poky/meta-yocto \
/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``.
BBLAYERS_FETCH_DIR
Sets the base location where layers are stored. This setting is used
@@ -670,13 +718,19 @@ overview of their function and contents.
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/"
``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"
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::
@@ -691,15 +745,18 @@ overview of their function and contents.
``conf/local.conf`` configuration file.
As an example, the following line specifies three multiconfigs, each
having a separate configuration file: BBMULTIFONFIG = "configA
configB configC" Each configuration file you use must reside in the
having a separate configuration file: ::
BBMULTIFONFIG = "configA configB configC"
Each configuration file you use must reside in the
build directory within a directory named ``conf/multiconfig`` (e.g.
build_directory\ ``/conf/multiconfig/configA.conf``).
For information on how to use ``BBMULTICONFIG`` in an environment
that supports building targets with multiple configurations, see the
"`Executing a Multiple Configuration
Build <#executing-a-multiple-configuration-build>`__" section.
":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
section.
BBPATH
Used by BitBake to locate class (``.bbclass``) and configuration
@@ -709,7 +766,11 @@ overview of their function and contents.
If you run BitBake from a directory outside of the build directory,
you must be sure to set ``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
BitBake: ::
$ BBPATH="build_directory"
$ export BBPATH
$ bitbake target
BBSERVER
Points to the server that runs memory-resident BitBake. The variable
@@ -725,8 +786,8 @@ overview of their function and contents.
using the :term:`OVERRIDES` mechanism for a
single version or for an optionally named range of versions.
For more information on ``BBVERSIONS``, see the "`Variants - Class
Extension Mechanism <#variants-class-extension-mechanism>`__"
For more information on ``BBVERSIONS``, see the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`"
section.
BITBAKE_UI
@@ -765,37 +826,35 @@ overview of their function and contents.
.. note::
The bias provided by
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.
The bias provided by 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.
DEPENDS
Lists a recipe's build-time dependencies (i.e. other recipe files).
Consider this simple example for two recipes named "a" and "b" that
produce similarly named packages. In this example, the ``DEPENDS``
statement appears in the "a" recipe: DEPENDS = "b" Here, the
dependency is such that the ``do_configure`` task for recipe "a"
depends on the ``do_populate_sysroot`` task of recipe "b". This means
anything that recipe "b" puts into sysroot is available when recipe
"a" is configuring itself.
statement appears in the "a" recipe: ::
For information on runtime dependencies, see the
:term:`RDEPENDS` variable.
DEPENDS = "b"
Here, the dependency is such that the ``do_configure`` task for recipe "a"
depends on the ``do_populate_sysroot`` task of recipe "b". This means
anything that recipe "b" puts into sysroot is available when recipe "a" is
configuring itself.
For information on runtime dependencies, see the :term:`RDEPENDS`
variable.
DESCRIPTION
A long description for the recipe.
DL_DIR
The central download directory used by the build process to store
downloads. By default, ``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.
downloads. By default, ``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.
EXCLUDE_FROM_WORLD
Directs BitBake to exclude a recipe from world builds (i.e.
@@ -808,13 +867,10 @@ overview of their function and contents.
.. note::
Recipes added to
EXCLUDE_FROM_WORLD
may still be built during a world build in order to satisfy
dependencies of other recipes. Adding a recipe to
EXCLUDE_FROM_WORLD
only ensures that the recipe is not explicitly added to the list
of build targets in a world build.
Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world
build in order to satisfy dependencies of other recipes. Adding a
recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not
explicitly added to the list of build targets in a world build.
FAKEROOT
Contains the command to use when running a shell script in a fakeroot
@@ -883,8 +939,8 @@ overview of their function and contents.
configuration and in each individual recipe. The OpenEmbedded build
system ignores changes to ``INHERIT`` in individual recipes.
For more information on ``INHERIT``, see the "```INHERIT``
Configuration Directive <#inherit-configuration-directive>`__"
For more information on ``INHERIT``, see the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
section.
LAYERDEPENDS
@@ -953,8 +1009,9 @@ overview of their function and contents.
Following is a simple example that uses an overrides list based on
machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
find information on how to use ``OVERRIDES`` in the "`Conditional
Syntax (Overrides) <#conditional-syntax-overrides>`__" section.
find information on how to use ``OVERRIDES`` in the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
(overrides)`" section.
P4DIR
The directory in which a local copy of a Perforce depot is stored
@@ -1000,20 +1057,26 @@ overview of their function and contents.
recipes provide the same item. You should always suffix the variable
with the name of the provided item, and you should set it to the
:term:`PN` of the recipe to which you want to give
precedence. Some examples: PREFERRED_PROVIDER_virtual/kernel ?=
"linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
precedence. Some examples: ::
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
PREFERRED_PROVIDERS
Determines which recipe should be given preference for cases where
multiple recipes provide the same item. Functionally,
``PREFERRED_PROVIDERS`` is identical to
:term:`PREFERRED_PROVIDER`. However, the
``PREFERRED_PROVIDERS`` variable lets you define preferences for
multiple situations using the following form: PREFERRED_PROVIDERS =
"xxx:yyy aaa:bbb ..." This form is a convenient replacement for the
following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa =
"bbb"
:term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable
lets you define preferences for multiple situations using the following
form: ::
PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
This form is a convenient replacement for the following: ::
PREFERRED_PROVIDER_xxx = "yyy"
PREFERRED_PROVIDER_aaa = "bbb"
PREFERRED_VERSION
If there are multiple versions of recipes available, this variable
@@ -1026,15 +1089,15 @@ overview of their function and contents.
through the "``%``" character. You can use the character to match any
number of characters, which can be useful when specifying versions
that contain long revision numbers that potentially change. Here are
two examples: PREFERRED_VERSION_python = "2.7.3"
PREFERRED_VERSION_linux-yocto = "4.12%"
two examples: ::
.. note::
PREFERRED_VERSION_python = "2.7.3"
PREFERRED_VERSION_linux-yocto = "4.12%"
The use of the "
%
" character is limited in that it only works at the end of the
string. You cannot use the wildcard character in any other
.. important::
The use of the " % " character is limited in that it only works at the
end of the string. You cannot use the wildcard character in any other
location of the string.
PREMIRRORS
@@ -1042,19 +1105,21 @@ overview of their function and contents.
the build system searches for source code, it first tries the local
download directory. If that location fails, the build system tries
locations defined by ``PREMIRRORS``, the upstream source, and then
locations specified by :term:`MIRRORS` in that
order.
locations specified by :term:`MIRRORS` in that order.
Typically, you would add a specific server for the build system to
attempt before any others by adding something like the following to
your configuration: PREMIRRORS_prepend = "\\ git://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
http://www.yoctoproject.org/sources/ \\n" These changes cause the
build system to intercept Git, FTP, HTTP, and HTTPS requests and
direct them to the ``http://`` sources mirror. You can use
``file://`` URLs to point to local directories or network shares as
your configuration: ::
PREMIRRORS_prepend = "\
git://.*/.* http://www.yoctoproject.org/sources/ \n \
ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
http://.*/.* http://www.yoctoproject.org/sources/ \n \
https://.*/.* http://www.yoctoproject.org/sources/ \n"
These changes cause the build system to intercept Git, FTP, HTTP, and
HTTPS requests and direct them to the ``http://`` sources mirror. You can
use ``file://`` URLs to point to local directories or network shares as
well.
PROVIDES
@@ -1066,9 +1131,12 @@ overview of their function and contents.
``DEPENDS``.
Consider the following example ``PROVIDES`` statement from a recipe
file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES``
statement results in the "libav" recipe also being known as
"libpostproc".
file ``libav_0.8.11.bb``: ::
PROVIDES += "libpostproc"
The ``PROVIDES`` statement results in the "libav" recipe also being known
as "libpostproc".
In addition to providing recipes under alternate names, the
``PROVIDES`` mechanism is also used to implement virtual targets. A
@@ -1086,10 +1154,13 @@ overview of their function and contents.
PRSERV_HOST
The network based :term:`PR` service host and port.
Following is an example of how the ``PRSERV_HOST`` variable is set:
PRSERV_HOST = "localhost:0" You must set the variable if you want to
automatically start a local PR service. You can set ``PRSERV_HOST``
to other values to use a remote PR service.
Following is an example of how the ``PRSERV_HOST`` variable is set: ::
PRSERV_HOST = "localhost:0"
You must set the variable if you want to automatically start a local PR
service. You can set ``PRSERV_HOST`` to other values to use a remote PR
service.
PV
The version of the recipe.
@@ -1104,21 +1175,36 @@ overview of their function and contents.
you should always use the variable in a form with an attached package
name. For example, suppose you are building a development package
that depends on the ``perl`` package. In this case, you would use the
following ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the
example, the development package depends on the ``perl`` package.
Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as
part of the variable.
following ``RDEPENDS`` statement: ::
RDEPENDS_${PN}-dev += "perl"
In the example, the development package depends on the ``perl`` package.
Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part
of the variable.
BitBake supports specifying versioned dependencies. Although the
syntax varies depending on the packaging format, BitBake hides these
differences from you. Here is the general syntax to specify versions
with the ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator
version)" For ``operator``, you can specify the following: = < > <=
>= For example, the following sets up a dependency on version 1.2 or
greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
with the ``RDEPENDS`` variable: ::
For information on build-time dependencies, see the
:term:`DEPENDS` variable.
RDEPENDS_${PN} = "package (operator version)"
For ``operator``, you can specify the following: ::
=
<
>
<=
>=
For example, the following sets up a dependency on version 1.2 or
greater of the package ``foo``: ::
RDEPENDS_${PN} = "foo (>= 1.2)"
For information on build-time dependencies, see the :term:`DEPENDS`
variable.
REPODIR
The directory in which a local copy of a ``google-repo`` directory is
@@ -1132,7 +1218,9 @@ overview of their function and contents.
As with all package-controlling variables, you must always use the
variable in conjunction with a package name override. Here is an
example: RPROVIDES_${PN} = "widget-abi-2"
example: ::
RPROVIDES_${PN} = "widget-abi-2"
RRECOMMENDS
A list of packages that extends the usability of a package being
@@ -1144,11 +1232,22 @@ overview of their function and contents.
BitBake supports specifying versioned recommends. Although the syntax
varies depending on the packaging format, BitBake hides these
differences from you. Here is the general syntax to specify versions
with the ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package
(operator version)" For ``operator``, you can specify the following:
= < > <= >= For example, the following sets up a recommend on version
1.2 or greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>=
1.2)"
with the ``RRECOMMENDS`` variable: ::
RRECOMMENDS_${PN} = "package (operator version)"
For ``operator``, you can specify the following: ::
=
<
>
<=
>=
For example, the following sets up a recommend on version
1.2 or greater of the package ``foo``: ::
RRECOMMENDS_${PN} = "foo (>= 1.2)"
SECTION
The section in which packages should be categorized.
@@ -1165,56 +1264,56 @@ overview of their function and contents.
The following list explains the available URI protocols:
- *``file://`` -* Fetches files, which are usually files shipped
- ``file://`` : Fetches files, which are usually files shipped
with the metadata, from the local machine. The path is relative to
the :term:`FILESPATH` variable.
- *``bzr://`` -* Fetches files from a Bazaar revision control
- ``bzr://`` : Fetches files from a Bazaar revision control
repository.
- *``git://`` -* Fetches files from a Git revision control
- ``git://`` : Fetches files from a Git revision control
repository.
- *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service)
- ``osc://`` : Fetches files from an OSC (OpenSUSE Build service)
revision control repository.
- *``repo://`` -* Fetches files from a repo (Git) repository.
- ``repo://`` : Fetches files from a repo (Git) repository.
- *``http://`` -* Fetches files from the Internet using HTTP.
- ``http://`` : Fetches files from the Internet using HTTP.
- *``https://`` -* Fetches files from the Internet using HTTPS.
- ``https://`` : Fetches files from the Internet using HTTPS.
- *``ftp://`` -* Fetches files from the Internet using FTP.
- ``ftp://`` : Fetches files from the Internet using FTP.
- *``cvs://`` -* Fetches files from a CVS revision control
- ``cvs://`` : Fetches files from a CVS revision control
repository.
- *``hg://`` -* Fetches files from a Mercurial (``hg``) revision
- ``hg://`` : Fetches files from a Mercurial (``hg``) revision
control repository.
- *``p4://`` -* Fetches files from a Perforce (``p4``) revision
- ``p4://`` : Fetches files from a Perforce (``p4``) revision
control repository.
- *``ssh://`` -* Fetches files from a secure shell.
- ``ssh://`` : Fetches files from a secure shell.
- *``svn://`` -* Fetches files from a Subversion (``svn``) revision
- ``svn://`` : Fetches files from a Subversion (``svn``) revision
control repository.
Here are some additional options worth mentioning:
- *``unpack`` -* Controls whether or not to unpack the file if it is
- ``unpack`` : Controls whether or not to unpack the file if it is
an archive. The default action is to unpack the file.
- *``subdir`` -* Places the file (or extracts its contents) into the
- ``subdir`` : Places the file (or extracts its contents) into the
specified subdirectory. This option is useful for unusual tarballs
or other archives that do not have their files already in a
subdirectory within the archive.
- *``name`` -* Specifies a name to be used for association with
- ``name`` : Specifies a name to be used for association with
``SRC_URI`` checksums when you have more than one file specified
in ``SRC_URI``.
- *``downloadfilename`` -* Specifies the filename used when storing
- ``downloadfilename`` : Specifies the filename used when storing
the downloaded file.
SRCDATE