diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
deleted file mode 100644
index 5c301a56f3..0000000000
--- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
+++ /dev/null
@@ -1,341 +0,0 @@
-
-
-
- The BitBake Command
-
-
- BitBake is the underlying piece of the build system.
- Two excellent examples are the Yocto Project and the OpenEmbedded
- build systems.
- Each provide an environment in which to develop embedded Linux
- images, and each use BitBake as their underlying build engine.
-
-
-
- BitBake facilitates executing tasks in a single .bb
- file, or executing a given task on a set of multiple
- .bb files, accounting for interdependencies
- amongst them.
- This chapter presents the BitBake syntax, provides some execution
- examples, and shows you how to control BitBake with key metadata.
-
-
-
- Usage and syntax
-
-
- Following is the usage and syntax for BitBake:
-
- $ bitbake -h
-Usage: bitbake [options] [recipename/target ...]
-
- 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.
- -a, --tryaltconfigs Continue with builds by trying to use alternative
- providers where possible.
- -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 Output more log message data to the terminal.
- -D, --debug Increase the debug level. You can specify this more
- than once.
- -n, --dry-run Don't execute, just go through the motions.
- -S, --dump-signatures
- Don't execute, just dump out the signature
- construction information.
- -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-package 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 (e.g. knotty, hob, depexp).
- -t SERVERTYPE, --servertype=SERVERTYPE
- Choose which server to use, process or xmlrpc.
- --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 server to bind to.
- --no-setscene Do not run any setscene tasks. sstate will be ignored
- and everything needed, built.
- --remote-server=REMOTE_SERVER
- Connect to the specified server.
- -m, --kill-server Terminate the remote server.
- --observe-only Connect to a server as an observing-only client.
- --status-only Check the status of the remote bitbake server.
-
-
-
-
-
-
- Examples
-
-
- This section presents some examples showing how to use BitBake.
-
-
-
- Executing a Task Against a Single Recipe
-
-
- Executing tasks for a single recipe file is relatively simple.
- You specify the file in question, and BitBake parses
- it and executes the specified task.
- If you do not specify a task, BitBake executes the default
- task, which is "build”.
- BitBake obeys inter-task dependencies when doing
- so.
-
-
-
- The following command runs the clean task on the
- foo_1.0.bb recipe file:
-
- $ bitbake -b foo.bb -c clean
-
- 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
-
-
-
-
-
- Executing Tasks Against a Set of Recipe Files
-
-
- There are a number of additional complexities introduced
- when one wants to manage multiple .bb
- files.
- Clearly there needs to be a way to tell BitBake what
- files are available, and of those, which you
- want to execute.
- There also needs to be a way for each recipe
- to express its dependencies, both for build-time and
- runtime.
- There must be a way for you to express recipe preferences
- when multiple recipes provide the same functionality, or when
- there are multiple versions of a recipe.
-
-
-
- The bitbake command, when not using
- "--buildfile" or "-b" only accepts a "PROVIDER".
- You cannot provide anything else.
- By default, a recipe file generally "PROVIDES" its
- "packagename", "packagename-version", and
- "packagename-version-revision" as shown in the following
- example:
-
- $ bitbake foo
-
- $ bitbake foo-1.0
-
- $ bitbake foo-1.0-r0
-
- This next example "PROVIDES" the package name and also uses
- the "-c" option to tell BitBake to just excute the
- do_clean task:
-
- $ bitbake -c clean foo
-
-
-
-
-
- Generating Dependency Graphs
-
-
- BitBake is able to generate dependency graphs using
- the dot syntax.
- You can convert these graphs into images using the dot
- application from
- Graphviz.
-
-
-
- When you generate a dependency graph, BitBake writes two files
- to the current working directory:
- depends.dot, which contains dependency information
- at the package level, and task-depends.dot,
- which contains a breakdown of the dependencies at the task level.
-
-
-
- To stop depending on common depends, use use the "-I" depend
- option and BitBake omits them from the graph.
- Leaving this information out can produce more readable graphs.
- This way, you can remove from the graph
- DEPENDS from inherited classes
- such as base.bbclass.
-
-
-
- Here are two exmples that create dependency graphs.
- The second example omits common depends from the graph:
-
- $ bitbake -g foo
-
- $ bitbake -g -I virtual/whatever -I bloom foo
-
-
-
-
-
-
- Controlling BitBake
-
-
- Including variables in your recipe and class files help control
- how BitBake operates.
-
-
-
- Execution Threads
-
-
- You can control how many thread BitBake supports by using the
- BB_NUMBER_THREADS
- variable.
- You would set this in your local.conf
- configuration file.
-
-
-
-
- Using <filename>PROVIDES</filename>
-
-
- This example shows the usage of the
- PROVIDES variable, which allows a
- given .bb to specify what
- functionality it provides.
-
- package1.bb:
-
- PROVIDES += "virtual/package"
-
- package2.bb:
-
- DEPENDS += "virtual/package"
-
- package3.bb:
-
- PROVIDES += "virtual/package"
-
- As you can see, we have two different
- recipes that provide the same functionality
- (virtual/package).
- Clearly, there needs to be a way for the person running
- BitBake to control which of those providers
- gets used.
- There is, indeed, such a way.
-
-
-
- The following would go into a .conf
- file, to select package1:
-
- PREFERRED_PROVIDER_virtual/package = "package1"
-
-
-
-
-
- Specifying Version Preference
-
-
- When there are multiple “versions” of a given package,
- BitBake defaults to selecting the most recent
- version, unless otherwise specified.
- If the .bb in question has a
- DEFAULT_PREFERENCE set lower than
- the other recipes (default is 0), then it will not be
- selected.
- This allows the person or persons maintaining
- the repository of .bb files to specify
- their preference for the default selected version.
- In addition, the user can specify their preferred version.
-
-
-
- If the first .bb is named
- a_1.1.bb, then the
- PN variable will be set to
- “a”, and the PV variable will be
- set to 1.1.
-
-
-
- If we then have an a_1.2.bb, BitBake
- will choose 1.2 by default.
- However, if we define the following variable in a
- .conf file that BitBake parses, we
- can change that.
-
- PREFERRED_VERSION_a = "1.1"
-
-
-
-
-
- Using Recipe File Collections
-
-
- 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"
-
-
-
-
-
diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index e9f19be6de..148ac3e38a 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -23,11 +23,19 @@
$ bitbake <target>
For information on the BitBake command and its options,
- see the
- "BitBake Command
- chapter.
+ see
+ "The BitBake Command"
+ section.
+
+ Prior to executing BitBake, you should take advantage of parallel
+ thread execution by setting the
+ BB_NUMBER_THREADS
+ variable in your local.conf
+ configuration file.
+
+
Parsing the Base Configuration Metadata
@@ -103,10 +111,13 @@
BB_ENV_WHITELISTBB_PRESERVE_ENVBB_ENV_EXTRAWHITE
- BB_ORIGENV
- PREFERRED_VERSION
- PREFERRED_PROVIDERS
+
+ BITBAKE_UI
+
+ You can find information on how to pass environment variables into the BitBake
+ execution environment in the
+ "Passing Information Into the Build Task Environment" section.
@@ -146,11 +157,15 @@
Only variable definitions and include directives are allowed
in .conf files.
- The following variables include:
+ 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.
+ See the
+ "Variables Glossary"
+ for a full list of variables.
+ The following list shows common variables set:
-
- BITBAKE_UI
- BBDEBUG
@@ -196,6 +211,8 @@
BBMASK
+ PREFERRED_VERSION
+ PREFERRED_PROVIDERS
@@ -234,8 +251,7 @@
Locating and Parsing Recipes
- During the configuration phase, BitBake will have
- set
+ During the configuration phase, BitBake will have set
BBFILES.
BitBake now uses it to construct a list of recipes to parse,
along with any append files (.bbappend)
@@ -244,7 +260,7 @@
available files and supports wildcards.
An example would be:
- BBFILES = "/path/to/bbfiles/*.bb"
+ BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
BitBake parses each recipe and append file located
with BBFILES and stores the values of
@@ -279,7 +295,8 @@
By the time parsing is complete for a recipe, BitBake
has a list of tasks that the recipe defines and a set of
- data consisting of keys and values.
+ data consisting of keys and values as well as
+ dependency information about the tasks.
@@ -287,16 +304,48 @@
It only needs a small subset of the information to make
decisions about the recipe.
Consequently, BitBake caches the values in which it is
- interested.
+ interested and does not store the rest of the information.
+ Experience has shown it's faster to re-parse the metadata than to
+ try and write it out to the disk and reload then it.
- Subsequent BitBake commands then parse the base
- configuration and compute a checksum of that data.
- If that checksum matches what is in the cache, the
- recipe and class files have not changed.
- In this case, BitBake reloads the cached information
- about the recipe instead of reparsing it from scratch.
+ Where possible, subsequent BitBake commands reuse this cache of
+ recipe information.
+ The validity of this cache is determined by first computing a
+ checksum of the base configuration data (see
+ BB_HASHCONFIG_WHITELIST)
+ and then checking if the checksum matches.
+ If that checksum matches what is in the cache and the recipe
+ and class files have not changed, Bitbake is able to use
+ the cache.
+ BitBake then reloads the cached information about the recipe
+ instead of reparsing it from scratch.
+
+
+
+ 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"
+
+
+ The layers mechanism is now the preferred method of collecting
+ code.
+ While the collections code remains, its main use is to set layer
+ priorities and to deal with overlap (conflicts) between layers.
+
@@ -304,37 +353,59 @@
Preferences and Providers
- Assuming BitBake has been instructed to execute a target and
- that all the recipe files have been parsed, BitBake starts to
- build the target and look for providers of that target.
- Once a provider is selected, BitBake resolves all the dependencies for
- the target.
- As an example, suppose the target is
- core-image-sato.
- In this case, it would lead to
- packagegroup-core-x11-sato,
- which in turn leads to recipes like matchbox-terminal,
- pcmanfm and gthumb.
- These recipes in turn depend on eglibc and the toolchain.
+ Assuming BitBake has been instructed to execute a target
+ and that all the recipe files have been parsed, BitBake
+ starts to figure out how to build the target.
+ BitBake starts by looking through the
+ PROVIDES
+ set in recipe files.
+ The default PROVIDES for a recipe is its name
+ (PN),
+ however, a recipe can provide multiple things.
+
+
+
+ As an example of adding an extra provider, suppose a recipe named
+ package1.bb contained the following:
+
+ PROVIDES += "virtual/package"
+
+ The recipe now provides both "package1" and "virtual/package.
+ The "virtual/" namespace is often used to denote cases where
+ multiple providers are expected with the user choosing between
+ them.
+ Kernels and toolchain components are common cases of this in
+ OpenEmbedded.
Sometimes a target might have multiple providers.
- A common example is "virtual/kernel", which is provided by each kernel package.
- Each machine often selects the best kernel provider by using a line similar to the
- following in the machine configuration file:
-
-
-
+ A common example is "virtual/kernel", which is provided by 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
PREFERRED_PROVIDER
is the provider with the same name as the target.
+
+ Bitbake iterates through each target it needs to build and resolve
+ them using this process.
+ As an example, suppose the target is
+ core-image-sato.
+ In this case, it would lead to
+ packagegroup-core-x11-sato,
+ which in turn leads to recipes like
+ matchbox-terminal, pcmanfm
+ and gthumb.
+ These recipes in turn depend on eglibc
+ and the toolchain.
+
+
Understanding how providers are chosen is made complicated by the fact
that multiple versions might exist.
@@ -358,6 +429,41 @@
In summary, BitBake has created a list of providers, which is prioritized, for each target.
+
+
+ When there are multiple “versions” of a given package,
+ BitBake defaults to selecting the most recent
+ version, unless otherwise specified.
+ If the recipe in question has a
+ DEFAULT_PREFERENCE
+ set lower than
+ the other recipes (default is 0), then it will not be
+ selected.
+ This allows the person or persons maintaining
+ the repository of recipe files to specify
+ their preference for the default selected version.
+ In addition, the user can specify their preferred version.
+
+
+
+ If the first recipe is named a_1.1.bb,
+ then the
+ PN variable
+ will be set to “a”, and the
+ PV
+ variable will be set to 1.1.
+
+
+
+ If we then have a recipe named a_1.2.bb, BitBake
+ will choose 1.2 by default.
+ However, if we define the following variable in a
+ .conf file that BitBake parses, we
+ can change that.
+
+ PREFERRED_VERSION_a = "1.1"
+
+
@@ -422,7 +528,20 @@
compile timestamp for a given target, then the compile task would rerun.
Running the compile task again, however, has no effect on other providers
that depend on that target.
- This behavior could change or become configurable in future versions of BitBake.
+
+
+
+ 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)"
+ 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.
@@ -462,7 +581,12 @@
- Variables specific to scheduling functionality exist:
+ The order in which BitBake runs the tasks is controlled by its
+ task scheduler.
+ It is possible to configure the scheduler and define custom
+ implementations for specific use cases.
+ For more information, see these variables that control the
+ behavior:
BB_SCHEDULER
@@ -471,22 +595,10 @@
BB_SCHEDULERS
-
-
-
-
- Setscene
-
-
- This section needs to get the concept of the setscene across.
- The reader needs to know what it is and what it is used for during
- the build process.
-
-
-
- You can find more information on setscene metadata in the
- "Task Checksums and Setscene"
- section.
+ It is possible to have functions run before and after a task's main
+ function.
+ This is done using the "prefuncs" and "postfuncs" flags of the task
+ that lists the functions to run.
@@ -495,10 +607,10 @@
A checksum is a unique signature of a task's inputs.
- The setscene code uses a checksum to determine if a task needs
- to be run.
+ The signature of a task can be used to determine if a task
+ needs to be run.
Because it is a change in a task's inputs that triggers running
- the task, the process needs to detect all the inputs to a given task.
+ the task, BitBake needs to detect all the inputs to a given task.
For shell tasks, this turns out to be fairly easy because
BitBake generates a "run" shell script for each task and
it is possible to create a checksum that gives you a good idea of when
@@ -514,6 +626,10 @@
affect the output for target packages.
The simplistic approach for excluding the working directory is to set
it to some fixed value and create the checksum for the "run" script.
+ BitBake goes one step better and uses the
+ BB_HASHBASE_WHITELIST
+ variable to define a list of variables that should never be included
+ when generating the signatures.
@@ -652,4 +768,87 @@
section.
+
+
+ Setscene
+
+
+ The setscene process enables BitBake to handle "pre-built" artifacts.
+ The ability to handle and reuse these artifacts allows BitBake
+ the luxury of not having to build something from scratch every time.
+ Instead, BitBake can use, when possible, existing build artifacts.
+
+
+
+ BitBake needs to have reliable data indicating whether or not an
+ artifact is compatible.
+ Signatures, described in the previous section, provide an ideal
+ way of representing whether an artifact is compatible.
+ If a signature is the same, an object can be reused.
+
+
+
+ If an object can be reused, the problem then becomes how to
+ replace a given task or set of tasks with the pre-built artifact.
+ BitBake solves the problem with the "setscene" process.
+
+
+
+ When BitBake is asked to build a given target, before building anything,
+ it first asks whether cached information is available for any of the
+ targets it's building, or any of the intermediate targets.
+ If cached information is available, BitBake uses this information instead of
+ running the main tasks.
+
+
+
+ BitBake first calls the function defined by the
+ BB_HASHCHECK_FUNCTION
+ variable with a list of tasks and corresponding
+ hashes it wants to build.
+ This function is designed to be fast and returns a list
+ of the tasks for which it believes in can obtain artifacts.
+
+
+
+ Next, for each of the tasks that were returned as possibilities,
+ BitBake executes a setscene version of the task that the possible
+ artifact covers.
+ Setscene versions of a task have the string "_setscene" appended to the
+ task name.
+ So, for example, the task with the name xxx has
+ a setscene task named xxx_setscene.
+ The setscene version of the task executes and provides the necessary
+ artifacts returning either success or failure.
+
+ Artifacts might need to be fetched from the network.
+
+
+
+
+ As previously mentioned, an artifact can cover more than one task.
+ For example, it is pointless to obtain a compiler if you
+ already have the compiled binary.
+ To handle this, BitBake calls the
+ BB_SETSCENE_DEPVALID
+ function for each successful setscene task to know whether or not it needs
+ to obtain the dependencies of that task.
+
+
+
+ Finally, after all the setscene tasks have executed, BitBake calls the
+ function listed in
+ BB_SETSCENE_VERIFY_FUNCTION
+ 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"
+ section.
+
+
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index 87951fd4b4..b4c1aa21d8 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -31,7 +31,7 @@
perhaps in a specific way.
Getting and unpacking the files is often optionally followed
by patching.
- Patching, however, is not covered by the fetch.
+ Patching, however, is not covered by this module.
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index c1a9aed3a5..6f9ad2049a 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -322,6 +322,29 @@
Information in append files overrides the information in the
similarly-named recipe file.
+
+
+ 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 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
+
+ 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
+ busybox_1.%.bb, then you would have a match.
+
@@ -373,7 +396,13 @@
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.
+ branch or release of BitBake.
+
+ 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:
@@ -387,4 +416,223 @@
+
+
+ The BitBake Command
+
+
+ BitBake is the underlying piece of the build system.
+ Two excellent examples are the Yocto Project and the OpenEmbedded
+ build systems.
+ Each provide an environment in which to develop embedded Linux
+ images, and each use BitBake as their underlying build engine.
+
+
+
+ BitBake facilitates executing tasks in a single .bb
+ file, or executing a given task on a set of multiple
+ .bb files, accounting for interdependencies
+ amongst them.
+ This section presents the BitBake syntax and provides some execution
+ examples.
+
+
+
+ Usage and syntax
+
+
+ Following is the usage and syntax for BitBake:
+
+ $ bitbake -h
+Usage: bitbake [options] [recipename/target ...]
+
+ 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.
+ -a, --tryaltconfigs Continue with builds by trying to use alternative
+ providers where possible.
+ -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 Output more log message data to the terminal.
+ -D, --debug Increase the debug level. You can specify this more
+ than once.
+ -n, --dry-run Don't execute, just go through the motions.
+ -S, --dump-signatures
+ Don't execute, just dump out the signature
+ construction information.
+ -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-package 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 (e.g. knotty, hob, depexp).
+ -t SERVERTYPE, --servertype=SERVERTYPE
+ Choose which server to use, process or xmlrpc.
+ --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 server to bind to.
+ --no-setscene Do not run any setscene tasks. sstate will be ignored
+ and everything needed, built.
+ --remote-server=REMOTE_SERVER
+ Connect to the specified server.
+ -m, --kill-server Terminate the remote server.
+ --observe-only Connect to a server as an observing-only client.
+ --status-only Check the status of the remote bitbake server.
+
+
+
+
+
+
+ Examples
+
+
+ This section presents some examples showing how to use BitBake.
+
+
+
+ Executing a Task Against a Single Recipe
+
+
+ Executing tasks for a single recipe file is relatively simple.
+ You specify the file in question, and BitBake parses
+ it and executes the specified task.
+ If you do not specify a task, BitBake executes the default
+ task, which is "build”.
+ BitBake obeys inter-task dependencies when doing
+ so.
+
+
+
+ The following command runs the clean task on the
+ foo_1.0.bb recipe file:
+
+ $ bitbake -b foo.bb -c clean
+
+ 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
+
+
+
+
+
+ Executing Tasks Against a Set of Recipe Files
+
+
+ There are a number of additional complexities introduced
+ when one wants to manage multiple .bb
+ files.
+ Clearly there needs to be a way to tell BitBake what
+ files are available, and of those, which you
+ want to execute.
+ There also needs to be a way for each recipe
+ to express its dependencies, both for build-time and
+ runtime.
+ There must be a way for you to express recipe preferences
+ when multiple recipes provide the same functionality, or when
+ there are multiple versions of a recipe.
+
+
+
+ The bitbake command, when not using
+ "--buildfile" or "-b" only accepts a "PROVIDER".
+ You cannot provide anything else.
+ By default, a recipe file generally "PROVIDES" its
+ "packagename", "packagename-version", and
+ "packagename-version-revision" as shown in the following
+ example:
+
+ $ bitbake foo
+
+ $ bitbake foo-1.0
+
+ $ bitbake foo-1.0-r0
+
+ 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
+
+
+
+
+
+ Generating Dependency Graphs
+
+
+ BitBake is able to generate dependency graphs using
+ the dot syntax.
+ You can convert these graphs into images using the dot
+ application from
+ Graphviz.
+
+
+
+ When you generate a dependency graph, BitBake writes two files
+ to the current working directory:
+ depends.dot, which contains dependency information
+ at the package level, and task-depends.dot,
+ which contains a breakdown of the dependencies at the task level.
+
+
+
+ To stop depending on common depends, use use the "-I" depend
+ option and BitBake omits them from the graph.
+ Leaving this information out can 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 common depends from the graph:
+
+ $ bitbake -g foo
+
+ $ bitbake -g -I virtual/whatever -I bloom foo
+
+
+
+
+
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index cabf25fb6f..9cd8bf0e68 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -819,6 +819,20 @@
+
+ Deleting a Task
+
+
+ As well as being able to add tasks, tasks can also be deleted.
+ This is done simply with deltask command.
+ For example, to delete the example task used in the previous
+ sections, you would use:
+
+ deltask printdate
+
+
+
+
Passing Information Into the Build Task Environment
@@ -867,6 +881,28 @@
+
+
+ Sometimes, its useful to be able to obtain information
+ from the original execution environment.
+ Bitbake saves a copy of the original environment into
+ a special variable named
+ BB_ORIGENV.
+
+
+
+ The BB_ORIGENV variable returns a datastore
+ object that can be queried using the standard datastore operators
+ such as getVar().
+ The datastore object is useful, for example, to find the original
+ DISPLAY variable.
+
+
+
+ By default, BitBake cleans the environment to include only those
+ things exported or listed in its whitelist to ensure that the build
+ environment is reproducible and consistent.
+
@@ -975,6 +1011,17 @@
"Inter-Task Dependencies"
section for more information.
+ postfuncs:
+ List of functions to call after the completion of the task.
+
+ prefuncs:
+ List of functions to call before the task executes.
+
+ stamp-extra-info:
+ Extra stamp information to append to the task's stamp
+ As an example, OpenEmbedded uses this flag to allow
+ machine-specific tasks.
+
@@ -1016,7 +1063,7 @@
- During all builds, the following common events occur:
+ During a standard build, the following common events might occur:
bb.event.ConfigParsed()
@@ -1100,7 +1147,19 @@
BBCLASSEXTEND
and
BBVERSIONS
- variables:
+ variables.
+
+ The mechanism for this class extension is extremely
+ specific to the implementation.
+ Usually, the recipe's
+ PROVIDES,
+ PN, and
+ DEPENDS
+ variables would need to be modified by the extension class.
+ For specific examples, see the OE-Core
+ native, nativesdk,
+ and multilib classes.
+ BBCLASSEXTEND:
This variable is a space separated list of classes used to "extend" the
diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml
index e1bf2b561d..ff2d59a6e6 100644
--- a/bitbake/doc/user-manual/user-manual-ref-variables.xml
+++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml
@@ -388,16 +388,15 @@
BB_HASHCONFIG_WHITELIST
- Lists variables that are excluded from checksum
- comparisons to determine if the cache can be reused.
+ Lists variables that are excluded from base configuration
+ checksum, which is used to determine if the cache can
+ be reused.
One of the ways BitBake determines whether to re-parse the
main metadata is through checksums of the variables in the
- datastore of the base configuration data (see the
- BB_HASHBASE_WHITELIST
- variable).
+ datastore of the base configuration data.
There are variables that you typically want to exclude when
checking whether or not to re-parse and thus rebuild the
cache.
diff --git a/bitbake/doc/user-manual/user-manual.xml b/bitbake/doc/user-manual/user-manual.xml
index 76c3edf527..9f94886c7f 100644
--- a/bitbake/doc/user-manual/user-manual.xml
+++ b/bitbake/doc/user-manual/user-manual.xml
@@ -81,8 +81,6 @@
-
-