Research state of support for SPM from source

[philprime]

Note

This issue was created with the help of Cursor.

Priority: High (Blocking)

Context: CocoaPods trunk is moving to read-only mode on December 2nd, 2026. No new versions or pods will be accepted after this date. This issue is part of the CocoaPods EOL migration effort.

Description:
Ensure the SDK fully compiles from source using Swift Package Manager. Verify all features work correctly when installed via SPM, including:

• All platform targets (iOS, macOS, tvOS, watchOS, visionOS)
• All product variants (static, dynamic, with/without ARM64e)
• All dependencies resolve correctly
• Sample apps using SPM work correctly

Acceptance Criteria:

• All SPM sample apps build and run successfully
• All product variants compile from source
• No SPM-specific build issues exist
• Documentation confirms SPM is fully supported

Notes:
This should be verified before proceeding with removal of CocoaPods support.

[linear]

COCOA-1203

[philprime]

Migration Plan: xcodebuild + CocoaPods → Swift Package Manager

Important

This plan has been drafted using Cursor

This document outlines the migration path from the current build system (xcodebuild + CocoaPods) to Swift Package Manager (SPM) as the primary build system. Context: CocoaPods trunk is moving to read-only mode on December 2nd, 2026. No new versions or pods will be accepted after that date.

---

1. Inventory: Artifacts, Variants, and Release Channels We Must Preserve

Before defining the migration plan, the following list captures everything we currently produce and must continue to support.

1.1 XCFramework Artifacts (Distribution)

Artifact	Mach-O Type	Configuration	ARM64e	Description
Sentry	staticlib	Release	included	Static framework, default SPM product
Sentry-Dynamic	mh_dylib	Release	excluded	Dynamic framework, common for app extensions
Sentry-Dynamic-WithARM64e	mh_dylib	Release	included	Dynamic with ARM64e pointer auth support
Sentry-WithoutUIKitOrAppKit	mh_dylib	ReleaseWithoutUIKit	excluded	No UIKit/AppKit linkage (e.g. File Provider extensions)
Sentry-WithoutUIKitOrAppKit-WithARM64e	mh_dylib	ReleaseWithoutUIKit	included	UIKit-free with ARM64e
SentrySwiftUI	mh_dylib	Release	N/A	SwiftUI-specific APIs, depends on Sentry

1.2 Platform Slices (per XCFramework)

Each XCFramework variant is built for these SDKs:

• iphoneos — iOS device
• iphonesimulator — iOS Simulator
• macosx — macOS
• maccatalyst — Mac Catalyst
• appletvos — tvOS device
• appletvsimulator — tvOS Simulator
• watchos — watchOS device
• watchsimulator — watchOS Simulator
• xros — visionOS device
• xrsimulator — visionOS Simulator

1.3 SPM Products (Package.swift)

Product	Type	Consumer Use
Sentry	binary target + SentryCppHelper	Default: pre-built static XCFramework
Sentry-Dynamic	binary target	Pre-built dynamic XCFramework
Sentry-Dynamic-WithARM64e	binary target	Pre-built dynamic with ARM64e
Sentry-WithoutUIKitOrAppKit	binary target + SentryCppHelper	Pre-built UIKit-free
Sentry-WithoutUIKitOrAppKit-WithARM64e	binary target + SentryCppHelper	Pre-built UIKit-free with ARM64e
SentrySwiftUI	source + dependency on Sentry	SwiftUI APIs
SentryDistribution	source	In-app update/distribution utilities
SentrySPM	source (compile-from-source)	Alternative to binary targets

1.4 CocoaPods Artifacts (To Be Replaced)

Spec	Description
Sentry	Core SDK pod
SentrySwiftUI	SwiftUI pod (depends on Sentry)

CocoaPods lint matrix: Sentry and SentrySwiftUI × ios, macos, tvos, watchos × dynamic, static.

1.5 Third-Party Integrations (SPM Packages)

Separate packages in 3rd-party-integrations/:

• SentryCocoaLumberjack
• SentryPulse
• SentrySwiftLog
• SentrySwiftyBeaver

1.6 Release Channels

Channel	Branch	Description
Pre-release	tags (alpha, beta, RC)	Larger changes, feature validation
Latest	main	Default for most teams
Stable	promoted from Latest	Marked as "Stable" on releases page
v8.x	v8.x	Legacy maintenance branch

1.7 Sample Apps (Build Validation)

Sample	SDK Integration	Platforms
iOS-Swift	subproject	iOS
iOS-ObjectiveC	subproject	iOS
iOS-Swift6	subproject	iOS
iOS-SwiftUI	subproject	iOS
iOS-15-SwiftUI	subproject	iOS
iOS-Cocoapods-Swift6	CocoaPods	iOS (+ keyboard extension)
iOS-SwiftUI-SPM	SPM (SentrySPM)	iOS, watchOS
macOS-Swift	subproject	macOS
macOS-SwiftUI	subproject	macOS
macOS-SwiftUI-SPM	SPM (SentrySPM)	macOS
macOS-SPM-CommandLine	SPM	macOS
tvOS-Swift	subproject	tvOS
tvOS-SwiftUI-SPM	SPM (SentrySPM)	tvOS
watchOS-Swift	subproject	watchOS
visionOS-Swift	subproject	visionOS
visionOS-SwiftUI-SPM	SPM (SentrySPM)	visionOS
visionOS-SPM	SPM	visionOS
SPM	SPM (SentrySPM)	iOS
SPM-Dynamic	SPM (Sentry-Dynamic binary)	iOS
DistributionSample	SPM (SentryDistribution)	iOS
XCFramework-Validation	XCFramework	iOS
SessionReplay-CameraTest	subproject	iOS
iOS-SwiftUI-Widgets	subproject	iOS
SDK-Size	subproject	iOS

1.8 Test Targets

Target	Purpose
SentryTests	Unit tests for core SDK
SentryProfilerTests	Profiler tests
SentryTestUtilsTests	Test utility tests
SentryDistributionTests	Distribution module tests
SentryTestUtils / SentryTestUtilsDynamic	Test helpers
Cross-platform (React Native, Flutter, .NET, Unity)	Integration validation

---

2. Migration Plan

The plan is structured so that each phase preserves the artifacts in Section 1. Nothing is dropped until a replacement is in place.

Phase 1: SPM as Primary Path for Unit Tests

Goal: Run all unit tests via SPM without losing coverage or platform support.

Current state: Tests run via sentry-xcodebuild.sh against Sentry.xcodeproj for iOS, macOS, Catalyst, tvOS, visionOS.

Actions:

1. Add SentryTestUtils and SentryTestUtilsDynamic as SPM targets in Package.swift.
2. Add test targets for SentryTests, SentryProfilerTests, SentryTestUtilsTests that depend on SentrySPM and test utils.
3. Add Make targets (e.g. test-spm-ios, test-spm-macos) using swift test or xcodebuild with SPM.
4. Add CI jobs that run SPM tests; run in parallel with xcodebuild tests initially.
5. Achieve parity: all platforms and test classes covered.
6. Switch CI to SPM tests as primary; keep xcodebuild tests as fallback until Phase 5.

Preserved: All test targets, all platforms, CI quality gates.

---

Phase 2: Build XCFrameworks from SPM

Goal: Produce all XCFramework variants from SPM instead of Sentry.xcodeproj, without changing outputs.

Current state: XCFrameworks are built via build-xcframework-slice.sh → build-xcframework-variant.sh → build-xcframework-local.sh, all using xcodebuild against Sentry.xcodeproj.

Approach: Use xcodebuild with SPM (e.g. -packagePath or SPM-generated project) to build slices, then reuse assemble-xcframework.sh and compress-xcframework.sh for assembly and packaging.

Actions:

1. Create SPM schemes/configurations that map to each variant:
   • Static (Sentry)
   • Dynamic (Sentry-Dynamic)
   • Dynamic-WithARM64e
   • WithoutUIKit
   • WithoutUIKit-WithARM64e
   • SentrySwiftUI
2. Implement build scripts that use SPM as the source (via xcodebuild) to produce the same slice structure as today.
3. Add support for SENTRY_NO_UI_FRAMEWORK=1 (or equivalent) for WithoutUIKit variants in SPM.
4. Integrate ARM64e exclusion where needed.
5. Validate each XCFramework: same structure, platforms, and checksums as current builds.
6. Update build-xcframework-local.sh (or equivalent) to invoke SPM-based builds.
7. Update release workflow to use the new build path.

Preserved: All 6 XCFramework variants, all 10 platform slices, release pipeline, Package.swift binary targets.

Risk: UIKit-free config is documented as "not compatible with SPM" in BUILD.md. Either implement SPM support for it or keep a minimal xcodebuild path for WithoutUIKit variants until SPM supports it.

---

Phase 3: Unify Sample Apps on SPM

Goal: All sample apps build and validate via SPM; no CocoaPods samples.

Current state: Most samples use xcodegen + subproject; iOS-Cocoapods-Swift6 uses CocoaPods; SPM samples use xcodegen + SPM dependency.

Actions:

1. Convert iOS-Cocoapods-Swift6 to use SPM (e.g. SentrySPM or local path) instead of pod 'Sentry'.
2. Remove Podfile and CocoaPods setup from that sample.
3. Ensure all SPM samples (iOS-SwiftUI-SPM, macOS-SwiftUI-SPM, etc.) build via make build-sample-spm or equivalent.
4. Add swift build paths where feasible for pure SPM samples.
5. Update Samples README and docs.

Preserved: All sample apps, all platforms, build validation in CI.

---

Phase 4: Deprecate CocoaPods

Goal: Remove CocoaPods from the build and release pipeline while giving consumers a clear migration path.

Actions:

1. Publish CocoaPods deprecation notice and migration guide.
2. Update README and docs to recommend SPM (and XCFramework where applicable).
3. Remove or disable:
   • lint-cocoapods-specs.yml
   • integration-test.yml (CocoaPods integration test)
4. Remove or archive Sentry.podspec and SentrySwiftUI.podspec (or keep as read-only stubs if desired).
5. Remove CocoaPods from Gemfile/Brewfile if no longer needed.
6. Coordinate with React Native, Flutter, Unity, .NET SDKs that consume sentry-cocoa.

Preserved: Consumer migration path via SPM and XCFramework; no new CocoaPods releases after EOL.

---

Phase 5: Remove xcodebuild as Primary Build System

Goal: SPM is the single source of truth; Sentry.xcodeproj is no longer required for SDK builds or tests.

Prerequisites: Phases 1–4 complete; SPM tests and XCFramework builds are proven.

Actions:

1. Remove or archive Sentry.xcodeproj and Sentry.xcworkspace.
2. Remove scripts/sentry-xcodebuild.sh, build-xcframework-slice.sh, and obsolete xcodebuild-oriented scripts.
3. Simplify Makefile: replace XCODE_SCHEME-based targets with SPM commands.
4. Update all CI workflows to use SPM.
5. Retain xcodebuild only where required (e.g. running tests on simulators, assembling XCFrameworks from SPM output).
6. Update develop-docs/BUILD.md, AGENTS.md, and contributing docs.

Preserved: All artifacts from Section 1; only the build tooling changes.

---

Phase 6: Cleanup and Documentation

Goal: Clear, consistent documentation and developer experience.

Actions:

1. Finalize develop-docs/BUILD.md with SPM-only instructions.
2. Update README.md installation instructions.
3. Update SDK docs (e.g. docs.sentry.io) for SPM.
4. Remove CocoaPods references from README badges and text.
5. Add SPM-MIGRATION-PLAN.md to the developer docs index.

---

3. Dependency Graph

Phase 1 (SPM tests) ──────────────────────────────────────┐
         │                                               │
         ▼                                               ▼
Phase 2 (XCFramework from SPM)              Phase 3 (Samples on SPM)
         │                                               │
         └───────────────────┬───────────────────────────┘
                             │
                             ▼
                    Phase 4 (CocoaPods deprecation)
                             │
                             ▼
                    Phase 5 (xcodebuild removal)
                             │
                             ▼
                    Phase 6 (Cleanup & docs)

---

4. Risk Mitigation

Risk	Mitigation
SPM cannot build all variants	Keep xcodebuild path for affected variants until SPM supports them.
Test parity gaps	Run SPM and xcodebuild tests in parallel until parity is confirmed.
CocoaPods consumers blocked	Early deprecation notice; migration guide; coordination with RN, Flutter, Unity, .NET.
UIKit-free not supported in SPM	Document as XCFramework-only for now, or scope work to add SPM support.
visionOS / Swift 6 compatibility	Validate early; Package.swift already uses Swift 6.

---

5. Existing Assets to Leverage

• SentrySPM — Compile-from-source product with ObjC/Swift split already in place.
• SentryDistributionTests — Already run via SPM (prepare-package.sh --remove-binary-targets true).
• SPM samples — iOS, macOS, tvOS, visionOS, watchOS samples exist.
• test-server — Already uses swift build.
• Distribution pipeline — assemble-xcframework.sh, compress-xcframework.sh, validate-xcframework-format.sh can be reused.

Other Results from initial investigation

Package Resolving Issues

• When using the latest branch I am constantly seeing the following Package resolving error:

sentry-cocoa
  Updating from https://github.com/getsentry/sentry-cocoa
    github.com: https://github.com/getsentry/sentry-cocoa: The repository could not be found. Make sure a valid repository exists at the specified location and try again.
Updating Package Graph Failed    11.02.26, 09:46    0.2 seconds

It's unclear what causes this, as clearing the derived data directory and any combination of cache reset or manual package resolving inside Xcode also does not help.

Interestingly it works from the command line:

$ xcodebuild -resolvePackageDependencies
Command line invocation:
    /Applications/Xcode-26.2.0.app/Contents/Developer/usr/bin/xcodebuild -resolvePackageDependencies

Resolve Package Graph


Resolved source packages:
  Sentry: https://github.com/getsentry/sentry-cocoa @ main (92e1256)

resolved source packages: Sentry

We must consider creating a mirror named getsentry/sentry-swift which only contains pure source code/SPM-compatible files.

Compilation Issues

I had to adapt the SentrySPM framework to properly support building for SPM: #7430

[philprime]

Closing this issue as it's ambiguous and seems to be completed