build(plugins): ship TableProPluginKit as an XCFramework so a driver can live in its own repo

[datlechin]

The other half of #2212.

#2212 lets a plugin signed by someone else load. This lets someone else build one. Both are needed: a third-party driver that loads but can only be compiled from a checkout of this repository is not really third party.

Why every driver lives under Plugins/ today

Not because the plugin system requires it. A plugin has to link TableProPluginKit, and the only way to obtain that framework was to check out this repository and build the app project. So a driver had to live here, be declared in project.yml, get a hand-written arm in build-plugin.yml, and be tagged by a maintainer. That is a packaging limit that grew into an architecture.

scripts/build-pluginkit-xcframework.sh produces a distributable TableProPluginKit.xcframework. A driver author links that from their own Xcode project and needs nothing else from here.

Verified by running it: one macos-arm64_x86_64 slice, lipo -archs reports x86_64 arm64, and .swiftinterface present for both architectures. 1.8 MB zipped.

Two things the script asserts

Both failure modes produce a framework that links today and breaks every consumer on the next release, which is exactly the class of bug CLAUDE.md's ABI section is about.

• No .swiftinterface means BUILD_LIBRARY_FOR_DISTRIBUTION did not take. Without Library Evolution the ABI is not resilient, so a plugin built against it stops loading the moment PluginKit changes. The script fails rather than shipping that.
• lipo -archs must list both architectures. A silently arm64-only framework works on the machine that built it and fails on every Intel Mac.

One design correction worth recording

The first version built arm64 and x86_64 separately and passed both to -create-xcframework. That is wrong and the tool says so:

Both 'macos-x86_64' and 'macos-arm64' represent two equivalent library definitions.

An XCFramework separates slices by platform, never by architecture. Several architectures for one platform belong in one universal binary, so it is a single build with ARCHS="arm64 x86_64" ONLY_ACTIVE_ARCH=NO.

DERIVED_DATA also sits outside the directory the script wipes. Inside it, every run re-resolved every SwiftPM dependency from scratch, which is minutes per build.

Not included

No CI job and no published release yet. Publishing is a one-liner the script prints, and it should happen deliberately alongside a PluginKit version rather than on every merge. The zip is not reproducible (ditto records timestamps), so the checksum to pin is the one from the artifact actually published, which is noted in the script.

Docs: a new "Building outside this repository" section in plugin-development.mdx, including that the XCFramework must be linked as Do Not Embed, since the app supplies PluginKit at runtime and a second copy inside the plugin bundle would conflict.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
TablePro	🟢 Ready	View Preview	Aug 18, 2026, 8:36 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.