GitHub - keithpotz/CrashCatch: Cross-Platform, Efficient easy to integrate crash reporting library for modern C++ (original) (raw)

CrashCatch

A cross-platform, efficient, and easy-to-integrate crash-reporting library for modern C++ applications.

License: MIT Header-only Platform C++ Crash Dumps Single Header CI

CrashCatch is a lightweight, single-header C++ crash-reporting library for generating .dmp and .txt crash logs — complete with stack traces, diagnostics, optional cleanup hooks, and user dialogs.

🎯 Overview

CrashCatch provides simple and powerful crash diagnostics for C++ applications on Windows and Linux, with macOS support planned. Whether you're building GUI apps, system tools, or CLI utilities, CrashCatch helps you catch and log critical failures with minimal setup.

As of v1.2, CrashCatch supports rich crash context capture and includes optional post-crash upload integration.

🚀 Key Features

✅ Supported Platforms

OS Supported Crash Handling Method
Windows ✅ Yes SetUnhandledExceptionFilter + MiniDump
Linux ✅ Yes POSIX signals (signal()) + backtrace
macOS 🚧 Planned POSIX + Mach exceptions

📁 Project Structure

CrashCatch/
├── include/
│   └── CrashCatch.hpp       # Single-header crash handler
├── examples/
│   └── CrashCatchExample.cpp
├── LICENSE                  # MIT License
├── README.md                # Project documentation
└── CONTRIBUTING.md          # Contribution guidelines

🔧 Installation

CrashCatch is 100% header-only.

To integrate:

  1. Copy include/CrashCatch.hpp into your project
  2. Add #include "CrashCatch.hpp" in your code
  3. (Optional) Use CrashCatch::enable() or the CRASHCATCH_AUTO_INIT macro
  4. For Linux inlcude -ldl or -rdynamic for deeper Linux symbole resolution if desired

✅ No build steps.
❌ No .lib, .dll, or .so.
🔒 Just one .hpp file, ready to use.

Copy CrashCatch.hpp into your project and include it:

#include "CrashCatch.hpp"

QuickStart

Zero Config (Auto-init)

#define CRASHCATCH_AUTO_INIT
#include "CrashCatch.hpp"

int main(){
    int* ptr = nullptr;
    *ptr = 42; // simulated crash
}

### One-Liner Initialization

[](#one-liner-initialization)

#include "CrashCatch.hpp"
int main(){
    CrashCatch::enable(); //Initalizes with default config

    int* ptr = nullptr;
    *ptr = 42; // simulated crash
}

### Full Configuration

[](#full-configuration)

#include "CrashCatch.hpp"

int main(){
    CrashCatch::Config config:
    config.appVersion = "1.0.0";
    config.buildConfig = "Release";
    config.additionalNotes = "This is a test build.";
    config.onCrash = []{
        std::cout << "Cleaning up before crash...\n"/
    };
    config.showCrashDialog = true;

    CrashCatch::initalize(config);

    int* ptr = nullptr;
    *ptr = 42; // simulated crash
}

---

## 📦 CMake Integration

[](#-cmake-integration)

You can install CrashCatch with:

cmake -Bbuild -DCMAKE_INSTALL_PREFIX=install
cmake --build build --target install
find_package(CrashCatch REQUIRED)
target_link_libraries(MyApp PRIVATE CrashCatch::CrashCatch)

---

---

## 📄 Crash Output

[](#-crash-output)

When a crash occurs, CrashCatch generates the following files in the `./crash_dumps/` directory:

* `crash_YYYY-MM-DD_HH-MM-SS.dmp` — Binary MiniDump (viewable in tools like WinDbg)
* `crash_YYYY-MM-DD_HH-MM-SS.txt` — Human-readable crash summary

### 📋 Example `.txt` Includes:

[](#-example-txt-includes)

Crash Report (Windows)

Timestamp: 2025-04-01_14-23-56 Dump File: ./crash_dumps/crash_2025-04-01_14-23-56.dmp Exception Code: 0xC0000005 Thread ID: 12345

Stack Trace: [0]: MyApp::SomeFunction + 0x15 [1]: MyApp::MainLoop + 0x2a [2]: WinMain + 0x10 [3]: __tmainCRTStartup + 0x20 [4]: BaseThreadInitThunk + 0x14 [5]: RtlUserThreadStart + 0x21

Environment Info: App Version: 1.0.0 Build Config: Release Architecture: x64 Executable: C:\Path\To\YourApp.exe Uptime (s): 182 Notes: Test build

Crash Report (Linux)

Timestamp: 2025-04-04_15-42-18 Signal: Segmentation fault (11)

Stack Trace: [0]: ./CrashCatchTest(+0x1234) [1]: libc.so.6(+0xdeadbeef) [2]: start_thread [3]: __libc_start_main

Environment Info: App Version: 1.1.0 Build Config: Release Platform: Linux Executable: /home/user/CrashCatchTest

```

The .txt files contains:

Crash Context API

CrashCatch provides detailed crash metadata via CrashContext:

struct CrashContext{ std::string dumpFilePath; std::string logFilePath; std::string timestamp; int singalOrCode; };

You can use both in onCrash and onCrashUpload

🗺 Roadmap

CrashCatch is actively being developed with the goal of becoming a robust, cross-platform crash-handling solution.

✅ Completed

🔜 Planned

📝 Contributing

We warmly welcome contributions! Check CONTRIBUTING.md for more information.

📄 License

CrashCatch is licensed under the MIT License. You're free to use, modify, and distribute it within your projects.