Debugging Support (original) (raw)

5.1. Reference Implementation

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.

5.2. Microsoft® C/C++ Optimizing Compiler

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

5.3. Microsoft® Win32

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

5.4. LLVM Clang

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

5.5. arm Keil, ARM® Compiler

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

5.6. Portable Snippets

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

5.7. Debug Break

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

5.8. Boost.Test

The Boost.Test library implements an unconditional break in a debugger_breakfunction.[12] And provides an under_debugger function that implements an immediateis_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]

5.9. EASTL

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.

5.10. Catch2

The Catch2 library implements an internal and immediate isDebuggerActivefunction equivalent to is_debugger_present for macOS® and Linux.[16] It also provides a CATCH_TRAP macro that implements an unconditionalbreakpoint 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.

5.11. JUCE

The JUCE open-source cross-platform C++ application framework provides ajuce_isRunningUnderDebugger function that implements an immediateis_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 aProcess::isRunningUnderDebugger method. Making it available to JUCE users in their applications to support user specific features.

5.12. Dear ImGui

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.

5.13. AWS C SDK

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_assertfunction. 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.

5.14. Unreal® Engine

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.