Binlogo/cargo-xcframework

Cargo plugin for building XCFrameworks

XCFramework

• XCFramework
• Features
• Getting started
• Configuration

⚠️ WARNING

This is work in progress and is not ready for use

A Cargo plugin and library for building Apple XCFrameworks from Rust libraries

• Features
• Getting started
• Configuration

Features

• Easily create Apple XCFrameworks from Rust libraries
• Integrates into the cargo build process. Run it with cargo xcframework with parameters that are almost the same as for cargo build
• Configuration in Cargo.toml section [package.metadata.xcframework]
• Currently supports building for iOS, macOS and simulators. If there is interest, watchOS and tvOS can be added as well.

Getting started

Install:

cargo install xcframework

If you for any reason needs the bleeding-edge super fresh version:

cargo install --git https://github.com/human-solutions/xcframework

Help:

cargo xcframework --help

For setting up your project, have a look at the examples

Configuration

The built XCFramework is named after the top-level module name declared in the module.modulemap file in the include-dir directory.

A typical such file looks like this:

// The XCFramework will be named 'MyModuleName.xcframework'
module MyModuleName {
    // a header file in the same directory as the modulemap
    header "mylib.h"
    export *
}

Cargo.toml parameters in section [package.metadata.xcframework].

# Directory where the `module.modulemap` file and the headers are located.
#
# Note that the modulemap needs to be present in the directory because the
# module name declared in it is used for the framework name.
include-dir = "my-bin-name"

# The library type. Can be staticlib or cdylib
#
# Optional. This is only necessary if both library types are configured in the
# [lib] sections `crate-type` parameter. Overridden by the command line parameter `--lib-type`.
lib-type = "staticlib"

# Whether to zip the resulting XCFramework
#
# Optional. Defaults to true.
zip = true

# Enable Cargo to compile the standard library itself as part of a crate graph compilation.
# If enabled either run with `cargo +nightly xcframework`, set the default toolchain to nightly
# or set run `rustup override set nightly` in the project directory.
#
# Optional. Defaults to false. Requires nightly. Only useful for staticlib's, ignored for cdylibs.
build-std = false

# Whether to build for macOS
#
# Optional. Defaults to false.
macOS = false

# The macOS target triples
#
# Optional. Defaults to ["x86_64-apple-darwin", "aarch64-apple-darwin"].
macOS-targets = ["x86_64-apple-darwin", "aarch64-apple-darwin"]

# Whether to build the simulator targets. Not used when building for macOS.
#
# Optional. Defaults to false
simulators = false

# Whether to build for iOS
#
# Optional. Defaults to false.
iOS = false

# The iOS target triples
#
# Optional. Defaults to ["aarch64-apple-ios"].
iOS-targets = ["aarch64-apple-ios"]


# The iOS simulator target triples. Only used if `simulators` and `iOS` are true.
#
# Optional. Defaults to ["aarch64-apple-ios-sim", "x86_64-apple-ios"]
iOS-simulator-targets = ["aarch64-apple-ios-sim", "x86_64-apple-ios"]

# If there is interest, watchOS and tvOS can be added as well.

The iOS and macOS versions targeted can be set with the environment variables: MACOSX_DEPLOYMENT_TARGET and IPHONEOS_DEPLOYMENT_TARGET. See apple_base.rs for the default values.