cargo-xcode 1.7.0

Make Xcode project files from Cargo projects
Documentation

Rust libaries as Xcode projects

Generates Xcode project files from Cargo.toml allowing use of Rust libraries in Mac and iOS applications without leaving Xcode.

Features

It's better than just launching cargo build from a script:

  • Configures Cargo to follow Xcode's Debug and Release configurations.
  • Supports Universal Binaries and cross-compilation.
  • Configures Cargo to use Xcode's standard build and temporary folders.
  • Makes Xcode aware of dependencies and rebuild Rust code only when needed.
  • Supports Cargo workspaces and multiple targets per crate.

Requirements

  • Rust, preferably installed via rustup (tested with 1.71)
  • Xcode (tested with 15.1)
  • Bash

The generated Xcode project files are self-contained, and work without cargo-xcode dependency. You can distribute the .xcodeproj files and use them with just Rust and Xcode.

Installation

cargo install cargo-xcode

Usage

TL;DR: Run cargo xcode and use the generated project files as subprojects in other Xcode projects.

This tool will generate Rust-aware project files for all binaries and C-compatible libraries in a Cargo workspace. Instead of modifying your Mac/iOS app's project file directly, take advantage of Xcode's ability to nest and combine multiple xcodeproj files together. The generated Xcode projects are not meant for standalone use. They are supposed to be used only as subprojects of other regular Mac Xcode projects.

  1. If you don't have an existing Cocoa app project yet, create one in Xcode (a normal ObjC or Swift app). This will be called your "parent project" in later steps.

  2. If your Rust project is a library, edit Cargo.toml and add crate-type = ["lib", "staticlib"] in the [lib] section. Only libraries of type "staticlib" or "cdylib" are suitable, and staticlib is much easier to work with (but keep the "lib" crate type for compatibility with other Cargo libraries and tests).

  3. In the same directory as Cargo.toml (or root of a Cargo workspace) run:

    cargo xcode

    This will generate <rust-project-name>.xcodeproj. Don't open it yet!

  4. Open your parent project (from step 1) in Xcode and add the <rust-crate-name>.xcodeproj to the workspace (drag the file into the parent project's sidebar). You should see the dragged Rust-Xcode project embedded in your parent project. If the new Rust-Xcode project appears empty in the sidebar, close all Xcode windows and re-open only the parent project.

  5. In your parent project's app's Build Phases, in Link Binary With Libraries phase, you can now add the Rust libraries from the workspace.

Real-world example of such usage.

Advanced usage

You can set features via CARGO_XCODE_FEATURES target's Build Setting in Xcode. It maps to --features flag.

If you're building .dylib for including in an application bundle, make sure to set DYLIB_INSTALL_NAME_BASE in Xcode's settings to @executable_path/../Frameworks/ or whatever location you're going to copy the library to.

Limitations

Rust binaries are exported as command-line tools. This tool intentionally does not make app bundles. If you want to build a Mac GUI app, create one as ObjC or Swift project in Xcode and call Rust code via a Rust static library, or use Tauri.

Trier DIY platforms

AppleTV and Mac Catalyst targets don't have pre-built rustup targets. You will need to:

  1. use nightly (set RUSTUP_TOOLCHAIN = nightly)
  2. and build std: In a target › Build Phases tab › Compile Sources phase, edit the Compiler Flags column of Cargo.toml, and append -Zbuild-std there.