skip to content

A vendor ships a closed-source analytics SDK as a zipped XCFramework; how do you declare it with SwiftPM's binaryTarget, and what does its checksum guard?

level: seniorimportance: should knowfreq 30%

answer

  1. an archive, not source
  2. https and a zip
  3. SHA-256 of the archive
  4. compute-checksum
  5. a wrapper target for dependencies

basics

~10 s

Declare .binaryTarget(name:url:checksum:) with an https URL to the zip and the SHA-256 that swift package compute-checksum prints. SwiftPM rejects a downloaded archive whose checksum differs, so a swapped or corrupted file never builds.

solid answer

~40 s

In `Package.swift` you add `.binaryTarget(name:url:checksum:)`: the URL must be `https` and point to a `.zip` whose root holds the `.xcframework`, and the checksum is the archive's SHA-256, produced by `swift package compute-checksum VendorAnalytics.xcframework.zip`. When SwiftPM downloads the archive it computes the checksum and fails if it does not match the manifest, so a file replaced on the server or a corrupted download cannot slip into a build. It is an **integrity** check, not a review of what the binary does. For a binary in your own repository use `.binaryTarget(name:path:)`, which takes no checksum. Binary targets take no `dependencies` or `resources`, so wrap the SDK in a small source target that depends on it and on anything else it needs, and expose your own API.

code

swift · 19 lines
swift
// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "AnalyticsKit",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "AnalyticsKit", targets: ["AnalyticsKit"]),
    ],
    targets: [
        // Your Swift API; the vendor's module stays behind it.
        .target(name: "AnalyticsKit", dependencies: ["VendorAnalytics"]),
        .binaryTarget(
            name: "VendorAnalytics",
            url: "https://downloads.example.com/sdk/4.2.0/VendorAnalytics.xcframework.zip",
            checksum: "4ed7d5c37642bb82772a80924a828e8a1e54b279249e32cd7d874757570363de"
        ),
    ]
)

go deeper

for a junior

Recall that a closed-source XCFramework is declared as a binary target, either by URL with a checksum or by local path.

for a middle

Explain the url and path factories, the https and zip rules, and that the checksum is the archive's SHA-256 from swift package compute-checksum.

for a senior

Diagnose a checksum mismatch, review a binary SDK upgrade, and wrap the binary in a source target that carries its dependencies and your own API.

for a principal

Set the policy for closed-source binaries: who may add one, how upgrades are reviewed, and why every vendor module sits behind a replaceable wrapper.

## Binary targets in SwiftPM Most packages ship source. A vendor that cannot — a closed analytics or payments SDK — ships a prebuilt **XCFramework**, and SwiftPM consumes it through a **binary target** (tools version 5.3 and later). How the vendor builds the XCFramework is covered in the XCFramework lesson; this one is about declaring and trusting it. PackageDescription's own documentation says binary targets are only available on Apple platforms. There are two factories: | Factory | Points at | Checksum | Typical use | |---|---|---|---| | `.binaryTarget(name:url:checksum:)` | A downloadable archive | Required | A vendor-hosted SDK | | `.binaryTarget(name:path:)` | A local `.xcframework`, `.zip` or `.artifactbundle` | None | A binary committed to your repository | SwiftPM validates the shape when it loads the manifest: - A remote URL must use `https`; anything else fails with "invalid URL scheme for binary target … valid schemes are: 'https'". - A remote URL must end in `.zip` (or `.artifactbundleindex`), and the archive must contain the binary artifact at its root. - A local path must end in `.xcframework`, `.zip` or `.artifactbundle`. ## The checksum The `checksum` is the **SHA-256** of the archive file — not of the unzipped framework. PackageDescription's documentation says to always produce it with: ```bash swift package compute-checksum VendorAnalytics.xcframework.zip ``` which prints the 64-character hex digest. When SwiftPM downloads the archive it computes the same digest and compares. A mismatch stops the build with an error that the checksum of the downloaded artifact of the binary target does not match the checksum specified by the manifest. What that protects: - **A file swapped on the server** under an unchanged URL. - **A corrupted or truncated download.** - **A mirror or cache serving a different build** than the one the manifest's author hashed. What it does not protect: - It does not say the binary is **safe** or well behaved — only that it is the exact archive whoever wrote the manifest hashed. - It does not check the manifest itself: a typo in the checksum is not caught when the manifest is parsed, only when the archive is fetched and compared. ## How vendors usually ship it The common pattern is a small vendor package in a Git repository whose only target is the binary target. Each release tag carries a manifest with a new URL and a new checksum. You add that package with a normal version requirement, and because `Package.resolved` pins the tag, it also pins the URL and checksum that tag declares. Since Swift 5.10, SwiftPM caches binary artifacts alongside repository checkouts so they are not downloaded again for every project. ## Wrapping the SDK A binary target's factories take only a name and a location: **no `dependencies`, no `resources`, no settings**. Three consequences follow: 1. If the SDK needs another library, declare that relationship in a **wrapper target** — a regular source target that depends on both the binary target and the other product. 2. Resources the SDK needs must already be inside its framework; SwiftPM generates no `Bundle.module` for a binary target. 3. The wrapper is the right place for **your** API: features import `AnalyticsKit`, not the vendor's module, so replacing or stubbing the vendor later touches one target. Module aliasing cannot rename a prebuilt binary module, which is another reason not to let its name spread through the app. ## When the checksum check fails A mismatch is a stop sign, not a typo to paste over. The disciplined response: - Download the archive from the declared URL and run `swift package compute-checksum` on it yourself. - Compare the digest with the one the vendor publishes for that release, through a channel other than the download server. - If the vendor re-uploaded a fixed build under the same URL, ask for a new release with a new URL and checksum rather than editing the old pair. - Only when the source is confirmed, update the checksum in the manifest, in a reviewed change of its own. Treating every mismatch as "the vendor forgot to update the hash" is how a tampered binary gets waved through. ## Reviewing a change to a binary target - A new URL **and** a new checksum together, matching the vendor's published release. - The checksum computed from the archive by `swift package compute-checksum`, not copied from an old manifest. - `https` only; no local path to a file outside the repository. - The wrapper target still compiles against the new SDK's public API.

  • The vendor's SDK needs a networking library that ships as a source package. Where do you declare that dependency?
    On a wrapper target, because `.binaryTarget` takes no `dependencies` parameter. A regular target such as `AnalyticsKit` depends on both the binary target and the networking product; the app links the wrapper's library product, so both get built and linked.
  • When would you use `.binaryTarget(name:path:)` instead of the URL form?
    When the XCFramework, or a zip of it, is committed to your repository, for instance an in-house binary or a vendor drop you must keep under version control. It takes a path ending in `.xcframework`, `.zip` or `.artifactbundle` and no checksum, since nothing is downloaded.

Like a tamper-evident seal number on a delivery note: if the seal on the box doesn't match the note, you refuse the box. A matching seal proves it's the box that was packed, not that what was packed is any good.

  • The checksum is computed on the unzipped .xcframework folder.
  • A matching checksum proves the vendor's binary is safe to ship.
  • A binary target can list its own package dependencies like a regular target.
  • An http URL is fine for a binary target inside a corporate network.
  • SwiftPM rewrites the checksum in Package.resolved when the vendor re-uploads the zip.