From 5f8756d86fb45b788f86c4313769570183e12cc1 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:34:58 +0200 Subject: [PATCH 1/8] docs(apple): restructure install docs and add SentryObjC Reorganize the SPM page into Pre-compiled, Compile from Source, and SentryObjC sections so users can quickly find the right product. Add SentryObjC xcframeworks to the manual install page and a callout on the install index for ObjC++/no-modules projects. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/index.mdx | 9 ++ .../apple/common/install/manual-install.mdx | 24 +++-- .../common/install/swift-package-manager.mdx | 90 ++++++++++++++++--- 3 files changed, 103 insertions(+), 20 deletions(-) diff --git a/docs/platforms/apple/common/install/index.mdx b/docs/platforms/apple/common/install/index.mdx index e5f3e0c6dd4931..375cf466317dd8 100644 --- a/docs/platforms/apple/common/install/index.mdx +++ b/docs/platforms/apple/common/install/index.mdx @@ -13,4 +13,13 @@ brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios This will patch your project and configure the SDK. You'll only need to patch the project once, then you'll be able to add the patched files to your version control system. If you prefer, you can choose one of the alternative methods below. + + If your project uses Objective-C++ or can't enable Clang modules, see the{" "} + + SentryObjC + {" "} + section for a pure Objective-C integration that doesn't require Swift headers + or `@import`. + + diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index ad7414b5d67cda..dea8d1e00e6310 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -7,14 +7,22 @@ sidebar_order: 3000 To integrate Sentry into your Xcode project, follow these steps: 1. Download the latest version of the SDK from the Sentry Cocoa [Releases page](https://github.com/getsentry/sentry-cocoa/releases). -2. Each release contains the following four framework options: - - Sentry-Dynamic.xcframework.zip: Dynamic framework - - Sentry.xcframework.zip: Static framework - - SentrySwiftUI.xcframework.zip: Static Framework with SwiftUI support - - Sentry-WithoutUIKitOrAppKit.xcframework.zip: Static framework without UIKit or AppKit linking and related features +2. Each release contains the following framework options: + + **Sentry (Swift / standard Objective-C):** + - `Sentry.xcframework.zip` — Static framework (recommended) + - `Sentry-Dynamic.xcframework.zip` — Dynamic framework + - `SentrySwiftUI.xcframework.zip` — Static framework with SwiftUI support + - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features + + **SentryObjC (pure Objective-C interface):** + - `SentryObjC.xcframework.zip` — Static framework + - `SentryObjC-Dynamic.xcframework.zip` — Dynamic framework + 3. Import the chosen framework into your Xcode project target. -### Usage Guidelines: +### Usage Guidelines - • Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. - • If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. +- If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no `@import`, no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 1c8a3e4524a96e..908ae2765dbf01 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -10,36 +10,42 @@ To integrate Sentry into your Xcode project using Swift Package Manager (SPM), o https://github.com/getsentry/sentry-cocoa.git ``` -You can define your dependency rule by selecting the SDK version (or branch), and then click the "Add Package" button. -You will then be prompted to choose one of the options `Sentry`, `Sentry-Dynamic`, `SentrySwiftUI`, or `SentrySPM`. - -- `Sentry` is the static pre-built framework, which is the recommended option if you prefer a fast app start time. -- `Sentry-Dynamic` is the dynamic pre-built framework. -- `SentrySwiftUI` is used to track performance of SwiftUI views, see more information in the [docs](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/). -- `SentrySPM` compiles the SDK from source as part of your project build instead of using a pre-built binary. This is useful if you want to step through SDK code while debugging. Not all product variants are available yet with this option. +You can define your dependency rule by selecting the SDK version (or branch), and then click the "Add Package" button. You will then be prompted to choose a product — see below for which one to pick. Xcode allows you to choose many options, but you should choose only one of the - options above. + options below. +## Pre-compiled (Recommended) + +These products use pre-built binary frameworks. They don't add to your project's compile time and are the recommended choice for most projects. + +- **`Sentry`** — Static pre-built framework. Recommended for most projects as it provides the fastest app start time. +- **`Sentry-Dynamic`** — Dynamic pre-built framework. Use this if your project requires dynamic linking. +- **`SentrySwiftUI`** — Static pre-built framework with SwiftUI performance tracking. Use this to measure the performance of your SwiftUI views. See [SwiftUI Instrumentation](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/) for more information. + Alternatively, when your project uses a `Package.swift` file to manage dependencies, you can specify the target with: ```swift {tabTitle:Swift} .package(url: "https://github.com/getsentry/sentry-cocoa", from: "{{@inject packages.version('sentry.cocoa') }}"), ``` -## Building Without UIKit or AppKit +## Compile from Source + +The **`SentrySPM`** product compiles the SDK from source as part of your project build instead of using a pre-built binary. This is useful if you want to step through SDK code while debugging. Not all product variants are available yet with this option. + +### Building Without UIKit or AppKit If you're building a command-line tool, a headless server app, or any other target where UIKit or AppKit isn't available, you can use the `NoUIFramework` package trait to strip out UI framework dependencies entirely. This requires **Sentry SDK 9.7.0+**, **Swift 6.1+**, and **Xcode 26.4+**. When enabled, the SDK compiles from source without linking UIKit, AppKit, or SwiftUI. UI-related features like UIViewController tracing and screenshot capture are excluded. -### Xcode +#### Xcode 1. Add the Sentry package as described above. 2. Select the **`SentrySPM`** product instead of `Sentry` or `Sentry-Dynamic`. 3. In your project settings, go to **Package Dependencies**, select the Sentry package, and enable the **`NoUIFramework`** trait. -### Package.swift +#### Package.swift Add the dependency with the `NoUIFramework` trait and depend on the `SentrySPM` product: @@ -65,5 +71,65 @@ let package = Package( ``` - The `SentrySPM` product compiles the SDK from source. This is required for package traits to take effect, since the pre-built binary targets (`Sentry`, `Sentry-Dynamic`) don't support compile-time configuration. + The `SentrySPM` product compiles the SDK from source. This is required for + package traits to take effect, since the pre-built binary targets (`Sentry`, + `Sentry-Dynamic`) don't support compile-time configuration. + + +## SentryObjC + +Available from SDK **9.16.1+**. + +**SentryObjC** is a pure Objective-C wrapper around the Sentry SDK, recommended for projects that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use `@import` or `-Swift.h`. It provides a standalone ObjC interface with no Swift dependencies in your headers. + +### Installation + +In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. + +With `Package.swift`: + +```swift {tabTitle:Swift} +.package(url: "https://github.com/getsentry/sentry-cocoa", from: "{{@inject packages.version('sentry.cocoa') }}"), +``` + +Then depend on the `SentryObjC` product: + +```swift {tabTitle:Swift} +.target( + name: "MyApp", + dependencies: [ + .product(name: "SentryObjC", package: "sentry-cocoa"), + ] +) +``` + +### Configuration + +All SentryObjC types use the `SentryObjC` prefix. Import the umbrella header and initialize the SDK: + +```objc +#import + +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + + [SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.debug = YES; + + // Adds IP for users. + // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.sendDefaultPii = YES; + + // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // We recommend adjusting this value in production. + options.tracesSampleRate = @1.0; + }]; + + return YES; +} +``` + + + SentryObjC embeds the full Sentry SDK. Do not link both `Sentry` and + `SentryObjC` in the same target. From 1aa896c933f43f744d40cda200bdb7254739c175 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:40:19 +0200 Subject: [PATCH 2/8] fix(apple): correct SentryObjC availability SentryObjC via SPM compiles from source; only the dynamic xcframework is available pre-compiled. Remove the non-existent static xcframework and clarify the SPM product compiles from source. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/manual-install.mdx | 1 - docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index dea8d1e00e6310..65d79daad04b9d 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -16,7 +16,6 @@ To integrate Sentry into your Xcode project, follow these steps: - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features **SentryObjC (pure Objective-C interface):** - - `SentryObjC.xcframework.zip` — Static framework - `SentryObjC-Dynamic.xcframework.zip` — Dynamic framework 3. Import the chosen framework into your Xcode project target. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 908ae2765dbf01..8cdf832ff8d91f 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -84,7 +84,7 @@ let package = Package( ### Installation -In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. +The `SentryObjC` SPM product compiles the SDK from source. In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. A pre-compiled dynamic framework is also available via manual download. With `Package.swift`: From 14669e2618dc81c1e0c110096c157df3aff4a396 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:42:49 +0200 Subject: [PATCH 3/8] docs(apple): deprecate SentrySwiftUI product SwiftUI view performance tracking is now included in the main Sentry product. Mark SentrySwiftUI as deprecated in both SPM and manual install pages. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/manual-install.mdx | 4 ++-- docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index 65d79daad04b9d..34abb27302005a 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -12,7 +12,7 @@ To integrate Sentry into your Xcode project, follow these steps: **Sentry (Swift / standard Objective-C):** - `Sentry.xcframework.zip` — Static framework (recommended) - `Sentry-Dynamic.xcframework.zip` — Dynamic framework - - `SentrySwiftUI.xcframework.zip` — Static framework with SwiftUI support + - `SentrySwiftUI.xcframework.zip` — Deprecated. SwiftUI tracking is now included in the main `Sentry` framework. - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features **SentryObjC (pure Objective-C interface):** @@ -23,5 +23,5 @@ To integrate Sentry into your Xcode project, follow these steps: ### Usage Guidelines - Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. -- If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- `SentrySwiftUI` is deprecated. If you still use it, it must be combined with `Sentry-Dynamic`. - Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no `@import`, no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 8cdf832ff8d91f..4cd31f6ca7d69a 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -23,7 +23,7 @@ These products use pre-built binary frameworks. They don't add to your project's - **`Sentry`** — Static pre-built framework. Recommended for most projects as it provides the fastest app start time. - **`Sentry-Dynamic`** — Dynamic pre-built framework. Use this if your project requires dynamic linking. -- **`SentrySwiftUI`** — Static pre-built framework with SwiftUI performance tracking. Use this to measure the performance of your SwiftUI views. See [SwiftUI Instrumentation](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/) for more information. +- **`SentrySwiftUI`** — Deprecated. SwiftUI view performance tracking is now included in the main `Sentry` product. Do not add this to new projects. Alternatively, when your project uses a `Package.swift` file to manage dependencies, you can specify the target with: From 9f1095fd8f39faff0e668c4d81ca54ec6759bc6b Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:47:47 +0200 Subject: [PATCH 4/8] Apply suggestion from @philprime --- docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 4cd31f6ca7d69a..595b1e394ee669 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -78,7 +78,7 @@ let package = Package( ## SentryObjC -Available from SDK **9.16.1+**. +Available from SDK **9.16.0+**. **SentryObjC** is a pure Objective-C wrapper around the Sentry SDK, recommended for projects that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use `@import` or `-Swift.h`. It provides a standalone ObjC interface with no Swift dependencies in your headers. From c8b7c80b262ab089dfcc23d5ecb29892e861bf71 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Tue, 2 Jun 2026 13:46:01 +0200 Subject: [PATCH 5/8] docs(apple): address review feedback and document all SentryObjC distribution channels Apply itaybre's suggestion to clarify `@import` as "semantic imports", add SentryObjC-Static xcframework to manual install, and expand the SPM section with a "Why SentryObjC?" explainer and pre-compiled binary target products. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/index.mdx | 2 +- .../apple/common/install/manual-install.mdx | 3 ++- .../common/install/swift-package-manager.mdx | 18 ++++++++++++++++-- 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/platforms/apple/common/install/index.mdx b/docs/platforms/apple/common/install/index.mdx index 375cf466317dd8..5ce8f476171f96 100644 --- a/docs/platforms/apple/common/install/index.mdx +++ b/docs/platforms/apple/common/install/index.mdx @@ -19,7 +19,7 @@ If you prefer, you can choose one of the alternative methods below. SentryObjC {" "} section for a pure Objective-C integration that doesn't require Swift headers - or `@import`. + or semantic imports (`@import`). diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index 34abb27302005a..223eea542ab56f 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -16,6 +16,7 @@ To integrate Sentry into your Xcode project, follow these steps: - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features **SentryObjC (pure Objective-C interface):** + - `SentryObjC-Static.xcframework.zip` — Static framework (recommended) - `SentryObjC-Dynamic.xcframework.zip` — Dynamic framework 3. Import the chosen framework into your Xcode project target. @@ -24,4 +25,4 @@ To integrate Sentry into your Xcode project, follow these steps: - Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. - `SentrySwiftUI` is deprecated. If you still use it, it must be combined with `Sentry-Dynamic`. -- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no `@import`, no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. +- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no semantic imports (`@import`), no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 595b1e394ee669..6354bc78511cd0 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -80,11 +80,17 @@ let package = Package( Available from SDK **9.16.0+**. -**SentryObjC** is a pure Objective-C wrapper around the Sentry SDK, recommended for projects that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use `@import` or `-Swift.h`. It provides a standalone ObjC interface with no Swift dependencies in your headers. +**SentryObjC** is a pure Objective-C wrapper around the Sentry SDK. It is the recommended integration for any Objective-C project — including those that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use semantic imports (`@import`) or `-Swift.h`. All public types use the `SentryObjC` prefix and no Swift-related headers appear in the public surface. + +### Why SentryObjC? + +With Clang modules disabled, `@import Sentry` doesn't work and `#import ` fails with forward-declaration errors in `.mm` files. This makes `SentrySDK`, `SentryOptions`, and other Swift-bridged APIs unavailable. SentryObjC solves this by providing hand-written Objective-C headers that don't depend on Swift modules or the Swift compiler. ### Installation -The `SentryObjC` SPM product compiles the SDK from source. In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. A pre-compiled dynamic framework is also available via manual download. +SentryObjC is available as both a compile-from-source SPM product and pre-compiled xcframeworks. + +**Via SPM (compile from source):** In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. With `Package.swift`: @@ -103,6 +109,14 @@ Then depend on the `SentryObjC` product: ) ``` +**Via SPM (pre-compiled):** The `SentryObjC-Static` and `SentryObjC-Dynamic` products use pre-built binary frameworks, so they don't add to your project's compile time. Select one of these products instead of `SentryObjC` when adding the package in Xcode, or reference them in `Package.swift`: + +```swift {tabTitle:Swift} +.product(name: "SentryObjC-Static", package: "sentry-cocoa"), +``` + +Pre-compiled xcframeworks are also available for manual download. + ### Configuration All SentryObjC types use the `SentryObjC` prefix. Import the umbrella header and initialize the SDK: From 54b115330bd34666b56e5fb38b24888fdf49335e Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 3 Jun 2026 14:42:09 +0200 Subject: [PATCH 6/8] docs(apple): document SentryObjC build settings for static and no-modules scenarios Adds missing configuration details derived from the sentry-cocoa sample apps: - SentryObjC-Static requires `-lc++` linker flag and an empty .swift file - Clang modules disabled / ObjC++ needs explicit framework linking and #import - SentryObjC-Dynamic supports @import module imports Co-Authored-By: Claude Opus 4.6 --- .../apple/common/install/manual-install.mdx | 4 +- .../common/install/swift-package-manager.mdx | 38 +++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index 223eea542ab56f..2d4245474e09ca 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -25,4 +25,6 @@ To integrate Sentry into your Xcode project, follow these steps: - Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. - `SentrySwiftUI` is deprecated. If you still use it, it must be combined with `Sentry-Dynamic`. -- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no semantic imports (`@import`), no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. +- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no semantic imports (`@import`), no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration and initialization details. +- When using **`SentryObjC-Static.xcframework`**, add `-lc++` to your target's **Other Linker Flags** (the static framework bundles C++ code for the profiler and crash reporter). You also need to add an empty `.swift` file to your target to force Xcode to link the Swift runtime — see the SentryObjC-Static build settings for details. +- When your project has **Clang modules disabled** or uses **Objective-C++** (`.mm` files), you must link system frameworks explicitly (e.g., `-framework UIKit -framework Foundation` in Other Linker Flags) and use `#import` instead of `@import` — see Clang Modules Disabled / Objective-C++. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 6354bc78511cd0..0faa1301f8c8a4 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -143,7 +143,45 @@ All SentryObjC types use the `SentryObjC` prefix. Import the umbrella header and } ``` +If your project has Clang modules enabled and you're using the dynamic variant (`SentryObjC-Dynamic`), you can also use a module import instead: + +```objc +@import SentryObjC; +``` + SentryObjC embeds the full Sentry SDK. Do not link both `Sentry` and `SentryObjC` in the same target. + +### Additional Build Settings + +#### SentryObjC-Static + +When using the static variant (`SentryObjC-Static`), two additional steps are needed because the static framework bundles C++ and Swift code that pure Objective-C targets don't link automatically: + +1. **Add `-lc++` to Other Linker Flags.** In Xcode, go to your target's **Build Settings > Linking - General > Other Linker Flags** and add `-lc++`. The static framework bundles C++ code (profiler, crash reporter) that requires the C++ standard library. + +2. **Add an empty Swift file to your target.** Create a file such as `SwiftRuntime.swift` with no content (or just a comment). This forces Xcode to link the Swift runtime, which is required because the static framework contains Swift code internally. + +```swift {tabTitle:SwiftRuntime.swift} +// Forces Xcode to link the Swift runtime into this pure-ObjC target. +``` + +These steps are not needed for `SentryObjC-Dynamic` or the compile-from-source `SentryObjC` product, as dynamic frameworks and SPM source targets handle runtime linking automatically. + +#### Clang Modules Disabled / Objective-C++ + +When your project has Clang modules disabled (`CLANG_ENABLE_MODULES = NO`) or uses Objective-C++ (`.mm` files): + +1. **Use `#import` instead of `@import`.** Module imports (`@import SentryObjC;`) require Clang modules to be enabled. Use the header import instead: + + ```objc + #import + ``` + +2. **Link system frameworks explicitly.** Without modules, automatic framework linking is unavailable. Add the system frameworks your app uses to **Other Linker Flags**: + + ``` + -framework UIKit -framework Foundation + ``` From 6b1033e489115b32b6eacd428125ffe8473ea8e4 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 3 Jun 2026 15:07:38 +0200 Subject: [PATCH 7/8] docs(apple): remove deprecated SentrySwiftUI references from SwiftUI instrumentation page SwiftUI view performance tracking is now included in the main Sentry SDK. Replace all `import SentrySwiftUI` with `import Sentry` and remove the outdated install instructions that contradicted the deprecation. Co-Authored-By: Claude Opus 4.6 --- .../instrumentation/swiftui-instrumentation.mdx | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx b/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx index dbadaae0baf9f8..3e9b6bff2f10ce 100644 --- a/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx +++ b/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx @@ -10,15 +10,11 @@ og_image: >- This feature is stable since version 8.17.0. -You can monitor the performance of your views in a SwiftUI project with the SentrySwiftUI library, which you can install via SPM (Swift Package Manager). - -> If you plan to add _SentrySwiftUI_, you don't need to also add _Sentry_ library since the former depends on the latter. - -In order to start monitoring the performance of your views, you need to wrap it with `SentryTracedView`, like this: +SwiftUI view performance tracking is included in the main `Sentry` SDK. To start monitoring the performance of your views, wrap them with `SentryTracedView`: ```swift {tabTitle:Swift} -import SentrySwiftUI +import Sentry var body: some View { SentryTracedView(""){ @@ -35,7 +31,7 @@ Alternatively, you can use a modifier like this: ```swift {tabTitle:Swift} -import SentrySwiftUI +import Sentry var body: some View { List { @@ -48,7 +44,7 @@ It is possible to use nested `SentryTracedView` to have a more granular transact ```swift {tabTitle:Swift} -import SentrySwiftUI +import Sentry var body: some View { SentryTracedView("My Awesome Screen"){ @@ -92,7 +88,6 @@ To enable TTFD tracking, set `waitForFullDisplay: true` when creating a `SentryT ```swift {tabTitle:Swift} -import SentrySwiftUI import Sentry var body: some View { @@ -112,7 +107,6 @@ Alternatively, you can use the `sentryTrace` modifier with `waitForFullDisplay: ```swift {tabTitle:Swift} -import SentrySwiftUI import Sentry var body: some View { @@ -152,7 +146,6 @@ Typically, you'll call this in the `onAppear` modifier after your async content ```swift {tabTitle:Swift} -import SentrySwiftUI import Sentry struct ContentView: View { From 5b7e373e0634cd97a6320ab6aed84c57a7accc14 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 3 Jun 2026 15:42:31 +0200 Subject: [PATCH 8/8] docs(apple): use explicit Swift runtime linker flags for SentryObjC-Static Replace the dummy .swift file approach with explicit linker flags (-lswiftCore, -force_load libswiftCompatibility56.a) as the primary method, matching getsentry/sentry-cocoa#7999. The dummy file is now documented as a fallback. Also notes that targets with existing .swift files only need -lc++. Co-Authored-By: Claude Opus 4.6 --- .../apple/common/install/manual-install.mdx | 2 +- .../common/install/swift-package-manager.mdx | 15 +++++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index 2d4245474e09ca..1d96842a1545f1 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -26,5 +26,5 @@ To integrate Sentry into your Xcode project, follow these steps: - Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. - `SentrySwiftUI` is deprecated. If you still use it, it must be combined with `Sentry-Dynamic`. - Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no semantic imports (`@import`), no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration and initialization details. -- When using **`SentryObjC-Static.xcframework`**, add `-lc++` to your target's **Other Linker Flags** (the static framework bundles C++ code for the profiler and crash reporter). You also need to add an empty `.swift` file to your target to force Xcode to link the Swift runtime — see the SentryObjC-Static build settings for details. +- When using **`SentryObjC-Static.xcframework`** in a pure Objective-C target, additional linker flags are needed for the C++ standard library and Swift runtime — see the SentryObjC-Static build settings for the full flags. - When your project has **Clang modules disabled** or uses **Objective-C++** (`.mm` files), you must link system frameworks explicitly (e.g., `-framework UIKit -framework Foundation` in Other Linker Flags) and use `#import` instead of `@import` — see Clang Modules Disabled / Objective-C++. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 0faa1301f8c8a4..aed8d211719be0 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -158,13 +158,20 @@ If your project has Clang modules enabled and you're using the dynamic variant ( #### SentryObjC-Static -When using the static variant (`SentryObjC-Static`), two additional steps are needed because the static framework bundles C++ and Swift code that pure Objective-C targets don't link automatically: +When using the static variant (`SentryObjC-Static`) in a pure Objective-C target, additional linker flags are needed because the static framework bundles C++ and Swift code that Xcode doesn't link automatically. If your target already contains at least one `.swift` file, Xcode links the Swift runtime for you and you only need `-lc++`. -1. **Add `-lc++` to Other Linker Flags.** In Xcode, go to your target's **Build Settings > Linking - General > Other Linker Flags** and add `-lc++`. The static framework bundles C++ code (profiler, crash reporter) that requires the C++ standard library. +Add the following to your target's **Build Settings > Linking - General > Other Linker Flags**: -2. **Add an empty Swift file to your target.** Create a file such as `SwiftRuntime.swift` with no content (or just a comment). This forces Xcode to link the Swift runtime, which is required because the static framework contains Swift code internally. +``` +-lc++ -lswiftCore -force_load $(DT_TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)/libswiftCompatibility56.a +``` + +- **`-lc++`** links the C++ standard library, required by the profiler and crash reporter bundled in the static framework. +- **`-lswiftCore`** and the **`-force_load`** flag link the Swift runtime and backward-compatibility stubs. These are only needed when your target has no Swift files. If your target already contains a `.swift` file, Xcode links the Swift runtime automatically and you can omit these two flags. + +As a fallback (for example, if the toolchain path causes issues in your build system), you can add an empty Swift file to your target instead of the explicit flags. Create a file such as `Dummy.swift` with no content and its presence forces Xcode to link the Swift runtime: -```swift {tabTitle:SwiftRuntime.swift} +```swift {tabTitle:Dummy.swift} // Forces Xcode to link the Swift runtime into this pure-ObjC target. ```