Cpptrace <!-- omit in toc -->

<br/> <br/>

Cpptrace is a simple and portable C++ stacktrace library supporting C++11 and greater on Linux, macOS, and Windows including MinGW and Cygwin environments. The goal: Make stack traces simple for once.

In addition to providing access to stack traces, cpptrace also provides a mechanism for getting stacktraces from thrown exceptions which is immensely valuable for debugging and triaging. More info below.

Cpptrace also has a C API, docs here.

Table of Contents <!-- omit in toc -->

• 30-Second Overview
  • CMake FetchContent Usage
• Prerequisites
• Basic Usage
• namespace cpptrace
  • Stack Traces
  • Object Traces
  • Raw Traces
  • Utilities
  • Formatting
    • Transforms
  • Configuration
    • Logging
  • Traces From All Exceptions (CPPTRACE_TRY and CPPTRACE_CATCH)
    • Removing the CPPTRACE_ prefix
    • How it works
    • Performance
  • Rethrowing Exceptions
  • cpptrace::try_catch
  • Traces from SEH exceptions
  • Traced Exception Objects
    • Wrapping std::exceptions
    • Exception handling with cpptrace exception objects
  • Terminate Handling
  • Signal-Safe Tracing
  • Utility Types
  • Headers
  • Libdwarf Tuning
  • JIT Support
  • Loading Libraries at Runtime
• ABI Versioning
• Supported Debug Formats
• How to Include The Library
  • CMake FetchContent
  • System-Wide Installation
  • Local User Installation
  • Use Without CMake
  • Installation Without Package Managers or FetchContent
  • Package Managers
    • Conan
    • Vcpkg
  • C++20 Modules
• Platform Logistics
  • Windows
  • macOS
• Library Back-Ends
  • Summary of Library Configurations
• Testing Methodology
• Notes About the Library
• FAQ
  • What about C++23 <stacktrace>?
  • What does cpptrace have over other C++ stacktrace libraries?
  • I'm getting undefined standard library symbols like std::__1::basic_string on MacOS
• Contributing
• License

30-Second Overview

Generating stack traces is as easy as:

#include <cpptrace/cpptrace.hpp>

void trace() {
    cpptrace::generate_trace().print();
}

Cpptrace can also retrieve function inlining information on optimized release builds:

Cpptrace provides access to resolved stack traces as well as fast and lightweight raw traces (just addresses) that can be resolved later:

const auto raw_trace = cpptrace::generate_raw_trace();
// then later
raw_trace.resolve().print();

One of the most important features cpptrace offers is the ability to retrieve stack traces on arbitrary exceptions. More information on this system below.

#include <cpptrace/from_current.hpp>
#include <iostream>
#include <stdexcept>

void foo() {
    throw std::runtime_error("foo failed");
}

int main() {
    CPPTRACE_TRY {
        foo();
    } CPPTRACE_CATCH(const std::exception& e) {
        std::cerr<<"Exception: "<<e.what()<<std::endl;
        cpptrace::from_current_exception().print();
    }
}

Cpptrace also provides a handful of traced exception objects that store stack traces when thrown. This is useful when the exceptions might not be caught by CPPTRACE_CATCH:

#include <cpptrace/cpptrace.hpp>

void trace() {
    throw cpptrace::logic_error("This wasn't supposed to happen!");
}

Additional notable features:

• Utilities for demangling
• Utilities for catching std::exceptions and wrapping them in traced exceptions
• Signal-safe stack tracing
  • As far as I can tell cpptrace is the only library which can truly do this in a signal-safe manner
• Source code snippets in traces
• Extensive configuration options for trace formatting and pretty-printing

CMake FetchContent Usage

include(FetchContent)
FetchContent_Declare(
  cpptrace
  GIT_REPOSITORY https://github.com/jeremy-rifkin/cpptrace.git
  GIT_TAG        v1.0.4 # <HASH or TAG>
)
FetchContent_MakeAvailable(cpptrace)
target_link_libraries(your_target cpptrace::cpptrace)

# Needed for shared library builds on windows:  copy cpptrace.dll to the same directory as the
# executable for your_target
if(WIN32)
  add_custom_command(
    TARGET your_target POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
    $<TARGET_FILE:cpptrace::cpptrace>
    $<TARGET_FILE_DIR:your_target>
  )
endif()

Be sure to configure with -DCMAKE_BUILD_TYPE=Debug or -DCMAKE_BUILD_TYPE=RelWithDebInfo for symbols and line information.

On macOS it is recommended to generate a .dSYM file, see Platform Logistics below.

For other ways to use the library, such as through package managers, a system-wide installation, or on a platform without internet access see How to Include The Library below.

Prerequisites

[!IMPORTANT] Debug info (-g//Z7//Zi//DEBUG/-DBUILD_TYPE=Debug/-DBUILD_TYPE=RelWithDebInfo) is required for complete trace information.

Basic Usage

cpptrace::generate_trace() can be used to generate a stacktrace object at the current call site. Resolved frames can be accessed from this object with .frames and the trace can be printed with .print(). Cpptrace also provides a method to get light-weight raw traces with cpptrace::generate_raw_trace(), which are just vectors of program counters, which can be resolved at a later time.

namespace cpptrace

All functions are thread-safe unless otherwise noted.

Stack Traces

The core resolved stack trace object. Generate a trace with cpptrace::generate_trace() or cpptrace::stacktrace::current(). On top of a set of helper functions struct stacktrace allows direct access to frames as well as iterators.

cpptrace::stacktrace::print can be used to print a stacktrace. cpptrace::stacktrace::print_with_snippets can be used to print a stack trace with source code snippets.

namespace cpptrace {
    // Some type sufficient for an instruction pointer, currently always an alias to std::uintptr_t
    using frame_ptr = std::uintptr_t;

    struct stacktrace_frame {
        frame_ptr raw_address; // address in memory
        frame_ptr object_address; // address in the object file
        // nullable<T> represents a nullable integer. More docs later.
        nullable<std::uint32_t> line;
        nullable<std::uint32_t> column;
        std::string filename;
        std::string symbol;
        bool is_inline;
        bool operator==(const stacktrace_frame& other) const;
        bool operator!=(const stacktrace_frame& other) const;
        object_frame get_object_info() const; // object_address is stored but if the object_path is needed this can be used
        std::string to_string() const;
        /* operator<<(ostream, ..) and std::format support exist for this object */
    };

    struct stacktrace {
        std::vector<stacktrace_frame> frames;
        // here as a drop-in for std::stacktrace
        static stacktrace current(std::size_t skip = 0);
        static stacktrace current(std::size_t skip, std::size_t max_depth);
        void print() const;
        vo