# 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](https://www.rust-lang.org/), preferably installed via [`rustup`](https://rustup.rs/) (tested with 1.71)
* [Xcode](https://developer.apple.com/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
```sh
cargo install cargo-xcode
```
## Usage
> TL;DR: Run `cargo xcode` and use the generated project files as **sub**projects 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 **sub**projects 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:
```sh
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](https://github.com/sindresorhus/Gifski/).
### 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](https://lib.rs/crates/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 › <samp>Build Phases</samp> tab › <samp>Compile Sources</samp> phase, edit the <samp>Compiler Flags</samp> column of `Cargo.toml`, and append `-Zbuild-std` there.