Debugging Support

Initial text based on P2514 and P2515. ^{[1] [2]} Changes include:

Knowing when a program is running in a debugger with std::is_debugger_present is a first step in enabling such functionality as:

Controlling when a debugger stops in your program with std::breakpoint allows for runtime control of breakpoints beyond what might be available from a debugger while not causing the program to exit. For example:

The goal of the std::breakpoint function is to "break" or pause the running program when called. Having an unconditional, i.e. attempts to break even if the debugger is or is not actually monitoring the program allows for use in conditions where it is not possible to detect if a debugger is present.

Implementations are expected to optimize the code generated to be as minimal as possible for the platform. For example, on X86 it’s expected that this produces a single INT3 instruction. The goal in this expectation is to place the debugger as close as possible in the caller of breakpoint() to improve the debugging experience for users.

The goal of the std::breakpoint_if_debugging function is to "break" when being debugged but to act as though it is a no-op when it is executing normally.

Although it’s trivial for users to implement a conditional break, it’s common enough that there is utility in providing a ready to use implementation.

The goal of the std::is_debugger_present function is to inform when a program is executing under the control of a debugger monitoring program. The interface is minimally simple to avoid having to reduce the user from having to know the intricacies of debugger operation. This is a feature that requires arcane platform knowledge for most platforms. But it is knowledge that is readily available to the platform tooling implementors.

Existing implementations of this functionality vary in how frequently they are expected to be called. Previously the proposal suggested that it would help to cache the debugger present query to avoid frequent repetition of the possible expensive query. But, first, doing that was not found to be done in any of the existing implementations. Second, doing so would add to the implementation complexity for something that can be better controlled by the user code. And, third, it would impact the std::breakpoint_if_debugging function to need to forward the argument to pass along to control the caching choice.

The debugging support functionality is particularly useful in situations where it’s difficult to debug in traditional hosted context. For example when the debugger is running on a development host machine while the program is running on specialize freestanding environment. In such situations it can be impossible to determine if a debugger is present remotely, and almost certainly unlikely that a debugger can run in the target environment. As such the debugger support in this proposal is expected to be supported, as best as possible, in freestanding environments. The wording reflects that by having maximum flexibility in implementation.

This proposal adds a utility header (debugging) with the new declarations.

A full reference implementation exists as a proof of concept. ^[4] It implements the full functionality for at least Windows, macOS, and Linux.

In addition to the prototype implementation there are the following, full or partial, equivalent implementations of the functions in common compilers and libraries.

The Microsoft® compiler provides a __debugbreak function that implements an unconditional break. ^[5]

The Windows® Win32 provides an IsDebuggerPresent function in the OS that implements querying if a debugger is tracing the calling process. ^[6]

Clang provides a __builtin_debugtrap function that implements an unconditional break. ^[7]

The arm Keil armcc compiler provides a __breakpoint function that implements an unconditional break. ^[8]

The "Portable Snippets" library ^[9] includes a psnip_trap function that implements an unconditional breakpoint in a variety of platforms and architectures. ^[10]

The "Debug Break" library provides a single debug_break function that attempts to implement an unconditional debugger break. ^[11]

The Boost.Test library implements an unconditional break in a debugger_break function. ^[12] And provides an under_debugger function that implements an immediate is_debugger_present function for Windows®, UNIX®, and macOS®. ^[13]

The two functions are used to implement an attach_debugger(bool) function that programmatically runs a debugger to trace the running program. ^[14]

The EASTL library provides a EASTL_DEBUG_BREAK() macro that implements an unconditional breakpoint. ^[15]

The EASTL_DEBUG_BREAK() macro is used to implement breaking into the debugger on failure in the EASTL_ASSERT(expression) macro.

The Catch2 library implements an internal and immediate isDebuggerActive function equivalent to is_debugger_present for macOS® and Linux. ^[16] It also provides a CATCH_TRAP macro that implements an unconditional breakpoint and a CATCH_BREAK_INTO_DEBUGGER macro that implements a conditional break per breakpoint_if_debugging. ^[17]

The CATCH_BREAK_INTO_DEBUGGER macro is used to cause failed assertions to pause in the debugger, if present. In addition to isDebuggerActive being used to implement the CATCH_BREAK_INTO_DEBUGGER macro, it’s also used to enable console text color output.

The JUCE open-source cross-platform C++ application framework provides a juce_isRunningUnderDebugger function that implements an immediate is_debugger_present. ^[18] It also provides a JUCE_BREAK_IN_DEBUGGER macro that implements an unconditional break. ^[19]

In JUCE the two are used implement a conditional breakpoint when an assertion fails in the provided jassert and jassertquiet. The user perceived feature is the ability to write assert checks that can be inspected in context when running in a debugger.

The juce_isRunningUnderDebugger function is also made available as a Process::isRunningUnderDebugger method. Making it available to JUCE users in their applications to support user specific features.

Dear ImGui provides an IM_DEBUG_BREAK() macro that implements an unconditional breakpoint. ^[20]

In addition to being available for users, the IM_DEBUG_BREAK() macro is used to provide a GUI button that will break into the debugger on demand.

The Amazon Web Services SDK for C provides a aws_is_debugger_present function which implements an immediate is_debugger_present. ^[21] And also provides a aws_debug_break function that implements a conditional break, i.e. breakpoint_if_debugging. ^[22]

The implementation is of these functions have platform support for Windows and POSIX.

The aws_debug_break function is used to implement the aws_fatal_assert function. Which in addition to conditionally breaking into the debugger also prints out the assertion info and backtrace. Which in turn is used in the AWS_FATAL_ASSERT macro.

Unreal® Engine ^[23] is a full blown game development environment composed of an IDE and more than a dozen different programs written using a common application framework. The engine provides an IsDebuggerPresent class function that implements an immediate is_debugger_present.

Unreal® Engine provides an implementation of the IsDebuggerPresent function in common platforms like Windows, macOS, Linux/POSIX, and Android. It also has implementations for a handful proprietary platforms like game consoles and virtual reality headsets.

Unreal® Engine also provides a UE_DEBUG_BREAK macro that implements a conditional break. Like the IsDebuggerPresent function this conditional break is implemented in many of the same platforms. The UE_DEBUG_BREAK macro uses IsDebuggerPresent to do the debugger conditional check.

The IsDebuggerPresent function has varied uses in Unreal® Engine: to log extra diagnostic output when certain inspection functions are called, to choose doing a debug break when present or to print out a stack trace instead, to prevent launching child parallel processes to allow debugging of normally distributed tasks, to disable auto-save on crash functionality, to turn off platform crash handling, to implement "wait for debugger" synchronization points, to add extra per thread context information to aid in finding task specific threads among the dozens of threads running, to prevent automated crash reporting, and to present GUI elements only when debugging.

SG15 approves of the design direction of P2514R0 and P2515R0 with the suggested changes of merging the two papers and adding an unconditional breakpoint interface.

Attendance: 8

Polls relating to the antecedent proposal P1279 are also of relevance. They can found in the corresponding GitHub issue. ^[24]

In [version.syn] add:

Add a new entry to General utilities library summary [tab:utilities.summary] table.

Add a new entry to the "C++ headers for freestanding implementations" table [tab:headers.cpp.fs].

Add section to General utilities library [utilities].