feat!: 1.0

.craft.yml

@@ -3,17 +3,23 @@ changelogPolicy: auto
 targets:
   - name: github
     includeNames: /^(sentry-native).*\.zip$/
+    excludeNames: /^sentry-native\.zip$/
   - name: registry
     sdks:
       github:getsentry/sentry-native:
       maven:io.sentry:sentry-native-ndk:
   - name: gcs
-    includeNames: /^(sentry-native\.zip)$/
+    includeNames: /^sentry-native-\d+\.\d+\.\d+.*\.zip$/
     bucket: sentry-sdk-assets
     paths:
       - path: /sentry-native/{{version}}/
         metadata:
           cacheControl: public, max-age=2592000
+  - name: gcs
+    id: latest
+    includeNames: /^sentry-native\.zip$/
+    bucket: sentry-sdk-assets
+    paths:
       - path: /sentry-native/latest/
         metadata:
           cacheControl: public, max-age=600
@@ -32,4 +38,5 @@ targets:
     batchType: android
     bundleIdPrefix: sentry-native-ndk-
 requireNames:
-  - /^sentry-native.zip$/
+  - /^sentry-native-\d+\.\d+\.\d+.*\.zip$/
+  - /^sentry-native\.zip$/

.github/workflows/benchmark.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+      - v1
     paths-ignore:
       - "*.md"
   pull_request:
@@ -59,5 +60,5 @@ jobs:
           tool: customSmallerIsBetter
           output-file-path: benchmark.json
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          benchmark-data-dir-path: ./
+          benchmark-data-dir-path: ${{ github.ref_name == 'v1' && 'v1/' || './' }}
           auto-push: true

.github/workflows/ci.yml

@@ -585,8 +585,11 @@ jobs:
 
       - name: Create source archive
         run: |
+          version=$(sed -nE 's/^#[[:space:]]*define[[:space:]]+SENTRY_SDK_VERSION[[:space:]]+"([^"]+)".*/\1/p' include/sentry.h)
+          test -n "$version"
           rm -rf build .c* .e* .git* scripts Makefile external/breakpad/src/tools external/breakpad/src/processor
-          zip -r sentry-native.zip .
+          zip -r "sentry-native-$version.zip" .
+          cp "sentry-native-$version.zip" sentry-native.zip
 
       - name: Build NDK artifacts
         working-directory: ndk
@@ -598,6 +601,7 @@ jobs:
           name: ${{ github.sha }}
           if-no-files-found: error
           path: |
+            sentry-native-*.zip
             sentry-native.zip
             ndk/lib/build/distributions/*.zip
             ndk/lib/build/intermediates/merged_native_libs/release/mergeReleaseNativeLibs/out/lib/*

.github/workflows/codeql.yml

@@ -2,10 +2,10 @@ name: 'CodeQL'
 
 on:
   push:
-    branches: [master]
+    branches: [master, v1]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [master]
+    branches: [master, v1]
   schedule:
     - cron: '17 23 * * 3'
 

.github/workflows/console-check.yml

@@ -72,6 +72,20 @@ jobs:
             echo "mode=BUILD_ONLY" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Resolve console branch
+        id: ref
+        env:
+          GH_TOKEN: ${{ github.token }}
+          SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          ahead() { gh api "repos/$GITHUB_REPOSITORY/compare/$1...$SHA?per_page=1" --jq .ahead_by; }
+          ref=main nearest=$(ahead master)
+          # version branches build against the same console branch
+          for branch in v1; do
+            if n=$(ahead "$branch" 2>/dev/null) && [[ $n -lt $nearest ]]; then ref=$branch nearest=$n; fi
+          done
+          echo "console_ref=$ref" >> "$GITHUB_OUTPUT"
+
       # gh workflow run sends a workflow_dispatch event to the console repo.
       # native-compat-check.yml must exist on the default branch (main) of
       # the console repo for this to work.
@@ -84,11 +98,12 @@ jobs:
           CALLBACK_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
           CALLBACK_CONTEXT: ${{ matrix.context }}
           MODE: ${{ steps.mode.outputs.mode }}
+          CONSOLE_REF: ${{ steps.ref.outputs.console_ref }}
           PR_NUMBER: ${{ github.event.pull_request.number || github.ref_name }}
         run: |
           gh workflow run native-compat-check.yml \
             --repo "$MATRIX_REPO" \
-            --ref main \
+            --ref "$CONSOLE_REF" \
             -f native_ref="$NATIVE_REF" \
             -f callback_repo="$CALLBACK_REPO" \
             -f callback_sha="$CALLBACK_SHA" \

.github/workflows/enforce-license-compliance.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [master, main, release/*]
   pull_request:
-    branches: [master, main]
+    branches: [master, main, v1]
 
 jobs:
   enforce-license-compliance:

CHANGELOG.md

@@ -1,9 +1,32 @@
 # Changelog
 
-## Unreleased
+## Unreleased (v1)
+
+**Breaking / Important behavior changes**:
+
+- The `native` backend is now the default on Linux, macOS, and Windows. ([#2186](https://github.com/getsentry/sentry-native/pull/2186))
+- macOS/Linux: shared libraries now use ABI-versioned filenames, such as `libsentry.1.dylib` or `libsentry.so.1` for 1.x. Windows, Android, and static libraries remain unchanged. ([#2103](https://github.com/getsentry/sentry-native/pull/2103))
+  - NOTE: Applications must package the real versioned library and its symlinks, including `libsentry.1.dylib` or `libsentry.so.1`, because they link to and load the ABI-versioned name.
+- Release archives now include the SDK version in the filename, such as `sentry-native-1.0.0.zip`. ([#2105](https://github.com/getsentry/sentry-native/pull/2105))
+
+**Features**:
+
+- Add `sentry_scope_begin_read`/`sentry_scope_end_read` and `sentry_scope_begin_write`/`sentry_scope_end_write` for consistent reads of multiple scope properties and applying multiple scope changes with a single scope flush. ([#2107](https://github.com/getsentry/sentry-native/pull/2107))
+- Add `sentry_scope_acquire` and `sentry_scope_release` to access the isolation scope. ([#2160](https://github.com/getsentry/sentry-native/pull/2160))
+- Native: Provide exception metadata, registers, and a basic crashing-thread stack to `on_crash` for crash identification. ([#2174](https://github.com/getsentry/sentry-native/pull/2174))
+- Native: reduce disk I/O on scope changes by sending incremental updates to the crash daemon over IPC. ([#2155](https://github.com/getsentry/sentry-native/pull/2155), [#2157](https://github.com/getsentry/sentry-native/pull/2157))
+- Native: install handlers for the daemon's own fatal signals and unhandled exceptions, allowing best-effort recovery actions such as dumping pending envelopes before termination. ([#2220](https://github.com/getsentry/sentry-native/pull/2220))
 
 **Fixes**:
 
+- Native/Inproc: provide `debug_meta.images` in events passed to `on_crash`. ([#2184](https://github.com/getsentry/sentry-native/pull/2184))
+- Native/Linux: reduce daemon stack usage during minidump creation to avoid stack overflows in environments with limited stack space. ([#2211](https://github.com/getsentry/sentry-native/pull/2211))
+- Native/Linux: reduce stack usage when unwinding the crashed thread. ([#2212](https://github.com/getsentry/sentry-native/pull/2212))
+- Native/Unix: Preserve existing alternate signal stacks to prevent ASan aborts when the initializing thread exits before SDK shutdown. ([#2219](https://github.com/getsentry/sentry-native/pull/2219))
+- Native/Linux: fix oversized `debug_meta.images` entries that overlapped other libraries when a file was mapped more than once. ([#2228](https://github.com/getsentry/sentry-native/pull/2228))
+
+## Unreleased
+
 - An empty proxy (`sentry_options_set_proxy(options, "")`) now means a direct connection with every transport and backend. Before, the WinHTTP transport, the Windows and macOS crashpad handlers and the native backend's daemon fell back to the proxy environment variables or the system proxy settings. ([#2218](https://github.com/getsentry/sentry-native/pull/2218), [crashpad#175](https://github.com/getsentry/crashpad/pull/175))
 
 **Thank you**:

CMakeLists.txt

@@ -200,6 +200,8 @@ elseif(SENTRY_TRANSPORT STREQUAL "curl")
 	set(SENTRY_TRANSPORT_CURL TRUE)
 elseif(SENTRY_TRANSPORT STREQUAL "none")
 	set(SENTRY_TRANSPORT_NONE TRUE)
+elseif(SENTRY_TRANSPORT STREQUAL "stdout")
+	set(SENTRY_TRANSPORT_STDOUT TRUE)
 elseif(SENTRY_TRANSPORT STREQUAL "pshttp")
 	# Not implemented here, but in the downstream SDK
 	if(NOT PROSPERO)
@@ -251,7 +253,7 @@ if(MSVC AND CMAKE_GENERATOR_TOOLSET MATCHES "_xp$")
 elseif(MSVC AND (XBOX OR WINGDK))
 	set(SENTRY_DEFAULT_BACKEND "breakpad")
 elseif((APPLE AND NOT IOS) OR WIN32 OR LINUX)
-	set(SENTRY_DEFAULT_BACKEND "crashpad")
+	set(SENTRY_DEFAULT_BACKEND "native")
 else()
 	set(SENTRY_DEFAULT_BACKEND "inproc")
 endif()
@@ -384,6 +386,27 @@ add_library(sentry ${SENTRY_LIBRARY_TYPE} "${PROJECT_SOURCE_DIR}/src/sentry_mpac
 if (XBOX)
 	set_target_properties(sentry PROPERTIES VS_USER_PROPS gdk_build.props)
 endif()
+
+set_target_properties(sentry PROPERTIES
+	VERSION "${SENTRY_VERSION_BASE}"
+	SOVERSION "${SENTRY_VERSION_MAJOR}")
+
+if(WIN32 AND SENTRY_BUILD_SHARED_LIBS)
+	set(_SENTRY_IMAGE_VERSION "${SENTRY_VERSION_MAJOR}.${SENTRY_VERSION_MINOR}")
+	if(CMAKE_GENERATOR MATCHES "^Visual Studio " AND CMAKE_VERSION VERSION_LESS 4.1)
+		# VS generators before CMake 4.1 ignore VERSION for the PE image header.
+		target_link_options(sentry PRIVATE "/VERSION:${_SENTRY_IMAGE_VERSION}")
+	elseif(MINGW)
+		include(CheckLinkerFlag)
+		check_linker_flag(C "LINKER:/version:0.0" _SENTRY_LINKER_SUPPORTS_PE_VERSION)
+		if(_SENTRY_LINKER_SUPPORTS_PE_VERSION)
+			# lld silently ignores CMake's GNU image-version flags.
+			target_link_options(sentry PRIVATE "LINKER:/version:${_SENTRY_IMAGE_VERSION}")
+		endif()
+	endif()
+	unset(_SENTRY_IMAGE_VERSION)
+endif()
+
 target_sources(sentry PRIVATE "${PROJECT_SOURCE_DIR}/include/sentry.h")
 add_library(sentry::sentry ALIAS sentry)
 
@@ -1153,7 +1176,7 @@ if(SENTRY_BUILD_TESTS)
 	else()
 		# Disable all optimizations for the `sentry_test_integration` in gcc/clang. This allows us to keep crash triggers simple.
 		# The effects besides reproducible code-gen across compiler versions, will be negligible for build- and runtime.
-		target_compile_options(sentry_test_integration PRIVATE $<BUILD_INTERFACE:-O0>)
+		target_compile_options(sentry_test_integration PRIVATE $<BUILD_INTERFACE:-O0 -fno-omit-frame-pointer>)
 	endif()
 
 	if(CMAKE_GENERATOR STREQUAL "Xcode")

CONTRIBUTING.md

@@ -207,7 +207,7 @@ The fixture currently supports the following commands:
 Only on Linux using crashpad:
 - `crashpad-wait-for-upload`: Couples application shutdown to complete the upload in the `crashpad_handler`.
 
-Only on Windows using crashpad with its WER handler module:
+Only on Windows using the native or crashpad backend with its WER handler module:
 
 - `fastfail`: Crashes the application using the `__fastfail` intrinsic directly, thus by-passing SEH.
 - `stack-buffer-overrun`: Triggers the Windows Control Flow Guard, which also fast fails and in turn by-passes SEH.

README.md

@@ -107,7 +107,7 @@ Building the Breakpad and Crashpad backends requires a `C++17` compatible compil
 **Build example**:
 
 ```sh
-# configure the cmake build into the `build` directory, with crashpad (on macOS)
+# configure the cmake build into the `build` directory, with native (on macOS)
 $ cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
 # build the project
 $ cmake --build build --parallel
@@ -117,18 +117,23 @@ $ cmake --install build --prefix install --config RelWithDebInfo
 $ eza --tree install
 install
 ├── bin
-│  └── crashpad_handler
+│  └── sentry-crash
 ├── include
 │  └── sentry.h
 └── lib
    ├── cmake
    │  └── sentry
-   ├── libsentry.dylib
-   └── libsentry.dylib.dSYM
+   ├── libsentry.1.0.0.dylib
+   ├── libsentry.1.dylib -> libsentry.1.0.0.dylib
+   ├── libsentry.dylib -> libsentry.1.dylib
+   └── libsentry.1.0.0.dylib.dSYM
 ```
 
 Please refer to the CMake Manual for more details.
 
+Starting with 1.0.0, shared libraries on macOS and Linux use ABI-versioned
+runtime names such as `libsentry.1.dylib` or `libsentry.so.1`.
+
 **Android**:
 
 The CMake project can also be configured to correctly work with the Android NDK,
@@ -144,7 +149,7 @@ The `ndk` folder provides a Gradle project that adds a Java JNI layer for Androi
 **MinGW**:
 
 64-bit 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.
+LLVM + Clang are mandatory here : they are required to generate .pdb files, used to symbolicate crash reports.
 
 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)`.
 
@@ -246,19 +251,33 @@ using `cmake -D BUILD_SHARED_LIBS=OFF ..`.
     Windows and is the default there.
   - **none**: Do not build any HTTP transport. This should be used if users
     want to handle uploads themselves
+  - **custom**: Provide an external
+    `sentry_transport_t *sentry_transport_new_default(void)` implementation
+    (with `extern "C"` linkage if written in C++). Return a transport created
+    with `sentry_transport_new` or `sentry_http_transport_new`, or `NULL` to
+    disable uploads.
+
+- `SENTRY_SCREENSHOT` (Default: `windows` on Windows, `none` elsewhere):
+  Selects the screenshot implementation. Set it to `custom` and provide an
+  external `int sentry_screenshot_capture(const char *path, uint32_t pid)`
+  implementation (with `extern "C"` linkage if written in C++).
+  Save a PNG screenshot to `path` and return `0` on success, nonzero on failure.
+  `pid` selects whose windows to capture: `0` for the current process, or the
+  crashed application's PID when capture runs in a separate daemon. The path is
+  UTF-8 on Windows.
 
 - `SENTRY_BACKEND` (Default: depending on platform):
   Sentry can use different backends depending on the platform.
 
   - **crashpad**: This uses the out-of-process crashpad handler. It is currently
-    only supported on Desktop OSes and used as the default on Windows, Linux, and macOS.
+    only supported on Desktop OSes.
   - **breakpad**: This uses the in-process breakpad handler. It is currently
     only supported on Desktop OSs.
   - **inproc**: A small in-process handler that is supported on all platforms,
     and is used as a default on Android.
   - **native**: An out-of-process crash handler that uses a lightweight daemon
     to monitor the application, generate minidumps, and send crash reports.
-    Supports Linux, macOS, and Windows. Compatible with TSAN and ASAN
+    Supports Linux, macOS, and Windows, where it is the default. Compatible with TSAN and ASAN
     sanitizers.
   - **none**: This builds `sentry-native` without a backend, so it does not handle
     crashes. It is primarily used for tests.
@@ -342,8 +361,8 @@ using `cmake -D BUILD_SHARED_LIBS=OFF ..`.
 | - none     | ✓       | ✓     | ✓     | ☑       | ☑    |
 |            |         |       |       |         |      |
 | Backends   |         |       |       |         |      |
-| - crashpad | ☑       | ☑     | ☑     |         |      |
-| - native   | ✓       | ✓     | ✓     |         |      |
+| - crashpad | ✓       | ✓     | ✓     |         |      |
+| - native   | ☑       | ☑     | ☑     |         |      |
 | - breakpad | ✓       | ✓     | ✓     | (✓)*    | (✓)* |
 | - inproc   | ✓       | ✓     | ✓     | ☑       |      |
 | - none     | ✓       | ✓     | ✓     | ✓       |      |