messense/cargo-xwin repository overview

⁠cargo-xwin

formerly cargo-xwinbuild

Cross compile Cargo project to Windows msvc target with ease using xwin⁠ or windows-msvc-sysroot⁠.

By using this software you are consented to accept the license at https://go.microsoft.com/fwlink/?LinkId=2086102⁠

⁠Prerequisite

1. Install clang⁠ (On macOS run brew install llvm and you're good to go).
2. For assembly dependencies, install llvm-tools component via rustup component add llvm-tools or install llvm⁠.

A full LLVM installation is recommended to avoid possible issues.

⁠Installation

cargo install --locked cargo-xwin

You can also install it using pip:

pip install cargo-xwin

We also provide a Docker image⁠ which has wine pre-installed in addition to cargo-xwin and Rust, for example to build for x86_64 Windows:

docker run --rm -it -v $(pwd):/io -w /io messense/cargo-xwin \
  cargo xwin build --release --target x86_64-pc-windows-msvc

⁠Usage

1. Install Rust Windows msvc target via rustup, for example, rustup target add x86_64-pc-windows-msvc
2. Run cargo xwin build, for example, cargo xwin build --target x86_64-pc-windows-msvc

⁠Pre-caching for offline builds

You can pre-download and cache the MSVC CRT and Windows SDK for offline builds:

# Cache Microsoft CRT and Windows SDK (for clang-cl backend)
cargo xwin cache xwin

# Cache windows-msvc-sysroot (for clang backend)
cargo xwin cache windows-msvc-sysroot

This is useful for Docker images or CI/CD pipelines where you want to cache dependencies ahead of time.

The clang-cl backend supports cache paths containing spaces. If you configure target.<triple>.rustflags in Cargo configuration, use an array (for example, rustflags = ["-C", "target-feature=+crt-static"]): Cargo cannot merge its space-preserving array override with string-valued rustflags. Native compiler flags use shell quoting through CC_SHELL_ESCAPED_FLAGS=1.

cargo xwin env cannot export flags that require Cargo --config arguments, including library paths containing spaces. Use cargo xwin build, check, or another build command directly in that case.

⁠Run tests with wine

With wine installed, you can run tests with the cargo xwin test command, for example, cargo xwin test --target x86_64-pc-windows-msvc

⁠Running Windows executables in WSL (without wine)

If you want to run Windows executables directly in WSL (without using wine), you can set the runner environment variable as follows:

CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_RUNNER="/usr/bin/env" cargo xwin run --target x86_64-pc-windows-msvc

⁠Customization

The Microsoft CRT and Windows SDK can be customized using the following environment variables or CLI options.

⁠CMake Support

Some Rust crates use the cmake⁠ crate to build C/C++ dependencies, cargo-xwin will generate a CMake toolchain⁠ file automatically to make cross compilation work out of the box.

ninja⁠ is required to enable CMake support.

⁠License

This work is released under the MIT license. A copy of the license is provided in the LICENSE⁠ file.