Home

Awesome

Conan Center nixpkgs unstable vcpkg

<p align="center"> <a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank"> <picture> <source srcset="https://sentry-brand.storage.googleapis.com/sentry-logo-white.png" media="(prefers-color-scheme: dark)" /> <source srcset="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" /> <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" alt="Sentry" width="280"> </picture> </a> </p>

Official Sentry SDK for C/C++ <!-- omit in toc -->

The Sentry Native SDK is an error and crash reporting client for native applications, optimized for C and C++. Sentry allows to add tags, breadcrumbs and arbitrary custom context to enrich error reports. Supports Sentry 20.6.0 and later.

Note <!-- omit in toc -->

Using the sentry-native SDK in a standalone use case is currently an experimental feature. The SDK’s primary function is to fuel our other SDKs, like sentry-java or sentry-unreal. Support from our side is best effort and we do what we can to respond to issues in a timely fashion, but please understand if we won’t be able to address your issues or feature suggestions.

Resources <!-- omit in toc -->

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

Downloads

The SDK can be downloaded from the Releases page, which also lists the changelog of every version. We recommend using our release packages, but if you want to use this repo directly, please follow the contribution guide to understand the setup better.

What is Inside

The SDK bundle contains the following folders:

Platform and Feature Support

The SDK currently supports and is tested on the following OS/Compiler variations:

Additionally, the SDK should support the following platforms, although they are not automatically tested, so breakage may occur:

The SDK supports different features on the target platform:

Building and Installation

The SDK is developed and shipped as a CMake project. CMake will pick an appropriate compiler and buildsystem toolchain automatically per platform, and can also be configured for cross-compilation. System-wide installation of the resulting sentry library is also possible via CMake.

The prerequisites for building differ depending on the platform and backend. You will always need CMake to build the code. Additionally, when using the crashpad backend, zlib is required. On Linux and macOS, libcurl is a prerequisite. For more details, check out the contribution guide.

Building the Crashpad Backend requires a C++20 compatible compiler. In particular, the standard library must support std::ranges for mini_chromium (a core library of crashpad).

Build example:

# configure the cmake build into the `build` directory, with crashpad (on macOS)
$ cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
# build the project
$ cmake --build build --parallel
# install the resulting artifacts into a specific prefix (use the correct config on windows)
$ cmake --install build --prefix install --config RelWithDebInfo
# which will result in the following (on macOS):
$ exa --tree install
install
├── bin
│  └── crashpad_handler
├── include
│  └── sentry.h
└── lib
   ├── cmake
   │  └── sentry
   ├── libsentry.dylib
   └── libsentry.dylib.dSYM

Please refer to the CMake Manual for more details.

Android:

The CMake project can also be configured to correctly work with the Android NDK, see the dedicated CMake Guide for details on how to integrate it with Gradle or use it on the command line.

The ndk folder provides Gradle project which adds a Java JNI layer for Android, suitable for accessing the sentry-native SDK from Java. See the NDK Readme for more details about this topic.

MinGW:

64-bits is the only platform supported for now. LLVM + Clang are mandatory here : they are required to generate .pdb files, used by Crashpad for the report generation.

For your application to generate the appropriate .pdb output, you need to activate CodeView file format generation on your application target. To do so, update your own CMakeLists.txt with something like target_compile_options(${yourApplicationTarget} PRIVATE -gcodeview).

If you use a MSYS2 environement to compile with MinGW, make sure to :

# Configure with Ninja as generator and use the MSYS2 toolchain file
$ cmake -GNinja -Bbuild -H. -DCMAKE_TOOLCHAIN_FILE=toolchains/msys2.cmake
# build with Ninja
$ ninja -C build

MacOS:

Building universal binaries/libraries is possible out of the box when using the CMAKE_OSX_ARCHITECTURES define, both with the Xcode generator as well as the default generator:

# using xcode generator:
$ cmake -B xcodebuild -GXcode -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
$ xcodebuild build -project xcodebuild/Sentry-Native.xcodeproj
$ lipo -info xcodebuild/Debug/libsentry.dylib
Architectures in the fat file: xcodebuild/Debug/libsentry.dylib are: x86_64 arm64

# using default generator:
$ cmake -B defaultbuild -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
$ cmake --build defaultbuild --parallel
$ lipo -info defaultbuild/libsentry.dylib
Architectures in the fat file: defaultbuild/libsentry.dylib are: x86_64 arm64

Make sure that MacOSX SDK 11 or later is used. It is possible that this requires manually overriding the SDKROOT:

$ export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)

Compile-Time Options

The following options can be set when running the cmake generator, for example using cmake -D BUILD_SHARED_LIBS=OFF ...

Support Matrix

FeatureWindowsmacOSLinuxAndroidiOS
Transports
- curl☑☑(✓)***
- winhttp☑
- none✓✓✓☑☑
Backends
- crashpad☑☑☑
- breakpad✓✓✓(✓)**(✓)**
- inproc✓(✓)*✓☑
- none✓✓✓✓

Legend:

In addition to platform support, the "Advanced Usage" section of the SDK docs now describes the tradeoffs involved in choosing a suitable backend for a particular use case.

Build Targets

Runtime Configuration

A minimal working example looks like this. For a more elaborate example see the example.c file which is also used to run sentries integration tests.

sentry_options_t *options = sentry_options_new();
sentry_options_set_dsn(options, "https://YOUR_KEY@oORG_ID.ingest.sentry.io/PROJECT_ID");
sentry_init(options);

// your application code …

sentry_close();

Other important configuration options include:

Known Limitations

Development

Please see the contribution guide.