diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml
index baee024cca..c8c7257822 100644
--- a/bitbake/doc/user-manual/user-manual-ref-variables.xml
+++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml
@@ -317,25 +317,99 @@
BB_HASHCONFIG_WHITELIST
- A list of variables that BitBake excludes from checksum
- comparisons.
+ Lists variables that are excluded from checksum
+ comparisons to determine if the cache can be reused.
One of the ways BitBake determines whether to re-parse the
- main metadata is by using a checksum of the variables in
- the datastore of the base configuration data.
- There are variables that you typically want to exclude from
- these checksum comparisons.
+ main metadata is through checksums of the variables in the
+ datastore of the base configuration data (see the
+ BB_HASHBASE_WHITELIST
+ variable).
+ There are variables that you typically want to exclude when
+ checking whether or not to re-parse and thus rebuild the
+ cache.
As an example, you would usually exclude
TIME and DATE
because these variables are always changing.
- If you did not exclude them, BitBake would never use the
+ If you did not exclude them, BitBake would never reuse the
cache.
+ BB_HASHBASE_WHITELIST
+
+
+ Lists variables that are excluded from checksum and
+ dependency data.
+ Variables that are excluded can therefore change without
+ affecting the checksum mechanism.
+ A common example would be the variable for the path of
+ the build.
+ BitBake's output should not (and usually does not) depend
+ on the directory in which it was built.
+
+
+
+
+ BB_HASHCHECK_FUNCTION
+
+
+ Specifies the name of the function to call during the
+ "setscene" part of the task's execution in order to
+ validate the list of task hashes.
+ The function returns the list of setscene tasks that should
+ be executed.
+
+
+
+ At this point in the execution of the code, the objective
+ is to quickly verify if a given setscene function is likely
+ to work or not.
+ It's easier to check the list of setscene functions in
+ one pass than to call many individual tasks.
+ The returned list need not be completely accurate.
+ A given setscene task can still later fail.
+ However, the more accurate the data returned, the more
+ efficient the build will be.
+
+
+
+
+ BB_INVALIDCONF
+
+
+ Used in combination with the
+ ConfigParsed event to trigger
+ re-parsing the base metadata (i.e. all the
+ recipes).
+ The ConfigParsed event can set the
+ variable to trigger the re-parse.
+ You must be careful to avoid recursive loops with this
+ functionality.
+
+
+
+
+ BB_LOGFMT
+
+
+ Specifies the name of the log files saved into
+ ${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.
+
+
+
+
BB_NICE_LEVEL
@@ -385,6 +459,231 @@
+ BB_RUNFMT
+
+
+ Specifies the name of the executable script files
+ (i.e. run files) saved into
+ ${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.
+
+
+
+
+ BB_RUNTASK
+
+
+ Contains the name of the currently executing task.
+ The value does not include the "do_" prefix.
+ For example, if the currently executing task is
+ do_config, the value is
+ "config".
+
+
+
+
+ BB_SCHEDULER
+
+
+ Selects the name of the scheduler to use for the
+ scheduling of BitBake tasks.
+ Three options exist:
+
+ basic -
+ The basic framework from which everything derives.
+ Using this option causes tasks to be ordered
+ numerically as they are parsed.
+
+ speed -
+ Executes tasks first that have more tasks
+ depending on them.
+ The "speed" option is the default.
+
+ completion -
+ Causes the scheduler to try to complete a given
+ recipe once its build has started.
+
+
+
+
+
+
+ BB_SCHEDULERS
+
+
+ Defines custom schedulers to import.
+ Custom schedulers need to be derived from the
+ RunQueueScheduler class.
+
+
+
+ For information how to select a scheduler, see the
+ BB_SCHEDULER
+ variable.
+
+
+
+
+ BB_SETSCENE_DEPVALID
+
+
+ Specifies a function BitBake calls that determines
+ whether BitBake requires a setscene dependency to be met.
+
+
+
+ When running a setscene task, BitBake needs to
+ know which dependencies of that setscene task also need
+ to be run.
+ Whether dependencies also need to be run is highly
+ dependent on the metadata.
+ The function specified by this variable returns a
+ "True" or "False" depending on whether the dependency needs
+ to be met.
+
+
+
+
+ BB_SETSCENE_VERIFY_FUNCTION
+
+
+ Specifies a function to call that verifies the list of
+ planned task execution before the main task execution
+ happens.
+ The function is called once BitBake has a list of setscene
+ tasks that have run and either succeeded or failed.
+
+
+
+ The function allows for a task list check to see if they
+ make sense.
+ Even if BitBake was planning to skip a task, the
+ returned value of the function can force BitBake to run
+ the task, which is necessary under certain metadata
+ defined circumstances.
+
+
+
+
+ BB_SIGNATURE_EXCLUDE_FLAGS
+
+
+ Lists flags that can be safely excluded from checksum
+ and dependency data for keys in the datastore.
+ When generating checksum or dependency data for keys in the
+ datastore, the flags set against that key are normally
+ included in the checksum.
+
+
+
+
+ BB_SIGNATURE_HANDLER
+
+
+ Defines the name of the signature handler BitBake uses.
+ The signature handler defines the way stamp files are
+ created and handled, if and how the signature is
+ incorporated into the stamps, and how the signature
+ itself is generated.
+
+
+
+ A new signature handler can be added by injecting a class
+ derived from the
+ SignatureGenerator class into the
+ global namespace.
+
+
+
+
+ BB_SRCREV_POLICY
+
+
+ Defines the behavior of the fetcher when it interacts with
+ source control systems and dynamic source revisions.
+ The BB_SRCREV_POLICY variable is
+ useful when working without a network.
+
+
+
+ The variable can be set using one of two policies:
+
+ cache -
+ Retains the value the system obtained previously
+ rather than querying the source control system
+ each time.
+
+ clear -
+ Queries the source controls system every time.
+ With this policy, there is no cache.
+ The "clear" policy is the default.
+
+
+
+
+
+
+ BB_STAMP_POLICY
+
+
+ Defines the mode used for how timestamps of stamp files
+ are compared.
+ You can set the variable to one of the following modes:
+
+ perfile -
+ Timestamp comparisons are only made
+ between timestamps of a specific recipe.
+ This is the default mode.
+
+ full -
+ Timestamp comparisons are made for all
+ dependencies.
+
+ whitelist -
+ Identical to "full" mode except timestamp
+ comparisons are made for recipes listed in the
+ BB_STAMP_WHITELIST
+ variable.
+
+
+
+ Stamp policies are largely obsolete with the
+ introduction of setscene tasks.
+
+
+
+
+
+ BB_STAMP_WHITELIST
+
+
+ Lists files whose stamp file timestamps are compared when
+ the stamp policy mode is set to "whitelist".
+ For information on stamp policies, see the
+ BB_STAMP_POLICY
+ variable.
+
+
+
+
+ BB_STRICT_CHECKSUM
+
+
+ Sets a more strict checksum mechanism for non-local URLs.
+ Setting this variable to a value causes BitBake
+ to report an error if it encounters a non-local URL
+ that does not have at least one checksum specified.
+
+
+
+
BB_TASK_NICE_LEVEL
@@ -404,6 +703,29 @@
+ BB_VERBOSE_LOGS
+
+
+ Controls how verbose BitBake is during builds.
+ If set, shell scripts echo commands and shell script output
+ appears on standard out (stdout).
+
+
+
+
+ BB_WORKERCONTEXT
+
+
+ Specifies if the current context is executing a task.
+ BitBake sets this variable to "1" when a task is
+ being executed.
+ The value is not set when the task is in server context
+ during parsing or event handling.
+
+
+
+
+
BBCLASSEXTEND