Official Sentry SDK for C/C++

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.

Note: This SDK is being actively developed and still in Beta. We recommend to check for updates regularly to benefit from latest features and bug fixes. Please see Known Issues.

Table of Contents

• Downloads
• Distributions
  • What is Inside
  • Platform Support
• Building and Installation
  • Build Prerequisites
  • Building the SDK
• Known Issues
• Sample Application
• Development
  • Additional Dependencies
  • Development Setup
  • Running Tests

Downloads

The SDK can be downloaded from the Releases page, which also lists the changelog of every version.

Distributions

The release archive contains three distributions of the SDK:

* Adding stack traces and capturing application crashes requires you to add an unwind library and hook into signal handlers of your process. The Standalone distribution currently does not contain integrations that perform this automatically.

Note: On Windows and macOS, we strongly encourage the Crashpad distribution. Due to limitations of Crashpad on Linux, we recommend to use Breakpad for Linux.

What is Inside

The SDK bundle contains the following folders:

• breakpad, crashpad: Contain headers and sources of the Breakpad and Crashpad libraries. These are required to build the SDK in its respective distributions. To build the standalone distribution of the SDK, these folders can be discarded.
• include: Contains the Sentry header file. Set the include path to this directory or copy the header file to your source tree so that it is available during the build.
• gen_*: Contains generated projects and build files for the supported platforms. See the next section for more information.
• premake: Contains build files that allow to generate new projects and customize build parameters. When building for one of the supported platforms, prefer to use build files from the gen_* folders, instead.
• src: Sources of the Sentry SDK required for building.

Platform Support

The Sentry SDK comes with pregenerated build files for the following platforms:

• Windows

  gen_windows contains a Microsoft Visual Studio 2017 solution. Open the solution and add your projects or copy the projects to an existing solution. Each project supports a debug and release configuration and includes all sources required for building.

• Linux and macOS

  gen_linux and gen_macos contain Makefiles that can be used to produce dynamic libraries. Run make help to see an overview of the available configurations and target. There are debug and release configurations, that can be toggled when building:

  make config=release sentry
  

Building and Installation

Build Prerequisites

To build the SDK from the provided source files, ensure that your system meets the following requirements:

Linux:

• GNU make
• clang 3.9 or later
• uuid-dev (on Ubuntu)

macOS:

• Xcode (can be installed from Mac App Store)
• GNU make
• clang 3.9 or later

Windows:

• Microsoft Visual Studio 2017 or later

Building the SDK

NOTE: The following commands will work for the packaged version of the Sentry SDK (see Downloads). The gen_* folders are only included in the release archives. There are multiple available targets to build (defaults to all targets):

• sentry: Builds the Native SDK built as a dynamic library.
• sentry_breakpad: Builds the Native SDK with Google Breakpad as a dynamic library.
• sentry_crashpad: Builds the Native SDK with Google Crashpad as a dynamic library. This requires to build and ship the crashpad_handler executable with the application.

Linux:

cd gen_linux
make

macOS:

cd gen_macosx
make

Windows:

The Visual Studio solution is located at gen_windows/Sentry-Native.sln and contains projects for both Sentry Native and Crashpad.

WARNING: There is a known issue that the Windows SDK version configured in the solution might not be present on your system. If you see "The Windows SDK version XXX was not found" error, you can try to "Retarget Solution" ("Project" -> "Retarget solution"). You can also regenerate build files on the target machine, for that please consult the Development.

Known Issues

• Sentry with Crashpad cannot upload minidumps on Linux. This is due to a limitation in the upstream Crashpad project.
• Sentry with Breakpad cannot upload minidumps. The uploader was temporarily removed and will be restored in a future version.
• Attachments are currently in Preview and may not be available to your organization. Please see Event Attachments for more information.

Sample Application

The build commands produce the Sentry Native libraries (e.g. ./bin/Release/libsentry.dylib on MacOS), and sample crashing applications. You can run them by passing your Sentry DSN key via an environment variable:

# MacOS
SENTRY_DSN=https://XXXXX@sentry.io/YYYYY ./bin/Release/example

The example sends a message event to Sentry.

Development

If you want to develop or test Sentry Native locally, or the distribution package doesn't fit your needs, you can run make configure from the root directory. On Windows, please check premake/README.md for more instructions.

Additional Dependencies

• premake5: We use premake to generate build files. When using make configure, this is downloaded automatically.

Development Setup

MacOS / Linux:

make configure
cd premake
make

This will create ./premake/Makefile, that you can use to build any part of the project and run tests.

Use make help to see all available targets.

Windows:

cd premake/
premake5 vs2017

The last command will create a Visual Studio 2017 solution (Sentry-Native.sln) that contains all variants of the Sentry Native library projects, and example projects.

Running Tests

The SDK ships with a test suite based on catch.hpp. Tests are built as separate test targets, prefixed with test_* each. You can build and run the test targets to execute tests.

On macOS and Linux, the top-level Makefile contains a convenience command to run tests:

make test