diff --git a/src/main.rs b/src/main.rs index 4a1fa63..b6a1978 100644 --- a/src/main.rs +++ b/src/main.rs @@ -25,6 +25,7 @@ //! ## Table of Contents //! //! - [Quick Start](#quick-start) +//! - [C Runtime](#c-runtime) //! - [Examples](#examples) //! - [Features](#features) //! - [Signing](#signing) @@ -73,6 +74,41 @@ //! installation destination is `C:\Program Files\`, where //! `` is replaced with the name of the project. //! +//! ## C Runtime +//! +//! If using the `x86_64-pc-windows-msvc` or the `i686-pc-windows-msvc` +//! toolchain, then an appropriate C RunTime (CRT) must be available on the host +//! system _or_ the CRT must be statically compiled with the Rust binary +//! (executable). By default, the CRT is dynamically linked to a Rust binary. This +//! may cause issues and errors when running the Rust binary immediately after +//! installation on a clean Windows installation, i.e. the CRT has not already been +//! installed. If the Rust compiler is installed and an `-msvc` toolchain is +//! available, then the Rust binary will execute after installation without an +//! issue. +//! +//! **Note**, the Rust programming language does _not_ need to be installed +//! to run an executable built using Cargo and Rust. Only a Microsoft provided CRT +//! needs to be installed. These are often referred to as "redistributables". Rust +//! with either of the `-msvc` toolchains currently dynamically links against the +//! `vcruntime140.dll`, which is part of the Visual C++ 2015 redistributable and +//! freely provided by Microsoft. +//! +//! For developers using the `cargo-wix` subcommand to create an installer, this +//! dependency on the present of an appropriate C runtime can lead to a sub-optimal +//! user experience. There are three options: (i) statically link the C runtime +//! within the Rust binary (recommended), (ii) add the Visual C++ redistributable to +//! the installer via the [Merge module] method for the WiX Toolset, or (iii) +//! provide the user with instructions for downloading and installing the CRT +//! _before_ running the executable. The currently recommended option is to +//! [statically link the CRT] when building the Rust binary. Rust v1.19 or newer is +//! required, and the solution ultimately becomes adding the `-C target-feature=+crt-static` +//! option to the invocation of the Rust compiler (rustc). There are a variety +//! of methods for adding the option to the invocation, including but not +//! limited to adding a configuration directive to the pacakge's manifest, using the +//! `RUSTFLAGS` environment variable, or adding to the user's Cargo +//! configuration. Please see the Rust compiler documentation on static linking +//! for more information and details. +//! //! ## Examples //! //! All of the following examples use the native Command Prompt (cmd.exe) for @@ -1085,6 +1121,7 @@ //! [LibreOffice]: https://www.libreoffice.org/ //! [`license`]: https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata //! [`license-file`]: https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata +//! [Merge module]: https://wixtoolset.org/documentation/manual/v3/howtos/redistributables_and_install_checks/install_vcredist.html //! [Microsoft Office]: https://products.office.com/en-us/home //! [Microsoft Notepad]: https://en.wikipedia.org/wiki/Microsoft_Notepad //! [PowerShell]: https://github.com/PowerShell/PowerShell @@ -1093,6 +1130,7 @@ //! [Rust]: https://www.rust-lang.org //! [sidecar]: https://en.wikipedia.org/wiki/Sidecar_file //! [SignTool]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa387764(v=vs.85).aspx +//! [statically link the CRT]: https://doc.rust-lang.org/reference/linkage.html#static-and-dynamic-c-runtimes //! [`std::process::Command`]: https://doc.rust-lang.org/std/process/struct.Command.html //! [`std::process::Command::status`]: https://doc.rust-lang.org/std/process/struct.Command.html#method.status //! [TOML array]: https://github.com/toml-lang/toml#user-content-array