Feature request: prebuilt binary xcframework for Cmlx to eliminate cold build cost

[sam-fakhreddine]

Summary

After looking at the repo more carefully: your existing release.yml already builds and uploads Cmlx.xcframework.zip to each GitHub Release. The missing piece is small — wiring that artifact to a .binaryTarget in Package.swift so SwiftPM consumers can resolve the binary instead of compiling 260 MB of C++ from source.

The gap

The existing workflow:

1. ✅ Builds Cmlx.xcframework via tools/create-xcframework.sh
2. ✅ Zips and uploads to GitHub Release via gh release upload
3. ❌ Does not compute SHA256 checksum
4. ❌ Does not update Package.swift with a .binaryTarget on the release tag

Proposed addition (~30 lines to release.yml)

After the existing upload step, add:

- name: Compute Cmlx xcframework checksum
  working-directory: xcode
  run: |
    CHECKSUM=$(swift package compute-checksum build/output/Cmlx.xcframework.zip)
    echo "CMLX_CHECKSUM=$CHECKSUM" >> $GITHUB_ENV

- name: Update Package.swift binary target for this release
  run: |
    VERSION="${{ github.ref_name }}"
    URL="https://github.com/ml-explore/mlx-swift/releases/download/${VERSION}/Cmlx.xcframework.zip"
    python3 tools/update-binary-target.py \
      --package Package.swift \
      --name Cmlx \
      --url "$URL" \
      --checksum "${{ env.CMLX_CHECKSUM }}"

- name: Commit and re-tag with updated Package.swift
  run: |
    git config user.name  "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add Package.swift
    git commit -m "chore: set Cmlx binary target for ${{ github.ref_name }}"
    git tag -f "${{ github.ref_name }}"
    git push origin "${{ github.ref_name }}" --force-with-lease
    git push origin --tags --force-with-lease

Plus a small Python script (tools/update-binary-target.py) that rewrites the Cmlx source target block to a .binaryTarget(...) in Package.swift.

Why main stays as source

main keeps Cmlx as a source target — the xcframework build workflow needs to compile from source. The tag-rewrite only affects the release commit, which is what SwiftPM resolves when consumers pin to a version.

Questions before opening a PR

1. Is this approach acceptable? (tag-rewrite pattern is used by other packages but I want to confirm you're comfortable with it)
2. Any preference on whether all 4 xcframework targets get binary targets, or just Cmlx first?
3. Your release.yml uses [self-hosted, macos] — the swift package compute-checksum step should work fine there, but let me know if there are any toolchain constraints.

Happy to open a PR with the full implementation once there's a green light.

[davidkoski]

It is an interesting idea for sure. Personally, I do like the fact that everything builds from source -- if you want to see what is building it is all there. The xcframeworks were added for people who want to consume binaries.

Although the sha256 isn't computed it does show up in the Releases page:

so anybody should be able to consume these, though how to do so may be tricky. For example, mlx-swift-lm references mlx-swift. Your proposal would pick it up directly (nice!).

It would be great if we could use something like a trait to switch between source and prebuilt. Traits can control what gets linked but they can't affect which dependencies are pulled. I can't see any other way to do this than what you suggested.

The downsides are:

• it forces people to use prebuilt binaries even if they don't want them or can't use them (policy)
• I am not sure how it affects the Linux builds (still early for them, but this complicates it)
• an xcframework is not the same thing as a swiftpm library (one isn't necessarily better than the other, but they are different)

I don't think we should do this given the current state of tooling, but I agree with the sentiment -- it would be nice to figure out how to make this work.

[sam-fakhreddine]

Thanks for the detailed response — the tooling constraints make sense.

While waiting for traits or a better mechanism, here's the workaround we landed on for projects that want to opt in locally without waiting for upstream changes:

Local path package override

1. Build the xcframework once (or download it from your Releases page — the checksums are visible there):

   curl -fsSL https://github.com/ml-explore/mlx-swift/releases/download/0.31.3/Cmlx.xcframework.zip -o Cmlx.zip
   unzip Cmlx.zip -d Prebuilts/

2. Create a minimal local override package at Prebuilts/mlx-swift/Package.swift:

   // swift-tools-version: 5.9
   import PackageDescription
   
   let package = Package(
       name: "mlx-swift",
       products: [
           .library(name: "MLX",  targets: ["MLX"]),
           // ... other products
       ],
       targets: [
           .binaryTarget(name: "Cmlx", path: "../Cmlx.xcframework"),
           .target(name: "MLX", dependencies: ["Cmlx"], path: "Sources/MLX"),
           // ... other targets with vendored Swift sources
       ]
   )

3. In your consuming Package.swift, replace the URL dependency with a path:

   // Before:
   .package(url: "https://github.com/ml-explore/mlx-swift", from: "0.31.3"),
   // After:
   .package(path: "Prebuilts/mlx-swift"),

The catch: this only works cleanly for direct dependencies. If you depend on mlx-swift-lm, which in turn depends on mlx-swift, the local path override needs to propagate up the chain — otherwise you get target name conflicts (Cmlx declared twice). For deep transitive deps, you'd need to fork every package in the chain, which defeats the purpose.

For our use case we got DuckDB working this way (it's a direct dep), but MLX remains source-built because it's transitive via mlx-swift-lm.

The traits idea you mentioned does seem like the right long-term solution — it would let package authors expose an opt-in prebuilt variant without forcing it on everyone or requiring consumers to fork the dependency chain.

[davidkoski]

I wonder if making a parallel xcode/xcframework path for mlx-swift-lm would help? Then app developers could consume both of those -- they only get into trouble if there is a third layer.

[davidkoski]

Another thought: Package.swift can examine environment variables and dynamically change dependencies. This isn't easy to manipulate with Xcode, but it is doable from a CI system.