From 1769e1a2dec036dbe950b86dbdc95ab5798ece38 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 22 Aug 2016 13:13:14 -0700 Subject: ref-manual: Suggested fleshing out of the sigdata/siginfo documentation Fixes [YOCTO #10141] Provided several fixes to address this situation: * Renamed "Debugging Build Failures" to "Debugging Tools and Techniques" as it fit better the subsections. * Renamed "Viewing Dependencies" to "Viewing Dependencies Between Recipes and Tasks" as it fit better the description. * Added a new "Viewing Task Variable Dependencies" section to describe how sigdata and siginfo stuff can be used. * Replaced the contents of "4.3.4.1 Debugging" with a shorter bit that now references into the new section on veiwing task variable dependencies. (From yocto-docs rev: 539d76366055bed74ccc926519e969324cac470d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/technical-details.xml | 59 ++---------- documentation/ref-manual/usingpoky.xml | 125 ++++++++++++++++++++++++- 2 files changed, 130 insertions(+), 54 deletions(-) diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 5ef764c8e0..6bad547e50 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -901,56 +901,15 @@ 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 -- cgit 1.2.3-korg