A small Rust library to facilitate adding Resources (metainformation and icons) to Portable Executables (Windows executables and dynamic libraries). Further details: API documentation and published crate.
By default, the metadata is inherited from the package description, but it can also be manually set or overridden in the build script or in the [package.metadata.winresource]
section in Cargo.toml
:
Note: winresource
is a fork of winres which no longer works on Rust 1.61 or higher and has been left unmaintained.
For this crate to work, you need to have the appropriate tools installed. Without these tools, the build process for the Windows target will fail. The prerequisites differ depending on your host operating system and the targeted ABI.
If you are using Rust with the MSVC ABI, you'll need rc.exe
from the Windows SDK. The build script will search for the location of the Windows SDK in the registry.
If you are using Rust with the GNU ABI, you'll need windres.exe
and ar.exe
from MinGW-w64. Note that the location of the MinGW-w64 toolchain has to be in the path environment variable.
If you are cross-compiling on a non-Windows OS, you need to install the mingw-w64
cross-compiler toolchain.
On Debian-based Linux distros like Ubuntu, you can do this with:
sudo apt-get install mingw-w64
On Arch Linux, install the entire mingw-w64 group:
sudo pacman -S mingw-w64
On macOS, you can get the toolchain with:
brew install mingw-w64
First, you will need to add a build script to your crate (build.rs
) by adding it to your crate's Cargo.toml
file:
[package]
#...
build = "build.rs"
[build-dependencies]
winresource = "0.1"
Next, you have to write a build script. A short example is shown below.
// build.rs
extern crate winresource;
fn main() {
if std::env::var("CARGO_CFG_TARGET_OS").unwrap() == "windows" {
let mut res = winresource::WindowsResource::new();
res.set_icon("test.ico");
res.compile().unwrap();
}
}
That's it. The file test.ico
should be located in the same directory as build.rs
. Metainformation (like program version and description) is taken from Cargo.toml
's [package]
section.
Please note: Using #[cfg(target_os = "windows")]
in build.rs
may not work as expected because build.rs
is executed on the host. This means that target_os
is always equal to host_os
when compiling build.rs
. E.g. if we use rustc
on Linux and want to cross-compile binaries that run on Windows, target_os
in build.rs
is "linux"
. However, CARGO_CFG_TARGET_OS
should always be defined and contains the actual target operating system, though it can only be checked at runtime of the build script.
For added convenience, winresource
parses Cargo.toml
for a package.metadata.winresource
section:
[package.metadata.winresource]
OriginalFilename = "PROGRAM.EXE"
LegalCopyright = "Copyright © 2016"
#...
This section may contain arbitrary string key-value pairs, to be included in the version info section of the executable/library file.
The following keys have special meanings and will be shown in the file properties of the Windows Explorer:
FileDescription
, ProductName
, ProductVersion
, OriginalFilename
and LegalCopyright
See MSDN for more details on the version info section of executables/libraries.
The original author and maintainers use this crate for their personal projects and although is has been tested in that context, we have no idea if the behaviour is the same everywhere.
To be brief, we are very much reliant on your bug reports and feature suggestions to make this crate better.