cargo-wix: 创建Windows安装程序的cargo子命令

一个用于 Cargo 的子命令，它使用 Wix Toolset 从 Rust 二进制项目的发布构建中构建Windows安装程序（msi）。它还支持使用可在 Windows 10 SDK 中找到的 SignTool 应用程序对Windows安装程序进行签名，如果可用。

快速开始

启动命令提示符（cmd.exe），然后执行以下命令

C:\>cargo install cargo-wix
C:\>cd Path\To\Project
C:\Path\To\Project\>cargo wix init
C:\Path\To\Project\>cargo wix

项目的Windows安装程序（msi）将在 C:\Path\To\Project\target\wix 文件夹中。有关更高级的用法、配置和自定义，请参阅 文档。

安装

cargo-wix项目可以在支持Rust编程语言的任何平台上安装，但Wix Toolset仅适用于Windows；因此，此项目仅在安装在Windows机器上时才有用。在进行下一步之前，请确保已安装以下依赖项。注意，安装Rust编程语言时，Cargo会自动安装。建议使用 stable-x86_64-pc-windows-msvc 工具链。

• Cargo
• Rust v1.64.0 或更高版本
• WiX Toolset
• Windows 10 SDK（可选），用于对安装程序进行签名

在安装和配置依赖项后，执行以下命令安装 cargo-wix 子命令

C:\> cargo install cargo-wix

用法

启动命令提示符，例如 cmd.exe，与 开发者提示符 一起安装的 VC 编译工具（推荐），或 git bash，然后导航到项目的根目录。运行子命令

C:\Path\to\Project> cargo wix init

这将在项目的根目录中创建 wix 文件夹（与 Cargo.toml 文件并列），然后从子命令中嵌入的 WiX 源（wxs）创建 wix\main.wxs 文件。生成的 wix\main.wxs 文件可以不经修改使用以下命令创建项目的安装程序

C:\Path\to\Project> cargo wix

cargo wix 子命令不带任何参数会在项目根目录相对位置查找 wix\main.wxs 文件。它将编译 wix\main.wxs 文件，然后将目标文件（target\wix\build\main.wixobj）链接以创建 Windows 安装程序（msi）。安装程序将位于 target\wix 文件夹。安装程序编译和链接过程的所有工件都放在 target\wix 文件夹中。在 wix\main.wxs 文件中的路径应该是相对于项目根目录的，即与 Cargo.toml 清单文件相同的路径。

可以通过指定到它的路径作为子命令的参数来使用与 wix\main.wxs 文件不同的 WiX 源（wxs）文件

C:\Path\to\Project> cargo wix Path\to\WiX\Source\File.wxs

您也可以通过指定 --install 参数在创建后自动运行安装程序

C:\Path\to\Project> cargo wix --install

可以使用打印其中一个嵌入模板到 stdout 的 print <template> 子命令来创建 main.wxs 文件。一个专门为此子命令设计的 WXS 模板 文件在安装期间嵌入到 cargo-wix 二进制文件中。使用以下命令创建 WiX 源文件，并使用它通过此子命令创建安装程序。

C:\Path\to\Project> cargo wix print wxs > example.wxs
C:\Path\to\Project> cargo wix example.wxs

可以使用文本编辑器自定义 WiX 源文件，但应避免修改 XML 预处理器变量，以确保 cargo wix 命令正常工作。

要将安装程序（msi）作为构建过程的一部分进行签名，请确保 signtool 命令在 PATH 系统环境变量中可用，或使用与 Windows 10 SDK 一起安装的 开发者提示符，并使用以下方式使用 sign 子子命令

C:\Path\to\Project> cargo wix sign

使用 -h,--help 标志显示有关附加选项和功能的信息。

C:\Path\to\Project> cargo wix -h

测试

存在一组环境变量，可以帮助调试失败的测试。环境变量 CARGO_WIX_TEST_PERSIST 可以设置为在集成测试期间保留创建的临时目录。这允许开发者检查临时目录的内容，以便更好地理解测试执行了什么。环境变量 CARGO_WIX_TEST_PERSIST 接受任何值。取消设置环境变量将在每次测试后删除临时目录。环境变量 CARGO_WIX_TEST_LOG 在运行集成测试时设置日志级别。它接受介于0到5之间的整数值，其中0关闭日志，5显示所有日志语句（ERROR、WARN、INFO、DEBUG和TRACE）。在测试期间不会捕获日志语句，因此仅在独立运行集成测试时使用此环境变量，以防止终端/控制台被语句淹没。最后，环境变量 CARGO_WIX_TEST_NO_CAPTURE 接受任何值，并在运行集成测试时显示WiX Toolset编译器（candle.exe）和链接器（light.exe）的输出。与 CARGO_WIX_TEST_LOG 环境变量类似，此变量也应在独立使用时避免终端/控制台被WiX Toolset命令的输出淹没。默认情况下，输出由 test 而不是cargo的测试框架捕获；因此，cargo test -- --nocapture 命令不会产生影响。以下是设置和取消设置所有环境变量以运行特定测试的示例

C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_PERSIST=1
C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_LOG=5
C:\Path\to\Cargo\Wix> set CARGO_WIX_TEST_NO_CAPTURE=1
C:\Path\to\Cargo\Wix> cargo test <TEST NAME>
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_NO_CAPTURE="
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_LOG="
C:\Path\to\Cargo\Wix> set "CARGO_WIX_TEST_PERSIST="

其中 <TEST NAME> 被集成测试的名称替换。最后三行/命令是可选的，取消设置三个环境变量以避免额外的测试也持久化、记录和将输出输出到终端/控制台。注意，-- --nocapture 选项 不是 需要显示日志语句或WiX Toolset编译器（candle.exe）和链接器（light.exe）的输出。以下是相同示例的 Powershell

PS C:\Path\to\Cargo\Wix> $env:CARGO_WIX_TEST_PERSIST=1; $env:CARGO_WIX_TEST_LOG=5; $env:CARGO_WIX_TEST_NO_CAPTURE=1; 
PS C:\Path\to\Cargo\Wix> cargo test <TEST NAME>
PS C:\Path\to\Cargo\Wix> Remove-Item Env:\CARGO_WIX_TEST_PERSIST; Remove-Item Env:\CARGO_WIX_TEST_LOG; Remove-Item Env:\CARGO_WIX_TEST_NO_CAPTURE

许可证

cargo-wix 项目受 MIT 许可证 或 Apache 2.0 许可证 许可。有关许可和版权的更多信息，请参阅 LICENSE-MIT 或 LICENSE-APACHE 文件。