diff options
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
| -rw-r--r-- | documentation/ref-manual/usingpoky.xml | 125 |
1 files changed, 121 insertions, 4 deletions
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 @@ </para> </section> -<section id='usingpoky-debugging'> - <title>Debugging Build Failures</title> +<section id='usingpoky-debugging-tools-and-techniques'> + <title>Debugging Tools and Techniques</title> <para> The exact method for debugging build failures depends on the nature of @@ -247,8 +247,8 @@ </para> </section> - <section id='usingpoky-viewing-dependencies'> - <title>Viewing Dependencies</title> + <section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'> + <title>Viewing Dependencies Between Recipes and Tasks</title> <para> Sometimes it can be hard to see why BitBake wants to build other @@ -348,6 +348,123 @@ </para> </section> + <section id='usingpoky-viewing-task-variable-dependencies'> + <title>Viewing Task Variable Dependencies</title> + + <para> + As mentioned in the + "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>" + 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 <filename>vardeps</filename> as described in the + "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" + section of the BitBake User Manual. + </para> + + <para> + 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: + <orderedlist> + <listitem><para> + Build the recipe containing the task: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipename</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + Inside the + <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link> + directory, find the signature data + (<filename>sigdata</filename>) file that corresponds to the + task. + The <filename>sigdata</filename> 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 + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task of the <filename>db</filename> recipe, the + <filename>sigdata</filename> file might be found in the + following location: + <literallayout class='monospaced'> + ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + For tasks that are accelerated through the shared state + (<link linkend='shared-state-cache'>sstate</link>) + cache, an additional <filename>siginfo</filename> file is + written into + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + along with the cached task output. + The <filename>siginfo</filename> files contain exactly the + same information as <filename>sigdata</filename> files. + </para></listitem> + <listitem><para> + Run <filename>bitbake-dumpsigs</filename> on the + <filename>sigdata</filename> or + <filename>siginfo</filename> file. + Here is an example: + <literallayout class='monospaced'> + $ bitbake-dumpsigs ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + 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. + <literallayout class='monospaced'> + Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch'] + </literallayout> + <note> + Functions (e.g. <filename>base_do_fetch</filename>) + also count as variable dependencies. + These functions in turn depend on the variables they + reference. + </note> + The output of <filename>bitbake-dumpsigs</filename> also includes + the value each variable had, a list of dependencies for each + variable, and + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink> + information. + </para></listitem> + </orderedlist> + </para> + + <para> + There is also a <filename>bitbake-diffsigs</filename> command for + comparing two <filename>siginfo</filename> or + <filename>sigdata</filename> files. + This command can be helpful when trying to figure out what changed + between two versions of a task. + If you call <filename>bitbake-diffsigs</filename> with just one + file, the command behaves like + <filename>bitbake-dumpsigs</filename>. + </para> + + <para> + 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: + <literallayout class='monospaced'> + ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable> + -S <replaceable>SIGNATURE_HANDLER</replaceable> + </literallayout> + <note> + Two common values for + <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and + "printdiff", which dump only the signature or compare the + dumped signature with the cached one, respectively. + </note> + Using BitBake with either of these options causes BitBake to dump + out <filename>sigdata</filename> files in the + <filename>stamps</filename> directory for every task it would have + executed instead of building the specified target package. + </para> + </section> + <section id='usingpoky-debugging-taskrunning'> <title>Running Specific Tasks</title> |