# bombela/backward-cpp architecture

> Architecture diagram of the GitHub repository bombela/backward-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bombela/backward-cpp
- Repository: https://github.com/bombela/backward-cpp

## Overview

##### Project type and purpose
- This is an open-source C++ library (“backward-cpp”) that provides a beautiful, pretty-printing stack-trace utility for C++ applications.
- It ships as a header-only API (`backward.hpp`) plus an optional implementation file (`backward.cpp`) to automatically hook into fatal signals.
- It includes a CMake-based build, Conan support, Travis CI configuration, documentation (`doc/`), unit tests (`test/`), and a test-package (`test_package/`).

##### File-tree and architectural patterns
- Top-level build files: `CMakeLists.txt`, `BackwardConfig.cmake`, `conanfile.py`, `.travis.yml`, `builds.sh`
→ Indicates a CMake-centric build and package management via Conan, continuous integration via Travis.
- Source code:
- `backward.hpp` (public API interface)
- `backward.cpp` (optional implementation for signal hooking)
- Modules inside the API (logical components):
- StackTrace (captures raw frames via libunwind/backtrace APIs)
- TraceResolver (resolves addresses to file/line via DWARF/BFD/libdw)
- SnippetFactory (loads source files and extracts code snippets)
- SignalHandling (registers fatal signal handlers)
- Tests (`test/`): multiple test cases verifying trace capture, inlining, signal handling, etc.
- Test package (`test_package/`): demonstrates usage in a consumer CMake/Conan project.

##### Key external dependencies
- OS stack-unwinding library: libunwind or GCC’s unwind
- Debug-info readers: libbfd, libdw (elfutils), or libdwarf/libelf
- Dynamic loader: `dl` on Linux
- Standard C++ library and I/O

##### Main components
- Build & packaging layer
- CMake & FetchContent/FindPackage (produces three CMake targets: Interface, Object, Backward)
- Conan recipe & Travis CI
- Library API layer
- Public interface header (`backward.hpp`)
- Implementation file (`backward.cpp`)
- Core modules (classes)
- StackTrace ↔ OS unwinding
- TraceResolver ↔ DWARF/BFD/libdw
- SnippetFactory ↔ File system (source files)
- Printer ↔ Terminal (TTY/stream)
- SignalHandling ↔ OS signal APIs
- Test harness
- Unit tests → CTest executables
- Test package → example consumer project
- Consumer applications
- User’s executable linking against Backward::Interface or Backward::Backward

##### Relationships and interactions
- Library API modules calling into:
- OS unwind library
- Debug info libraries
- File system for snippet loading
- Terminal or logging sink
- Build system pulling in external dependencies via Conan or system packages
- Tests invoking the API modules directly to verify behavior

##### Architectural patterns and design principles
- Clear separation of interface (`backward.hpp`) vs implementation (`backward.cpp`)
- Modular class design: single-responsibility classes (StackTrace, Resolver, Printer, SnippetFactory)
- CMake targets that expose include paths, compile options, and link dependencies separately (Interface vs Object vs Backward)
- Header-only usage with optional object/archive linkage for signal handling

##### Essential details to capture
- CMake targets (Interface/Object/Backward) and how they expose compile/link settings
- The five main classes and their interactions with OS/APIs
- External library integrations (unwind, BFD/libdw, libdwarf)
- Test layer separate from production code
- Consumer usage path for embedding into a C++ project

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Packaging Layer
    subgraph "Build & Packaging"
        CMakeLists["CMakeLists.txt"]:::build
        BackwardConfig["BackwardConfig.cmake"]:::build
        Conanfile["conanfile.py"]:::build
        TravisYml[".travis.yml"]:::build
        BuildSh["builds.sh"]:::build

        CMakeLists -->|generates| InterfaceTarget
        CMakeLists -->|generates| ObjectTarget
        CMakeLists -->|generates| BackwardTarget
        Conanfile -->|manages deps for| InterfaceTarget
        Conanfile -->|manages deps for| ObjectTarget
        TravisYml -->|CI for| BackwardTarget
        BuildSh -->|helper scripts for| BackwardTarget
    end

    %% CMake Targets
    InterfaceTarget["Backward::Interface (CMake Target)"]:::target
    ObjectTarget["Backward::Object (CMake Target)"]:::target
    BackwardTarget["Backward::Backward (CMake Target)"]:::target

    %% Core Library API Layer
    subgraph "Core Library API"
        Backward_hpp["backward.hpp"]:::api
        Backward_cpp["backward.cpp"]:::api

        Backward_hpp -->|defines| StackTrace
        Backward_hpp -->|defines| TraceResolver
        Backward_hpp -->|defines| SnippetFactory
        Backward_hpp -->|defines| Printer
        Backward_cpp -->|implements| SignalHandling
    end

    %% Core Modules
    StackTrace["StackTrace"]:::module
    TraceResolver["TraceResolver"]:::module
    SnippetFactory["SnippetFactory"]:::module
    Printer["Printer"]:::module
    SignalHandling["SignalHandling"]:::module

    %% External Systems
    subgraph "External Systems"
        Unwind["Unwind Lib (libunwind)"]:::external
        DebugLib["Debug Info Lib (BFD/DW)"]:::external
        FileSystem["File System"]:::external
        Terminal["Terminal/Tty"]:::external
        SignalAPI["OS Signal API"]:::external
    end

    StackTrace -->|uses| Unwind
    TraceResolver -->|uses| DebugLib
    SnippetFactory -->|loads snippets from| FileSystem
    Printer -->|outputs to| Terminal
    SignalHandling -->|hooks signals via| SignalAPI

    %% Consumer & Test Layer
    subgraph "Consumer & Tests"
        ConsumerApp["Consumer Application"]:::consumer

        subgraph "Unit Tests"
            Test_main["_test_main.cpp"]:::test
            Rectrace["rectrace.cpp"]:::test
            SelectSignals["select_signals.cpp"]:::test
            StacktraceTest["stacktrace.cpp"]:::test
            Suicide["suicide.cpp"]:::test
            Test_cpp["test.cpp"]:::test
            Test_hpp["test.hpp"]:::test
        end

        Test_main -->|builds| TestExec["CTest Executable"]:::test
        Rectrace --> TestExec
        SelectSignals --> TestExec
        StacktraceTest --> TestExec
        Suicide --> TestExec
        Test_cpp --> TestExec
        Test_hpp --> TestExec

        subgraph "Test Package"
            TP_CMake["test_package/CMakeLists.txt"]:::test
            TP_conan["test_package/conanfile.py"]:::test
            TP_main["main.cpp"]:::test
        end

        TP_CMake -->|builds| TP_app["Example Consumer"]:::consumer
        TP_conan --> TP_app
        TP_main --> TP_app

        ConsumerApp -->|links| InterfaceTarget
        ConsumerApp -->|optional signal| BackwardTarget
        TestExec -->|tests| Backward_hpp
        TestExec -->|tests| Backward_cpp
        TP_app -->|links| Backward::Interface
    end

    %% Click Events
    click CMakeLists "https://github.com/bombela/backward-cpp/blob/master/CMakeLists.txt"
    click BackwardConfig "https://github.com/bombela/backward-cpp/blob/master/BackwardConfig.cmake"
    click Conanfile "https://github.com/bombela/backward-cpp/blob/master/conanfile.py"
    click TravisYml "https://github.com/bombela/backward-cpp/blob/master/.travis.yml"
    click BuildSh "https://github.com/bombela/backward-cpp/blob/master/builds.sh"
    click Backward_hpp "https://github.com/bombela/backward-cpp/blob/master/backward.hpp"
    click Backward_cpp "https://github.com/bombela/backward-cpp/blob/master/backward.cpp"
    click StackTrace "https://github.com/bombela/backward-cpp/blob/master/backward.hpp"
    click TraceResolver "https://github.com/bombela/backward-cpp/blob/master/backward.hpp"
    click SnippetFactory "https://github.com/bombela/backward-cpp/blob/master/backward.hpp"
    click Printer "https://github.com/bombela/backward-cpp/blob/master/backward.hpp"
    click SignalHandling "https://github.com/bombela/backward-cpp/blob/master/backward.cpp"
    click Doc "https://github.com/bombela/backward-cpp/tree/master/doc/"
    click Test_main "https://github.com/bombela/backward-cpp/blob/master/test/_test_main.cpp"
    click Rectrace "https://github.com/bombela/backward-cpp/blob/master/test/rectrace.cpp"
    click SelectSignals "https://github.com/bombela/backward-cpp/blob/master/test/select_signals.cpp"
    click StacktraceTest "https://github.com/bombela/backward-cpp/blob/master/test/stacktrace.cpp"
    click Suicide "https://github.com/bombela/backward-cpp/blob/master/test/suicide.cpp"
    click Test_cpp "https://github.com/bombela/backward-cpp/blob/master/test/test.cpp"
    click Test_hpp "https://github.com/bombela/backward-cpp/blob/master/test/test.hpp"
    click TP_CMake "https://github.com/bombela/backward-cpp/blob/master/test_package/CMakeLists.txt"
    click TP_conan "https://github.com/bombela/backward-cpp/blob/master/test_package/conanfile.py"
    click TP_main "https://github.com/bombela/backward-cpp/blob/master/test_package/main.cpp"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef target fill:#fcf,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef module fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffb,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
    classDef consumer fill:#dfd,stroke:#333,stroke-width:1px
    classDef doc fill:#ffc,stroke:#333,stroke-width:1px
```
