Crate embed_manifest

The embed-manifest crate provides a straightforward way to embed a Windows manifest in an executable, whatever the build environment and even when cross-compiling, without dependencies on external tools from LLVM or MinGW.

This should be called from a build script, as shown below.

On MSVC targets, the manifest file is embedded in the executable by instructing Cargo to pass /MANIFEST options to LINK.EXE. This requires Cargo from Rust 1.56.

On GNU targets, the manifest file is added as a resource in a COFF object file, and Cargo is instructed to link this file into the executable, also using functionality from Rust 1.56.

Usage

This crate should be added to the [build-dependencies] section in your executable’s Cargo.toml:

[build-dependencies]
embed-manifest = "1.3.1"

In the same directory, create a build.rs file to call this crate’s code when building for Windows, and to only run once:

use embed_manifest::{embed_manifest, new_manifest};

fn main() {
    if std::env::var_os("CARGO_CFG_WINDOWS").is_some() {
        embed_manifest(new_manifest("Contoso.Sample")).expect("unable to embed manifest file");
    }
    println!("cargo:rerun-if-changed=build.rs");
}

To customise the application manifest, use the methods on it to change things like enabling the segment heap:

use embed_manifest::{embed_manifest, new_manifest, manifest::HeapType};

fn main() {
    if std::env::var_os("CARGO_CFG_WINDOWS").is_some() {
        embed_manifest(new_manifest("Contoso.Sample").heap_type(HeapType::SegmentHeap))
            .expect("unable to embed manifest file");
    }
    println!("cargo:rerun-if-changed=build.rs");
}

or making it always use legacy single-byte API encoding and only declaring compatibility up to Windows 8.1, without checking whether this is a Windows build:

use embed_manifest::{embed_manifest, new_manifest};
use embed_manifest::manifest::{ActiveCodePage::Legacy, SupportedOS::*};

fn main() {
    let manifest = new_manifest("Contoso.Sample")
        .active_code_page(Legacy)
        .supported_os(Windows7..=Windows81);
    embed_manifest(manifest).expect("unable to embed manifest file");
    println!("cargo:rerun-if-changed=build.rs");
}

Modules

• manifest
  A builder for Windows application manifest XML files.

Structs

• Error
  The error type which is returned when application manifest embedding fails.

Functions

• embed_manifest
  Embeds the manifest described by manifest by converting it to XML, then saving it to a file and passing the correct options to the linker on MSVC targets, or by building a static library and instructing Cargo to link the executable against it on GNU targets.
• embed_manifest_file
  Directly embeds the manifest in the provided file by passing the correct options to the linker on MSVC targets, or by building a static library and instructing Cargo to link the executable against it on GNU targets.
• empty_manifest
  Creates a new ManifestBuilder without any settings, allowing creation of a manifest with only desired content.
• new_manifest
  Creates a new ManifestBuilder with sensible defaults, allowing customisation before the Windows application manifest XML is generated.