diff --git a/docs/platforms/apple/common/install/index.mdx b/docs/platforms/apple/common/install/index.mdx index e5f3e0c6dd493..5ce8f476171f9 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 semantic imports (`@import`). + + diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index ad7414b5d67cd..1d96842a1545f 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -7,14 +7,24 @@ 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` — 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):** + - `SentryObjC-Static.xcframework.zip` — Static framework (recommended) + - `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. +- `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`** 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 1c8a3e4524a96..aed8d211719be 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`** — 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: ```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,124 @@ 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.0+**. + +**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 + +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`: + +```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"), + ] +) +``` + +**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: + +```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; +} +``` + +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`) 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++`. + +Add the following to your target's **Build Settings > Linking - General > Other Linker Flags**: + +``` +-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:Dummy.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 + ``` diff --git a/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx b/docs/platforms/apple/common/tracing/instrumentation/swiftui-instrumentation.mdx index dbadaae0baf9f..3e9b6bff2f10c 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 {