Skip to content

packer: fix framework names and fat static archives in binary targets - #198

Draft
guitaripod wants to merge 2 commits into
xtool-org:mainfrom
guitaripod:fix-sentry-package-bugs
Draft

guitaripod wants to merge 2 commits into
xtool-org:mainfrom
guitaripod:fix-sentry-package-bugs

Conversation

@guitaripod

@guitaripod guitaripod commented Jan 27, 2026 •

Copy link
Copy Markdown

What does this PR do?

Fixes the two packaging bugs from #130. The SourceKit-LSP point in that issue is not covered here.

  1. Framework names come from the xcframework. A binary target can ship a framework named differently from the target: Sentry-Dynamic.xcframework contains Sentry.framework, and SentryObjC-Dynamic.xcframework contains SentryObjC.framework. The packer now reads the LibraryPath that the xcframework's Info.plist lists for the build triple, matched by platform, variant and architecture the way SwiftPM picks the library it links. Remote and zipped xcframeworks are read from .build/artifacts/<package>/<target>/, local ones from the target path that swift package describe reports. When no xcframework is found, <target>.framework is used as before. There is no prefix matching or directory scan.
  2. Universal binaries of static archives are not embedded. A fat binary (fat_arch or fat_arch_64) counts as static when every slice is an ar archive. Only the outer magic was checked before, so the static Sentry framework (and the MPVKit and GoogleAdsOnDeviceConversion frameworks) got embedded and the install failed.

How was it tested?

Unit tests in PackerTests.swift cover the LibraryPath selection (device, simulator, Mac Catalyst, macOS, tvOS, visionOS, an unmatched architecture, an invalid plist) and the archive check (bare and thin archives, fat_arch and fat_arch_64 with archive slices, mixed slices, plain Mach-O, truncated and bogus headers). The full suite passes on macOS and Linux (Swift 6.4.2), and make lint is clean.

End to end on macOS 27.3 with Xcode 27.3 and sentry-cocoa 9.34.0: xtool dev build for arm64-apple-ios-simulator and arm64-apple-ios, then a launch on an iOS 27.3 simulator, main (a2875dd) against this branch:

App depends on main this branch
Sentry-Dynamic not embedded, launch fails with Library not loaded: @rpath/Sentry.framework/Sentry Sentry.framework embedded, launches, SentrySDK.isEnabled == true
Sentry (static) embedded, install fails with Frameworks/Sentry.framework/Sentry contained no image slices not embedded, launches, SentrySDK.isEnabled == true
SentryObjC-Dynamic not embedded, launch fails with Library not loaded: @rpath/SentryObjC.framework/SentryObjC SentryObjC.framework embedded, launches, SentryObjCSDK.isEnabled == true
local .binaryTarget(name: "VendoredSentry", path: "Frameworks/Sentry-Dynamic.xcframework") not embedded, launch fails with Library not loaded: @rpath/Sentry.framework/Sentry Sentry.framework embedded, launches, SentrySDK.isEnabled == true

The device builds embed the arm64 iOS slices of the same frameworks (not installed on a device). I ran the matrix with the default SwiftBuild build system and again with the native one. The results match, except that native SwiftPM linked the Sentry-Dynamic app against the static Sentry slice, so that app also launches on main there, and this branch correctly leaves the static copy out of the bundle.

AI tool usage

How much of the code in this PR was AI-assisted? (check one)

  • 0 - No AI was used to write code
  • 1 - I was assisted by AI in writing code. I reviewed the finished result.
  • 2 - I set the AI going and left it to it; nobody has read the result - no review, or AI review only

Summary by CodeRabbit

  • New Features
    • Binary targets now select the matching library from an XCFramework based on the current build platform and architecture, including support for iOS, macOS, tvOS, visionOS, and Catalyst.
    • XCFrameworks supplied directly or found in build artifacts can be used even when the framework name differs from the binary target name.
  • Bug Fixes
    • Static archive libraries and frameworks with missing binaries are skipped during packing, avoiding attempts to package unsupported or incomplete frameworks.

@guitaripod
guitaripod marked this pull request as draft January 27, 2026 11:23
@guitaripod
guitaripod force-pushed the fix-sentry-package-bugs branch from eabc6df to e4c1959 Compare January 27, 2026 11:24
@guitaripod
guitaripod marked this pull request as ready for review January 27, 2026 11:45
@guitaripod
guitaripod marked this pull request as draft January 27, 2026 13:07
@guitaripod
guitaripod marked this pull request as ready for review January 27, 2026 13:12

@chintan100 chintan100 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested this on macOS (Xcode 27 / Swift 6.4) with sentry-cocoa 8.53.0, building with xtool dev build --triple arm64-apple-ios-simulator and running on an iOS 26.5 simulator, comparing main (d802c71) with main + this PR:

Sentry (static) Sentry-Dynamic
main static Sentry.framework gets embedded, so the simulator install fails: Failed to iterate on macho slices … Frameworks/Sentry.framework/Sentry Sentry.framework isn't embedded, so launch crashes: Library not loaded: @rpath/Sentry.framework/Sentry
this PR not embedded; app launches, SentrySDK.isEnabled == true dynamic Sentry.framework embedded; app launches, SentrySDK.isEnabled == true

So both packaging bugs from #130 are fixed for Sentry (the SourceKit-LSP point in #130 isn't covered by this PR).

One thing I noticed: findFrameworkName(for:in:) runs for every binary target, since the Planner always passes frameworkName: nil, not only when \(name).framework is missing as the description says. With several binary targets whose names share a prefix (say Foo and FooBar), the prefix match plus the unordered directory listing could resolve Foo to FooBar.framework. Checking for \(name).framework first and scanning only as a fallback would avoid that; reading LibraryPath from the xcframework's Info.plist would give an exact mapping.

@gulian

gulian commented Nov 14, 2026

Copy link
Copy Markdown

Another real-world case for the FAT detection half of this PR, in case it helps it land: MPVKit 1.1.0-n9.0.2 (libmpv, FFmpeg and their dependencies, 38 xcframeworks).

Every framework binary I checked in it (37) is a universal file whose slices are static archives, the same shape as the static Sentry build described here:

xcframework slice first 8 bytes slices
ios-arm64 cafebabe 00000001 1, an ar archive
tvos-arm64_arm64e cafebabe 00000002 2, both ar archives

On current main these are taken for dynamic frameworks and copied into Frameworks/, although they are already linked into the executable. In a tvOS app built with the #362 branch, that was about 139 MB of archives in a 176 MB bundle. Once they are recognised as static, the app is 38 MB with no Frameworks/ directory, and it installs and runs on an Apple TV.

I measured this with a local patch that checks every slice rather than with this branch. All slices are archives here, so the first-slice check in this PR should classify them the same way. #383 reported the same shape for GoogleAdsOnDeviceConversion before it was closed.

Some xcframeworks wrap static archives in a universal (fat) Mach-O, such
as the static Sentry framework and the MPVKit frameworks. Only the outer
magic was checked, so these were taken for dynamic frameworks and
embedded, and installing the app then failed with "contained no image
slices". Treat a binary as static when every slice of a universal binary
is an archive.

Refs xtool-org#130
A binary target can ship a framework named differently from the target:
Sentry-Dynamic.xcframework contains Sentry.framework, and
SentryObjC-Dynamic.xcframework contains SentryObjC.framework. Looking
for <target>.framework missed them, so they were never embedded and the
app crashed at launch with "Library not loaded".

Read the LibraryPath that the xcframework's Info.plist lists for the
build triple, matched by platform, variant and architecture the way
SwiftPM picks the library it links. The xcframework comes from the
package for local binary targets and from .build/artifacts for remote
or zipped ones. When none is found, the <target>.framework convention
still applies.

Refs xtool-org#130
@guitaripod
guitaripod force-pushed the fix-sentry-package-bugs branch from e4c1959 to f3e164e Compare November 15, 2026 13:15
@guitaripod guitaripod changed the title Fix Sentry package bugs: name mismatch and FAT static detection packer: fix framework names and fat static archives in binary targets Nov 15, 2026
@guitaripod
guitaripod marked this pull request as draft November 15, 2026 13:15
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

Binary-target planning now carries an optional XCFramework path. Packer uses XCFramework metadata to select a library for the build triple and checks framework binaries for static archives before packing.

Changes: XCFramework binary target packing

Layer / File(s) Summary
Carry XCFramework paths into the plan
Sources/PackLib/Planner.swift
PackageDump decodes package and target paths. Binary-target resources include a resolved XCFramework path when the target path ends in .xcframework.
Select libraries and inspect archives
Sources/PackLib/Packer+BinaryTarget.swift, Tests/XToolTests/PackerTests.swift
Helpers match XCFramework libraries to Apple target triples and detect static archives in regular or universal binaries. Tests cover supported triples, archive formats, and malformed inputs.
Resolve and pack binary targets
Sources/PackLib/Packer.swift
Packer uses the selected XCFramework library name, skips missing frameworks and static framework binaries, and packs and signs other frameworks.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant PackageDump
  participant Planner
  participant Packer
  participant XCFrameworkPlist
  participant FrameworkBinary
  PackageDump->>Planner: package path and target path
  Planner->>Packer: binary target with resolved XCFramework path
  Packer->>XCFrameworkPlist: select library matching build triple
  Packer->>FrameworkBinary: inspect binary for static archive
  Packer->>Packer: pack and sign non-static framework
Loading

Suggested reviewers: kabiroberai

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names two changes: framework name resolution for binary targets and detection of fat (universal) static archives. Both match the raw summary and the PR objectives, which describe the name-mi…
Linked Issues check Passed Issue #130 directly links to this PR. Its two coding requirements are covered at the reviewed head.

(1) Framework name mismatch [#130]: Packer.swift resolves the framework name from the xcframework I…
Out of Scope Changes check Passed All changes support binary-target framework resolution or static-archive detection, which are the issue #130 objectives.

- Packer+BinaryTarget.swift: xcframework plist decoding, library selection, an…
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names two changes: framework name resolution for binary targets and detection of fat (universal) static archives. Both match the raw summary and the PR objectives, which describe the name-mismatch fix and FAT static detection. The title is specific and omits no main change. It states the scope as 'packer', which is accurate because the changes sit in Packer.swift and Packer+BinaryTarget.swift.

Full details: Linked Issues check

Explanation

Issue #130 directly links to this PR. Its two coding requirements are covered at the reviewed head.

(1) Framework name mismatch [#130]: Packer.swift resolves the framework name from the xcframework Info.plist LibraryPath. It matches platform, variant, and architecture for the build triple. Planner.swift passes the xcframework path through Plan.Resource.binaryTarget. A fallback keeps the <target>.framework convention. Packer+BinaryTarget.swift adds xcframeworkLibraryPath, and PackerTests.swift tests library selection for iOS, simulator, Catalyst, macOS, tvOS, and visionOS triples.

(2) FAT binaries with static archive slices [#130]: Packer+BinaryTarget.swift adds isStaticArchive. It accepts a universal binary only when every slice (1 to 64 slices) starts with an archive magic. Non-archive slices, malformed headers, and truncated input return false. PackerTests.swift covers bare archives, 32- and 64-bit universal headers, mixed slices, and malformed input. Packer.swift skips framework binaries that are static archives.

The issue also lists a SourceKit-LSP failure on import Sentry. The issue marks this as possibly upstream. The PR objectives and description do not claim to fix it. No xtool-side change for it appears in the summarized diff. This item is not treated as a requirement of this PR.

The PR description is partly stale. It describes a first-slice check and a scan-based findFrameworkName(). The current objectives and code use an every-slice check and LibraryPath resolution. The assessment uses the current code.

Full details: Out of Scope Changes check

Explanation

All changes support binary-target framework resolution or static-archive detection, which are the issue #130 objectives.

  • Packer+BinaryTarget.swift: xcframework plist decoding, library selection, and static-archive detection. Helper types and a big-endian Data reader support these functions.
  • Packer.swift: uses the resolved framework name and skips static archive binaries.
  • Planner.swift: adds an optional xcframeworkPath to Plan.Resource.binaryTarget. The path comes from PackageDump and is limited to existing .xcframework targets. This input is needed for LibraryPath resolution.
  • PackerTests.swift: tests for the new helpers.

No unrelated change appears in the summary. The review relies on the AI-generated summaries. I did not inspect the diff hunks directly.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Review coverage is incomplete: 4 files could not be fully reviewed. Findings from completed review steps are included; see review info for details.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ae89e9fd-0f64-4426-9085-e71f0197544e
Commits

Reviewing files that changed from the base of the PR and between a2875dd and f3e164e.

Files selected for processing: 4

  • Sources/PackLib/Packer+BinaryTarget.swift
  • Sources/PackLib/Packer.swift
  • Sources/PackLib/Planner.swift
  • Tests/XToolTests/PackerTests.swift
Files not reviewed due to moderation or processing errors: 4

  • Sources/PackLib/Planner.swift
  • Sources/PackLib/Packer+BinaryTarget.swift
  • Tests/XToolTests/PackerTests.swift
  • Sources/PackLib/Packer.swift

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@guitaripod

Copy link
Copy Markdown
Author

I rebased this onto current main and reworked both halves:

  • @chintan100 The framework name now comes from the LibraryPath that the xcframework's Info.plist lists for the build triple, so the prefix match and the directory scan are gone. Remote and zipped xcframeworks are read from .build/artifacts, local ones from the target path. Thanks for the simulator matrix.
  • @gulian A fat binary now counts as static only when every slice is an archive, as in your local patch. Thanks for the MPVKit numbers.

I re-tested with sentry-cocoa 9.34.0 (Sentry, Sentry-Dynamic, SentryObjC-Dynamic and a vendored local xcframework); the results are in the description.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants