Crate embed_resource[−][src]

A Cargo build script library to handle compilation and inclusion of Windows resources in the most resilient fashion imaginable

Background

Including Windows resources seems very easy at first, despite the build scripts’ abhorrent documentation: compile with windres, then make linkable with ar.

I was very happy with that solution until it was brought to my attention, that MSVC uses something different, and now either windres-ar combo or RC.EXE would be used, which was OK.

Later it transpired, that MSVC is even more incompatible with everything else by way of not having RC.EXE in $PATH (because it would only be reasonable to do so), so another MSVC artisan made the script find the most likely places for RC.EXE to be, and the script grew yet again, now standing at 100 lines and 3.2 kB.

After copying the build script in its entirety and realising how error-prone that was, then being nudged by Shepmaster to extract it to a crate, here we are.

Usage

For the purposes of the demonstration we will assume that the resource file’s name is “checksums.rc”, but it can be any name relative to the crate root.

In Cargo.toml:

# The general section with crate name, license, etc.
build = "build.rs"

[build-dependencies]
embed-resource = "1.6"

In build.rs:

extern crate embed_resource;

fn main() {
    embed_resource::compile("checksums.rc");
}

Cross-compilation

It is possible to embed resources in Windows executables built on non-Windows hosts. There are two ways to do this:

When targetting *-pc-windows-gnu, *-w64-mingw32-windres is attempted by default, for *-pc-windows-msvc it’s llvm-rc, this can be overriden by setting RC_$TARGET, RC_${TARGET//-/_}, or RC environment variables.

When compiling with LLVM-RC, an external C compiler is used to preprocess the resource, preloaded with configuration from cc.

Credit

In chronological order:

@liigo – persistency in pestering me and investigating problems where I have failed

@mzji – MSVC lab rat

@TheCatPlusPlus – knowledge and providing first iteration of manifest-embedding code

@azyobuzin – providing code for finding places where RC.EXE could hide

@retep998 – fixing MSVC support

@SonnyX – Windows cross-compilation support and testing

@MSxDOS – finding and supplying RC.EXE its esoteric header include paths

@roblabla – cross-compilation to Windows MSVC via LLVM-RC

Special thanks

To all who support further development on Patreon, in particular:

Functions

compile

Compile the Windows resource file and update the cargo search path if we’re on Windows.

find_windows_sdk_tool

Find MSVC build tools other than the compiler and linker