feat: introduce sentry-native on macOS as experimental backend

.github/workflows/build.yml

@@ -92,6 +92,12 @@ jobs:
           name: Cocoa-sdk
           path: package-dev/Plugins
 
+      - name: Download MacOSNative SDK
+        uses: ./.github/actions/wait-for-artifact
+        with:
+          name: MacOSNative-sdk
+          path: package-dev/Plugins/macOS/SentryNative~
+
       - name: Download Linux SDK
         uses: ./.github/actions/wait-for-artifact
         with:

.github/workflows/ci.yml

@@ -44,6 +44,8 @@ jobs:
             host: windows-latest
           - target: Cocoa
             host: macos-latest
+          - target: MacOSNative
+            host: macos-latest
     uses: ./.github/workflows/sdk.yml
     with:
       target: ${{ matrix.target }}
@@ -421,18 +423,20 @@ jobs:
       platform: windows
 
   test-run-macos:
-    name: Run macOS ${{ matrix.unity-version }} Integration Test
+    name: Run macOS ${{ matrix.backend }} ${{ matrix.unity-version }} Integration Test
     if: ${{ !startsWith(github.ref, 'refs/heads/release/') }}
     needs: [test-build-macos, create-unity-matrix]
     secrets: inherit
     strategy:
       fail-fast: false
       matrix:
         unity-version: ${{ fromJSON(needs.create-unity-matrix.outputs.unity-matrix).unity-version }}
+        backend: ["cocoa", "native"]
     uses: ./.github/workflows/test-run-desktop.yml
     with:
       unity-version: ${{ matrix.unity-version }}
       platform: macos
+      backend: ${{ matrix.backend }}
 
   build-size-summary:
     name: Build Size

.github/workflows/sdk.yml

@@ -107,12 +107,20 @@ jobs:
           name: ${{ env.TARGET }}-sdk
           path: |
             package-dev/Plugins/iOS/Sentry.xcframework~
-            package-dev/Plugins/macOS/Sentry
+            package-dev/Plugins/macOS/Sentry~
           # Lower retention period - we only need this to retry CI.
           retention-days: 14
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        if: ${{ env.TARGET != 'Cocoa' }}
+        if: ${{ env.TARGET == 'MacOSNative' }}
+        with:
+          name: ${{ env.TARGET }}-sdk
+          path: package-dev/Plugins/macOS/SentryNative~
+          # Lower retention period - we only need this to retry CI.
+          retention-days: 14
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: ${{ env.TARGET != 'Cocoa' && env.TARGET != 'MacOSNative' }}
         with:
           name: ${{ env.TARGET }}-sdk
           path: package-dev/Plugins/${{ env.TARGET }}

.github/workflows/test-build-macos.yml

@@ -87,7 +87,7 @@ jobs:
         env:
           SENTRY_DSN: ${{ secrets.SENTRY_TEST_DSN }}
 
-      - name: Build with Sentry SDK
+      - name: Build with Sentry SDK (Cocoa backend)
         run: ./test/Scripts.Integration.Test/build-project.ps1 -UnityPath "$env:UNITY_PATH" -Platform MacOS -UnityVersion "$env:UNITY_VERSION"
 
       - name: Compare build sizes
@@ -101,15 +101,39 @@ jobs:
           retention-days: 1
 
       # We create tar explicitly because upload-artifact is slow for many files.
-      - name: Create archive
+      - name: Create archive (Cocoa backend)
         run: |
           Remove-Item -Recurse -Force samples/IntegrationTest/Build/*_BackUpThisFolder_ButDontShipItWithYourGame -ErrorAction SilentlyContinue
           tar -cvzf test-app-desktop.tar.gz samples/IntegrationTest/Build
 
-      - name: Upload test app
+      - name: Upload test app (Cocoa backend)
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: testapp-desktop-compiled-${{ env.UNITY_VERSION }}-macos
+          name: testapp-desktop-compiled-${{ env.UNITY_VERSION }}-macos-cocoa
+          if-no-files-found: error
+          path: test-app-desktop.tar.gz
+          retention-days: 14
+
+      - name: Overwrite IntegrationOptionsConfiguration for Native backend
+        run: |
+          $optionsPath = "samples/IntegrationTest/Assets/Scripts/IntegrationOptionsConfiguration.cs"
+          $content = Get-Content $optionsPath -Raw
+          $content = $content -replace 'MacosBackend = MacosBackend.Cocoa', 'MacosBackend = MacosBackend.Native'
+          Set-Content $optionsPath $content
+
+      - name: Build with Sentry SDK (Native backend)
+        run: ./test/Scripts.Integration.Test/build-project.ps1 -UnityPath "$env:UNITY_PATH" -Platform MacOS -UnityVersion "$env:UNITY_VERSION"
+
+      - name: Create archive (Native backend)
+        run: |
+          Remove-Item -Recurse -Force samples/IntegrationTest/Build/*_BackUpThisFolder_ButDontShipItWithYourGame -ErrorAction SilentlyContinue
+          Remove-Item -Force test-app-desktop.tar.gz -ErrorAction SilentlyContinue
+          tar -cvzf test-app-desktop.tar.gz samples/IntegrationTest/Build
+
+      - name: Upload test app (Native backend)
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: testapp-desktop-compiled-${{ env.UNITY_VERSION }}-macos-native
           if-no-files-found: error
           path: test-app-desktop.tar.gz
           retention-days: 14

.github/workflows/test-run-desktop.yml

@@ -9,14 +9,19 @@ on:
         required: true
         type: string
         description: "linux, windows, or macos"
+      backend:
+        required: false
+        type: string
+        default: ""
+        description: "macOS only: native or cocoa"
 
 defaults:
   run:
     shell: pwsh
 
 jobs:
   run:
-    name: ${{ inputs.platform }} ${{ inputs.unity-version }}
+    name: ${{ inputs.platform }}${{ inputs.backend && format(' ({0})', inputs.backend) || '' }} ${{ inputs.unity-version }}
     runs-on: ${{ inputs.platform == 'linux' && 'ubuntu-latest' || inputs.platform == 'macos' && 'macos-latest' || 'windows-latest' }}
     env:
       SENTRY_DSN: ${{ secrets.SENTRY_TEST_DSN }}
@@ -33,7 +38,7 @@ jobs:
       - name: Download test app artifact
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: testapp-desktop-compiled-${{ inputs.unity-version }}-${{ inputs.platform }}
+          name: testapp-desktop-compiled-${{ inputs.unity-version }}-${{ inputs.platform }}${{ inputs.backend && format('-{0}', inputs.backend) || '' }}
 
       - name: Extract test app
         run: tar -xvzf test-app-desktop.tar.gz
@@ -78,7 +83,7 @@ jobs:
         if: ${{ failure() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: testapp-desktop-logs-${{ inputs.platform }}-${{ inputs.unity-version }}
+          name: testapp-desktop-logs-${{ inputs.platform }}${{ inputs.backend && format('-{0}', inputs.backend) || '' }}-${{ inputs.unity-version }}
           path: |
             test/IntegrationTest/results/
           retention-days: 14

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Introduce `sentry-native` on macOS as experimental backend. This is an opt-in and accessible programmatically via the `options.Experimental`. The `sentry-native` backend allows for crashes to be sent immediately and will enable further updates, like `AppHangTracking` support ([#2687](https://github.com/getsentry/sentry-unity/pull/2687))
+
 ### Fixes
 
 - When targeting iOS, the SDK no longer crashes in `urlSessionTask:setState:` when handling an `AVAssetDownloadTask` ([#2677](https://github.com/getsentry/sentry-unity/pull/2677))

build/native-sdks.targets

@@ -5,7 +5,8 @@
     <!-- Cocoa -->
     <SentryCocoaRoot>$(RepoRoot)modules/sentry-cocoa/</SentryCocoaRoot>
     <SentryiOSArtifactsDestination>$(SentryArtifactsDestination)iOS/Sentry.xcframework~/</SentryiOSArtifactsDestination>
-    <SentrymacOSArtifactsDestination>$(SentryArtifactsDestination)macOS/Sentry/</SentrymacOSArtifactsDestination>
+    <SentrymacOSArtifactsDestination>$(SentryArtifactsDestination)macOS/Sentry~/</SentrymacOSArtifactsDestination>
+    <SentryMacOSNativeArtifactsDestination>$(SentryArtifactsDestination)macOS/SentryNative~/</SentryMacOSNativeArtifactsDestination>
 
     <!-- Android -->
     <SentryAndroidRoot>$(RepoRoot)modules/sentry-java/</SentryAndroidRoot>
@@ -131,6 +132,57 @@
     <CallTarget Targets="BuildWindowsSDK" />
   </Target>
 
+  <!--
+    Build the Sentry Native SDK for macOS:
+        dotnet msbuild /t:BuildMacOSNativeSDK src/Sentry.Unity
+    Always wipes prior outputs and rebuilds. Produces a universal
+    (x86_64 + arm64) dylib and the sentry-crash out-of-process handler.
+    Debug symbols are extracted into .dSYM bundles; binaries are then stripped.
+  -->
+  <Target Name="BuildMacOSNativeSDK" Condition="'$(MSBuildProjectName)' == 'Sentry.Unity'">
+    <Error Condition="!$([MSBuild]::IsOSPlatform('OSX'))" Text="BuildMacOSNativeSDK can only run on macOS." />
+    <Error Condition="!Exists('$(SentryNativeRoot)')" Text="sentry-native submodule not checked out at $(SentryNativeRoot). Run: git submodule update --init modules/sentry-native" />
+
+    <Message Importance="High" Text="Building Sentry Native SDK for macOS (clean rebuild)." />
+
+    <!-- Wipe prior outputs -->
+    <RemoveDir Directories="$(SentryNativeRoot)build_macos" ContinueOnError="true" />
+    <Delete Files="$(SentryMacOSNativeArtifactsDestination)libsentry.dylib" ContinueOnError="true" />
+    <Delete Files="$(SentryMacOSNativeArtifactsDestination)sentry-crash" ContinueOnError="true" />
+    <RemoveDir Directories="$(SentryMacOSNativeArtifactsDestination)libsentry.dylib.dSYM" ContinueOnError="true" />
+    <RemoveDir Directories="$(SentryMacOSNativeArtifactsDestination)sentry-crash.dSYM" ContinueOnError="true" />
+
+    <Exec WorkingDirectory="$(SentryNativeRoot)" Command="cmake -B build_macos -D SENTRY_BACKEND=native -D SENTRY_SDK_NAME=sentry.native.unity -D SENTRY_BUILD_SHARED_LIBS=ON -D &quot;CMAKE_OSX_ARCHITECTURES=x86_64;arm64&quot; -D CMAKE_OSX_DEPLOYMENT_TARGET=10.15 -D CMAKE_BUILD_TYPE=RelWithDebInfo -S ." />
+    <Exec WorkingDirectory="$(SentryNativeRoot)" Command="cmake --build build_macos --target sentry --config RelWithDebInfo --parallel" />
+    <Exec WorkingDirectory="$(SentryNativeRoot)" Command="cmake --build build_macos --target sentry-crash --config RelWithDebInfo --parallel" />
+
+    <MakeDir Directories="$(SentryMacOSNativeArtifactsDestination)" />
+
+    <ItemGroup>
+      <MacOSNativeSdkArtifacts Include="$(SentryNativeRoot)build_macos/libsentry.dylib" />
+      <MacOSNativeSdkArtifacts Include="$(SentryNativeRoot)build_macos/sentry-crash" />
+    </ItemGroup>
+
+    <Copy SourceFiles="@(MacOSNativeSdkArtifacts)" DestinationFolder="$(SentryMacOSNativeArtifactsDestination)" />
+
+    <!-- Generate dSYMs for symbol upload, then strip debug info from the shipped binaries -->
+    <Exec Command="dsymutil $(SentryMacOSNativeArtifactsDestination)libsentry.dylib -o $(SentryMacOSNativeArtifactsDestination)libsentry.dylib.dSYM" />
+    <Exec Command="dsymutil $(SentryMacOSNativeArtifactsDestination)sentry-crash -o $(SentryMacOSNativeArtifactsDestination)sentry-crash.dSYM" />
+    <Exec Command="strip -x $(SentryMacOSNativeArtifactsDestination)libsentry.dylib" />
+    <Exec Command="strip -x $(SentryMacOSNativeArtifactsDestination)sentry-crash" />
+
+    <Error Condition="!Exists('$(SentryMacOSNativeArtifactsDestination)libsentry.dylib')" Text="Failed to set up the macOS Native SDK." />
+  </Target>
+
+  <!-- Hooks into 'dotnet build' so a missing macOS Native plugin auto-triggers BuildMacOSNativeSDK. -->
+  <Target Name="EnsureMacOSNativeSDK"
+          BeforeTargets="BeforeBuild"
+          Condition="'$(MSBuildProjectName)' == 'Sentry.Unity'
+            And $([MSBuild]::IsOSPlatform('OSX'))
+            And !Exists('$(SentryMacOSNativeArtifactsDestination)libsentry.dylib')">
+    <CallTarget Targets="BuildMacOSNativeSDK" />
+  </Target>
+
   <!--
     Build sentry-native-ndk and publish it to the local Maven repo (~/.m2)
     so sentry-java's :sentry-android-ndk build can resolve it via mavenLocal().