From 0d52f18d39ee46290a266fabf0d01ad1dffd7bac Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 16 Jan 2018 10:59:43 -0800 Subject: dev-manual, ref-manual: Consolidated debug info into dev-manual Fixes [YOCTO #12370] Moved the debug information from the ref-manual to the dev-manual where other debug information exists. We now have a single area (section) that deals with various debugging techniques and tips. (From yocto-docs rev: 95394197fc04981bf7571e581ff8a0fd9c76223f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-variables.xml | 9 +- documentation/ref-manual/usingpoky.xml | 899 ----------------------------- 2 files changed, 5 insertions(+), 903 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 29f227e58c..fa4724984f 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -9286,8 +9286,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" OVERRIDES in the output of the bitbake -e command. See the - "Viewing Variable Values" - section for more information. + "Viewing Variable Values" + section in the Yocto Project Development Tasks + Manual for more information. @@ -10413,8 +10414,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For examples of how this data is used, see the "Automatically Added Runtime Dependencies" section in the Yocto Project Overview Manual and the - "Viewing Package Information with oe-pkgdata-util" - section elsewhere in this manual. + "Viewing Package Information with oe-pkgdata-util" + section in the Yocto Project Development Tasks Manual. diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index bfca60a99b..7c2f0f67bc 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -11,905 +11,6 @@ documentation set provide more details on how to use the Yocto Project. -
- Debugging Tools and Techniques - - - The exact method for debugging build failures depends on the nature of - the problem and on the system's area from which the bug originates. - Standard debugging practices such as comparison against the last - known working version with examination of the changes and the - re-application of steps to identify the one causing the problem are - valid for the Yocto Project just as they are for any other system. - Even though it is impossible to detail every possible potential failure, - this section provides some general tips to aid in debugging. - - - - A useful feature for debugging is the error reporting tool. - Configuring the Yocto Project to use this tool causes the - OpenEmbedded build system to produce error reporting commands as - part of the console output. - You can enter the commands after the build completes - to log error information - into a common database, that can help you figure out what might be - going wrong. - For information on how to enable and use this feature, see the - "Using the Error Reporting Tool" - section in the Yocto Project Development Tasks Manual. - - - - For discussions on debugging, see the - "Debugging With the GNU Project Debugger (GDB) Remotely" section - in the Yocto Project Development Tasks Manual - and the - "Working within Eclipse" - section in the Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) manual. - - - - The remainder of this section presents many examples of the - bitbake command. - You can learn about BitBake by reading the - BitBake User Manual. - - -
- Viewing Logs from Failed Tasks - - - You can find the log for a task in the file - ${WORKDIR}/temp/log.do_taskname. - For example, the log for the - do_compile - task of the QEMU minimal image for the x86 machine - (qemux86) might be in - tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile. - To see the commands - BitBake ran - to generate a log, look at the corresponding - run.do_taskname - file in the same directory. - - - - log.do_taskname and - run.do_taskname - are actually symbolic links to - log.do_taskname.pid - and - log.run_taskname.pid, - where pid is the PID the task had when - it ran. - The symlinks always point to the files corresponding to the most - recent run. - -
- -
- Viewing Variable Values - - BitBake's -e option is used to display - variable values after parsing. - The following command displays the variable values after the - configuration files (i.e. local.conf, - bblayers.conf, - bitbake.conf and so forth) have been - parsed: - - $ bitbake -e - - The following command displays variable values after a specific - recipe has been parsed. - The variables include those from the configuration as well: - - $ bitbake -e recipename - - - Each recipe has its own private set of variables (datastore). - Internally, after parsing the configuration, a copy of the - resulting datastore is made prior to parsing each recipe. - This copying implies that variables set in one recipe will - not be visible to other recipes. - - Likewise, each task within a recipe gets a private - datastore based on the recipe datastore, which means that - variables set within one task will not be visible to - other tasks. - - - - - In the output of bitbake -e, each variable is - preceded by a description of how the variable got its value, - including temporary values that were later overriden. - This description also includes variable flags (varflags) set on - the variable. - The output can be very helpful during debugging. - - - - Variables that are exported to the environment are preceded by - export in the output of - bitbake -e. - See the following example: - - export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" - - - - - In addition to variable values, the output of the - bitbake -e and - bitbake -e recipe - commands includes the following information: - - - The output starts with a tree listing all configuration - files and classes included globally, recursively listing - the files they include or inherit in turn. - Much of the behavior of the OpenEmbedded build system - (including the behavior of the - normal recipe build tasks) - is implemented in the - base - class and the classes it inherits, rather than being built - into BitBake itself. - - - After the variable values, all functions appear in the - output. - For shell functions, variables referenced within the - function body are expanded. - If a function has been modified using overrides or - using override-style operators like - _append and - _prepend, then the final assembled - function body appears in the output. - - - -
- -
- Viewing Package Information with <filename>oe-pkgdata-util</filename> - - - You can use the oe-pkgdata-util command-line - utility to query - PKGDATA_DIR - and display various package-related information. - When you use the utility, you must use it to view information - on packages that have already been built. - - - - Following are a few of the available - oe-pkgdata-util subcommands. - - You can use the standard * and ? globbing wildcards as part of - package names and paths. - - - - oe-pkgdata-util list-pkgs [pattern]: - Lists all packages that have been built, optionally - limiting the match to packages that match - pattern. - - - oe-pkgdata-util list-pkg-files package ...: - Lists the files and directories contained in the given - packages. - - - A different way to view the contents of a package is - to look at the - ${WORKDIR}/packages-split - directory of the recipe that generates the - package. - This directory is created by the - do_package - task and has one subdirectory for each package the - recipe generates, which contains the files stored in - that package. - - If you want to inspect the - ${WORKDIR}/packages-split - directory, make sure that - rm_work - is not enabled when you build the recipe. - - - - - oe-pkgdata-util find-path path ...: - Lists the names of the packages that contain the given - paths. - For example, the following tells us that - /usr/share/man/man1/make.1 - is contained in the make-doc - package: - - $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 - make-doc: /usr/share/man/man1/make.1 - - - - oe-pkgdata-util lookup-recipe package ...: - Lists the name of the recipes that - produce the given packages. - - - - - - For more information on the oe-pkgdata-util - command, use the help facility: - - $ oe-pkgdata-util ‐‐help - $ oe-pkgdata-util subcommand --help - - -
- -
- Viewing Dependencies Between Recipes and Tasks - - - Sometimes it can be hard to see why BitBake wants to build other - recipes before the one you have specified. - Dependency information can help you understand why a recipe is - built. - - - - To generate dependency information for a recipe, run the following - command: - - $ bitbake -g recipename - - This command writes the following files in the current directory: - - - pn-buildlist: A list of - recipes/targets involved in building - recipename. - "Involved" here means that at least one task from the - recipe needs to run when building - recipename from scratch. - Targets that are in - ASSUME_PROVIDED - are not listed. - - - task-depends.dot: A graph showing - dependencies between tasks. - - - - - - The graphs are in - DOT - format and can be converted to images (e.g. using the - dot tool from - Graphviz). - Notes - - - DOT files use a plain text format. - The graphs generated using the - bitbake -g command are often so - large as to be difficult to read without special - pruning (e.g. with Bitbake's - -I option) and processing. - Despite the form and size of the graphs, the - corresponding .dot files can still - be possible to read and provide useful information. - - - As an example, the - task-depends.dot file contains - lines such as the following: - - "libxslt.do_configure" -> "libxml2.do_populate_sysroot" - - The above example line reveals that the - do_configure - task in libxslt depends on the - do_populate_sysroot - task in libxml2, which is a normal - DEPENDS - dependency between the two recipes. - - - For an example of how .dot files - can be processed, see the - scripts/contrib/graph-tool Python - script, which finds and displays paths between graph - nodes. - - - - - - - You can use a different method to view dependency information - by using the following command: - - $ bitbake -g -u taskexp recipename - - This command displays a GUI window from which you can view - build-time and runtime dependencies for the recipes involved in - building recipename. - -
- -
- 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-dumpsig on the - sigdata or - siginfo file. - Here is an example: - - $ bitbake-dumpsig ${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-dumpsig 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-dumpsig. - - - - 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 - - - Any given recipe consists of a set of tasks. - The standard BitBake behavior in most cases is: - do_fetch, - do_unpack, - do_patch, do_configure, - do_compile, do_install, - do_package, - do_package_write_*, and - do_build. - The default task is do_build and any tasks - on which it depends build first. - Some tasks, such as do_devshell, are not part - of the default build chain. - If you wish to run a task that is not part of the default build - chain, you can use the -c option in BitBake. - Here is an example: - - $ bitbake matchbox-desktop -c devshell - - - - - The -c option respects task dependencies, - which means that all other tasks (including tasks from other - recipes) that the specified task depends on will be run before the - task. - Even when you manually specify a task to run with - -c, BitBake will only run the task if it - considers it "out of date". - See the - "Stamp Files and the Rerunning of Tasks" - section in the Yocto Project Overview Manual for how BitBake - determines whether a task is "out of date". - - - - If you want to force an up-to-date task to be rerun (e.g. - because you made manual modifications to the recipe's - WORKDIR - that you want to try out), then you can use the - -f option. - - The reason -f is never required when - running the - do_devshell - task is because the - [nostamp] - variable flag is already set for the task. - - The following example shows one way you can use the - -f option: - - $ bitbake matchbox-desktop - . - . - make some changes to the source code in the work directory - . - . - $ bitbake matchbox-desktop -c compile -f - $ bitbake matchbox-desktop - - - - - This sequence first builds and then recompiles - matchbox-desktop. - The last command reruns all tasks (basically the packaging tasks) - after the compile. - BitBake recognizes that the do_compile - task was rerun and therefore understands that the other tasks - also need to be run again. - - - - Another, shorter way to rerun a task and all - normal recipe build tasks - that depend on it is to use the -C - option. - - This option is upper-cased and is separate from the - -c option, which is lower-cased. - - Using this option invalidates the given task and then runs the - do_build - task, which is the default task if no task is given, and the - tasks on which it depends. - You could replace the final two commands in the previous example - with the following single command: - - $ bitbake matchbox-desktop -C compile - - Internally, the -f and - -C options work by tainting (modifying) the - input checksum of the specified task. - This tainting indirectly causes the task and its - dependent tasks to be rerun through the normal task dependency - mechanisms. - - BitBake explicitly keeps track of which tasks have been - tainted in this fashion, and will print warnings such as the - following for builds involving such tasks: - - WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run - - The purpose of the warning is to let you know that the work - directory and build output might not be in the clean state they - would be in for a "normal" build, depending on what actions - you took. - To get rid of such warnings, you can remove the work directory - and rebuild the recipe, as follows: - - $ bitbake matchbox-desktop -c clean - $ bitbake matchbox-desktop - - - - - - You can view a list of tasks in a given package by running the - do_listtasks task as follows: - - $ bitbake matchbox-desktop -c listtasks - - The results appear as output to the console and are also in the - file ${WORKDIR}/temp/log.do_listtasks. - -
- -
- General BitBake Problems - - - You can see debug output from BitBake by using the -D option. - The debug output gives more information about what BitBake - is doing and the reason behind it. - Each -D option you use increases the logging level. - The most common usage is -DDD. - - - - The output from bitbake -DDD -v targetname can reveal why - BitBake chose a certain version of a package or why BitBake - picked a certain provider. - This command could also help you in a situation where you think BitBake did something - unexpected. - -
- -
- Development Host System Issues - - - Sometimes issues on the host development system can cause your - build to fail. - Following are known, host-specific problems. - Be sure to always consult the - Release Notes - for a look at all release-related issues. - - glibc-initial fails to build: - If your development host system has the unpatched - GNU Make 3.82, - the - do_install - task fails for glibc-initial during - the build. - Typically, every distribution that ships - GNU Make 3.82 as - the default already has the patched version. - However, some distributions, such as Debian, have - GNU Make 3.82 as an option, which - is unpatched. - You will see this error on these types of distributions. - Switch to GNU Make 3.81 or patch - your make to solve the problem. - - - -
- -
- Building with No Dependencies - - To build a specific recipe (.bb file), - you can use the following command form: - - $ bitbake -b somepath/somerecipe.bb - - This command form does not check for dependencies. - Consequently, you should use it - only when you know existing dependencies have been met. - - You can also specify fragments of the filename. - In this case, BitBake checks for a unique match. - - -
- -
- Recipe Logging Mechanisms - - The Yocto Project provides several logging functions for producing - debugging output and reporting errors and warnings. - For Python functions, the following logging functions exist. - All of these functions log to - ${T}/log.do_task, - and can also log to standard output (stdout) with the right - settings: - - - bb.plain(msg): - Writes msg as is to the log while - also logging to stdout. - - - bb.note(msg): - Writes "NOTE: msg" to the log. - Also logs to stdout if BitBake is called with "-v". - - - bb.debug(level, msg): - Writes "DEBUG: msg" to the log. - Also logs to stdout if the log level is greater than or - equal to level. - See the - "-D" - option in the BitBake User Manual for more information. - - - bb.warn(msg): - Writes "WARNING: msg" to the log - while also logging to stdout. - - - bb.error(msg): - Writes "ERROR: msg" to the log - while also logging to stdout. - - Calling this function does not cause the task to fail. - - - - bb.fatal(msg): - This logging function is similar to - bb.error(msg) - but also causes the calling task to fail. - - bb.fatal() raises an exception, - which means you do not need to put a "return" - statement after the function. - - - - - - - The same logging functions are also available in shell functions, - under the names - bbplain, bbnote, - bbdebug, bbwarn, - bberror, and bbfatal. - The - logging - class implements these functions. - See that class in the - meta/classes folder of the - Source Directory - for information. - - -
- Logging With Python - - When creating recipes using Python and inserting code that handles build logs, - keep in mind the goal is to have informative logs while keeping the console as - "silent" as possible. - Also, if you want status messages in the log, use the "debug" loglevel. - - - - Following is an example written in Python. - The code handles logging for a function that determines the - number of tasks needed to be run. - See the - "do_listtasks" - section for additional information: - - python do_listtasks() { - bb.debug(2, "Starting to figure out the task list") - if noteworthy_condition: - bb.note("There are 47 tasks to run") - bb.debug(2, "Got to point xyz") - if warning_trigger: - bb.warn("Detected warning_trigger, this might be a problem later.") - if recoverable_error: - bb.error("Hit recoverable_error, you really need to fix this!") - if fatal_error: - bb.fatal("fatal_error detected, unable to print the task list") - bb.plain("The tasks present are abc") - bb.debug(2, "Finished figuring out the tasklist") - } - - -
- -
- Logging With Bash - - When creating recipes using Bash and inserting code that handles build - logs, you have the same goals - informative with minimal console output. - The syntax you use for recipes written in Bash is similar to that of - recipes written in Python described in the previous section. - - - - Following is an example written in Bash. - The code logs the progress of the do_my_function function. - - do_my_function() { - bbdebug 2 "Running do_my_function" - if [ exceptional_condition ]; then - bbnote "Hit exceptional_condition" - fi - bbdebug 2 "Got to point xyz" - if [ warning_trigger ]; then - bbwarn "Detected warning_trigger, this might cause a problem later." - fi - if [ recoverable_error ]; then - bberror "Hit recoverable_error, correcting" - fi - if [ fatal_error ]; then - bbfatal "fatal_error detected" - fi - bbdebug 2 "Completed do_my_function" - } - - -
-
- -
- Other Tips - - - Here are some other tips that you might find useful: - - - When adding new packages, it is worth watching for - undesirable items making their way into compiler command - lines. - For example, you do not want references to local system - files like - /usr/lib/ or - /usr/include/. - - - If you want to remove the psplash - boot splashscreen, - add psplash=false to the kernel - command line. - Doing so prevents psplash from loading - and thus allows you to see the console. - It is also possible to switch out of the splashscreen by - switching the virtual console (e.g. Fn+Left or Fn+Right - on a Zaurus). - - - Removing - TMPDIR - (usually tmp/, within the - Build Directory) - can often fix temporary build issues. - Removing TMPDIR is usually a - relatively cheap operation, because task output will be - cached in - SSTATE_DIR - (usually sstate-cache/, which is - also in the Build Directory). - - Removing TMPDIR might be a - workaround rather than a fix. - Consequently, trying to determine the underlying cause - of an issue before removing the directory is a good - idea. - - - - Understanding how a feature is used in practice within - existing recipes can be very helpful. - It is recommended that you configure some method that - allows you to quickly search through files. - - Using GNU Grep, you can use the following shell - function to recursively search through common - recipe-related files, skipping binary files, - .git directories, and the - Build Directory (assuming its name starts with - "build"): - - g() { - grep -Ir \ - --exclude-dir=.git \ - --exclude-dir='build*' \ - --include='*.bb*' \ - --include='*.inc*' \ - --include='*.conf*' \ - --include='*.py*' \ - "$@" - } - - Following are some usage examples: - - $ g FOO # Search recursively for "FOO" - $ g -i foo # Search recursively for "foo", ignoring case - $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR" - - If figuring out how some feature works requires a lot of - searching, it might indicate that the documentation should - be extended or improved. - In such cases, consider filing a documentation bug using - the Yocto Project implementation of - Bugzilla. - For general information on how to submit a bug against - the Yocto Project, see the Yocto Project Bugzilla - wiki page" - or the - Submitting a Defect Against the Yocto Project" - section, which is in the Yocto Project Development Tasks - Manual. - - The manuals might not be the right place to document - variables that are purely internal and have a limited - scope (e.g. internal variables used to implement a - single .bbclass file). - - - - -
-
-
Quick EMUlator (QEMU) -- cgit v1.2.3-54-g00ecf