The goal of the cargo-wix project and
cargo wix subcommand is to make it easy to create
a Windows installer (msi) for any Rust project.
Ensure the WiX Toolset is installed and the
C:\Program Files\WiX Toolset\bin folder has been added to the PATH system environment variable. Then start
a commmand prompt (cmd.exe) and execute the following commands:
C:\>cargo install cargo-wix C:\>cd Path\To\Project C:\Path\To\Project\>cargo wix --init C:\Path\To\Project\>cargo wix
The Windows installer (msi) will be in the
The cargo-wix project is primarily implemented as a cargo subcommand, but the core
functionality is provided in a library (crate). Documentation for the binary and Command Line
Interface (CLI) are provided with the
cargo wix --help command, but documentation is provided
here for the concepts and core functionality that govern the subcommand.
The cargo-wix binary, and related
cargo wix subcommand, use the WiX Toolset and
application available in the Windows 10
SDK. These are
obviously Windows-only applications, so while the crate and binary can be built on any platform
supported by the Rust programming language, the
subcommand is only really useful on a Windows machine.
The WiX Toolset provides a compiler (
candle.exe) and linker (
light.exe). These can be found
bin directory of the installation location for the WiX Toolset. This subcommand uses
these two applications with the
std::process::Command module to create an installer.
Generally, it is best to add the WiX Toolset
bin folder to the PATH system environment
variable, but a WIX_PATH environment variable or the
-B,--bin-path option can be used to
specify a path (relative or absolute) to the WiX Toolset
bin folder. The order of precedence
-B,--bin-path option, WIX_PATH environment variable, and then the PATH
system environment variable.
The Windows SDK provides a signer (
signtool) application for signing installers. The
application is installed in the
bin folder of the Windows SDK installation. The location of
bin folder varies depending on the version. It is recommended to use the Developer Prompt
to ensure the
signtool application is available; however, it is possible to specify the path
to the Windows SDK
bin folder using the
-S,--sign-path option at the command line. Since
signing is optional.
The WiX Toolset requires a WiX Source (wxs) file, which is an XML file. A template is provided with this subcommand that attempts to meet the majority of use cases for developers, so extensive knowledge of the WiX Toolset and Windows installer technologies is not required (but always recommended). Modification of the template is encouraged, but please consult the WiX Toolset's extensive documentation and tutorials for information about writing, customizing, and using wxs files. The documentation here is only for this subcommand.
The WXS template is
embedded in the binary installation of the subcommand and it can be printed to stdout using the
cargo wix --print-template wxs command from the command prompt (cmd.exe). Note, each time the
cargo wix --print-template wxs command is invoked, new GUIDs are generated for fields that
require them. Thus, a developer does not need to worry about generating GUIDs and can begin
using the template immediately with this subcommand or the WiX Toolset's
In addition to the WXS template, there are several license templates which are used to generate
an End User License Agreement (EULA) during the
cargo wix --init command. Depending on the
license ID(s) in the
license field for a package's manifest (Cargo.toml), a license file
in the Rich Text Format (RTF) is generated from a template and placed in the
wix folder. This
RTF file is then displayed in the license dialog of the installer. See the help information on
--print-template option for information about supported licenses. If the
is not used or the license ID is not supported, then the EULA will not be automatically created
during initialization and it will have to be created manually with a text editor or other
During creation of the installer, the
cargo wix subcommand will look for a LICENSE file in
the root of the project. If the file exists, then it is used as the source file for the
License.txt file that is placed alongside the
bin folder during installation of the project
with the Windows installer (msi). If a LICENSE file does not exist, then the
option should be used to specify a path to a file that can be used.
If a custom license is used, then the
license-file field should be used with the package's
manifest. The path specified for the
license-file field is used to create a "sidecar" license
file that is installed alongside the
bin folder during installation. Basically, if a custom
license is used, everything should be manually setup and modified.
Generally, any value that is obtained from the package's manifest (Cargo.toml) can be
overridden at the command line with an appropriate option. For example, the manufacturer, which
is displayed as the "Publisher" in the Add/Remove Programs (ARP) control panel is obtained from
the first author listed in the
authors field of a package's manifest, but it can be
overridden using the
-m,--manufacturer option. The default in most cases is to use a value
from a field in the package's manifest.
cargo wix subcommand uses the package name for the product name. The default install
location is at
C:\Program Files\[Product Name], where
[Product Name] is replaced with the
product name determined from the package name. This can be overridden with the
-p,--product-name option. The binary name, which is the
name field for the
section, is used for the executable file name, i.e. "name.exe". This can also be overridden
-b,--bin-name option. The package description is used in multiple places for the
installer, including the text that appears in the blue UAC dialog when using a signed
installer. This can be overridden using the
An unmodified WXS file from the embedded template will create an installer that installs the
executable file in a
bin folder within the installation directory selected by the end-user
during installation. It will add a
License.txt file to the same folder as the
LICENSE file, and it will add the
bin folder to the PATH system environment variable
so that the executable can be called from anywhere with a commmand prompt. Most of these
behaviors can be adjusted during the installation process of the Windows installer.
A builder for running the subcommand.
The error type for cargo-wix-related operations and associated traits.
The different values for the
The different templates that can be printed using the
The aliases for the URLs to different Microsoft Authenticode timestamp servers.