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 :
- Create an environement variable `MINGW_ROOT` (ex : `C:/msys64/mingw64`)
- Run from `mingw64.exe` : `pacman -S --needed - < ./toolchains/msys2-mingw64-pkglist.txt`
- Build as :
```sh
# Configure with Ninja as generator and use the MSYS2 toolchain file
The following options can be set when running the cmake generator, for example
using `cmake -D BUILD_SHARED_LIBS=OFF ..`.
-`SENTRY_BUILD_SHARED_LIBS` (Default: ON):
By default, `sentry` is built as a shared library. Setting this option to
`OFF` will build `sentry` as a static library instead.
If sentry is used as a subdirectory of another project, the value `BUILD_SHARED_LIBS` will be inherited by default.
When using `sentry` as a static library, make sure to `#define SENTRY_BUILD_STATIC 1` before including the sentry header.
-`SENTRY_PIC` (Default: ON):
By default, `sentry` is built as a position independent library.
-`SENTRY_EXPORT_SYMBOLS` (Default: ON):
By default, `sentry` exposes all symbols in the dynamic symbol table. You might want to disable it in case the program intends to `dlopen` third-party shared libraries and avoid symbol collisions.
-`SENTRY_BUILD_RUNTIMESTATIC` (Default: OFF):
Enables linking with the static MSVC runtime. Has no effect if the compiler is not MSVC.
-`SENTRY_LINK_PTHREAD` (Default: ON):
Links platform threads library like `pthread` on unix targets.
-`SENTRY_BUILD_FORCE32` (Default: OFF):
Forces cross-compilation from 64-bit host to 32-bit target. Only has an effect on Linux.
-`CMAKE_SYSTEM_VERSION` (Default: depending on Windows SDK version):
Sets up a minimal version of Windows where sentry-native can be guaranteed to run.
Possible values:
-`5.1` (Windows XP)
-`5.2` (Windows XP 64-bit / Server 2003 / Server 2003 R2)
-`6.0` (Windows Vista / Server 2008)
-`6.1` (Windows 7 / Server 2008 R2)
-`6.2` (Windows 8.0 / Server 2012)
-`6.3` (Windows 8.1 / Server 2012 R2)
-`10` (Windows 10 / Server 2016 / Server 2019)
For Windows versions below than `6.0` it is also necessary to use XP toolchain
in case of MSVC compiler (pass `-T v141_xp` to CMake command line).
-`SENTRY_TRANSPORT` (Default: depending on platform):
Sentry can use different http libraries to send reports to the server.
- **curl**: This uses the `curl` library for HTTP handling. This requires
that the development version of the package is available.
- **winhttp**: This uses the `winhttp` system library, is only supported on
Windows and is the default there.
- **none**: Do not build any http transport. This should be used if users
want to handle uploads themselves
-`SENTRY_BACKEND` (Default: depending on platform):
Sentry can use different backends depending on platform.
- **crashpad**: This uses the out-of-process crashpad handler. It is currently
only supported on Desktop OSs, and used as the default on Windows and macOS.
- **breakpad**: This uses the in-process breakpad handler. It is currently
only supported on Desktop OSs, and used as the default on Linux.
- **inproc**: A small in-process handler which is supported on all platforms,
and is used as default on Android.
- **none**: This builds `sentry-native` without a backend, so it does not handle
crashes at all. It is primarily used for tests.
-`SENTRY_INTEGRATION_QT` (Default: OFF):
Builds the Qt integration, which turns Qt log messages into breadcrumbs.
-`sentry`: This is the main library and the only default build target.
-`crashpad_handler`: When configured with the `crashpad` backend, this is
the out of process crash handler, which will need to be installed along with
the projects executable.
-`sentry_test_unit`: These are the main unit-tests, which are conveniently built
also by the toplevel makefile.
-`sentry_example`: This is a small example program highlighting the API, which
can be controlled via command-line parameters, and is also used for
integration tests.
## Runtime Configuration
A minimal working example looks like this. For a more elaborate example see the [example.c](examples/example.c) file which is also used to run sentries integration tests.
-`sentry_options_set_database_path`: Sentry needs to persist some cache data across application restarts, especially for proper handling of release health sessions. It is recommended to set an explicit absolute path corresponding to the applications cache directory (equivalent to `AppData/Local` on Windows, and `XDG_CACHE_HOME` on Linux). Sentry should be given its own directory which is not shared with other application data, as the SDK will enumerate and possibly delete files in that directory. An example might be `$XDG_CACHE_HOME/your-app/sentry`.
When not set explicitly, sentry will create and use the `.sentry-native` directory inside of the current working directory.
-`sentry_options_set_handler_path`: When using the crashpad backend, sentry will look for a `crashpad_handler` executable in the same directory as the running executable. It is recommended to set this as an explicit absolute path based on the applications install location.
-`sentry_options_set_release`: Some features in sentry, including release health, need to have a release version set. This corresponds to the application’s version and needs to be set explicitly. See [Releases](https://docs.sentry.io/product/releases/) for more information.
## Known Limitations
- The crashpad backend on macOS currently has no support for notifying the crashing
process, and can thus not properly terminate sessions or call the registered
`before_send` hook. It will also lose any events that have been queued for
sending at time of crash.
## Development
Please see the [contribution guide](./CONTRIBUTING.md).
