summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-16 10:59:43 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:29 +0000
commit0d52f18d39ee46290a266fabf0d01ad1dffd7bac (patch)
treea1ebfbf384583e6ff91c0c31f697c79a0df4273b /documentation/dev-manual
parent09e9f81c34f1edf432ea217c1c12e99ff0ef4f44 (diff)
downloadpoky-0d52f18d39ee46290a266fabf0d01ad1dffd7bac.tar.gz
dev-manual, ref-manual: Consolidated debug info into dev-manual
Fixes [YOCTO #12370] Moved the debug information from the ref-manual to the dev-manual where other debug information exists. We now have a single area (section) that deals with various debugging techniques and tips. (From yocto-docs rev: 95394197fc04981bf7571e581ff8a0fd9c76223f) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml1870
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:
9994 </section> 9994 </section>
9995 </section> 9995 </section>
9996 9996
9997 <section id="platdev-gdb-remotedebug"> 9997 <section id='usingpoky-debugging-tools-and-techniques'>
9998 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title> 9998 <title>Debugging Tools and Techniques</title>
9999 9999
10000 <para> 10000 <para>
10001 GDB allows you to examine running programs, which in turn helps you to understand and fix problems. 10001 The exact method for debugging build failures depends on the nature
10002 It also allows you to perform post-mortem style analysis of program crashes. 10002 of the problem and on the system's area from which the bug
10003 GDB is available as a package within the Yocto Project and is 10003 originates.
10004 installed in SDK images by default. 10004 Standard debugging practices such as comparison against the last
10005 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter 10005 known working version with examination of the changes and the
10006 in the Yocto Project Reference Manual for a description of these images. 10006 re-application of steps to identify the one causing the problem are
10007 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>. 10007 valid for the Yocto Project just as they are for any other system.
10008 Even though it is impossible to detail every possible potential
10009 failure, this section provides some general tips to aid in
10010 debugging given a variety of situations.
10011 <note><title>Tip</title>
10012 A useful feature for debugging is the error reporting tool.
10013 Configuring the Yocto Project to use this tool causes the
10014 OpenEmbedded build system to produce error reporting commands as
10015 part of the console output.
10016 You can enter the commands after the build completes to log
10017 error information into a common database, that can help you
10018 figure out what might be going wrong.
10019 For information on how to enable and use this feature, see the
10020 "<link linkend='using-the-error-reporting-tool'>Using the Error Reporting Tool</link>"
10021 section.
10022 </note>
10008 </para> 10023 </para>
10009 10024
10010 <tip>
10011 For best results, install debug (<filename>-dbg</filename>) packages
10012 for the applications you are going to debug.
10013 Doing so makes extra debug symbols available that give you more
10014 meaningful output.
10015 </tip>
10016
10017 <para> 10025 <para>
10018 Sometimes, due to memory or disk space constraints, it is not possible 10026 The following list shows the debugging topics in the remainder of
10019 to use GDB directly on the remote target to debug applications. 10027 this section:
10020 These constraints arise because GDB needs to load the debugging information and the 10028 <itemizedlist>
10021 binaries of the process being debugged. 10029 <listitem><para>
10022 Additionally, GDB needs to perform many computations to locate information such as function 10030 "<link linkend='dev-debugging-viewing-logs-from-failed-tasks'>Viewing Logs from Failed Tasks</link>"
10023 names, variable names and values, stack traces and so forth - even before starting the 10031 describes how to find and view logs from tasks that
10024 debugging process. 10032 failed during the build process.
10025 These extra computations place more load on the target system and can alter the 10033 </para></listitem>
10026 characteristics of the program being debugged. 10034 <listitem><para>
10035 "<link linkend='dev-debugging-viewing-variable-values'>Viewing Variable Values</link>"
10036 describes how to use the BitBake <filename>-e</filename>
10037 option to examine variable values after a recipe has been
10038 parsed.
10039 </para></listitem>
10040 <listitem><para>
10041 "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
10042 describes how to use the
10043 <filename>oe-pkgdata-util</filename> utility to query
10044 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
10045 and display package-related information for built
10046 packages.
10047 </para></listitem>
10048 <listitem><para>
10049 "<link linkend='dev-viewing-dependencies-between-recipes-and-tasks'>Viewing Dependencies Between Recipes and Tasks</link>"
10050 describes how to use the BitBake <filename>-g</filename>
10051 option to display recipe dependency information used
10052 during the build.
10053 </para></listitem>
10054 <listitem><para>
10055 "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
10056 describes how to use the
10057 <filename>bitbake-dumpsig</filename> command in
10058 conjunction with key subdirectories in the
10059 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
10060 to determine variable dependencies.
10061 </para></listitem>
10062 <listitem><para>
10063 "<link linkend='dev-debugging-taskrunning'>Running Specific Tasks</link>"
10064 describes how to use several BitBake options (e.g.
10065 <filename>-c</filename>, <filename>-C</filename>, and
10066 <filename>-f</filename>) to run specific tasks in the
10067 build chain.
10068 It can be useful to run tasks "out-of-order" when trying
10069 isolate build issues.
10070 </para></listitem>
10071 <listitem><para>
10072 "<link linkend='dev-debugging-bitbake'>General BitBake Problems</link>"
10073 describes how to use BitBake's <filename>-D</filename>
10074 debug output option to reveal more about what BitBake is
10075 doing during the build.
10076 </para></listitem>
10077 <listitem><para>
10078 "<link linkend='dev-debugging-buildfile'>Building with No Dependencies</link>"
10079 describes how to use the BitBake <filename>-b</filename>
10080 option to build a recipe while ignoring dependencies.
10081 </para></listitem>
10082 <listitem><para>
10083 "<link linkend='recipe-logging-mechanisms'>Recipe Logging Mechanisms</link>"
10084 describes how to use the many recipe logging functions
10085 to produce debugging output and report errors and warnings.
10086 </para></listitem>
10087 <listitem><para>
10088 "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
10089 describes how to debug situations where the build consists
10090 of several parts that are run simultaneously and when the
10091 output or result of one part is not ready for use with a
10092 different part of the build that depends on that output.
10093 </para></listitem>
10094 <listitem><para>
10095 "<link linkend='platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</link>"
10096 describes how to use GDB to allow you to examine running
10097 programs, which can help you fix problems.
10098 </para></listitem>
10099 <listitem><para>
10100 "<link linkend='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>Debugging with the GNU Project Debugger (GDB) on the Target</link>"
10101 describes how to use GDB directly on target hardware for
10102 debugging.
10103 </para></listitem>
10104 <listitem><para>
10105 "<link linkend='dev-other-debugging-others'>Other Debugging Tips</link>"
10106 describes miscellaneous debugging tips that can be useful.
10107 </para></listitem>
10108 </itemizedlist>
10027 </para> 10109 </para>
10028 10110
10029 <para> 10111 <para>
10030 To help get past the previously mentioned constraints, you can use 10112 For debugging information within the popular
10031 gdbserver, which runs on the remote target and does not load any 10113 <trademark class='trade'>Eclipse</trademark> IDE, see the
10032 debugging information from the debugged process. 10114 "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
10033 Instead, a GDB instance processes the debugging information that is run on a 10115 section in the Yocto Project Application Development and the
10034 remote computer - the host GDB. 10116 Extensible Software Development Kit (eSDK) manual.
10035 The host GDB then sends control commands to gdbserver to make it stop or start the debugged
10036 program, as well as read or write memory regions of that debugged program.
10037 All the debugging information loaded and processed as well
10038 as all the heavy debugging is done by the host GDB.
10039 Offloading these processes gives the gdbserver running on the target a chance to remain
10040 small and fast.
10041 </para> 10117 </para>
10042 10118
10043 <para> 10119 <section id='dev-debugging-viewing-logs-from-failed-tasks'>
10044 Because the host GDB is responsible for loading the debugging information and 10120 <title>Viewing Logs from Failed Tasks</title>
10045 for doing the necessary processing to make actual debugging happen,
10046 you have to make sure the host can access the unstripped binaries complete
10047 with their debugging information and also be sure the target is compiled with no optimizations.
10048 The host GDB must also have local access to all the libraries used by the
10049 debugged program.
10050 Because gdbserver does not need any local debugging information, the binaries on
10051 the remote target can remain stripped.
10052 However, the binaries must also be compiled without optimization
10053 so they match the host's binaries.
10054 </para>
10055 10121
10056 <para> 10122 <para>
10057 To remain consistent with GDB documentation and terminology, the binary being debugged 10123 You can find the log for a task in the file
10058 on the remote target machine is referred to as the "inferior" binary. 10124 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
10059 For documentation on GDB see the 10125 For example, the log for the
10060 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>. 10126 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
10061 </para> 10127 task of the QEMU minimal image for the x86 machine
10128 (<filename>qemux86</filename>) might be in
10129 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
10130 To see the commands
10131 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
10132 ran to generate a log, look at the corresponding
10133 <filename>run.do_</filename><replaceable>taskname</replaceable>
10134 file in the same directory.
10135 </para>
10062 10136
10063 <para> 10137 <para>
10064 The following steps show you how to debug using the GNU project 10138 <filename>log.do_</filename><replaceable>taskname</replaceable>
10065 debugger. 10139 and
10066 <orderedlist> 10140 <filename>run.do_</filename><replaceable>taskname</replaceable>
10067 <listitem><para> 10141 are actually symbolic links to
10068 <emphasis>Configure your build system to construct the 10142 <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
10069 companion debug filesystem:</emphasis></para> 10143 and
10144 <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
10145 where <replaceable>pid</replaceable> is the PID the task had
10146 when it ran.
10147 The symlinks always point to the files corresponding to the most
10148 recent run.
10149 </para>
10150 </section>
10070 10151
10071 <para>In your <filename>local.conf</filename> file, set 10152 <section id='dev-debugging-viewing-variable-values'>
10072 the following: 10153 <title>Viewing Variable Values</title>
10073 <literallayout class='monospaced'>
10074 IMAGE_GEN_DEBUGFS = "1"
10075 IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
10076 </literallayout>
10077 These options cause the OpenEmbedded build system
10078 to generate a special companion filesystem fragment,
10079 which contains the matching source and debug symbols to
10080 your deployable filesystem.
10081 The build system does this by looking at what is in the
10082 deployed filesystem, and pulling the corresponding
10083 <filename>-dbg</filename> packages.</para>
10084
10085 <para>The companion debug filesystem is not a complete
10086 filesystem, but only contains the debug fragments.
10087 This filesystem must be combined with the full filesystem
10088 for debugging.
10089 Subsequent steps in this procedure show how to combine
10090 the partial filesystem with the full filesystem.
10091 </para></listitem>
10092 <listitem><para>
10093 <emphasis>Configure the system to include gdbserver in
10094 the target filesystem:</emphasis></para>
10095 10154
10096 <para>Make the following addition in either your 10155 <para>
10097 <filename>local.conf</filename> file or in an image 10156 BitBake's <filename>-e</filename> option is used to display
10098 recipe: 10157 variable values after parsing.
10099 <literallayout class='monospaced'> 10158 The following command displays the variable values after the
10100 IMAGE_INSTALL_append = “ gdbserver" 10159 configuration files (i.e. <filename>local.conf</filename>,
10101 </literallayout> 10160 <filename>bblayers.conf</filename>,
10102 The change makes sure the <filename>gdbserver</filename> 10161 <filename>bitbake.conf</filename> and so forth) have been
10103 package is included. 10162 parsed:
10104 </para></listitem> 10163 <literallayout class='monospaced'>
10105 <listitem><para> 10164 $ bitbake -e
10106 <emphasis>Build the environment:</emphasis></para> 10165 </literallayout>
10166 The following command displays variable values after a specific
10167 recipe has been parsed.
10168 The variables include those from the configuration as well:
10169 <literallayout class='monospaced'>
10170 $ bitbake -e recipename
10171 </literallayout>
10172 <note><para>
10173 Each recipe has its own private set of variables
10174 (datastore).
10175 Internally, after parsing the configuration, a copy of the
10176 resulting datastore is made prior to parsing each recipe.
10177 This copying implies that variables set in one recipe will
10178 not be visible to other recipes.</para>
10179
10180 <para>Likewise, each task within a recipe gets a private
10181 datastore based on the recipe datastore, which means that
10182 variables set within one task will not be visible to
10183 other tasks.</para>
10184 </note>
10185 </para>
10107 10186
10108 <para>Use the following command to construct the image and 10187 <para>
10109 the companion Debug Filesystem: 10188 In the output of <filename>bitbake -e</filename>, each
10110 <literallayout class='monospaced'> 10189 variable is preceded by a description of how the variable
10111 $ bitbake <replaceable>image</replaceable> 10190 got its value, including temporary values that were later
10112 </literallayout> 10191 overriden.
10113 Build the cross GDB component and make it available 10192 This description also includes variable flags (varflags) set on
10114 for debugging. 10193 the variable.
10115 Build the SDK that matches the image. 10194 The output can be very helpful during debugging.
10116 Building the SDK is best for a production build 10195 </para>
10117 that can be used later for debugging, especially
10118 during long term maintenance:
10119 <literallayout class='monospaced'>
10120 $ bitbake -c populate_sdk <replaceable>image</replaceable>
10121 </literallayout></para>
10122
10123 <para>Alternatively, you can build the minimal
10124 toolchain components that match the target.
10125 Doing so creates a smaller than typical SDK and only
10126 contains a minimal set of components with which to
10127 build simple test applications, as well as run the
10128 debugger:
10129 <literallayout class='monospaced'>
10130 $ bitbake meta-toolchain
10131 </literallayout></para>
10132 10196
10133 <para>A final method is to build Gdb itself within 10197 <para>
10134 the build system: 10198 Variables that are exported to the environment are preceded by
10135 <literallayout class='monospaced'> 10199 <filename>export</filename> in the output of
10136 $ bitbake gdb-cross-<replaceable>architecture</replaceable> 10200 <filename>bitbake -e</filename>.
10137 </literallayout> 10201 See the following example:
10138 Doing so produces a temporary copy of 10202 <literallayout class='monospaced'>
10139 <filename>cross-gdb</filename> you can use for 10203 export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
10140 debugging during development. 10204 </literallayout>
10141 While this is the quickest approach, the two previous 10205 </para>
10142 methods in this step are better when considering
10143 long-term maintenance strategies.
10144 <note>
10145 If you run
10146 <filename>bitbake gdb-cross</filename>, the
10147 OpenEmbedded build system suggests the actual
10148 image (e.g. <filename>gdb-cross-i586</filename>).
10149 The suggestion is usually the actual name you want
10150 to use.
10151 </note>
10152 </para></listitem>
10153 <listitem><para>
10154 <emphasis>Set up the</emphasis>&nbsp;<filename>debugfs</filename></para>
10155 10206
10156 <para>Run the following commands to set up the 10207 <para>
10157 <filename>debugfs</filename>: 10208 In addition to variable values, the output of the
10158 <literallayout class='monospaced'> 10209 <filename>bitbake -e</filename> and
10159 $ mkdir debugfs 10210 <filename>bitbake -e</filename>&nbsp;<replaceable>recipe</replaceable>
10160 $ cd debugfs 10211 commands includes the following information:
10161 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2 10212 <itemizedlist>
10162 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2 10213 <listitem><para>
10163 </literallayout> 10214 The output starts with a tree listing all configuration
10164 </para></listitem> 10215 files and classes included globally, recursively listing
10165 <listitem><para> 10216 the files they include or inherit in turn.
10166 <emphasis>Set up GDB</emphasis></para> 10217 Much of the behavior of the OpenEmbedded build system
10218 (including the behavior of the
10219 <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>)
10220 is implemented in the
10221 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
10222 class and the classes it inherits, rather than being
10223 built into BitBake itself.
10224 </para></listitem>
10225 <listitem><para>
10226 After the variable values, all functions appear in the
10227 output.
10228 For shell functions, variables referenced within the
10229 function body are expanded.
10230 If a function has been modified using overrides or
10231 using override-style operators like
10232 <filename>_append</filename> and
10233 <filename>_prepend</filename>, then the final assembled
10234 function body appears in the output.
10235 </para></listitem>
10236 </itemizedlist>
10237 </para>
10238 </section>
10167 10239
10168 <para>Install the SDK (if you built one) and then 10240 <section id='viewing-package-information-with-oe-pkgdata-util'>
10169 source the correct environment file. 10241 <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
10170 Sourcing the environment file puts the SDK in your
10171 <filename>PATH</filename> environment variable.</para>
10172 10242
10173 <para>If you are using the build system, Gdb is 10243 <para>
10174 located in 10244 You can use the <filename>oe-pkgdata-util</filename>
10175 <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb 10245 command-line utility to query
10176 </para></listitem> 10246 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
10177 <listitem><para> 10247 and display various package-related information.
10178 <emphasis>Boot the target:</emphasis></para> 10248 When you use the utility, you must use it to view information
10249 on packages that have already been built.
10250 </para>
10179 10251
10180 <para>For information on how to run QEMU, see the 10252 <para>
10181 <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>. 10253 Following are a few of the available
10182 <note> 10254 <filename>oe-pkgdata-util</filename> subcommands.
10183 Be sure to verify that your host can access the 10255 <note>
10184 target via TCP. 10256 You can use the standard * and ? globbing wildcards as part
10185 </note> 10257 of package names and paths.
10186 </para></listitem> 10258 </note>
10187 <listitem><para> 10259 <itemizedlist>
10188 <emphasis>Debug a program:</emphasis></para> 10260 <listitem><para>
10261 <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
10262 Lists all packages that have been built, optionally
10263 limiting the match to packages that match
10264 <replaceable>pattern</replaceable>.
10265 </para></listitem>
10266 <listitem><para>
10267 <filename>oe-pkgdata-util list-pkg-files&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
10268 Lists the files and directories contained in the given
10269 packages.
10270 <note>
10271 <para>
10272 A different way to view the contents of a package is
10273 to look at the
10274 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
10275 directory of the recipe that generates the
10276 package.
10277 This directory is created by the
10278 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
10279 task and has one subdirectory for each package the
10280 recipe generates, which contains the files stored in
10281 that package.</para>
10282 <para>
10283 If you want to inspect the
10284 <filename>${WORKDIR}/packages-split</filename>
10285 directory, make sure that
10286 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
10287 is not enabled when you build the recipe.
10288 </para>
10289 </note>
10290 </para></listitem>
10291 <listitem><para>
10292 <filename>oe-pkgdata-util find-path&nbsp;</filename><replaceable>path</replaceable><filename>&nbsp;...</filename>:
10293 Lists the names of the packages that contain the given
10294 paths.
10295 For example, the following tells us that
10296 <filename>/usr/share/man/man1/make.1</filename>
10297 is contained in the <filename>make-doc</filename>
10298 package:
10299 <literallayout class='monospaced'>
10300 $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
10301 make-doc: /usr/share/man/man1/make.1
10302 </literallayout>
10303 </para></listitem>
10304 <listitem><para>
10305 <filename>oe-pkgdata-util lookup-recipe&nbsp;</filename><replaceable>package</replaceable><filename>&nbsp;...</filename>:
10306 Lists the name of the recipes that
10307 produce the given packages.
10308 </para></listitem>
10309 </itemizedlist>
10310 </para>
10189 10311
10190 <para>Debugging a program involves running gdbserver 10312 <para>
10191 on the target and then running Gdb on the host. 10313 For more information on the <filename>oe-pkgdata-util</filename>
10192 The example in this step debugs 10314 command, use the help facility:
10193 <filename>gzip</filename>: 10315 <literallayout class='monospaced'>
10194 <literallayout class='monospaced'> 10316 $ oe-pkgdata-util &dash;&dash;help
10195 root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help 10317 $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
10196 </literallayout> 10318 </literallayout>
10197 For additional gdbserver options, see the 10319 </para>
10198 <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>. 10320 </section>
10199 </para>
10200 10321
10201 <para>After running gdbserver on the target, you need 10322 <section id='dev-viewing-dependencies-between-recipes-and-tasks'>
10202 to run Gdb on the host and configure it and connect to 10323 <title>Viewing Dependencies Between Recipes and Tasks</title>
10203 the target.
10204 Use these commands:
10205 <literallayout class='monospaced'>
10206 $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
10207 $ <replaceable>arch</replaceable>-gdb
10208 10324
10209 (gdb) set sysroot debugfs 10325 <para>
10210 (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug 10326 Sometimes it can be hard to see why BitBake wants to build other
10211 (gdb) target remote <replaceable>IP-of-target</replaceable>:1234 10327 recipes before the one you have specified.
10212 </literallayout> 10328 Dependency information can help you understand why a recipe is
10213 At this point, everything should automatically load 10329 built.
10214 (i.e. matching binaries, symbols and headers). 10330 </para>
10215 <note>
10216 The Gdb <filename>set</filename> commands in the
10217 previous example can be placed into the users
10218 <filename>~/.gdbinit</filename> file.
10219 Upon starting, Gdb automatically runs whatever
10220 commands are in that file.
10221 </note>
10222 </para></listitem>
10223 <listitem><para>
10224 <emphasis>Deploying without a full image
10225 rebuild:</emphasis></para>
10226 10331
10227 <para>In many cases, during development you want a 10332 <para>
10228 quick method to deploy a new binary to the target and 10333 To generate dependency information for a recipe, run the
10229 debug it, without waiting for a full image build. 10334 following command:
10230 </para> 10335 <literallayout class='monospaced'>
10336 $ bitbake -g <replaceable>recipename</replaceable>
10337 </literallayout>
10338 This command writes the following files in the current
10339 directory:
10340 <itemizedlist>
10341 <listitem><para>
10342 <filename>pn-buildlist</filename>: A list of
10343 recipes/targets involved in building
10344 <replaceable>recipename</replaceable>.
10345 "Involved" here means that at least one task from the
10346 recipe needs to run when building
10347 <replaceable>recipename</replaceable> from scratch.
10348 Targets that are in
10349 <ulink url='&YOCTO_DOCS_REF_URL;#var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></ulink>
10350 are not listed.
10351 </para></listitem>
10352 <listitem><para>
10353 <filename>task-depends.dot</filename>: A graph showing
10354 dependencies between tasks.
10355 </para></listitem>
10356 </itemizedlist>
10357 </para>
10231 10358
10232 <para>One approach to solving this situation is to 10359 <para>
10233 just build the component you want to debug. 10360 The graphs are in
10234 Once you have built the component, copy the 10361 <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
10235 executable directly to both the target and the 10362 format and can be converted to images (e.g. using the
10236 host <filename>debugfs</filename>.</para> 10363 <filename>dot</filename> tool from
10237 10364 <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
10238 <para>If the binary is processed through the debug 10365 <note><title>Notes</title>
10239 splitting in OpenEmbedded, you should also 10366 <itemizedlist>
10240 copy the debug items (i.e. <filename>.debug</filename> 10367 <listitem><para>
10241 contents and corresponding 10368 DOT files use a plain text format.
10242 <filename>/usr/src/debug</filename> files) 10369 The graphs generated using the
10243 from the work directory. 10370 <filename>bitbake -g</filename> command are often so
10244 Here is an example: 10371 large as to be difficult to read without special
10245 <literallayout class='monospaced'> 10372 pruning (e.g. with Bitbake's
10246 $ bitbake bash 10373 <filename>-I</filename> option) and processing.
10247 $ bitbake -c devshell bash 10374 Despite the form and size of the graphs, the
10248 $ cd .. 10375 corresponding <filename>.dot</filename> files can
10249 $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash 10376 still be possible to read and provide useful
10250 $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs 10377 information.
10251 </literallayout> 10378 </para>
10252 </para></listitem>
10253 </orderedlist>
10254 </para>
10255 </section>
10256 10379
10257 <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'> 10380 <para>As an example, the
10258 <title>Debugging with the GNU Project Debugger (GDB) on the Target</title> 10381 <filename>task-depends.dot</filename> file contains
10382 lines such as the following:
10383 <literallayout class='monospaced'>
10384 "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
10385 </literallayout>
10386 The above example line reveals that the
10387 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
10388 task in <filename>libxslt</filename> depends on the
10389 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
10390 task in <filename>libxml2</filename>, which is a
10391 normal
10392 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
10393 dependency between the two recipes.
10394 </para></listitem>
10395 <listitem><para>
10396 For an example of how <filename>.dot</filename>
10397 files can be processed, see the
10398 <filename>scripts/contrib/graph-tool</filename>
10399 Python script, which finds and displays paths
10400 between graph nodes.
10401 </para></listitem>
10402 </itemizedlist>
10403 </note>
10404 </para>
10259 10405
10260 <para> 10406 <para>
10261 The previous section addressed using GDB remotely for debugging 10407 You can use a different method to view dependency information
10262 purposes, which is the most usual case due to the inherent 10408 by using the following command:
10263 hardware limitations on many embedded devices. 10409 <literallayout class='monospaced'>
10264 However, debugging in the target hardware itself is also possible 10410 $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
10265 with more powerful devices. 10411 </literallayout>
10266 This section describes what you need to do in order to support 10412 This command displays a GUI window from which you can view
10267 using GDB to debug on the target hardware. 10413 build-time and runtime dependencies for the recipes involved in
10268 </para> 10414 building <replaceable>recipename</replaceable>.
10415 </para>
10416 </section>
10269 10417
10270 <para> 10418 <section id='dev-viewing-task-variable-dependencies'>
10271 To support this kind of debugging, you need do the following: 10419 <title>Viewing Task Variable Dependencies</title>
10272 <itemizedlist> 10420
10273 <listitem><para> 10421 <para>
10274 Ensure that GDB is on the target. 10422 As mentioned in the
10275 You can do this by adding "gdb" to 10423 "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
10276 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>: 10424 section of the BitBake User Manual, BitBake tries to
10277 <literallayout class='monospaced'> 10425 automatically determine what variables a task depends on so
10278 IMAGE_INSTALL_append = " gdb" 10426 that it can rerun the task if any values of the variables
10279 </literallayout> 10427 change.
10280 Alternatively, you can add "tools-debug" to 10428 This determination is usually reliable.
10281 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>: 10429 However, if you do things like construct variable names at
10282 <literallayout class='monospaced'> 10430 runtime, then you might have to manually declare dependencies
10283 IMAGE_FEATURES_append = " tools-debug" 10431 on those variables using <filename>vardeps</filename> as
10284 </literallayout> 10432 described in the
10285 </para></listitem> 10433 "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
10286 <listitem><para> 10434 section of the BitBake User Manual.
10287 Ensure that debug symbols are present. 10435 </para>
10288 You can make sure these symbols are present by installing 10436
10289 <filename>-dbg</filename>: 10437 <para>
10438 If you are unsure whether a variable dependency is being
10439 picked up automatically for a given task, you can list the
10440 variable dependencies BitBake has determined by doing the
10441 following:
10442 <orderedlist>
10443 <listitem><para>
10444 Build the recipe containing the task:
10445 <literallayout class='monospaced'>
10446 $ bitbake <replaceable>recipename</replaceable>
10447 </literallayout>
10448 </para></listitem>
10449 <listitem><para>
10450 Inside the
10451 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
10452 directory, find the signature data
10453 (<filename>sigdata</filename>) file that corresponds
10454 to the task.
10455 The <filename>sigdata</filename> files contain a pickled
10456 Python database of all the metadata that went into
10457 creating the input checksum for the task.
10458 As an example, for the
10459 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
10460 task of the <filename>db</filename> recipe, the
10461 <filename>sigdata</filename> file might be found in the
10462 following location:
10463 <literallayout class='monospaced'>
10464 ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
10465 </literallayout>
10466 For tasks that are accelerated through the shared state
10467 (<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#shared-state-cache'>sstate</ulink>)
10468 cache, an additional <filename>siginfo</filename> file
10469 is written into
10470 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
10471 along with the cached task output.
10472 The <filename>siginfo</filename> files contain exactly
10473 the same information as <filename>sigdata</filename>
10474 files.
10475 </para></listitem>
10476 <listitem><para>
10477 Run <filename>bitbake-dumpsig</filename> on the
10478 <filename>sigdata</filename> or
10479 <filename>siginfo</filename> file.
10480 Here is an example:
10481 <literallayout class='monospaced'>
10482 $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
10483 </literallayout>
10484 In the output of the above command, you will find a
10485 line like the following, which lists all the (inferred)
10486 variable dependencies for the task.
10487 This list also includes indirect dependencies from
10488 variables depending on other variables, recursively.
10489 <literallayout class='monospaced'>
10490 Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
10491 </literallayout>
10492 <note>
10493 Functions (e.g. <filename>base_do_fetch</filename>)
10494 also count as variable dependencies.
10495 These functions in turn depend on the variables they
10496 reference.
10497 </note>
10498 The output of <filename>bitbake-dumpsig</filename> also
10499 includes the value each variable had, a list of
10500 dependencies for each variable, and
10501 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
10502 information.
10503 </para></listitem>
10504 </orderedlist>
10505 </para>
10506
10507 <para>
10508 There is also a <filename>bitbake-diffsigs</filename> command
10509 for comparing two <filename>siginfo</filename> or
10510 <filename>sigdata</filename> files.
10511 This command can be helpful when trying to figure out what
10512 changed between two versions of a task.
10513 If you call <filename>bitbake-diffsigs</filename> with just one
10514 file, the command behaves like
10515 <filename>bitbake-dumpsig</filename>.
10516 </para>
10517
10518 <para>
10519 You can also use BitBake to dump out the signature construction
10520 information without executing tasks by using either of the
10521 following BitBake command-line options:
10522 <literallayout class='monospaced'>
10523 &dash;&dash;dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
10524 -S <replaceable>SIGNATURE_HANDLER</replaceable>
10525 </literallayout>
10526 <note>
10527 Two common values for
10528 <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
10529 "printdiff", which dump only the signature or compare the
10530 dumped signature with the cached one, respectively.
10531 </note>
10532 Using BitBake with either of these options causes BitBake to
10533 dump out <filename>sigdata</filename> files in the
10534 <filename>stamps</filename> directory for every task it would
10535 have executed instead of building the specified target package.
10536 </para>
10537 </section>
10538
10539 <section id='dev-debugging-taskrunning'>
10540 <title>Running Specific Tasks</title>
10541
10542 <para>
10543 Any given recipe consists of a set of tasks.
10544 The standard BitBake behavior in most cases is:
10545 <filename>do_fetch</filename>,
10546 <filename>do_unpack</filename>,
10547 <filename>do_patch</filename>,
10548 <filename>do_configure</filename>,
10549 <filename>do_compile</filename>,
10550 <filename>do_install</filename>,
10551 <filename>do_package</filename>,
10552 <filename>do_package_write_*</filename>, and
10553 <filename>do_build</filename>.
10554 The default task is <filename>do_build</filename> and any tasks
10555 on which it depends build first.
10556 Some tasks, such as <filename>do_devshell</filename>, are not
10557 part of the default build chain.
10558 If you wish to run a task that is not part of the default build
10559 chain, you can use the <filename>-c</filename> option in
10560 BitBake.
10561 Here is an example:
10562 <literallayout class='monospaced'>
10563 $ bitbake matchbox-desktop -c devshell
10564 </literallayout>
10565 </para>
10566
10567 <para>
10568 The <filename>-c</filename> option respects task dependencies,
10569 which means that all other tasks (including tasks from other
10570 recipes) that the specified task depends on will be run before
10571 the task.
10572 Even when you manually specify a task to run with
10573 <filename>-c</filename>, BitBake will only run the task if it
10574 considers it "out of date".
10575 See the
10576 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
10577 section in the Yocto Project Overview Manual for how BitBake
10578 determines whether a task is "out of date".
10579 </para>
10580
10581 <para>
10582 If you want to force an up-to-date task to be rerun (e.g.
10583 because you made manual modifications to the recipe's
10584 <ulink linkend='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
10585 that you want to try out), then you can use the
10586 <filename>-f</filename> option.
10587 <note>
10588 The reason <filename>-f</filename> is never required when
10589 running the
10590 <ulink linkend='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink>
10591 task is because the
10592 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
10593 variable flag is already set for the task.
10594 </note>
10595 The following example shows one way you can use the
10596 <filename>-f</filename> option:
10597 <literallayout class='monospaced'>
10598 $ bitbake matchbox-desktop
10599 .
10600 .
10601 make some changes to the source code in the work directory
10602 .
10603 .
10604 $ bitbake matchbox-desktop -c compile -f
10605 $ bitbake matchbox-desktop
10606 </literallayout>
10607 </para>
10608
10609 <para>
10610 This sequence first builds and then recompiles
10611 <filename>matchbox-desktop</filename>.
10612 The last command reruns all tasks (basically the packaging
10613 tasks) after the compile.
10614 BitBake recognizes that the <filename>do_compile</filename>
10615 task was rerun and therefore understands that the other tasks
10616 also need to be run again.
10617 </para>
10618
10619 <para>
10620 Another, shorter way to rerun a task and all
10621 <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>
10622 that depend on it is to use the <filename>-C</filename>
10623 option.
10624 <note>
10625 This option is upper-cased and is separate from the
10626 <filename>-c</filename> option, which is lower-cased.
10627 </note>
10628 Using this option invalidates the given task and then runs the
10629 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-build'><filename>do_build</filename></ulink>
10630 task, which is the default task if no task is given, and the
10631 tasks on which it depends.
10632 You could replace the final two commands in the previous example
10633 with the following single command:
10634 <literallayout class='monospaced'>
10635 $ bitbake matchbox-desktop -C compile
10636 </literallayout>
10637 Internally, the <filename>-f</filename> and
10638 <filename>-C</filename> options work by tainting (modifying) the
10639 input checksum of the specified task.
10640 This tainting indirectly causes the task and its
10641 dependent tasks to be rerun through the normal task dependency
10642 mechanisms.
10643 <note>
10644 BitBake explicitly keeps track of which tasks have been
10645 tainted in this fashion, and will print warnings such as the
10646 following for builds involving such tasks:
10290 <literallayout class='monospaced'> 10647 <literallayout class='monospaced'>
10291 IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg" 10648 WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
10292 </literallayout> 10649 </literallayout>
10293 Alternatively, you can do the following to include all the 10650 The purpose of the warning is to let you know that the work
10294 debug symbols: 10651 directory and build output might not be in the clean state
10652 they would be in for a "normal" build, depending on what
10653 actions you took.
10654 To get rid of such warnings, you can remove the work
10655 directory and rebuild the recipe, as follows:
10295 <literallayout class='monospaced'> 10656 <literallayout class='monospaced'>
10296 IMAGE_FEATURES_append = " dbg-pkgs" 10657 $ bitbake matchbox-desktop -c clean
10658 $ bitbake matchbox-desktop
10297 </literallayout> 10659 </literallayout>
10298 </para></listitem> 10660 </note>
10299 </itemizedlist> 10661 </para>
10300 <note> 10662
10301 To improve the debug information accuracy, you can reduce the 10663 <para>
10302 level of optimization used by the compiler. 10664 You can view a list of tasks in a given package by running the
10303 For example, when adding the following line to your 10665 <filename>do_listtasks</filename> task as follows:
10304 <filename>local.conf</filename> file, you will reduce
10305 optimization from
10306 <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
10307 of "-O2" to
10308 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
10309 of "-O -fno-omit-frame-pointer":
10310 <literallayout class='monospaced'> 10666 <literallayout class='monospaced'>
10311 DEBUG_BUILD = "1" 10667 $ bitbake matchbox-desktop -c listtasks
10312 </literallayout> 10668 </literallayout>
10313 Consider that this will reduce the application's performance 10669 The results appear as output to the console and are also in the
10314 and is recommended only for debugging purposes. 10670 file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
10315 </note> 10671 </para>
10316 </para> 10672 </section>
10317 </section>
10318 10673
10319 <section id='debugging-parallel-make-races'> 10674 <section id='dev-debugging-bitbake'>
10320 <title>Debugging Parallel Make Races</title> 10675 <title>General BitBake Problems</title>
10321 10676
10322 <para> 10677 <para>
10323 A parallel <filename>make</filename> race occurs when the build 10678 You can see debug output from BitBake by using the
10324 consists of several parts that are run simultaneously and 10679 <filename>-D</filename> option.
10325 a situation occurs when the output or result of one 10680 The debug output gives more information about what BitBake
10326 part is not ready for use with a different part of the build that 10681 is doing and the reason behind it.
10327 depends on that output. 10682 Each <filename>-D</filename> option you use increases the
10328 Parallel make races are annoying and can sometimes be difficult 10683 logging level.
10329 to reproduce and fix. 10684 The most common usage is <filename>-DDD</filename>.
10330 However, some simple tips and tricks exist that can help 10685 </para>
10331 you debug and fix them. 10686
10332 This section presents a real-world example of an error encountered 10687 <para>
10333 on the Yocto Project autobuilder and the process used to fix it. 10688 The output from
10334 <note> 10689 <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable>
10335 If you cannot properly fix a <filename>make</filename> race 10690 can reveal why BitBake chose a certain version of a package or
10336 condition, you can work around it by clearing either the 10691 why BitBake picked a certain provider.
10337 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> 10692 This command could also help you in a situation where you think
10338 or 10693 BitBake did something unexpected.
10339 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> 10694 </para>
10340 variables. 10695 </section>
10341 </note>
10342 </para>
10343 10696
10344 <section id='the-failure'> 10697 <section id='dev-debugging-buildfile'>
10345 <title>The Failure</title> 10698 <title>Building with No Dependencies</title>
10346 10699
10347 <para> 10700 <para>
10348 For this example, assume that you are building an image that 10701 To build a specific recipe (<filename>.bb</filename> file),
10349 depends on the "neard" package. 10702 you can use the following command form:
10350 And, during the build, BitBake runs into problems and 10703 <literallayout class='monospaced'>
10351 creates the following output. 10704 $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
10705 </literallayout>
10706 This command form does not check for dependencies.
10707 Consequently, you should use it only when you know existing
10708 dependencies have been met.
10352 <note> 10709 <note>
10353 This example log file has longer lines artificially 10710 You can also specify fragments of the filename.
10354 broken to make the listing easier to read. 10711 In this case, BitBake checks for a unique match.
10355 </note> 10712 </note>
10356 If you examine the output or the log file, you see the 10713 </para>
10357 failure during <filename>make</filename>: 10714 </section>
10358 <literallayout class='monospaced'> 10715
10716 <section id='recipe-logging-mechanisms'>
10717 <title>Recipe Logging Mechanisms</title>
10718
10719 <para>
10720 The Yocto Project provides several logging functions for
10721 producing debugging output and reporting errors and warnings.
10722 For Python functions, the following logging functions exist.
10723 All of these functions log to
10724 <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
10725 and can also log to standard output (stdout) with the right
10726 settings:
10727 <itemizedlist>
10728 <listitem><para>
10729 <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
10730 Writes <replaceable>msg</replaceable> as is to the
10731 log while also logging to stdout.
10732 </para></listitem>
10733 <listitem><para>
10734 <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
10735 Writes "NOTE: <replaceable>msg</replaceable>" to the
10736 log.
10737 Also logs to stdout if BitBake is called with "-v".
10738 </para></listitem>
10739 <listitem><para>
10740 <filename>bb.debug(</filename><replaceable>level</replaceable><filename>,&nbsp;</filename><replaceable>msg</replaceable><filename>)</filename>:
10741 Writes "DEBUG: <replaceable>msg</replaceable>" to the
10742 log.
10743 Also logs to stdout if the log level is greater than or
10744 equal to <replaceable>level</replaceable>.
10745 See the
10746 "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
10747 option in the BitBake User Manual for more information.
10748 </para></listitem>
10749 <listitem><para>
10750 <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
10751 Writes "WARNING: <replaceable>msg</replaceable>" to the
10752 log while also logging to stdout.
10753 </para></listitem>
10754 <listitem><para>
10755 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
10756 Writes "ERROR: <replaceable>msg</replaceable>" to the
10757 log while also logging to standard out (stdout).
10758 <note>
10759 Calling this function does not cause the task to fail.
10760 </note>
10761 </para></listitem>
10762 <listitem><para>
10763 <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
10764 This logging function is similar to
10765 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
10766 but also causes the calling task to fail.
10767 <note>
10768 <filename>bb.fatal()</filename> raises an exception,
10769 which means you do not need to put a "return"
10770 statement after the function.
10771 </note>
10772 </para></listitem>
10773 </itemizedlist>
10774 </para>
10775
10776 <para>
10777 The same logging functions are also available in shell
10778 functions, under the names
10779 <filename>bbplain</filename>, <filename>bbnote</filename>,
10780 <filename>bbdebug</filename>, <filename>bbwarn</filename>,
10781 <filename>bberror</filename>, and <filename>bbfatal</filename>.
10782 The
10783 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-logging'><filename>logging</filename></ulink>
10784 class implements these functions.
10785 See that class in the
10786 <filename>meta/classes</filename> folder of the
10787 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
10788 for information.
10789 </para>
10790
10791 <section id='logging-with-python'>
10792 <title>Logging With Python</title>
10793
10794 <para>
10795 When creating recipes using Python and inserting code that
10796 handles build logs, keep in mind the goal is to have
10797 informative logs while keeping the console as "silent" as
10798 possible.
10799 Also, if you want status messages in the log, use the
10800 "debug" loglevel.
10801 </para>
10802
10803 <para>
10804 Following is an example written in Python.
10805 The code handles logging for a function that determines the
10806 number of tasks needed to be run.
10807 See the
10808 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-listtasks'><filename>do_listtasks</filename></ulink>"
10809 section for additional information:
10810 <literallayout class='monospaced'>
10811 python do_listtasks() {
10812 bb.debug(2, "Starting to figure out the task list")
10813 if noteworthy_condition:
10814 bb.note("There are 47 tasks to run")
10815 bb.debug(2, "Got to point xyz")
10816 if warning_trigger:
10817 bb.warn("Detected warning_trigger, this might be a problem later.")
10818 if recoverable_error:
10819 bb.error("Hit recoverable_error, you really need to fix this!")
10820 if fatal_error:
10821 bb.fatal("fatal_error detected, unable to print the task list")
10822 bb.plain("The tasks present are abc")
10823 bb.debug(2, "Finished figuring out the tasklist")
10824 }
10825 </literallayout>
10826 </para>
10827 </section>
10828
10829 <section id='logging-with-bash'>
10830 <title>Logging With Bash</title>
10831
10832 <para>
10833 When creating recipes using Bash and inserting code that
10834 handles build logs, you have the same goals - informative
10835 with minimal console output.
10836 The syntax you use for recipes written in Bash is similar
10837 to that of recipes written in Python described in the
10838 previous section.
10839 </para>
10840
10841 <para>
10842 Following is an example written in Bash.
10843 The code logs the progress of the <filename>do_my_function</filename> function.
10844 <literallayout class='monospaced'>
10845 do_my_function() {
10846 bbdebug 2 "Running do_my_function"
10847 if [ exceptional_condition ]; then
10848 bbnote "Hit exceptional_condition"
10849 fi
10850 bbdebug 2 "Got to point xyz"
10851 if [ warning_trigger ]; then
10852 bbwarn "Detected warning_trigger, this might cause a problem later."
10853 fi
10854 if [ recoverable_error ]; then
10855 bberror "Hit recoverable_error, correcting"
10856 fi
10857 if [ fatal_error ]; then
10858 bbfatal "fatal_error detected"
10859 fi
10860 bbdebug 2 "Completed do_my_function"
10861 }
10862 </literallayout>
10863 </para>
10864 </section>
10865 </section>
10866
10867 <section id='debugging-parallel-make-races'>
10868 <title>Debugging Parallel Make Races</title>
10869
10870 <para>
10871 A parallel <filename>make</filename> race occurs when the build
10872 consists of several parts that are run simultaneously and
10873 a situation occurs when the output or result of one
10874 part is not ready for use with a different part of the build
10875 that depends on that output.
10876 Parallel make races are annoying and can sometimes be difficult
10877 to reproduce and fix.
10878 However, some simple tips and tricks exist that can help
10879 you debug and fix them.
10880 This section presents a real-world example of an error
10881 encountered on the Yocto Project autobuilder and the process
10882 used to fix it.
10883 <note>
10884 If you cannot properly fix a <filename>make</filename> race
10885 condition, you can work around it by clearing either the
10886 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
10887 or
10888 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
10889 variables.
10890 </note>
10891 </para>
10892
10893 <section id='the-failure'>
10894 <title>The Failure</title>
10895
10896 <para>
10897 For this example, assume that you are building an image that
10898 depends on the "neard" package.
10899 And, during the build, BitBake runs into problems and
10900 creates the following output.
10901 <note>
10902 This example log file has longer lines artificially
10903 broken to make the listing easier to read.
10904 </note>
10905 If you examine the output or the log file, you see the
10906 failure during <filename>make</filename>:
10907 <literallayout class='monospaced'>
10359 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] 10908 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
10360 | DEBUG: Executing shell function do_compile 10909 | DEBUG: Executing shell function do_compile
10361 | NOTE: make -j 16 10910 | NOTE: make -j 16
@@ -10420,61 +10969,62 @@ Some notes from Cal:
10420 | make[1]: *** Waiting for unfinished jobs.... 10969 | make[1]: *** Waiting for unfinished jobs....
10421 | make: *** [all] Error 2 10970 | make: *** [all] Error 2
10422 | ERROR: oe_runmake failed 10971 | ERROR: oe_runmake failed
10423 </literallayout> 10972 </literallayout>
10424 </para> 10973 </para>
10425 </section> 10974 </section>
10426 10975
10427 <section id='reproducing-the-error'> 10976 <section id='reproducing-the-error'>
10428 <title>Reproducing the Error</title> 10977 <title>Reproducing the Error</title>
10429 10978
10430 <para> 10979 <para>
10431 Because race conditions are intermittent, they do not 10980 Because race conditions are intermittent, they do not
10432 manifest themselves every time you do the build. 10981 manifest themselves every time you do the build.
10433 In fact, most times the build will complete without problems 10982 In fact, most times the build will complete without problems
10434 even though the potential race condition exists. 10983 even though the potential race condition exists.
10435 Thus, once the error surfaces, you need a way to reproduce it. 10984 Thus, once the error surfaces, you need a way to reproduce
10436 </para> 10985 it.
10986 </para>
10437 10987
10438 <para> 10988 <para>
10439 In this example, compiling the "neard" package is causing the 10989 In this example, compiling the "neard" package is causing
10440 problem. 10990 the problem.
10441 So the first thing to do is build "neard" locally. 10991 So the first thing to do is build "neard" locally.
10442 Before you start the build, set the 10992 Before you start the build, set the
10443 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> 10993 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
10444 variable in your <filename>local.conf</filename> file to 10994 variable in your <filename>local.conf</filename> file to
10445 a high number (e.g. "-j 20"). 10995 a high number (e.g. "-j 20").
10446 Using a high value for <filename>PARALLEL_MAKE</filename> 10996 Using a high value for <filename>PARALLEL_MAKE</filename>
10447 increases the chances of the race condition showing up: 10997 increases the chances of the race condition showing up:
10448 <literallayout class='monospaced'> 10998 <literallayout class='monospaced'>
10449 $ bitbake neard 10999 $ bitbake neard
10450 </literallayout> 11000 </literallayout>
10451 </para> 11001 </para>
10452 11002
10453 <para> 11003 <para>
10454 Once the local build for "neard" completes, start a 11004 Once the local build for "neard" completes, start a
10455 <filename>devshell</filename> build: 11005 <filename>devshell</filename> build:
10456 <literallayout class='monospaced'> 11006 <literallayout class='monospaced'>
10457 $ bitbake neard -c devshell 11007 $ bitbake neard -c devshell
10458 </literallayout> 11008 </literallayout>
10459 For information on how to use a 11009 For information on how to use a
10460 <filename>devshell</filename>, see the 11010 <filename>devshell</filename>, see the
10461 "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>" 11011 "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
10462 section. 11012 section.
10463 </para> 11013 </para>
10464 11014
10465 <para> 11015 <para>
10466 In the <filename>devshell</filename>, do the following: 11016 In the <filename>devshell</filename>, do the following:
10467 <literallayout class='monospaced'> 11017 <literallayout class='monospaced'>
10468 $ make clean 11018 $ make clean
10469 $ make tools/snep-send.o 11019 $ make tools/snep-send.o
10470 </literallayout> 11020 </literallayout>
10471 The <filename>devshell</filename> commands cause the failure 11021 The <filename>devshell</filename> commands cause the failure
10472 to clearly be visible. 11022 to clearly be visible.
10473 In this case, a missing dependency exists for the "neard" 11023 In this case, a missing dependency exists for the "neard"
10474 Makefile target. 11024 Makefile target.
10475 Here is some abbreviated, sample output with the 11025 Here is some abbreviated, sample output with the
10476 missing dependency clearly visible at the end: 11026 missing dependency clearly visible at the end:
10477 <literallayout class='monospaced'> 11027 <literallayout class='monospaced'>
10478 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... 11028 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
10479 . 11029 .
10480 . 11030 .
@@ -10487,113 +11037,547 @@ Some notes from Cal:
10487 compilation terminated. 11037 compilation terminated.
10488 make: *** [tools/snep-send.o] Error 1 11038 make: *** [tools/snep-send.o] Error 1
10489 $ 11039 $
10490 </literallayout> 11040 </literallayout>
10491 </para> 11041 </para>
10492 </section> 11042 </section>
10493 11043
10494 <section id='creating-a-patch-for-the-fix'> 11044 <section id='creating-a-patch-for-the-fix'>
10495 <title>Creating a Patch for the Fix</title> 11045 <title>Creating a Patch for the Fix</title>
10496 11046
10497 <para> 11047 <para>
10498 Because there is a missing dependency for the Makefile 11048 Because there is a missing dependency for the Makefile
10499 target, you need to patch the 11049 target, you need to patch the
10500 <filename>Makefile.am</filename> file, which is generated 11050 <filename>Makefile.am</filename> file, which is generated
10501 from <filename>Makefile.in</filename>. 11051 from <filename>Makefile.in</filename>.
10502 You can use Quilt to create the patch: 11052 You can use Quilt to create the patch:
10503 <literallayout class='monospaced'> 11053 <literallayout class='monospaced'>
10504 $ quilt new parallelmake.patch 11054 $ quilt new parallelmake.patch
10505 Patch patches/parallelmake.patch is now on top 11055 Patch patches/parallelmake.patch is now on top
10506 $ quilt add Makefile.am 11056 $ quilt add Makefile.am
10507 File Makefile.am added to patch patches/parallelmake.patch 11057 File Makefile.am added to patch patches/parallelmake.patch
10508 </literallayout> 11058 </literallayout>
10509 For more information on using Quilt, see the 11059 For more information on using Quilt, see the
10510 "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" 11060 "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
10511 section. 11061 section.
10512 </para> 11062 </para>
10513 11063
10514 <para> 11064 <para>
10515 At this point you need to make the edits to 11065 At this point you need to make the edits to
10516 <filename>Makefile.am</filename> to add the missing 11066 <filename>Makefile.am</filename> to add the missing
10517 dependency. 11067 dependency.
10518 For our example, you have to add the following line 11068 For our example, you have to add the following line
10519 to the file: 11069 to the file:
10520 <literallayout class='monospaced'> 11070 <literallayout class='monospaced'>
10521 tools/snep-send.$(OBJEXT): include/near/dbus.h 11071 tools/snep-send.$(OBJEXT): include/near/dbus.h
10522 </literallayout> 11072 </literallayout>
10523 </para> 11073 </para>
10524 11074
10525 <para> 11075 <para>
10526 Once you have edited the file, use the 11076 Once you have edited the file, use the
10527 <filename>refresh</filename> command to create the patch: 11077 <filename>refresh</filename> command to create the patch:
10528 <literallayout class='monospaced'> 11078 <literallayout class='monospaced'>
10529 $ quilt refresh 11079 $ quilt refresh
10530 Refreshed patch patches/parallelmake.patch 11080 Refreshed patch patches/parallelmake.patch
10531 </literallayout> 11081 </literallayout>
10532 Once the patch file exists, you need to add it back to the 11082 Once the patch file exists, you need to add it back to the
10533 originating recipe folder. 11083 originating recipe folder.
10534 Here is an example assuming a top-level 11084 Here is an example assuming a top-level
10535 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 11085 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
10536 named <filename>poky</filename>: 11086 named <filename>poky</filename>:
10537 <literallayout class='monospaced'> 11087 <literallayout class='monospaced'>
10538 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard 11088 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
10539 </literallayout> 11089 </literallayout>
10540 The final thing you need to do to implement the fix in the 11090 The final thing you need to do to implement the fix in the
10541 build is to update the "neard" recipe (i.e. 11091 build is to update the "neard" recipe (i.e.
10542 <filename>neard-0.14.bb</filename>) so that the 11092 <filename>neard-0.14.bb</filename>) so that the
10543 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 11093 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
10544 statement includes the patch file. 11094 statement includes the patch file.
10545 The recipe file is in the folder above the patch. 11095 The recipe file is in the folder above the patch.
10546 Here is what the edited <filename>SRC_URI</filename> 11096 Here is what the edited <filename>SRC_URI</filename>
10547 statement would look like: 11097 statement would look like:
10548 <literallayout class='monospaced'> 11098 <literallayout class='monospaced'>
10549 SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ 11099 SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
10550 file://neard.in \ 11100 file://neard.in \
10551 file://neard.service.in \ 11101 file://neard.service.in \
10552 file://parallelmake.patch \ 11102 file://parallelmake.patch \
10553 " 11103 "
10554 </literallayout> 11104 </literallayout>
11105 </para>
11106
11107 <para>
11108 With the patch complete and moved to the correct folder and
11109 the <filename>SRC_URI</filename> statement updated, you can
11110 exit the <filename>devshell</filename>:
11111 <literallayout class='monospaced'>
11112 $ exit
11113 </literallayout>
11114 </para>
11115 </section>
11116
11117 <section id='testing-the-build'>
11118 <title>Testing the Build</title>
11119
11120 <para>
11121 With everything in place, you can get back to trying the
11122 build again locally:
11123 <literallayout class='monospaced'>
11124 $ bitbake neard
11125 </literallayout>
11126 This build should succeed.
11127 </para>
11128
11129 <para>
11130 Now you can open up a <filename>devshell</filename> again
11131 and repeat the clean and make operations as follows:
11132 <literallayout class='monospaced'>
11133 $ bitbake neard -c devshell
11134 $ make clean
11135 $ make tools/snep-send.o
11136 </literallayout>
11137 The build should work without issue.
11138 </para>
11139
11140 <para>
11141 As with all solved problems, if they originated upstream,
11142 you need to submit the fix for the recipe in OE-Core and
11143 upstream so that the problem is taken care of at its
11144 source.
11145 See the
11146 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
11147 section for more information.
11148 </para>
11149 </section>
11150 </section>
11151
11152 <section id="platdev-gdb-remotedebug">
11153 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
11154
11155 <para>
11156 GDB allows you to examine running programs, which in turn helps
11157 you to understand and fix problems.
11158 It also allows you to perform post-mortem style analysis of
11159 program crashes.
11160 GDB is available as a package within the Yocto Project and is
11161 installed in SDK images by default.
11162 See the
11163 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
11164 chapter in the Yocto Project Reference Manual for a description of
11165 these images.
11166 You can find information on GDB at
11167 <ulink url="http://sourceware.org/gdb/"/>.
11168 <note><title>Tip</title>
11169 For best results, install debug (<filename>-dbg</filename>)
11170 packages for the applications you are going to debug.
11171 Doing so makes extra debug symbols available that give you
11172 more meaningful output.
11173 </note>
10555 </para> 11174 </para>
10556 11175
10557 <para> 11176 <para>
10558 With the patch complete and moved to the correct folder and 11177 Sometimes, due to memory or disk space constraints, it is not
10559 the <filename>SRC_URI</filename> statement updated, you can 11178 possible to use GDB directly on the remote target to debug
10560 exit the <filename>devshell</filename>: 11179 applications.
10561 <literallayout class='monospaced'> 11180 These constraints arise because GDB needs to load the debugging
10562 $ exit 11181 information and the binaries of the process being debugged.
10563 </literallayout> 11182 Additionally, GDB needs to perform many computations to locate
11183 information such as function names, variable names and values,
11184 stack traces and so forth - even before starting the debugging
11185 process.
11186 These extra computations place more load on the target system
11187 and can alter the characteristics of the program being debugged.
11188 </para>
11189
11190 <para>
11191 To help get past the previously mentioned constraints, you can
11192 use gdbserver, which runs on the remote target and does not
11193 load any debugging information from the debugged process.
11194 Instead, a GDB instance processes the debugging information that
11195 is run on a remote computer - the host GDB.
11196 The host GDB then sends control commands to gdbserver to make
11197 it stop or start the debugged program, as well as read or write
11198 memory regions of that debugged program.
11199 All the debugging information loaded and processed as well
11200 as all the heavy debugging is done by the host GDB.
11201 Offloading these processes gives the gdbserver running on the
11202 target a chance to remain small and fast.
11203 </para>
11204
11205 <para>
11206 Because the host GDB is responsible for loading the debugging
11207 information and for doing the necessary processing to make
11208 actual debugging happen, you have to make sure the host can
11209 access the unstripped binaries complete with their debugging
11210 information and also be sure the target is compiled with no
11211 optimizations.
11212 The host GDB must also have local access to all the libraries
11213 used by the debugged program.
11214 Because gdbserver does not need any local debugging information,
11215 the binaries on the remote target can remain stripped.
11216 However, the binaries must also be compiled without optimization
11217 so they match the host's binaries.
11218 </para>
11219
11220 <para>
11221 To remain consistent with GDB documentation and terminology,
11222 the binary being debugged on the remote target machine is
11223 referred to as the "inferior" binary.
11224 For documentation on GDB see the
11225 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
11226 </para>
11227
11228 <para>
11229 The following steps show you how to debug using the GNU project
11230 debugger.
11231 <orderedlist>
11232 <listitem><para>
11233 <emphasis>Configure your build system to construct the
11234 companion debug filesystem:</emphasis></para>
11235
11236 <para>In your <filename>local.conf</filename> file, set
11237 the following:
11238 <literallayout class='monospaced'>
11239 IMAGE_GEN_DEBUGFS = "1"
11240 IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
11241 </literallayout>
11242 These options cause the OpenEmbedded build system
11243 to generate a special companion filesystem fragment,
11244 which contains the matching source and debug symbols to
11245 your deployable filesystem.
11246 The build system does this by looking at what is in the
11247 deployed filesystem, and pulling the corresponding
11248 <filename>-dbg</filename> packages.</para>
11249
11250 <para>The companion debug filesystem is not a complete
11251 filesystem, but only contains the debug fragments.
11252 This filesystem must be combined with the full filesystem
11253 for debugging.
11254 Subsequent steps in this procedure show how to combine
11255 the partial filesystem with the full filesystem.
11256 </para></listitem>
11257 <listitem><para>
11258 <emphasis>Configure the system to include gdbserver in
11259 the target filesystem:</emphasis></para>
11260
11261 <para>Make the following addition in either your
11262 <filename>local.conf</filename> file or in an image
11263 recipe:
11264 <literallayout class='monospaced'>
11265 IMAGE_INSTALL_append = “ gdbserver"
11266 </literallayout>
11267 The change makes sure the <filename>gdbserver</filename>
11268 package is included.
11269 </para></listitem>
11270 <listitem><para>
11271 <emphasis>Build the environment:</emphasis></para>
11272
11273 <para>Use the following command to construct the image
11274 and the companion Debug Filesystem:
11275 <literallayout class='monospaced'>
11276 $ bitbake <replaceable>image</replaceable>
11277 </literallayout>
11278 Build the cross GDB component and make it available
11279 for debugging.
11280 Build the SDK that matches the image.
11281 Building the SDK is best for a production build
11282 that can be used later for debugging, especially
11283 during long term maintenance:
11284 <literallayout class='monospaced'>
11285 $ bitbake -c populate_sdk <replaceable>image</replaceable>
11286 </literallayout></para>
11287
11288 <para>Alternatively, you can build the minimal
11289 toolchain components that match the target.
11290 Doing so creates a smaller than typical SDK and only
11291 contains a minimal set of components with which to
11292 build simple test applications, as well as run the
11293 debugger:
11294 <literallayout class='monospaced'>
11295 $ bitbake meta-toolchain
11296 </literallayout></para>
11297
11298 <para>A final method is to build Gdb itself within
11299 the build system:
11300 <literallayout class='monospaced'>
11301 $ bitbake gdb-cross-<replaceable>architecture</replaceable>
11302 </literallayout>
11303 Doing so produces a temporary copy of
11304 <filename>cross-gdb</filename> you can use for
11305 debugging during development.
11306 While this is the quickest approach, the two previous
11307 methods in this step are better when considering
11308 long-term maintenance strategies.
11309 <note>
11310 If you run
11311 <filename>bitbake gdb-cross</filename>, the
11312 OpenEmbedded build system suggests the actual
11313 image (e.g. <filename>gdb-cross-i586</filename>).
11314 The suggestion is usually the actual name you want
11315 to use.
11316 </note>
11317 </para></listitem>
11318 <listitem><para>
11319 <emphasis>Set up the</emphasis>&nbsp;<filename>debugfs</filename></para>
11320
11321 <para>Run the following commands to set up the
11322 <filename>debugfs</filename>:
11323 <literallayout class='monospaced'>
11324 $ mkdir debugfs
11325 $ cd debugfs
11326 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
11327 $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
11328 </literallayout>
11329 </para></listitem>
11330 <listitem><para>
11331 <emphasis>Set up GDB</emphasis></para>
11332
11333 <para>Install the SDK (if you built one) and then
11334 source the correct environment file.
11335 Sourcing the environment file puts the SDK in your
11336 <filename>PATH</filename> environment variable.</para>
11337
11338 <para>If you are using the build system, Gdb is
11339 located in
11340 <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
11341 </para></listitem>
11342 <listitem><para>
11343 <emphasis>Boot the target:</emphasis></para>
11344
11345 <para>For information on how to run QEMU, see the
11346 <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
11347 <note>
11348 Be sure to verify that your host can access the
11349 target via TCP.
11350 </note>
11351 </para></listitem>
11352 <listitem><para>
11353 <emphasis>Debug a program:</emphasis></para>
11354
11355 <para>Debugging a program involves running gdbserver
11356 on the target and then running Gdb on the host.
11357 The example in this step debugs
11358 <filename>gzip</filename>:
11359 <literallayout class='monospaced'>
11360 root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
11361 </literallayout>
11362 For additional gdbserver options, see the
11363 <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
11364 </para>
11365
11366 <para>After running gdbserver on the target, you need
11367 to run Gdb on the host and configure it and connect to
11368 the target.
11369 Use these commands:
11370 <literallayout class='monospaced'>
11371 $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
11372 $ <replaceable>arch</replaceable>-gdb
11373
11374 (gdb) set sysroot debugfs
11375 (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
11376 (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
11377 </literallayout>
11378 At this point, everything should automatically load
11379 (i.e. matching binaries, symbols and headers).
11380 <note>
11381 The Gdb <filename>set</filename> commands in the
11382 previous example can be placed into the users
11383 <filename>~/.gdbinit</filename> file.
11384 Upon starting, Gdb automatically runs whatever
11385 commands are in that file.
11386 </note>
11387 </para></listitem>
11388 <listitem><para>
11389 <emphasis>Deploying without a full image
11390 rebuild:</emphasis></para>
11391
11392 <para>In many cases, during development you want a
11393 quick method to deploy a new binary to the target and
11394 debug it, without waiting for a full image build.
11395 </para>
11396
11397 <para>One approach to solving this situation is to
11398 just build the component you want to debug.
11399 Once you have built the component, copy the
11400 executable directly to both the target and the
11401 host <filename>debugfs</filename>.</para>
11402
11403 <para>If the binary is processed through the debug
11404 splitting in OpenEmbedded, you should also
11405 copy the debug items (i.e. <filename>.debug</filename>
11406 contents and corresponding
11407 <filename>/usr/src/debug</filename> files)
11408 from the work directory.
11409 Here is an example:
11410 <literallayout class='monospaced'>
11411 $ bitbake bash
11412 $ bitbake -c devshell bash
11413 $ cd ..
11414 $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
11415 $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
11416 </literallayout>
11417 </para></listitem>
11418 </orderedlist>
10564 </para> 11419 </para>
10565 </section> 11420 </section>
10566 11421
10567 <section id='testing-the-build'> 11422 <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
10568 <title>Testing the Build</title> 11423 <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
10569 11424
10570 <para> 11425 <para>
10571 With everything in place, you can get back to trying the 11426 The previous section addressed using GDB remotely for debugging
10572 build again locally: 11427 purposes, which is the most usual case due to the inherent
10573 <literallayout class='monospaced'> 11428 hardware limitations on many embedded devices.
10574 $ bitbake neard 11429 However, debugging in the target hardware itself is also
10575 </literallayout> 11430 possible with more powerful devices.
10576 This build should succeed. 11431 This section describes what you need to do in order to support
11432 using GDB to debug on the target hardware.
10577 </para> 11433 </para>
10578 11434
10579 <para> 11435 <para>
10580 Now you can open up a <filename>devshell</filename> again 11436 To support this kind of debugging, you need do the following:
10581 and repeat the clean and make operations as follows: 11437 <itemizedlist>
10582 <literallayout class='monospaced'> 11438 <listitem><para>
10583 $ bitbake neard -c devshell 11439 Ensure that GDB is on the target.
10584 $ make clean 11440 You can do this by adding "gdb" to
10585 $ make tools/snep-send.o 11441 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
10586 </literallayout> 11442 <literallayout class='monospaced'>
10587 The build should work without issue. 11443 IMAGE_INSTALL_append = " gdb"
11444 </literallayout>
11445 Alternatively, you can add "tools-debug" to
11446 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
11447 <literallayout class='monospaced'>
11448 IMAGE_FEATURES_append = " tools-debug"
11449 </literallayout>
11450 </para></listitem>
11451 <listitem><para>
11452 Ensure that debug symbols are present.
11453 You can make sure these symbols are present by
11454 installing <filename>-dbg</filename>:
11455 <literallayout class='monospaced'>
11456 IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
11457 </literallayout>
11458 Alternatively, you can do the following to include all
11459 the debug symbols:
11460 <literallayout class='monospaced'>
11461 IMAGE_FEATURES_append = " dbg-pkgs"
11462 </literallayout>
11463 </para></listitem>
11464 </itemizedlist>
11465 <note>
11466 To improve the debug information accuracy, you can reduce
11467 the level of optimization used by the compiler.
11468 For example, when adding the following line to your
11469 <filename>local.conf</filename> file, you will reduce
11470 optimization from
11471 <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
11472 of "-O2" to
11473 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
11474 of "-O -fno-omit-frame-pointer":
11475 <literallayout class='monospaced'>
11476 DEBUG_BUILD = "1"
11477 </literallayout>
11478 Consider that this will reduce the application's performance
11479 and is recommended only for debugging purposes.
11480 </note>
10588 </para> 11481 </para>
11482 </section>
11483
11484 <section id='dev-other-debugging-others'>
11485 <title>Other Debugging Tips</title>
10589 11486
10590 <para> 11487 <para>
10591 As with all solved problems, if they originated upstream, you 11488 Here are some other tips that you might find useful:
10592 need to submit the fix for the recipe in OE-Core and upstream 11489 <itemizedlist>
10593 so that the problem is taken care of at its source. 11490 <listitem><para>
10594 See the 11491 When adding new packages, it is worth watching for
10595 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" 11492 undesirable items making their way into compiler command
10596 section for more information. 11493 lines.
11494 For example, you do not want references to local system
11495 files like
11496 <filename>/usr/lib/</filename> or
11497 <filename>/usr/include/</filename>.
11498 </para></listitem>
11499 <listitem><para>
11500 If you want to remove the <filename>psplash</filename>
11501 boot splashscreen,
11502 add <filename>psplash=false</filename> to the kernel
11503 command line.
11504 Doing so prevents <filename>psplash</filename> from
11505 loading and thus allows you to see the console.
11506 It is also possible to switch out of the splashscreen by
11507 switching the virtual console (e.g. Fn+Left or Fn+Right
11508 on a Zaurus).
11509 </para></listitem>
11510 <listitem><para>
11511 Removing
11512 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
11513 (usually <filename>tmp/</filename>, within the
11514 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>)
11515 can often fix temporary build issues.
11516 Removing <filename>TMPDIR</filename> is usually a
11517 relatively cheap operation, because task output will be
11518 cached in
11519 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
11520 (usually <filename>sstate-cache/</filename>, which is
11521 also in the Build Directory).
11522 <note>
11523 Removing <filename>TMPDIR</filename> might be a
11524 workaround rather than a fix.
11525 Consequently, trying to determine the underlying
11526 cause of an issue before removing the directory is
11527 a good idea.
11528 </note>
11529 </para></listitem>
11530 <listitem><para>
11531 Understanding how a feature is used in practice within
11532 existing recipes can be very helpful.
11533 It is recommended that you configure some method that
11534 allows you to quickly search through files.</para>
11535
11536 <para>Using GNU Grep, you can use the following shell
11537 function to recursively search through common
11538 recipe-related files, skipping binary files,
11539 <filename>.git</filename> directories, and the
11540 Build Directory (assuming its name starts with
11541 "build"):
11542 <literallayout class='monospaced'>
11543 g() {
11544 grep -Ir \
11545 --exclude-dir=.git \
11546 --exclude-dir='build*' \
11547 --include='*.bb*' \
11548 --include='*.inc*' \
11549 --include='*.conf*' \
11550 --include='*.py*' \
11551 "$@"
11552 }
11553 </literallayout>
11554 Following are some usage examples:
11555 <literallayout class='monospaced'>
11556 $ g FOO # Search recursively for "FOO"
11557 $ g -i foo # Search recursively for "foo", ignoring case
11558 $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
11559 </literallayout>
11560 If figuring out how some feature works requires a lot of
11561 searching, it might indicate that the documentation
11562 should be extended or improved.
11563 In such cases, consider filing a documentation bug using
11564 the Yocto Project implementation of
11565 <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
11566 For general information on how to submit a bug against
11567 the Yocto Project, see the Yocto Project Bugzilla
11568 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
11569 or the
11570 <link linkend='submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</link>"
11571 section.
11572 <note>
11573 The manuals might not be the right place to document
11574 variables that are purely internal and have a
11575 limited scope (e.g. internal variables used to
11576 implement a single <filename>.bbclass</filename>
11577 file).
11578 </note>
11579 </para></listitem>
11580 </itemizedlist>
10597 </para> 11581 </para>
10598 </section> 11582 </section>
10599 </section> 11583 </section>