1 files changed, 1427 insertions, 443 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 075d0f6fdf..13a84b9c22 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -9994,368 +9994,917 @@ Some notes from Cal:
         </section>
     </section>
 
-    <section id="platdev-gdb-remotedebug">
-        <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+    <section id='usingpoky-debugging-tools-and-techniques'>
+        <title>Debugging Tools and Techniques</title>
 
         <para>
-            GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
-            It also allows you to perform post-mortem style analysis of program crashes.
-            GDB is available as a package within the Yocto Project and is
-            installed in SDK images by default.
-            See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
-            in the Yocto Project Reference Manual for a description of these images.
-            You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
+            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 given a variety of situations.
+            <note><title>Tip</title>
+                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
+                "<link linkend='using-the-error-reporting-tool'>Using the Error Reporting Tool</link>"
+                section.
+            </note>
         </para>
 
-        <tip>
-            For best results, install debug (<filename>-dbg</filename>) packages
-            for the applications you are going to debug.
-            Doing so makes extra debug symbols available that give you more
-            meaningful output.
-        </tip>
-
         <para>
-            Sometimes, due to memory or disk space constraints, it is not possible
-            to use GDB directly on the remote target to debug applications.
-            These constraints arise because GDB needs to load the debugging information and the
-            binaries of the process being debugged.
-            Additionally, GDB needs to perform many computations to locate information such as function
-            names, variable names and values, stack traces and so forth - even before starting the
-            debugging process.
-            These extra computations place more load on the target system and can alter the
-            characteristics of the program being debugged.
+            The following list shows the debugging topics in the remainder of
+            this section:
+            <itemizedlist>
+                <listitem><para>
+                    "<link linkend='dev-debugging-viewing-logs-from-failed-tasks'>Viewing Logs from Failed Tasks</link>"
+                    describes how to find and view logs from tasks that
+                    failed during the build process.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-debugging-viewing-variable-values'>Viewing Variable Values</link>"
+                    describes how to use the BitBake <filename>-e</filename>
+                    option to examine variable values after a recipe has been
+                    parsed.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
+                    describes how to use the
+                    <filename>oe-pkgdata-util</filename> utility to query
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+                    and display package-related information for built
+                    packages.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-viewing-dependencies-between-recipes-and-tasks'>Viewing Dependencies Between Recipes and Tasks</link>"
+                    describes how to use the BitBake <filename>-g</filename>
+                    option to display recipe dependency information used
+                    during the build.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+                    describes how to use the
+                    <filename>bitbake-dumpsig</filename> command in
+                    conjunction with key subdirectories in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+                    to determine variable dependencies.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-debugging-taskrunning'>Running Specific Tasks</link>"
+                    describes how to use several BitBake options (e.g.
+                    <filename>-c</filename>, <filename>-C</filename>, and
+                    <filename>-f</filename>) to run specific tasks in the
+                    build chain.
+                    It can be useful to run tasks "out-of-order" when trying
+                    isolate build issues.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-debugging-bitbake'>General BitBake Problems</link>"
+                    describes how to use BitBake's <filename>-D</filename>
+                    debug output option to reveal more about what BitBake is
+                    doing during the build.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-debugging-buildfile'>Building with No Dependencies</link>"
+                    describes how to use the BitBake <filename>-b</filename>
+                    option to build a recipe while ignoring dependencies.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='recipe-logging-mechanisms'>Recipe Logging Mechanisms</link>"
+                    describes how to use the many recipe logging functions
+                    to produce debugging output and report errors and warnings.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
+                    describes how to debug situations where the build consists
+                    of several parts that are run simultaneously and when the
+                    output or result of one part is not ready for use with a
+                    different part of the build that depends on that output.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</link>"
+                    describes how to use GDB to allow you to examine running
+                    programs, which can help you fix problems.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>Debugging with the GNU Project Debugger (GDB) on the Target</link>"
+                    describes how to use GDB directly on target hardware for
+                    debugging.
+                    </para></listitem>
+                <listitem><para>
+                    "<link linkend='dev-other-debugging-others'>Other Debugging Tips</link>"
+                    describes miscellaneous debugging tips that can be useful.
+                    </para></listitem>
+            </itemizedlist>
         </para>
 
         <para>
-            To help get past the previously mentioned constraints, you can use
-            gdbserver, which runs on the remote target and does not load any
-            debugging information from the debugged process.
-            Instead, a GDB instance processes the debugging information that is run on a
-            remote computer - the host GDB.
-            The host GDB then sends control commands to gdbserver to make it stop or start the debugged
-            program, as well as read or write memory regions of that debugged program.
-            All the debugging information loaded and processed as well
-            as all the heavy debugging is done by the host GDB.
-            Offloading these processes gives the gdbserver running on the target a chance to remain
-            small and fast.
+            For debugging information within the popular
+            <trademark class='trade'>Eclipse</trademark> IDE, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
+            section in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) manual.
         </para>
 
-        <para>
-            Because the host GDB is responsible for loading the debugging information and
-            for doing the necessary processing to make actual debugging happen,
-            you have to make sure the host can access the unstripped binaries complete
-            with their debugging information and also be sure the target is compiled with no optimizations.
-            The host GDB must also have local access to all the libraries used by the
-            debugged program.
-            Because gdbserver does not need any local debugging information, the binaries on
-            the remote target can remain stripped.
-            However, the binaries must also be compiled without optimization
-            so they match the host's binaries.
-        </para>
+        <section id='dev-debugging-viewing-logs-from-failed-tasks'>
+            <title>Viewing Logs from Failed Tasks</title>
 
-        <para>
-            To remain consistent with GDB documentation and terminology, the binary being debugged
-            on the remote target machine is referred to as the "inferior" binary.
-            For documentation on GDB see the
-            <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
-        </para>
+            <para>
+                You can find the log for a task in the file
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
+                For example, the log for the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+                task of the QEMU minimal image for the x86 machine
+                (<filename>qemux86</filename>) might be in
+                <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
+                To see the commands
+                <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+                ran to generate a log, look at the corresponding
+                <filename>run.do_</filename><replaceable>taskname</replaceable>
+                file in the same directory.
+            </para>
 
-        <para>
-            The following steps show you how to debug using the GNU project
-            debugger.
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Configure your build system to construct the
-                    companion debug filesystem:</emphasis></para>
+            <para>
+                <filename>log.do_</filename><replaceable>taskname</replaceable>
+                and
+                <filename>run.do_</filename><replaceable>taskname</replaceable>
+                are actually symbolic links to
+                <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
+                and
+                <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
+                where <replaceable>pid</replaceable> is the PID the task had
+                when it ran.
+                The symlinks always point to the files corresponding to the most
+                recent run.
+            </para>
+        </section>
 
-                    <para>In your <filename>local.conf</filename> file, set
-                    the following:
-                    <literallayout class='monospaced'>
-     IMAGE_GEN_DEBUGFS = "1"
-     IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
-                    </literallayout>
-                    These options cause the OpenEmbedded build system
-                    to generate a special companion filesystem fragment,
-                    which contains the matching source and debug symbols to
-                    your deployable filesystem.
-                    The build system does this by looking at what is in the
-                    deployed filesystem, and pulling the corresponding
-                    <filename>-dbg</filename> packages.</para>
-
-                    <para>The companion debug filesystem is not a complete
-                    filesystem, but only contains the debug fragments.
-                    This filesystem must be combined with the full filesystem
-                    for debugging.
-                    Subsequent steps in this procedure show how to combine
-                    the partial filesystem with the full filesystem.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Configure the system to include gdbserver in
-                    the target filesystem:</emphasis></para>
+        <section id='dev-debugging-viewing-variable-values'>
+            <title>Viewing Variable Values</title>
 
-                    <para>Make the following addition in either your
-                    <filename>local.conf</filename> file or in an image
-                    recipe:
-                    <literallayout class='monospaced'>
-     IMAGE_INSTALL_append = “ gdbserver"
-                    </literallayout>
-                    The change makes sure the <filename>gdbserver</filename>
-                    package is included.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Build the environment:</emphasis></para>
+            <para>
+                BitBake's <filename>-e</filename> option is used to display
+                variable values after parsing.
+                The following command displays the variable values after the
+                configuration files (i.e. <filename>local.conf</filename>,
+                <filename>bblayers.conf</filename>,
+                <filename>bitbake.conf</filename> and so forth) have been
+                parsed:
+                <literallayout class='monospaced'>
+     $ bitbake -e
+                </literallayout>
+                The following command displays variable values after a specific
+                recipe has been parsed.
+                The variables include those from the configuration as well:
+                <literallayout class='monospaced'>
+     $ bitbake -e recipename
+                </literallayout>
+                <note><para>
+                    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.</para>
+
+                    <para>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.</para>
+                </note>
+            </para>
 
-                    <para>Use the following command to construct the image and
-                    the companion Debug Filesystem:
-                    <literallayout class='monospaced'>
-     $ bitbake <replaceable>image</replaceable>
-                    </literallayout>
-                    Build the cross GDB component and make it available
-                    for debugging.
-                    Build the SDK that matches the image.
-                    Building the SDK is best for a production build
-                    that can be used later for debugging, especially
-                    during long term maintenance:
-                    <literallayout class='monospaced'>
-     $ bitbake -c populate_sdk <replaceable>image</replaceable>
-                    </literallayout></para>
-
-                    <para>Alternatively, you can build the minimal
-                    toolchain components that match the target.
-                    Doing so creates a smaller than typical SDK and only
-                    contains a minimal set of components with which to
-                    build simple test applications, as well as run the
-                    debugger:
-                    <literallayout class='monospaced'>
-     $ bitbake meta-toolchain
-                    </literallayout></para>
+            <para>
+                In the output of <filename>bitbake -e</filename>, 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.
+            </para>
 
-                    <para>A final method is to build Gdb itself within
-                    the build system:
-                    <literallayout class='monospaced'>
-     $ bitbake gdb-cross-<replaceable>architecture</replaceable>
-                    </literallayout>
-                    Doing so produces a temporary copy of
-                    <filename>cross-gdb</filename> you can use for
-                    debugging during development.
-                    While this is the quickest approach, the two previous
-                    methods in this step are better when considering
-                    long-term maintenance strategies.
-                    <note>
-                        If you run
-                        <filename>bitbake gdb-cross</filename>, the
-                        OpenEmbedded build system suggests the actual
-                        image (e.g. <filename>gdb-cross-i586</filename>).
-                        The suggestion is usually the actual name you want
-                        to use.
-                    </note>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Set up the</emphasis>&nbsp;<filename>debugfs</filename></para>
+            <para>
+                Variables that are exported to the environment are preceded by
+                <filename>export</filename> in the output of
+                <filename>bitbake -e</filename>.
+                See the following example:
+                <literallayout class='monospaced'>
+     export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+                </literallayout>
+            </para>
 
-                    <para>Run the following commands to set up the
-                    <filename>debugfs</filename>:
-                    <literallayout class='monospaced'>
-     $ mkdir debugfs
-     $ cd debugfs
-     $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
-     $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Set up GDB</emphasis></para>
+            <para>
+                In addition to variable values, the output of the
+                <filename>bitbake -e</filename> and
+                <filename>bitbake -e</filename>&nbsp;<replaceable>recipe</replaceable>
+                commands includes the following information:
+                <itemizedlist>
+                    <listitem><para>
+                        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
+                        <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>)
+                        is implemented in the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+                        class and the classes it inherits, rather than being
+                        built into BitBake itself.
+                        </para></listitem>
+                    <listitem><para>
+                        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
+                        <filename>_append</filename> and
+                        <filename>_prepend</filename>, then the final assembled
+                        function body appears in the output.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
 
-                    <para>Install the SDK (if you built one) and then
-                    source the correct environment file.
-                    Sourcing the environment file puts the SDK in your
-                    <filename>PATH</filename> environment variable.</para>
+        <section id='viewing-package-information-with-oe-pkgdata-util'>
+            <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
 
-                    <para>If you are using the build system, Gdb is
-                    located in
-                    <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Boot the target:</emphasis></para>
+            <para>
+                You can use the <filename>oe-pkgdata-util</filename>
+                command-line utility to query
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+                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.
+            </para>
 
-                    <para>For information on how to run QEMU, see the
-                    <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
-                    <note>
-                        Be sure to verify that your host can access the
-                        target via TCP.
-                    </note>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Debug a program:</emphasis></para>
+            <para>
+                Following are a few of the available
+                <filename>oe-pkgdata-util</filename> subcommands.
+                <note>
+                    You can use the standard * and ? globbing wildcards as part
+                    of package names and paths.
+                </note>
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
+                        Lists all packages that have been built, optionally
+                        limiting the match to packages that match
+                        <replaceable>pattern</replaceable>.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>oe-pkgdata-util list-pkg-files&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
+                        Lists the files and directories contained in the given
+                        packages.
+                        <note>
+                            <para>
+                            A different way to view the contents of a package is
+                            to look at the
+                            <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
+                            directory of the recipe that generates the
+                            package.
+                            This directory is created by the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+                            task and has one subdirectory for each package the
+                            recipe generates, which contains the files stored in
+                            that package.</para>
+                            <para>
+                            If you want to inspect the
+                            <filename>${WORKDIR}/packages-split</filename>
+                            directory, make sure that
+                            <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+                            is not enabled when you build the recipe.
+                            </para>
+                            </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>oe-pkgdata-util find-path&nbsp;</filename><replaceable>path</replaceable><filename>&nbsp;...</filename>:
+                        Lists the names of the packages that contain the given
+                        paths.
+                        For example, the following tells us that
+                        <filename>/usr/share/man/man1/make.1</filename>
+                        is contained in the <filename>make-doc</filename>
+                        package:
+                        <literallayout class='monospaced'>
+     $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
+     make-doc: /usr/share/man/man1/make.1
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>oe-pkgdata-util lookup-recipe&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
+                        Lists the name of the recipes that
+                        produce the given packages.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
 
-                    <para>Debugging a program involves running gdbserver
-                    on the target and then running Gdb on the host.
-                    The example in this step debugs
-                    <filename>gzip</filename>:
-                    <literallayout class='monospaced'>
-     root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
-                    </literallayout>
-                    For additional gdbserver options, see the
-                    <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
-                    </para>
+            <para>
+                For more information on the <filename>oe-pkgdata-util</filename>
+                command, use the help facility:
+                <literallayout class='monospaced'>
+     $ oe-pkgdata-util &dash;&dash;help
+     $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
+                </literallayout>
+            </para>
+        </section>
 
-                    <para>After running gdbserver on the target, you need
-                    to run Gdb on the host and configure it and connect to
-                    the target.
-                    Use these commands:
-                    <literallayout class='monospaced'>
-     $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
-     $ <replaceable>arch</replaceable>-gdb
+        <section id='dev-viewing-dependencies-between-recipes-and-tasks'>
+            <title>Viewing Dependencies Between Recipes and Tasks</title>
 
-     (gdb) set sysroot debugfs
-     (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
-     (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
-                    </literallayout>
-                    At this point, everything should automatically load
-                    (i.e. matching binaries, symbols and headers).
-                    <note>
-                        The Gdb <filename>set</filename> commands in the
-                        previous example can be placed into the users
-                        <filename>~/.gdbinit</filename> file.
-                        Upon starting, Gdb automatically runs whatever
-                        commands are in that file.
-                    </note>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Deploying without a full image
-                    rebuild:</emphasis></para>
+            <para>
+                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.
+            </para>
 
-                    <para>In many cases, during development you want a
-                    quick method to deploy a new binary to the target and
-                    debug it, without waiting for a full image build.
-                    </para>
+            <para>
+                To generate dependency information for a recipe, run the
+                following command:
+                <literallayout class='monospaced'>
+     $ bitbake -g <replaceable>recipename</replaceable>
+                </literallayout>
+                This command writes the following files in the current
+                directory:
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>pn-buildlist</filename>: A list of
+                        recipes/targets involved in building
+                        <replaceable>recipename</replaceable>.
+                        "Involved" here means that at least one task from the
+                         recipe needs to run when building
+                        <replaceable>recipename</replaceable> from scratch.
+                        Targets that are in
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></ulink>
+                        are not listed.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>task-depends.dot</filename>: A graph showing
+                        dependencies between tasks.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
 
-                    <para>One approach to solving this situation is to
-                    just build the component you want to debug.
-                    Once you have built the component, copy the
-                    executable directly to both the target and the
-                    host <filename>debugfs</filename>.</para>
-
-                    <para>If the binary is processed through the debug
-                    splitting in OpenEmbedded, you should also
-                    copy the debug items (i.e. <filename>.debug</filename>
-                    contents and corresponding
-                    <filename>/usr/src/debug</filename> files)
-                    from the work directory.
-                    Here is an example:
-                    <literallayout class='monospaced'>
-     $ bitbake bash
-     $ bitbake -c devshell bash
-     $ cd ..
-     $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
-     $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
-                    </literallayout>
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
+            <para>
+                The graphs are in
+                <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
+                format and can be converted to images (e.g. using the
+                <filename>dot</filename> tool from
+                <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
+                <note><title>Notes</title>
+                    <itemizedlist>
+                        <listitem><para>
+                            DOT files use a plain text format.
+                            The graphs generated using the
+                            <filename>bitbake -g</filename> command are often so
+                            large as to be difficult to read without special
+                            pruning (e.g. with Bitbake's
+                            <filename>-I</filename> option) and processing.
+                            Despite the form and size of the graphs, the
+                            corresponding <filename>.dot</filename> files can
+                            still be possible to read and provide useful
+                            information.
+                            </para>
 
-    <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
-        <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
+                            <para>As an example, the
+                            <filename>task-depends.dot</filename> file contains
+                            lines such as the following:
+                            <literallayout class='monospaced'>
+     "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
+                            </literallayout>
+                            The above example line reveals that the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
+                            task in <filename>libxslt</filename> depends on the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
+                            task in <filename>libxml2</filename>, which is a
+                            normal
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                            dependency between the two recipes.
+                            </para></listitem>
+                        <listitem><para>
+                            For an example of how <filename>.dot</filename>
+                            files can be processed, see the
+                            <filename>scripts/contrib/graph-tool</filename>
+                            Python script, which finds and displays paths
+                            between graph nodes.
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+            </para>
 
-        <para>
-            The previous section addressed using GDB remotely for debugging
-            purposes, which is the most usual case due to the inherent
-            hardware limitations on many embedded devices.
-            However, debugging in the target hardware itself is also possible
-            with more powerful devices.
-            This section describes what you need to do in order to support
-            using GDB to debug on the target hardware.
-        </para>
+            <para>
+                You can use a different method to view dependency information
+                by using the following command:
+                <literallayout class='monospaced'>
+     $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
+                </literallayout>
+                This command displays a GUI window from which you can view
+                build-time and runtime dependencies for the recipes involved in
+                building <replaceable>recipename</replaceable>.
+            </para>
+        </section>
 
-        <para>
-            To support this kind of debugging, you need do the following:
-            <itemizedlist>
-                <listitem><para>
-                    Ensure that GDB is on the target.
-                    You can do this by adding "gdb" to
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
-                    <literallayout class='monospaced'>
-     IMAGE_INSTALL_append = " gdb"
-                    </literallayout>
-                    Alternatively, you can add "tools-debug" to
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
-                    <literallayout class='monospaced'>
-     IMAGE_FEATURES_append = " tools-debug"
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para>
-                    Ensure that debug symbols are present.
-                    You can make sure these symbols are present by installing
-                    <filename>-dbg</filename>:
+        <section id='dev-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
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
+                        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
+                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+                        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
+                        (<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#shared-state-cache'>sstate</ulink>)
+                        cache, an additional <filename>siginfo</filename> file
+                        is written into
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+                        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-dumpsig</filename> on the
+                        <filename>sigdata</filename> or
+                        <filename>siginfo</filename> file.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ bitbake-dumpsig ${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-dumpsig</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-dumpsig</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'>
+     &dash;&dash;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='dev-debugging-taskrunning'>
+            <title>Running Specific Tasks</title>
+
+            <para>
+                Any given recipe consists of a set of tasks.
+                The standard BitBake behavior in most cases is:
+                <filename>do_fetch</filename>,
+                <filename>do_unpack</filename>,
+                <filename>do_patch</filename>,
+                <filename>do_configure</filename>,
+                <filename>do_compile</filename>,
+                <filename>do_install</filename>,
+                <filename>do_package</filename>,
+                <filename>do_package_write_*</filename>, and
+                <filename>do_build</filename>.
+                The default task is <filename>do_build</filename> and any tasks
+                on which it depends build first.
+                Some tasks, such as <filename>do_devshell</filename>, 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 <filename>-c</filename> option in
+                BitBake.
+                Here is an example:
+                <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devshell
+                </literallayout>
+            </para>
+
+            <para>
+                The <filename>-c</filename> 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
+                <filename>-c</filename>, BitBake will only run the task if it
+                considers it "out of date".
+                See the
+                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
+                section in the Yocto Project Overview Manual for how BitBake
+                determines whether a task is "out of date".
+            </para>
+
+            <para>
+                If you want to force an up-to-date task to be rerun (e.g.
+                because you made manual modifications to the recipe's
+                <ulink linkend='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+                that you want to try out), then you can use the
+                <filename>-f</filename> option.
+                <note>
+                    The reason <filename>-f</filename> is never required when
+                    running the
+                    <ulink linkend='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink>
+                    task is because the
+                    <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
+                    variable flag is already set for the task.
+                </note>
+                The following example shows one way you can use the
+                <filename>-f</filename> option:
+                <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop
+               .
+               .
+     make some changes to the source code in the work directory
+               .
+               .
+     $ bitbake matchbox-desktop -c compile -f
+     $ bitbake matchbox-desktop
+                </literallayout>
+            </para>
+
+            <para>
+                This sequence first builds and then recompiles
+                <filename>matchbox-desktop</filename>.
+                The last command reruns all tasks (basically the packaging
+                tasks) after the compile.
+                BitBake recognizes that the <filename>do_compile</filename>
+                task was rerun and therefore understands that the other tasks
+                also need to be run again.
+            </para>
+
+            <para>
+                Another, shorter way to rerun a task and all
+                <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>
+                that depend on it is to use the <filename>-C</filename>
+                option.
+                <note>
+                    This option is upper-cased and is separate from the
+                    <filename>-c</filename> option, which is lower-cased.
+                </note>
+                Using this option invalidates the given task and then runs the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-build'><filename>do_build</filename></ulink>
+                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:
+                <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -C compile
+                </literallayout>
+                Internally, the <filename>-f</filename> and
+                <filename>-C</filename> 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.
+                <note>
+                    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:
                     <literallayout class='monospaced'>
-     IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
+     WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
                     </literallayout>
-                    Alternatively, you can do the following to include all the
-                    debug symbols:
+                    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:
                     <literallayout class='monospaced'>
-     IMAGE_FEATURES_append = " dbg-pkgs"
+     $ bitbake matchbox-desktop -c clean
+     $ bitbake matchbox-desktop
                     </literallayout>
-                    </para></listitem>
-            </itemizedlist>
-            <note>
-                To improve the debug information accuracy, you can reduce the
-                level of optimization used by the compiler.
-                For example, when adding the following line to your
-                <filename>local.conf</filename> file, you will reduce
-                optimization from
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
-                of "-O2" to
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
-                of "-O -fno-omit-frame-pointer":
+                </note>
+            </para>
+
+            <para>
+                You can view a list of tasks in a given package by running the
+                <filename>do_listtasks</filename> task as follows:
                 <literallayout class='monospaced'>
-     DEBUG_BUILD = "1"
+     $ bitbake matchbox-desktop -c listtasks
                 </literallayout>
-                Consider that this will reduce the application's performance
-                and is recommended only for debugging purposes.
-            </note>
-        </para>
-    </section>
+                The results appear as output to the console and are also in the
+                file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
+            </para>
+        </section>
 
-    <section id='debugging-parallel-make-races'>
-        <title>Debugging Parallel Make Races</title>
+        <section id='dev-debugging-bitbake'>
+            <title>General BitBake Problems</title>
 
-        <para>
-            A parallel <filename>make</filename> race occurs when the build
-            consists of several parts that are run simultaneously and
-            a situation occurs when the output or result of one
-            part is not ready for use with a different part of the build that
-            depends on that output.
-            Parallel make races are annoying and can sometimes be difficult
-            to reproduce and fix.
-            However, some simple tips and tricks exist that can help
-            you debug and fix them.
-            This section presents a real-world example of an error encountered
-            on the Yocto Project autobuilder and the process used to fix it.
-            <note>
-                If you cannot properly fix a <filename>make</filename> race
-                condition, you can work around it by clearing either the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
-                or
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
-                variables.
-            </note>
-        </para>
+            <para>
+                You can see debug output from BitBake by using the
+                <filename>-D</filename> option.
+                The debug output gives more information about what BitBake
+                is doing and the reason behind it.
+                Each <filename>-D</filename> option you use increases the
+                logging level.
+                The most common usage is <filename>-DDD</filename>.
+            </para>
+
+            <para>
+                The output from
+                <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable>
+                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.
+            </para>
+        </section>
 
-        <section id='the-failure'>
-            <title>The Failure</title>
+        <section id='dev-debugging-buildfile'>
+            <title>Building with No Dependencies</title>
 
             <para>
-                For this example, assume that you are building an image that
-                depends on the "neard" package.
-                And, during the build, BitBake runs into problems and
-                creates the following output.
+                To build a specific recipe (<filename>.bb</filename> file),
+                you can use the following command form:
+                <literallayout class='monospaced'>
+     $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
+                </literallayout>
+                This command form does not check for dependencies.
+                Consequently, you should use it only when you know existing
+                dependencies have been met.
                 <note>
-                    This example log file has longer lines artificially
-                    broken to make the listing easier to read.
+                    You can also specify fragments of the filename.
+                    In this case, BitBake checks for a unique match.
                 </note>
-                If you examine the output or the log file, you see the
-                failure during <filename>make</filename>:
-                <literallayout class='monospaced'>
+            </para>
+        </section>
+
+        <section id='recipe-logging-mechanisms'>
+            <title>Recipe Logging Mechanisms</title>
+
+            <para>
+                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
+                <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
+                and can also log to standard output (stdout) with the right
+                settings:
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        Writes <replaceable>msg</replaceable> as is to the
+                        log while also logging to stdout.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        Writes "NOTE: <replaceable>msg</replaceable>" to the
+                        log.
+                        Also logs to stdout if BitBake is called with "-v".
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>bb.debug(</filename><replaceable>level</replaceable><filename>,&nbsp;</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        Writes "DEBUG: <replaceable>msg</replaceable>" to the
+                        log.
+                        Also logs to stdout if the log level is greater than or
+                        equal to <replaceable>level</replaceable>.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
+                        option in the BitBake User Manual for more information.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        Writes "WARNING: <replaceable>msg</replaceable>" to the
+                        log while also logging to stdout.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        Writes "ERROR: <replaceable>msg</replaceable>" to the
+                        log while also logging to standard out (stdout).
+                        <note>
+                            Calling this function does not cause the task to fail.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
+                        This logging function is similar to
+                        <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
+                        but also causes the calling task to fail.
+                        <note>
+                            <filename>bb.fatal()</filename> raises an exception,
+                            which means you do not need to put a "return"
+                            statement after the function.
+                        </note>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                The same logging functions are also available in shell
+                functions, under the names
+                <filename>bbplain</filename>, <filename>bbnote</filename>,
+                <filename>bbdebug</filename>, <filename>bbwarn</filename>,
+                <filename>bberror</filename>, and <filename>bbfatal</filename>.
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-logging'><filename>logging</filename></ulink>
+                class implements these functions.
+                See that class in the
+                <filename>meta/classes</filename> folder of the
+                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                for information.
+            </para>
+
+            <section id='logging-with-python'>
+                <title>Logging With Python</title>
+
+                <para>
+                    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.
+                </para>
+
+                <para>
+                    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
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-listtasks'><filename>do_listtasks</filename></ulink>"
+                    section for additional information:
+                    <literallayout class='monospaced'>
+     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")
+     }
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='logging-with-bash'>
+                <title>Logging With Bash</title>
+
+                <para>
+                    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.
+                </para>
+
+                <para>
+                    Following is an example written in Bash.
+                    The code logs the progress of the <filename>do_my_function</filename> function.
+                    <literallayout class='monospaced'>
+     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"
+     }
+                    </literallayout>
+                </para>
+            </section>
+        </section>
+
+        <section id='debugging-parallel-make-races'>
+            <title>Debugging Parallel Make Races</title>
+
+            <para>
+                A parallel <filename>make</filename> race occurs when the build
+                consists of several parts that are run simultaneously and
+                a situation occurs when the output or result of one
+                part is not ready for use with a different part of the build
+                that depends on that output.
+                Parallel make races are annoying and can sometimes be difficult
+                to reproduce and fix.
+                However, some simple tips and tricks exist that can help
+                you debug and fix them.
+                This section presents a real-world example of an error
+                encountered on the Yocto Project autobuilder and the process
+                used to fix it.
+                <note>
+                    If you cannot properly fix a <filename>make</filename> race
+                    condition, you can work around it by clearing either the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+                    or
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
+                    variables.
+                </note>
+            </para>
+
+            <section id='the-failure'>
+                <title>The Failure</title>
+
+                <para>
+                    For this example, assume that you are building an image that
+                    depends on the "neard" package.
+                    And, during the build, BitBake runs into problems and
+                    creates the following output.
+                    <note>
+                        This example log file has longer lines artificially
+                        broken to make the listing easier to read.
+                    </note>
+                    If you examine the output or the log file, you see the
+                    failure during <filename>make</filename>:
+                    <literallayout class='monospaced'>
      | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
      | DEBUG: Executing shell function do_compile
      | NOTE: make -j 16
@@ -10420,61 +10969,62 @@ Some notes from Cal:
      | make[1]: *** Waiting for unfinished jobs....
      | make: *** [all] Error 2
      | ERROR: oe_runmake failed
-                </literallayout>
-            </para>
-        </section>
+                    </literallayout>
+                </para>
+            </section>
 
-        <section id='reproducing-the-error'>
-            <title>Reproducing the Error</title>
+            <section id='reproducing-the-error'>
+                <title>Reproducing the Error</title>
 
-            <para>
-                Because race conditions are intermittent, they do not
-                manifest themselves every time you do the build.
-                In fact, most times the build will complete without problems
-                even though the potential race condition exists.
-                Thus, once the error surfaces, you need a way to reproduce it.
-            </para>
+                <para>
+                    Because race conditions are intermittent, they do not
+                    manifest themselves every time you do the build.
+                    In fact, most times the build will complete without problems
+                    even though the potential race condition exists.
+                    Thus, once the error surfaces, you need a way to reproduce
+                    it.
+                </para>
 
-            <para>
-                In this example, compiling the "neard" package is causing the
-                problem.
-                So the first thing to do is build "neard" locally.
-                Before you start the build, set the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
-                variable in your <filename>local.conf</filename> file to
-                a high number (e.g. "-j 20").
-                Using a high value for <filename>PARALLEL_MAKE</filename>
-                increases the chances of the race condition showing up:
-                <literallayout class='monospaced'>
+                <para>
+                    In this example, compiling the "neard" package is causing
+                    the problem.
+                    So the first thing to do is build "neard" locally.
+                    Before you start the build, set the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+                    variable in your <filename>local.conf</filename> file to
+                    a high number (e.g. "-j 20").
+                    Using a high value for <filename>PARALLEL_MAKE</filename>
+                    increases the chances of the race condition showing up:
+                    <literallayout class='monospaced'>
      $ bitbake neard
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                Once the local build for "neard" completes, start a
-                <filename>devshell</filename> build:
-                <literallayout class='monospaced'>
+                <para>
+                    Once the local build for "neard" completes, start a
+                    <filename>devshell</filename> build:
+                    <literallayout class='monospaced'>
      $ bitbake neard -c devshell
-                </literallayout>
-                For information on how to use a
-                <filename>devshell</filename>, see the
-                "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
-                section.
-            </para>
+                    </literallayout>
+                    For information on how to use a
+                    <filename>devshell</filename>, see the
+                    "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
+                    section.
+                </para>
 
-            <para>
-                In the <filename>devshell</filename>, do the following:
-                <literallayout class='monospaced'>
+                <para>
+                    In the <filename>devshell</filename>, do the following:
+                    <literallayout class='monospaced'>
      $ make clean
      $ make tools/snep-send.o
-                </literallayout>
-                The <filename>devshell</filename> commands cause the failure
-                to clearly be visible.
-                In this case, a missing dependency exists for the "neard"
-                Makefile target.
-                Here is some abbreviated, sample output with the
-                missing dependency clearly visible at the end:
-                <literallayout class='monospaced'>
+                    </literallayout>
+                    The <filename>devshell</filename> commands cause the failure
+                    to clearly be visible.
+                    In this case, a missing dependency exists for the "neard"
+                    Makefile target.
+                    Here is some abbreviated, sample output with the
+                    missing dependency clearly visible at the end:
+                    <literallayout class='monospaced'>
      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/home/scott-lenovo/......
         .
         .
@@ -10487,113 +11037,547 @@ Some notes from Cal:
      compilation terminated.
      make: *** [tools/snep-send.o] Error 1
      $
-                </literallayout>
-            </para>
-        </section>
+                    </literallayout>
+                </para>
+            </section>
 
-        <section id='creating-a-patch-for-the-fix'>
-            <title>Creating a Patch for the Fix</title>
+            <section id='creating-a-patch-for-the-fix'>
+                <title>Creating a Patch for the Fix</title>
 
-            <para>
-                Because there is a missing dependency for the Makefile
-                target, you need to patch the
-                <filename>Makefile.am</filename> file, which is generated
-                from <filename>Makefile.in</filename>.
-                You can use Quilt to create the patch:
-                <literallayout class='monospaced'>
+                <para>
+                    Because there is a missing dependency for the Makefile
+                    target, you need to patch the
+                    <filename>Makefile.am</filename> file, which is generated
+                    from <filename>Makefile.in</filename>.
+                    You can use Quilt to create the patch:
+                    <literallayout class='monospaced'>
      $ quilt new parallelmake.patch
      Patch patches/parallelmake.patch is now on top
      $ quilt add Makefile.am
      File Makefile.am added to patch patches/parallelmake.patch
-                </literallayout>
-                For more information on using Quilt, see the
-                "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
-                section.
-            </para>
+                    </literallayout>
+                    For more information on using Quilt, see the
+                    "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
+                    section.
+                </para>
 
-            <para>
-                At this point you need to make the edits to
-                <filename>Makefile.am</filename> to add the missing
-                dependency.
-                For our example, you have to add the following line
-                to the file:
-                <literallayout class='monospaced'>
+                <para>
+                    At this point you need to make the edits to
+                    <filename>Makefile.am</filename> to add the missing
+                    dependency.
+                    For our example, you have to add the following line
+                    to the file:
+                    <literallayout class='monospaced'>
      tools/snep-send.$(OBJEXT): include/near/dbus.h
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                Once you have edited the file, use the
-                <filename>refresh</filename> command to create the patch:
-                <literallayout class='monospaced'>
+                <para>
+                    Once you have edited the file, use the
+                    <filename>refresh</filename> command to create the patch:
+                    <literallayout class='monospaced'>
      $ quilt refresh
      Refreshed patch patches/parallelmake.patch
-                </literallayout>
-                Once the patch file exists, you need to add it back to the
-                originating recipe folder.
-                Here is an example assuming a top-level
-                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                named <filename>poky</filename>:
-                <literallayout class='monospaced'>
+                    </literallayout>
+                    Once the patch file exists, you need to add it back to the
+                    originating recipe folder.
+                    Here is an example assuming a top-level
+                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                    named <filename>poky</filename>:
+                    <literallayout class='monospaced'>
      $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
-                </literallayout>
-                The final thing you need to do to implement the fix in the
-                build is to update the "neard" recipe (i.e.
-                <filename>neard-0.14.bb</filename>) so that the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-                statement includes the patch file.
-                The recipe file is in the folder above the patch.
-                Here is what the edited <filename>SRC_URI</filename>
-                statement would look like:
-                <literallayout class='monospaced'>
+                    </literallayout>
+                    The final thing you need to do to implement the fix in the
+                    build is to update the "neard" recipe (i.e.
+                    <filename>neard-0.14.bb</filename>) so that the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    statement includes the patch file.
+                    The recipe file is in the folder above the patch.
+                    Here is what the edited <filename>SRC_URI</filename>
+                    statement would look like:
+                    <literallayout class='monospaced'>
      SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
                 file://neard.in \
                 file://neard.service.in \
                 file://parallelmake.patch \
                "
-                </literallayout>
+                    </literallayout>
+                </para>
+
+                <para>
+                    With the patch complete and moved to the correct folder and
+                    the <filename>SRC_URI</filename> statement updated, you can
+                    exit the <filename>devshell</filename>:
+                    <literallayout class='monospaced'>
+     $ exit
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='testing-the-build'>
+                <title>Testing the Build</title>
+
+                <para>
+                    With everything in place, you can get back to trying the
+                    build again locally:
+                    <literallayout class='monospaced'>
+     $ bitbake neard
+                    </literallayout>
+                    This build should succeed.
+                </para>
+
+                <para>
+                    Now you can open up a <filename>devshell</filename> again
+                    and repeat the clean and make operations as follows:
+                    <literallayout class='monospaced'>
+     $ bitbake neard -c devshell
+     $ make clean
+     $ make tools/snep-send.o
+                    </literallayout>
+                    The build should work without issue.
+                </para>
+
+                <para>
+                    As with all solved problems, if they originated upstream,
+                    you need to submit the fix for the recipe in OE-Core and
+                    upstream so that the problem is taken care of at its
+                    source.
+                    See the
+                    "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+                    section for more information.
+                </para>
+            </section>
+        </section>
+
+        <section id="platdev-gdb-remotedebug">
+            <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+
+            <para>
+                GDB allows you to examine running programs, which in turn helps
+                you to understand and fix problems.
+                It also allows you to perform post-mortem style analysis of
+                program crashes.
+                GDB is available as a package within the Yocto Project and is
+                installed in SDK images by default.
+                See the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                chapter in the Yocto Project Reference Manual for a description of
+                these images.
+                You can find information on GDB at
+                <ulink url="http://sourceware.org/gdb/"/>.
+                <note><title>Tip</title>
+                    For best results, install debug (<filename>-dbg</filename>)
+                    packages for the applications you are going to debug.
+                    Doing so makes extra debug symbols available that give you
+                    more meaningful output.
+                </note>
             </para>
 
             <para>
-                With the patch complete and moved to the correct folder and
-                the <filename>SRC_URI</filename> statement updated, you can
-                exit the <filename>devshell</filename>:
-                <literallayout class='monospaced'>
-     $ exit
-                </literallayout>
+                Sometimes, due to memory or disk space constraints, it is not
+                possible to use GDB directly on the remote target to debug
+                applications.
+                These constraints arise because GDB needs to load the debugging
+                information and the binaries of the process being debugged.
+                Additionally, GDB needs to perform many computations to locate
+                information such as function names, variable names and values,
+                stack traces and so forth - even before starting the debugging
+                process.
+                These extra computations place more load on the target system
+                and can alter the characteristics of the program being debugged.
+            </para>
+
+            <para>
+                To help get past the previously mentioned constraints, you can
+                use gdbserver, which runs on the remote target and does not
+                load any debugging information from the debugged process.
+                Instead, a GDB instance processes the debugging information that
+                is run on a remote computer - the host GDB.
+                The host GDB then sends control commands to gdbserver to make
+                it stop or start the debugged program, as well as read or write
+                memory regions of that debugged program.
+                All the debugging information loaded and processed as well
+               as all the heavy debugging is done by the host GDB.
+                Offloading these processes gives the gdbserver running on the
+                target a chance to remain small and fast.
+            </para>
+
+            <para>
+                Because the host GDB is responsible for loading the debugging
+                information and for doing the necessary processing to make
+                actual debugging happen, you have to make sure the host can
+                access the unstripped binaries complete with their debugging
+                information and also be sure the target is compiled with no
+                optimizations.
+                The host GDB must also have local access to all the libraries
+                used by the debugged program.
+                Because gdbserver does not need any local debugging information,
+                the binaries on the remote target can remain stripped.
+                However, the binaries must also be compiled without optimization
+                so they match the host's binaries.
+            </para>
+
+            <para>
+                To remain consistent with GDB documentation and terminology,
+                the binary being debugged on the remote target machine is
+                referred to as the "inferior" binary.
+                For documentation on GDB see the
+                <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
+            </para>
+
+            <para>
+                The following steps show you how to debug using the GNU project
+                debugger.
+                <orderedlist>
+                    <listitem><para>
+                        <emphasis>Configure your build system to construct the
+                        companion debug filesystem:</emphasis></para>
+
+                        <para>In your <filename>local.conf</filename> file, set
+                        the following:
+                        <literallayout class='monospaced'>
+     IMAGE_GEN_DEBUGFS = "1"
+     IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
+                        </literallayout>
+                        These options cause the OpenEmbedded build system
+                        to generate a special companion filesystem fragment,
+                        which contains the matching source and debug symbols to
+                        your deployable filesystem.
+                        The build system does this by looking at what is in the
+                        deployed filesystem, and pulling the corresponding
+                        <filename>-dbg</filename> packages.</para>
+
+                        <para>The companion debug filesystem is not a complete
+                        filesystem, but only contains the debug fragments.
+                        This filesystem must be combined with the full filesystem
+                        for debugging.
+                        Subsequent steps in this procedure show how to combine
+                        the partial filesystem with the full filesystem.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Configure the system to include gdbserver in
+                        the target filesystem:</emphasis></para>
+
+                        <para>Make the following addition in either your
+                        <filename>local.conf</filename> file or in an image
+                        recipe:
+                        <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = “ gdbserver"
+                        </literallayout>
+                        The change makes sure the <filename>gdbserver</filename>
+                        package is included.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build the environment:</emphasis></para>
+
+                        <para>Use the following command to construct the image
+                        and the companion Debug Filesystem:
+                        <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable>
+                        </literallayout>
+                        Build the cross GDB component and make it available
+                        for debugging.
+                        Build the SDK that matches the image.
+                        Building the SDK is best for a production build
+                        that can be used later for debugging, especially
+                        during long term maintenance:
+                        <literallayout class='monospaced'>
+     $ bitbake -c populate_sdk <replaceable>image</replaceable>
+                        </literallayout></para>
+
+                        <para>Alternatively, you can build the minimal
+                        toolchain components that match the target.
+                        Doing so creates a smaller than typical SDK and only
+                        contains a minimal set of components with which to
+                        build simple test applications, as well as run the
+                        debugger:
+                        <literallayout class='monospaced'>
+     $ bitbake meta-toolchain
+                        </literallayout></para>
+
+                        <para>A final method is to build Gdb itself within
+                        the build system:
+                        <literallayout class='monospaced'>
+     $ bitbake gdb-cross-<replaceable>architecture</replaceable>
+                        </literallayout>
+                        Doing so produces a temporary copy of
+                        <filename>cross-gdb</filename> you can use for
+                        debugging during development.
+                        While this is the quickest approach, the two previous
+                        methods in this step are better when considering
+                        long-term maintenance strategies.
+                        <note>
+                            If you run
+                            <filename>bitbake gdb-cross</filename>, the
+                            OpenEmbedded build system suggests the actual
+                            image (e.g. <filename>gdb-cross-i586</filename>).
+                            The suggestion is usually the actual name you want
+                            to use.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Set up the</emphasis>&nbsp;<filename>debugfs</filename></para>
+
+                        <para>Run the following commands to set up the
+                        <filename>debugfs</filename>:
+                        <literallayout class='monospaced'>
+     $ mkdir debugfs
+     $ cd debugfs
+     $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
+     $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Set up GDB</emphasis></para>
+
+                        <para>Install the SDK (if you built one) and then
+                        source the correct environment file.
+                        Sourcing the environment file puts the SDK in your
+                        <filename>PATH</filename> environment variable.</para>
+
+                        <para>If you are using the build system, Gdb is
+                        located in
+                        <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Boot the target:</emphasis></para>
+
+                        <para>For information on how to run QEMU, see the
+                        <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
+                        <note>
+                            Be sure to verify that your host can access the
+                            target via TCP.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Debug a program:</emphasis></para>
+
+                        <para>Debugging a program involves running gdbserver
+                        on the target and then running Gdb on the host.
+                        The example in this step debugs
+                        <filename>gzip</filename>:
+                        <literallayout class='monospaced'>
+     root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
+                        </literallayout>
+                        For additional gdbserver options, see the
+                        <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
+                        </para>
+
+                        <para>After running gdbserver on the target, you need
+                        to run Gdb on the host and configure it and connect to
+                        the target.
+                        Use these commands:
+                        <literallayout class='monospaced'>
+     $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
+     $ <replaceable>arch</replaceable>-gdb
+
+     (gdb) set sysroot debugfs
+     (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
+     (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
+                        </literallayout>
+                        At this point, everything should automatically load
+                        (i.e. matching binaries, symbols and headers).
+                        <note>
+                            The Gdb <filename>set</filename> commands in the
+                            previous example can be placed into the users
+                           <filename>~/.gdbinit</filename> file.
+                            Upon starting, Gdb automatically runs whatever
+                            commands are in that file.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Deploying without a full image
+                        rebuild:</emphasis></para>
+
+                        <para>In many cases, during development you want a
+                        quick method to deploy a new binary to the target and
+                        debug it, without waiting for a full image build.
+                        </para>
+
+                        <para>One approach to solving this situation is to
+                        just build the component you want to debug.
+                        Once you have built the component, copy the
+                        executable directly to both the target and the
+                        host <filename>debugfs</filename>.</para>
+
+                        <para>If the binary is processed through the debug
+                        splitting in OpenEmbedded, you should also
+                        copy the debug items (i.e. <filename>.debug</filename>
+                        contents and corresponding
+                        <filename>/usr/src/debug</filename> files)
+                        from the work directory.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ bitbake bash
+     $ bitbake -c devshell bash
+     $ cd ..
+     $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
+     $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
             </para>
         </section>
 
-        <section id='testing-the-build'>
-            <title>Testing the Build</title>
+        <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
+            <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
 
             <para>
-                With everything in place, you can get back to trying the
-                build again locally:
-                <literallayout class='monospaced'>
-     $ bitbake neard
-                </literallayout>
-                This build should succeed.
+                The previous section addressed using GDB remotely for debugging
+                purposes, which is the most usual case due to the inherent
+                hardware limitations on many embedded devices.
+                However, debugging in the target hardware itself is also
+                possible with more powerful devices.
+                This section describes what you need to do in order to support
+                using GDB to debug on the target hardware.
             </para>
 
             <para>
-                Now you can open up a <filename>devshell</filename> again
-                and repeat the clean and make operations as follows:
-                <literallayout class='monospaced'>
-     $ bitbake neard -c devshell
-     $ make clean
-     $ make tools/snep-send.o
-                </literallayout>
-                The build should work without issue.
+                To support this kind of debugging, you need do the following:
+                <itemizedlist>
+                    <listitem><para>
+                        Ensure that GDB is on the target.
+                        You can do this by adding "gdb" to
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+                        <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " gdb"
+                        </literallayout>
+                        Alternatively, you can add "tools-debug" to
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
+                        <literallayout class='monospaced'>
+     IMAGE_FEATURES_append = " tools-debug"
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Ensure that debug symbols are present.
+                        You can make sure these symbols are present by
+                        installing <filename>-dbg</filename>:
+                        <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
+                        </literallayout>
+                        Alternatively, you can do the following to include all
+                        the debug symbols:
+                        <literallayout class='monospaced'>
+     IMAGE_FEATURES_append = " dbg-pkgs"
+                        </literallayout>
+                        </para></listitem>
+                </itemizedlist>
+                <note>
+                    To improve the debug information accuracy, you can reduce
+                    the level of optimization used by the compiler.
+                    For example, when adding the following line to your
+                    <filename>local.conf</filename> file, you will reduce
+                    optimization from
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
+                    of "-O2" to
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
+                    of "-O -fno-omit-frame-pointer":
+                    <literallayout class='monospaced'>
+     DEBUG_BUILD = "1"
+                    </literallayout>
+                    Consider that this will reduce the application's performance
+                    and is recommended only for debugging purposes.
+                </note>
             </para>
+        </section>
+
+        <section id='dev-other-debugging-others'>
+            <title>Other Debugging Tips</title>
 
             <para>
-                As with all solved problems, if they originated upstream, you
-                need to submit the fix for the recipe in OE-Core and upstream
-                so that the problem is taken care of at its source.
-                See the
-                "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
-                section for more information.
+                Here are some other tips that you might find useful:
+                <itemizedlist>
+                    <listitem><para>
+                        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
+                        <filename>/usr/lib/</filename> or
+                        <filename>/usr/include/</filename>.
+                        </para></listitem>
+                    <listitem><para>
+                        If you want to remove the <filename>psplash</filename>
+                        boot splashscreen,
+                        add <filename>psplash=false</filename> to  the kernel
+                        command line.
+                        Doing so prevents <filename>psplash</filename> 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).
+                        </para></listitem>
+                    <listitem><para>
+                        Removing
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+                        (usually <filename>tmp/</filename>, within the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>)
+                        can often fix temporary build issues.
+                        Removing <filename>TMPDIR</filename> is usually a
+                        relatively cheap operation, because task output will be
+                        cached in
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+                        (usually <filename>sstate-cache/</filename>, which is
+                        also in the Build Directory).
+                        <note>
+                            Removing <filename>TMPDIR</filename> 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.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        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.</para>
+
+                        <para>Using GNU Grep, you can use the following shell
+                        function to recursively search through common
+                        recipe-related files, skipping binary files,
+                        <filename>.git</filename> directories, and the
+                        Build Directory (assuming its name starts with
+                        "build"):
+                        <literallayout class='monospaced'>
+     g() {
+         grep -Ir \
+              --exclude-dir=.git \
+              --exclude-dir='build*' \
+              --include='*.bb*' \
+              --include='*.inc*' \
+              --include='*.conf*' \
+              --include='*.py*' \
+              "$@"
+     }
+                        </literallayout>
+                        Following are some usage examples:
+                        <literallayout class='monospaced'>
+     $ 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"
+                        </literallayout>
+                        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
+                        <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
+                        For general information on how to submit a bug against
+                        the Yocto Project, see the Yocto Project Bugzilla
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
+                        or the
+                        <link linkend='submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</link>"
+                        section.
+                        <note>
+                            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 <filename>.bbclass</filename>
+                            file).
+                        </note>
+                        </para></listitem>
+                </itemizedlist>
             </para>
         </section>
     </section>