Debugging Notes#

Debugging Carbonite based applications can sometimes be challenging given how large they can get. Below are some notes and pointers for using some of the common debuggers with Carbonite based apps. The notes below assume familiarity with common debuggers such as Visual Studio and GDB/LLDB.

carb.tasking Debugging#

The carb.tasking plugin has its own debugging notes that can be found here.

Debugging With Visual Studio#

Known Issues#

  • Visual Studio has a known bug that causes it to only list the first 500 modules loaded into a process when attaching to a process that is already running. This does not affect any modules that are loaded after the debugger attaches but rather only the modules that are already loaded in the process at the time the debugger attaches. If the process already has more than 500 modules loaded at attach time, several modules could be missing in the debugger thereby preventing breakpoints from being set or insecting variable values from a missing module. There are a few possible ways to work around this limitation:

    • Launch the application through the debugger. While this is not always possible, it is the best and simplest way to guarantee that all modules’ information is correctly loaded as the debugged process starts up.

    • Attach the debugger as early as possible during process startup. As long as the debugger is attached before 500 modules have been loaded into the process, it will behave as though the test process had been launched from within the debugger itself.

    • When debugging Kit-kernel or Kit based apps, use the --wait-debugger/-d command line options to cause the test process to pause during startup to wait for a debugger to attach. This may not always be possible in various debugging situations. When it is possible however, it is a good way to ensure that the debugger is attached early enough that the 500 module limit on debugger attach is not hit.

    • Under Visual Studio this module enumeration limit can be changed with a Windows registry change. The Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\DebuggerMaxModuleMsgs key can be added as a DWORD value and set to the new desired limit. Note that it seems this requires a system reboot in order for it to take effect.

Natvis Files#

Several Carbonite types can be confusing to inspect in the MSVC debugger when looking at their raw data. To work around this type of problem, MSVC allows for customization in how the debugger displays certain data types to make them more friendly or logical using .natvis files. These are XML files that provide information about how the debugger should interpret and display data for certain data types.

Carbonite includes the carb.natvis file that improves the visibility of several data types. This includes several carb.tasking and carb.dictionary types, carb::RString, omni::string, several carb::container, carb::cpp, and carb::extras types. This file can be included in Visual Studio solutions by adding the following lines to the main premake5.lua file for the repo:

  • Add the carb.natvis file to the project files:

filter { "system:windows" }
    files { "include/carb/carb.natvis" }

  • Add a link option to specify the carb.natvis file’s location:

filter { "kind:not staticlib", "system:windows" }
    linkoptions { "/NATVIS:<path_to_carb_package>/include/carb/carb.natvis" }

Debugging With GDB#

Pretty Printers#

GDB supports a set of Python helpers that can be used to visualize variables and objects in a more friendly way under the debugger. These scripts use the GDB Python API to provide the debugger with more specific information about how a certain data type should be displayed or interpreted.

Carbonite provides the include/carb/carb-gdb-printers.py file to help instruct GDB how to better display some of Carbonite’s data types. This file can be activated in GDB through one of the following methods:

  • In GDB 7.9 and newer, run the command source /path/to/carb-gdb-printers.py from inside the debugger.

  • Add the path to the carb-gdb-printers.py file in your ~/.gdbinit file.