49 stable releases
Uses old Rust 2015
3.0.1 | Nov 9, 2024 |
---|---|
2.5.1 | Nov 9, 2024 |
2.5.0 | Sep 26, 2024 |
2.4.3 | Jul 17, 2024 |
0.1.2 |
|
#9 in Development tools
360,774 downloads per month
Used in 200 crates
(56 directly)
48KB
574 lines
rust-embed-resource
A Cargo
build script library to handle compilation and inclusion of Windows resources
in the most resilient fashion imaginable
Documentation
Quickstart
In your build script, assuming the resource file is called checksums.rc
:
extern crate embed_resource;
fn main() {
// Compile and link checksums.rc
embed_resource::compile("checksums.rc", embed_resource::NONE).manifest_optional().unwrap();
// Or, to select a resource file for each binary separately
embed_resource::compile_for("assets/poke-a-mango.rc", &["poke-a-mango", "poke-a-mango-installer"], &["VERSION=\"0.5.0\""]).manifest_required().unwrap();
embed_resource::compile_for("assets/uninstaller.rc", &["unins001"], embed_resource::NONE).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.).
Example: Embedding a Windows Manifest
Courtesy of @jpoles1.
The following steps are used to embed a manifest in your compiled rust .exe file. In this example the manifest will cause admin permissions to be requested for the final executable:
- Add the following to your cargo.toml:
[build-dependencies]
embed-resource = "2.5"
- In your project root directory, add a file named
build.rs
with the following:
extern crate embed_resource;
fn main() {
embed_resource::compile("app-name-manifest.rc", embed_resource::NONE).manifest_optional().unwrap();
}
- In your project root directory, add a file named
app-name-manifest.rc
with the following:
#define RT_MANIFEST 24
1 RT_MANIFEST "app-name.exe.manifest"
- In your project root directory, add a file named
app-name.exe.manifest
with the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
<security>
<requestedPrivileges>
<requestedExecutionLevel level="requireAdministrator" uiAccess="false"/>
</requestedPrivileges>
</security>
</trustInfo>
</assembly>
- Build your project!
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).manifest_optional().unwrap();
for the above example (cf. #41).
Old releases with backports
v1.6-stable
continues after 1.6.6 broke library-only crates, then 1.7.0 introduced a new interface. 1.6.6 was yanked, 1.6.7 fixed this.
v2.5-stable
continues after it turned out that builds have been universally broken on Win32 below \?\\
paths. 3.0.1 and 2.5.1 (and 1.6.14) fixed this.
These both receive backports of all fixes that affect them. You should still probably update.
The default branch is stable, and currently has 3.x.
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 embed_resource::compile()
and embed_resource::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
Dependencies
~0.7–11MB
~64K SLoC