cargo-xwin 0.21.4

Cross compile Cargo project to Windows MSVC target with ease
Documentation

cargo-xwin

formerly cargo-xwinbuild

CI Crates.io docs.rs PyPI Docker Image

🚀 Help me to become a full-time open-source developer by sponsoring me on GitHub

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.

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.

Environment Variable CLI option Description
XWIN_CROSS_COMPILER --cross-compiler The cross compiler to use, defaults to clang-cl, possible values: clang-cl, clang
XWIN_ARCH --xwin-arch The architectures to include, defaults to x86_64,aarch64, possible values: x86, x86_64, aarch, aarch64
XWIN_VARIANT --xwin-variant The variants to include, defaults to desktop, possible values: desktop, onecore, spectre
XWIN_VERSION --xwin-version The version to retrieve, defaults to 17, can either be a major version of 15, 16, or 17, or a <major>.<minor> version
XWIN_SDK_VERSION --xwin-sdk-version The SDK version to retrieve, defaults to the latest version
XWIN_CRT_VERSION --xwin-crt-version The CRT version to retrieve, defaults to the latest version
XWIN_INCLUDE_ATL --xwin-include-atl Whether to include the Active Template Library (ATL) in the installation
XWIN_CACHE_DIR --xwin-cache-dir xwin cache directory to put CRT and SDK files
XWIN_INCLUDE_DEBUG_LIBS --xwin-include-debug-libs Whether or not to include debug libs in installation (default false).
XWIN_INCLUDE_DEBUG_SYMBOLS --xwin-include-debug-symbols Whether or not to include debug symbols (PDBs) in installation (default false).
XWIN_HTTP_RETRIES --xwin-http-retries Number of times to retry HTTP requests when downloading (default 3).

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.