Debugging
- When things go wrong, debugging needs to be straightforward.
- Because of this, the Yocto Project includes strong debugging
- tools:
-
- Whenever a shared state package is written
- out into the
- SSTATE_DIR,
- a corresponding .siginfo file is
- also written.
- This file contains a pickled Python database of all
- the Metadata that went into creating the hash for a
- given shared state package.
- Whenever a stamp is written into the stamp directory
- STAMP,
- a corresponding .sigdata file
- is created that contains the same hash data that
- represented the executed task.
-
- You can use BitBake to dump out the
- signature construction information without executing
- tasks by using either of the following BitBake
- command-line options:
-
- ‐‐dump-signatures=SIGNATURE_HANDLER
- -S SIGNATURE_HANDLER
-
-
- Two common values for
- SIGNATURE_HANDLER are
- "none" and "printdiff" to only dump the signature
- or to compare the dumped signature with the
- cached one, respectively.
-
- Using BitBake with either of these options causes
- BitBake to dump out .sigdata files
- in the stamp directory for every task it would have
- executed instead of building the specified target
- package.
-
- There is a
- bitbake-diffsigs command that
- can process .sigdata and
- .siginfo files.
- If you specify one of these files, BitBake dumps out
- the dependency information in the file.
- If you specify two files, BitBake compares the two
- files and dumps out the differences between the two.
- This more easily helps answer the question of "What
- changed between X and Y?"
-
+ Seeing what metadata went into creating the input signature
+ of a shared state (sstate) task can be a useful debugging aid.
+ This information is available in signature information
+ (siginfo) files in
+ SSTATE_DIR.
+ For information on how to view and interpret information in
+ siginfo files, see the
+ "Viewing Task Variable Dependencies"
+ section.
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 15e1d47301..574de7b4b7 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -119,8 +119,8 @@
-
- Debugging Build Failures
+
+ Debugging Tools and Techniques
The exact method for debugging build failures depends on the nature of
@@ -247,8 +247,8 @@
-
- Viewing Dependencies
+
+ Viewing Dependencies Between Recipes and Tasks
Sometimes it can be hard to see why BitBake wants to build other
@@ -348,6 +348,123 @@
+
+ Viewing Task Variable Dependencies
+
+
+ As mentioned in the
+ "Checksums (Signatures)"
+ section of the BitBake User Manual, BitBake tries to automatically
+ determine what variables a task depends on so that it can rerun
+ the task if any values of the variables change.
+ This determination is usually reliable.
+ However, if you do things like construct variable names at runtime,
+ then you might have to manually declare dependencies on those
+ variables using vardeps as described in the
+ "Variable Flags"
+ section of the BitBake User Manual.
+
+
+
+ If you are unsure whether a variable dependency is being picked up
+ automatically for a given task, you can list the variable
+ dependencies BitBake has determined by doing the following:
+
+
+ Build the recipe containing the task:
+
+ $ bitbake recipename
+
+
+
+ Inside the
+ STAMPS_DIR
+ directory, find the signature data
+ (sigdata) file that corresponds to the
+ task.
+ The sigdata files contain a pickled
+ Python database of all the metadata that went into creating
+ the input checksum for the task.
+ As an example, for the
+ do_fetch
+ task of the db recipe, the
+ sigdata file might be found in the
+ following location:
+
+ ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+
+ For tasks that are accelerated through the shared state
+ (sstate)
+ cache, an additional siginfo file is
+ written into
+ SSTATE_DIR
+ along with the cached task output.
+ The siginfo files contain exactly the
+ same information as sigdata files.
+
+
+ Run bitbake-dumpsigs on the
+ sigdata or
+ siginfo file.
+ Here is an example:
+
+ $ bitbake-dumpsigs ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+
+ In the output of the above command, you will find a line
+ like the following, which lists all the (inferred) variable
+ dependencies for the task.
+ This list also includes indirect dependencies from
+ variables depending on other variables, recursively.
+
+ Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
+
+
+ Functions (e.g. base_do_fetch)
+ also count as variable dependencies.
+ These functions in turn depend on the variables they
+ reference.
+
+ The output of bitbake-dumpsigs also includes
+ the value each variable had, a list of dependencies for each
+ variable, and
+ BB_HASHBASE_WHITELIST
+ information.
+
+
+
+
+
+ There is also a bitbake-diffsigs command for
+ comparing two siginfo or
+ sigdata files.
+ This command can be helpful when trying to figure out what changed
+ between two versions of a task.
+ If you call bitbake-diffsigs with just one
+ file, the command behaves like
+ bitbake-dumpsigs.
+
+
+
+ You can also use BitBake to dump out the signature construction
+ information without executing tasks by using either of the
+ following BitBake command-line options:
+
+ ‐‐dump-signatures=SIGNATURE_HANDLER
+ -S SIGNATURE_HANDLER
+
+
+ Two common values for
+ SIGNATURE_HANDLER are "none" and
+ "printdiff", which dump only the signature or compare the
+ dumped signature with the cached one, respectively.
+
+ Using BitBake with either of these options causes BitBake to dump
+ out sigdata files in the
+ stamps directory for every task it would have
+ executed instead of building the specified target package.
+
+
+
Running Specific Tasks