From 641398df75f6f5c2a7337dcf88ff938f69b4a736 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Thu, 2 Jun 2022 12:23:44 +0200 Subject: [PATCH 1/7] improved native support docs --- src/includes/getting-started-primer/unity.mdx | 3 +- src/platforms/unity/native-support/index.mdx | 32 ++++++++++++++----- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/src/includes/getting-started-primer/unity.mdx b/src/includes/getting-started-primer/unity.mdx index d05e3bb69f42a..8647adf27dec8 100644 --- a/src/includes/getting-started-primer/unity.mdx +++ b/src/includes/getting-started-primer/unity.mdx @@ -5,7 +5,8 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it - [Native support](/platforms/unity/native-support/) for automatic crash error tracking for - Android by using the [Android SDK](/platforms/android/) to support Java, Kotlin, C and C++ - iOS by using the [iOS SDK](/platforms/apple/guides/ios/) to support Objective-C, Swift, C and C++ - - Windows by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps. + - Windows and Linux by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps. + - macOS by using the [macOS SDK](/platforms/apple/guides/macos/) to support Objective-C, Swift, C and C++ - [Offline caching](/platforms/unity/configuration/options/#cache-directory-path) stores event data to disk in case the device is not online - [Release health](/platforms/unity/configuration/releases/) to keep track of crash free users and sessions - [Breadcrumbs automatically](/platforms/unity/enriching-events/breadcrumbs/#automatic-breadcrumbs) captured for diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index d50dd6a560c14..815b5a5cafd2a 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -14,25 +14,41 @@ The setup for the iOS and Android native SDKs happens during build time, with th -## Android +## Mobile + +The native crash support for Android and iOS is achieved by modifying the generated platform specific projects during build time. That way the Sentry native crash support gets initialized before Unity, making it possible to capture errors of the Unity engine itself. + +### Android When chosing Android as a build target, Unity creates a Gradle project. During the Unity build process, the SDK embeds the [Android SDK](/platforms/android/), as well as the provided options, by adding it to the generated project's Android Manifest. -## iOS +### iOS When building your game for iOS, Unity exports it as an Xcode project. By modifying that generated project, the SDK adds the [iOS SDK](/platforms/apple/guides/ios/) to provide native support. It adds the initialization code to the `main.m` and generates the options provided by the editor configuration window as `SentryOptions.m`. The SDK also copies the `SentryNativeBridge` that enables the C# layer to communicate with the iOS SDK. This means that there's no need to use the Unity [built-in crash reporting](https://docs.unity3d.com/ScriptReference/CrashReport.html) functionality. The [iOS SDK](/platforms/apple/guides/ios/) supports capturing Objective-C exceptions which are disabled in the generated Xcode project by default. Consider enabling them in the "Build Settings" tab by setting `GCC_ENABLE_OBJC_EXCEPTIONS` to true. -## Windows +## Desktop + +The native support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different than on Mobile where we inject native initialization code that runs before the Unity engine runs. + +### Windows + +On Windows the Unity SDK includes the [Native SDK](/platforms/native/) with the crashpad backend. Windows native crashes are automatically captured through minidumps. To upload these to Sentry, the SDK copies the `crashpad_handler.exe` to the build output directory at the end of the build process. This executable must be included when shipping your game. + +### macOS + +The Native Support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. + +### Linux -Windows native crashes are automatically captured through minidumps. The Native Support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different than the Android and iOS support where we inject native initialization code that runs before Unity engine runs. +On Linux the Unity SDK includes the [Native SDK](/platforms/native/) with the breakpad backend. A minidump is created in process and no handler executable is required. ## Debug Symbols -Sentry requires [debug information files](/platforms/android/data-management/debug-files/) to symbolicate your crash logs. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). We've included the executables for Windows, macOS, and Linux inside the Unity SDK package. +Sentry requires [debug information files](/platforms/unity/data-management/debug-files/) to symbolicate your crashes. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). This is done transparently so you are not required to run `sentry-cli` manually. The symbol upload happens during Unity build in the editor. We've included the executables for Windows, macOS, and Linux as part of the Unity SDK package. -The automated debug symbols upload is enabled by default but requires configuration. Go to **Tools > Sentry > Editor** to enter the [Auth Token](https://sentry.io/api/), Org Slug, and the Project Name. Note that the Unity SDK creates a file at `Assets/Plugins/Sentry/SentryCliOptions.asset` to store the configuration, that should not be made publicly available. +The automated debug symbols upload is enabled by default but requires configuration. Go to **Tools > Sentry > Editor** to enter the [Auth Token](https://sentry.io/api/), Organization Slug, and the Project Name. Note that the Unity SDK creates a file at `Assets/Plugins/Sentry/SentryCliOptions.asset` to store the configuration, that should **not** be made publicly available. ### iOS - dSYM and Bitcode @@ -42,13 +58,13 @@ For Sentry to symbolicate your crash logs and with `bitcode` enabled, we need tw 1. `dSYM` files available only **after** App Store Connect finishes processing the build 2. `BCSymbolMap` files that are created during the archiving process -The automated symbol upload will take care of the `BCSymbolMap` files by processing them during the archiving process. To provide the dSYM files to Sentry, you can either set up the [App Store Connect Integration](/platforms/apple/guides/ios/dsym/#bitcode-appstore) so Sentry can fetch them for you or download and then upload them [manually using sentry-cli](/platforms/apple/guides/ios/dsym/#bitcode-sentrycli). +The automated symbol upload will take care of the `BCSymbolMap` files by processing them during the archiving process. To provide the dSYM files to Sentry, you can either set up the [Sentry App Store Connect Integration](/platforms/apple/guides/ios/dsym/#bitcode-appstore) so Sentry can fetch them for you, or download them from Apple and then upload them [manually using sentry-cli](/platforms/apple/guides/ios/dsym/#bitcode-sentrycli). With `bitcode` disabled, the automated symbols upload will pick up the `dSYM` files at the end of the build process without further action required. ### Manual Upload Using sentry-cli -You can either use the provided executables from within the package or follow the [sentry-cli documentation](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: +If you do not want to rely on the automated symbol upload, you can run `sentry-cli` through the commandline. For that you can use the provided executables from within the package or follow the [sentry-cli documentation](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: ```bash sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ PATH_TO_SYMBOLS From bf072e67f7f4276be40b1a36698a176c3fb562fb Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:46:18 +0200 Subject: [PATCH 2/7] Update src/includes/getting-started-primer/unity.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/includes/getting-started-primer/unity.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/includes/getting-started-primer/unity.mdx b/src/includes/getting-started-primer/unity.mdx index 8647adf27dec8..d65de9a45f633 100644 --- a/src/includes/getting-started-primer/unity.mdx +++ b/src/includes/getting-started-primer/unity.mdx @@ -5,7 +5,7 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it - [Native support](/platforms/unity/native-support/) for automatic crash error tracking for - Android by using the [Android SDK](/platforms/android/) to support Java, Kotlin, C and C++ - iOS by using the [iOS SDK](/platforms/apple/guides/ios/) to support Objective-C, Swift, C and C++ - - Windows and Linux by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps. + - Windows and Linux by using the [Native SDK](/platforms/native/) to support C and C++ with minidumps - macOS by using the [macOS SDK](/platforms/apple/guides/macos/) to support Objective-C, Swift, C and C++ - [Offline caching](/platforms/unity/configuration/options/#cache-directory-path) stores event data to disk in case the device is not online - [Release health](/platforms/unity/configuration/releases/) to keep track of crash free users and sessions From 2ad544781c8cb4d850bfb32144e1b93627331e16 Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:46:33 +0200 Subject: [PATCH 3/7] Update src/platforms/unity/native-support/index.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index 815b5a5cafd2a..16cbcaab09d16 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -16,7 +16,7 @@ The setup for the iOS and Android native SDKs happens during build time, with th ## Mobile -The native crash support for Android and iOS is achieved by modifying the generated platform specific projects during build time. That way the Sentry native crash support gets initialized before Unity, making it possible to capture errors of the Unity engine itself. +The native crash support for Android and iOS is achieved by modifying the generated platform-specific projects during build time. That way, the Sentry native crash support gets initialized before Unity, making it possible to capture errors of the Unity engine itself. ### Android From ca29a70b505c02898035180b307371f412e6eaf1 Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:46:55 +0200 Subject: [PATCH 4/7] Update src/platforms/unity/native-support/index.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index 16cbcaab09d16..6e9b67a799185 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -30,7 +30,7 @@ The [iOS SDK](/platforms/apple/guides/ios/) supports capturing Objective-C excep ## Desktop -The native support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different than on Mobile where we inject native initialization code that runs before the Unity engine runs. +The native support is configured and enabled as early as possible by the C# layer, right after the Unity engine starts. This is slightly different from on mobile where we inject native initialization code that runs before the Unity engine runs. ### Windows From fec282f88d227496ee51e6a9d1016997f2a52cb0 Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:47:07 +0200 Subject: [PATCH 5/7] Update src/platforms/unity/native-support/index.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index 6e9b67a799185..2bfdc3b8da76b 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -34,7 +34,7 @@ The native support is configured and enabled as early as possible by the C# laye ### Windows -On Windows the Unity SDK includes the [Native SDK](/platforms/native/) with the crashpad backend. Windows native crashes are automatically captured through minidumps. To upload these to Sentry, the SDK copies the `crashpad_handler.exe` to the build output directory at the end of the build process. This executable must be included when shipping your game. +On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the crashpad backend. Windows native crashes are automatically captured through minidumps. To upload these to Sentry, the SDK copies the `crashpad_handler.exe` to the build output directory at the end of the build process. This executable must be included when shipping your game. ### macOS From a0c24ee6a3180a1baf7fe5f811560c3c0bf71f4d Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:47:25 +0200 Subject: [PATCH 6/7] Update src/platforms/unity/native-support/index.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index 2bfdc3b8da76b..751a55a3da187 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -64,7 +64,7 @@ With `bitcode` disabled, the automated symbols upload will pick up the `dSYM` fi ### Manual Upload Using sentry-cli -If you do not want to rely on the automated symbol upload, you can run `sentry-cli` through the commandline. For that you can use the provided executables from within the package or follow the [sentry-cli documentation](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: +If you don't want to rely on the automated symbol upload, you can run `sentry-cli` through the commandline. For that, you can use the provided executables from within the package or follow the [sentry-cli documentation](/product/cli/installation/) to make it available globally. To upload debug symbols, run it with: ```bash sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org ___ORG_SLUG___ --project ___PROJECT_SLUG___ PATH_TO_SYMBOLS From 01cae982537c7059dc6322489b09f03a20dd8f39 Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Fri, 3 Jun 2022 10:47:41 +0200 Subject: [PATCH 7/7] Update src/platforms/unity/native-support/index.mdx Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/platforms/unity/native-support/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/unity/native-support/index.mdx b/src/platforms/unity/native-support/index.mdx index 751a55a3da187..6f3e639235ffa 100644 --- a/src/platforms/unity/native-support/index.mdx +++ b/src/platforms/unity/native-support/index.mdx @@ -46,7 +46,7 @@ On Linux the Unity SDK includes the [Native SDK](/platforms/native/) with the br ## Debug Symbols -Sentry requires [debug information files](/platforms/unity/data-management/debug-files/) to symbolicate your crashes. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). This is done transparently so you are not required to run `sentry-cli` manually. The symbol upload happens during Unity build in the editor. We've included the executables for Windows, macOS, and Linux as part of the Unity SDK package. +Sentry requires [debug information files](/platforms/unity/data-management/debug-files/) to symbolicate your crashes. The Unity SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). This is done transparently so you're not required to run `sentry-cli` manually. The symbol upload happens during Unity build in the editor. We've included the executables for Windows, macOS, and Linux as part of the Unity SDK package. The automated debug symbols upload is enabled by default but requires configuration. Go to **Tools > Sentry > Editor** to enter the [Auth Token](https://sentry.io/api/), Organization Slug, and the Project Name. Note that the Unity SDK creates a file at `Assets/Plugins/Sentry/SentryCliOptions.asset` to store the configuration, that should **not** be made publicly available.