cargo-xwin Docker镜像文档

镜像概述和主要用途

cargo-xwin（前身为cargo-xwinbuild）是一款简化Cargo项目交叉编译到Windows msvc目标的工具，基于xwin或windows-msvc-sysroot实现。其Docker镜像messense/cargo-xwin预安装了wine、cargo-xwin及Rust环境，无需手动配置依赖，可直接用于构建Windows平台可执行文件，特别适合非Windows环境（如Linux、macOS）下的跨平台开发。

注意：使用本软件即表示同意接受Microsoft许可协议。

核心功能和特性

• 简化交叉编译：自动处理Windows SDK和CRT依赖，无需手动配置msvc环境
• 多架构支持：默认支持x86_64、aarch64等Windows架构，可通过参数扩展
• 测试集成：结合wine支持直接运行Windows测试用例（cargo xwin test）
• 自定义配置：支持通过环境变量或CLI选项调整CRT版本、SDK版本及编译器
• CMake兼容：自动生成CMake工具链文件，适配依赖CMake的C/C++组件
• 完整环境：Docker镜像包含Rust、wine及LLVM工具链，开箱即用

使用场景和适用范围

• 非Windows系统（Linux/macOS）下开发Windows Rust应用的开发者
• 需要自动化构建Windows目标程序的CI/CD流程
• 跨平台Rust项目的测试与验证（通过wine运行测试）
• 对Windows SDK版本或CRT有特定需求的定制化构建

详细使用方法和配置说明

获取镜像

docker pull messense/cargo-xwin

基本构建示例

在项目目录中执行以下命令，构建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

参数说明：

• -v $(pwd):/io：将当前目录挂载到容器内/io路径
• -w /io：设置工作目录为/io（项目根目录）
• --release：构建发布版本
• --target：指定目标架构（如x86_64-pc-windows-msvc、aarch64-pc-windows-msvc）

运行测试

通过wine在容器内运行Windows测试用例：

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

在WSL中运行可执行文件（无需wine）

若在WSL环境使用该镜像，可直接运行Windows可执行文件：

docker run --rm -it -v $(pwd):/io -w /io messense/cargo-xwin \
  sh -c "CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_RUNNER='/usr/bin/env' cargo xwin run --target x86_64-pc-windows-msvc"

自定义配置选项

可通过环境变量或CLI参数调整构建配置，常见选项如下：

示例：指定使用clang编译器构建aarch64架构

docker run --rm -it -v $(pwd):/io -w /io messense/cargo-xwin \
  cargo xwin build --target aarch64-pc-windows-msvc --cross-compiler clang --xwin-arch aarch64

注意事项

1. 首次运行会自动下载Windows SDK和CRT，可能需要较长时间（依赖网络环境）
2. 构建大型项目建议增加容器内存限制（如--memory=4g）
3. CMake支持需确保项目中CMakeLists.txt正确配置交叉编译选项