Chapter 9. Debugging with the Yocto Project

The debug process is an important step in every development cycle. In this chapter, we will understand how to configure Poky to help us with the debugging process, for example, how we can configure our system to provide the needed tools for a remote debug using GDB, how we can track our changes using buildhistory, and how we can use a handy tool called devshell.

Differentiating metadata and application debugging

When we first think about debugging, we usually don't realize that there are different types of debugging.

Metadata debugging is needed to ensure that the behavior of BitBake's tasks is aligned with our goals, and to identify the culprit, when it's not. In this case, we use several log files generated by BitBake in the host in order to help to trace the execution path of the involved task. As a consequence of a wrong behavior, a file may not be copied or a feature may not be enabled.

On the other hand, the debugging of run-time code is more natural for us as it is essentially the same as what we do during the normal development cycle of an application, a library, or a kernel. Depending on the kind of issue we are after, the right tool to help may vary from a debugger to code instrumentation (for example, adding debug prints).

In this chapter, we detail metadata debugging as it is the essence of the Yocto Project and supports us along the development...

Tracking image, package, and SDK contents

The easiest way to ensure we have the image, packages, and SDK, along with the expected contents, is to use the Build History mechanism. Its contents may change in unexpected ways when we change a recipe.

When a recipe is updated for a new version or has its code changed, it may influence the contents put in the generated packages and, as consequence, in the image or SDK.

As Poky deals with a huge amount of recipes, and our images or SDKs frequently have tens or hundreds of packages included, it may be quite difficult to track the package contents. The Poky tool responsible to help us in this task is the Build History.

The Build History, as we can guess from its name, keeps the history of contents of several artifacts built during the Poky use. It can track package, image, and SDK building.

To enable the Build History in our system, we need to add the following lines of code in our local.conf file:

INHERIT += "buildhistory" 
BUILDHISTORY_COMMIT = "1"...

Debugging packaging

In more sophisticated recipes, we split the installed contents in several subpackages. The subpackages can be optional features, modules, or any other set of files that are optional to be installed.

To inspect how the recipe's content has been split, we can use the build/tmp/work/<arch>/<recipe name>/<software version>/packages-split directory. It contains a subdirectory for every subpackage and has its contents in the subtree. Among the possible reasons for a mistaken content split, we have the following:

• Contents not being installed (for example, an error in installation scripts)

• Application or library configuration error (for example, a disabled feature)

• Metadata error (for example, wrong package order)

Another common issue that we find, mainly in library recipes, is that the needed artifacts are not made available in the sysroot directory (for example, headers or dynamic libraries), causing a build breakage. The counterpart of the sysroot generation can...

Logging information during task execution

The logging utilities provided by BitBake are very useful to trace the code execution path. BitBake provides logging functions for use in Python and Shell Script code, as described:

• Python: For use within Python functions, BitBake supports several log levels, which are bb.fatal, bb.error, bb.warn, bb.note, bb.plain, and bb.debug

• Shell Script: For use in Shell Script functions, the same set of log levels exists and is accessed with a similar syntax: bbfatal, bberror, bbwarn, bbnote, bbplain, and bbdebug

These logging functions are very similar to each other but have inner differences as described:

• bb.fatal and bbfatal: These have the highest priority of logging messages as they print the message and terminate the processing. They cause the build to be interrupted.

• bb.error and bberror: They are used to display an error but do not force the build to stop.

• bb.warn and bbwarn: They are used to warn users about something.

• bb.note and bbnote: These add...

Utilizing a development shell

When editing packages or debugging build failures, a development shell can be a useful tool. When we use devshell, source files are extracted into the working directory, patches are applied, a new terminal is opened, and files are placed in the working directory.

In the new terminal, all the environment variables needed for the build are still defined, so we can use commands such as configure and make. The commands execute just as if the build system was executing them.

The following command is an example that uses devshell on a target named linux-yocto:

$: bitbake linux-yocto -c devshell 

This allow us to rework the Linux kernel source code and build it in place, to avoid building it from scratch in our development machine, and change its code as needed.

Tip

It is important to bear in mind that all changes made inside devshell are not persistent between builds; thus, we must be careful to record any change that is important, prior to leaving it.

As we have the source...

Using the GNU Project Debugger for debugging

While developing any project we, from time to time, end up struggling to understand subtle bugs. The GNU Project Debugger (GDB) is available as a package within Poky and is installed in SDK images by default, as was detailed in Chapter 8, Developing with the Yocto Project.

Tip

In order to install debugging packages that contain the debug symbols and debugging tools in an image, add IMAGE_FEATURES += "dbg-pkgs tools-debug" in local.conf.

The use of the SDK, or an image with the debugging packages and tools installed, allows us to debug applications directly in the target, as we usually do in our development machine.

Sometimes, due to memory or disk space constraints, it is not possible to use GDB directly on the target to debug. These constraints arise because GDB needs to load the debugging information and the binaries of the process being debugged, and it needs to perform many computations to locate information such as function names, variable names...

Summary

In this chapter, we understood how we can configure Poky to help us with the debugging process. We learned the contents of deployed directories that can be used on debugging, how we can track our changes using buildhistory, how we can use devshell to emulate the same build environment found by BitBake, and how we configure our system to provide the needed tools for GDB debugging.

In the next chapter, we will understand how to expand the Poky source code using external layers. We will be introduced to the concept of layering, and we will learn in detail the directory structure and the content of each layer type; additionally, we will learn how to add an external layer on our project manually or by using the Hob configuration.