repository·main·Indexed 43 days ago
https://github.com/antoniusnaumann/cargo-swiftA Cargo plugin for building Swift Packages from Rust code using Mozilla's UniFFI. It automates the bridging process, XCFramework creation, and Swift Package Manager structure for iOS and macOS applications. Requires macOS and specific version matching between cargo-swift and uniffi-rs (e.g., cargo-swift 0.11.1 for UniFFI 0.31.1).
When providing configuration values, cargo-swift resolves conflicts using the following order of precedence (highest to lowest):
--platforms macos ios)[package.metadata.swiftpackage] within Cargo.toml[workspace.metadata.swiftpackage] within the workspace Cargo.tomlTo package an existing Rust library as a Swift Package (compatible with Swift Package Manager for iOS and macOS apps), run cargo swift package.
This command is interactive and will prompt you for:
If required toolchains for your selected target platforms are missing, cargo-swift will offer to install them automatically.
cargo swift packageInstall the cargo-swift plugin using cargo install.
Important Requirements:
cargo-swift you install matches the version of uniffi-rs used in your Rust project.cargo install cargo-swiftcargo swift init. This sets up the foundation for a library that can be bridged to Swift.cargo swift initTo avoid manual editing, you can use the --save option with the cargo swift package command. This will automatically write the provided configuration values into your crate's Cargo.toml under the [package.metadata.swiftpackage] section.
cargo swift package --save --platforms macos iosSince cargo-swift does not automatically detect your project's UniFFI version, you must manually install the version of cargo-swift that corresponds to your uniffi-rs version. Use the following mapping:
| UniFFI | cargo swift |
|---|---|
| 0.25 | 0.5 |
| 0.26 | 0.6 |
| 0.27 | 0.7 |
| 0.28 | 0.8 |
| 0.29 | 0.9 |
| 0.30 | 0.10 |
| 0.31 | 0.11 |
| 0.31.1 | 0.11.1 |
To install a specific version, use the @ syntax with the -f flag:
cargo install cargo-swift@0.X -f
# Replace 0.X with the desired cargo swift versionWhen creating an XCFramework from static libraries, xcodebuild often produces a lowercase headers directory. To comply with Apple conventions, cargo-swift performs a patching step:
headers directory.Headers directory.ffi_module_name inside Headers/.This is handled automatically by create_xcframework when LibType::Static is used.
Apple platforms use different framework bundle structures. You can check if a platform requires a versioned layout (e.g., Versions/A/... with symlinks) or a flat (shallow) layout using uses_versioned_bundle().
MacOS, MacCatalystWhen building frameworks for Apple platforms, cargo-swift uses ApplePlatform::info_plist() to retrieve the necessary PlatformInfoPlist fragments. These fragments ensure that the generated Info.plist contains the correct keys (like MinimumOSVersion or LSMinimumSystemVersion) and deployment target environment variables required for App Store validation.
Supported platforms include:
IOS, IOSSimulatorMacOS, MacCatalystTvOS, TvOSSimulatorWatchOS, WatchOSSimulatorVisionOS, VisionOSSimulatorWhen generating dynamic libraries, cargo-swift creates .framework bundles using different directory structures based on the target ApplePlatform:
Uses a flat structure where the binary and headers reside at the root:
{framework_name}.framework/
├── Info.plist
├── {framework_name} (the dylib)
├── Headers/
└── Modules/Requires a versioned structure where the actual content is stored in Versions/A/ and the root contains symlinks:
{framework_name}.framework/
├── {framework_name} -> Versions/Current/{framework_name}
├── Headers -> Versions/Current/Headers
├── Modules -> Versions/Current/Modules
├── Resources -> Versions/Current/Resources
└── Versions/
├── A/
│ ├── {framework_name}
│ ├── Headers/
│ ├── Modules/
│ └── Resources/Info.plist
└── Current -> AThe ToolchainTargets struct manages the availability and installation status of Rust targets across both stable and nightly toolchains. It is used to determine if a build requires the nightly toolchain or the -Z build-std flag (used when a target is available in Rust but not installed on either stable or nightly).
Key behaviors:
cargo-swift will use the nightly toolchain for the entire build to ensure compiler version consistency.-Z build-std.cargo-swift is only supported via command line arguments. Most default settings are sufficient for standard use cases. Persistent configuration via a config file is a planned feature (see CONFIG-DRAFT.md in the repository for details).