Crate embed_resource

Source
Expand description

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 = "3.0"

In build.rs:

extern crate embed_resource;

fn main() {
    embed_resource::compile("checksums.rc", embed_resource::NONE).manifest_optional().unwrap();
    // or
    embed_resource::compile("checksums.rc", &["VERSION=000901"]).manifest_required().unwrap();
}

Use .manifest_optional().unwrap() if the manifest is cosmetic (like an icon).
Use .manifest_required().unwrap() if the manifest is required (security, entry point, &c.).

§Errata

If no cargo:rerun-if-changed annotations are generated, Cargo scans the entire build root by default. Because the first step in building a manifest is an unspecified C preprocessor step with-out the ability to generate the equivalent of cc -MD, we do not output said annotation.

If scanning is prohibitively expensive, or you have something else that generates the annotations, you may want to spec the full non-system dependency list for your manifest manually, so:

println!("cargo:rerun-if-changed=app-name-manifest.rc");
embed_resource::compile("app-name-manifest.rc", embed_resource::NONE);

for the above example (cf, #41).

§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.

§Migration

§2.x

Add embed_resource::NONE as the last argument to embed_resource::compile() and embed_resource::compile_for().

§3.x

Add .manifest_optional().unwrap() or .manifest_required().unwrap() to all compile() and compile_for*() calls. CompilationResult is #[must_use] so should be highlighted automatically.

Embed-resource <3.x always behaves like .manifest_optional().unwrap().

§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:

  • ThePhD
  • Embark Studios
  • Lars Strojny
  • EvModder

Enums§

Constants§

  • NONE
    Empty slice, properly-typed for compile() and compile_for*()’s macro list.

Functions§