### Compile Resources for Examples

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Use compile_for_examples to link resources specifically to example binaries. Requires rustc 1.60+.

```rust
// In build.rs
embed_resource::compile_for_examples("example.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();

```

--------------------------------

### Minimal Build Script Example

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/index.md

A basic build.rs script to compile resources with no additional parameters, suitable for minimal setups. Includes Cargo.toml dependency.

```rust
// build.rs
extern crate embed_resource;

fn main() {
    embed_resource::compile("app.rc", embed_resource::NONE)
        .manifest_optional()
        .unwrap();
}
```

```toml
[build-dependencies]
embed-resource = "3.0"
```

--------------------------------

### Compile Resource for Examples

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file specifically for example binaries. It links the resource using `cargo:rustc-link-arg-examples`. This function is available from rustc 1.60.0 onwards.

```rust
embed_resource::compile_for_examples("examples.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile Specific Binaries with Macros

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/index.md

This example shows how to compile resources for specific binaries and define version macros. It ensures the manifest is required.

```rust
// In build.rs
embed_resource::compile_for(
    "app.rc",
    &["myapp", "myapp-installer"],
    &["VERSION=\"1.0.0\""])
    .manifest_required()
    .unwrap();
```

--------------------------------

### File Layout Example

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

Illustrates the typical directory structure for a project using rust-embed-resource, showing the location of documentation files and API references.

```text
output/
├── README.md                           ← You are here
├── index.md                            ← Central overview
├── quick-start.md                      ← Common patterns & examples
├── types.md                            ← All public types
├── configuration.md                    ← Env vars, build.rs setup
├── errors.md                           ← Error catalog & troubleshooting
├── modules.md                          ← Crate structure
└── api-reference/
    ├── compile-functions.md            ← All compile() variants
    ├── compilation-result.md           ← Result type
    ├── parameter-types.md              ← Parameter wrappers
    ├── windows-sdk-tool.md             ← Tool discovery
    ├── platform-support.md             ← Platform details
    └── cli-tool.md                     ← CLI binary
```

--------------------------------

### Install Windows SDK for RC.EXE

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

If encountering 'RC.EXE not in $PATH' errors on Windows, install the Windows SDK via the Visual Studio installer.

```bash
# Visual Studio installer: Choose "Windows 10/11 SDK" component

```

--------------------------------

### Display Implementation Examples

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compilation-result.md

Shows the human-readable string formats for different CompilationResult variants when implementing the Display trait.

```text
"embed-resource: not building for windows"
```

```text
"embed-resource: OK"
```

```text
"embed-resource: compilation not attempted: missing compiler: RC.EXE"
```

```text
"embed-resource: RC.EXE failed to compile..."
```

--------------------------------

### compile_for_examples

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file specifically for example binaries. This function is available since rustc 1.60.0 and links the resource using `cargo:rustc-link-arg-examples=<resource>`.

```APIDOC
## compile_for_examples()

### Description
Compiles a Windows resource file for example binaries only.

### Signature
```rust
pub fn compile_for_examples<T: AsRef<Path>, Ms: AsRef<OsStr>, Mi: IntoIterator<Item = Ms>, Is: AsRef<OsStr>, Ii: IntoIterator<Item = Is>, P: Into<ParameterBundle<Ms, Mi, Is, Ii>>>(resource_file: T, parameters: P) -> CompilationResult
```

### Parameters
#### Path Parameters
- `resource_file` (AsRef<Path>) - Required - Path to the Windows resource file

#### Request Body
- `parameters` (Into<ParameterBundle<...>>) - Required - Macro definitions and include directories

### Response
#### Success Response (CompilationResult)
- Returns a `CompilationResult` indicating the outcome of the compilation.

### Example
```rust
embed_resource::compile_for_examples("examples.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```
```

--------------------------------

### Basic build.rs for compiling resources

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Create a build.rs file to compile a resource script using embed_resource::compile. This example uses .manifest_optional() for non-critical manifests.

```rust
extern crate embed_resource;

fn main() {
    embed_resource::compile("app.rc", embed_resource::NONE)
        .manifest_optional()
        .unwrap();
}

```

--------------------------------

### Compile Specific Binaries

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

This example shows how to compile resources for specific binary targets within your project, rather than all of them. Use this when you need to apply different resources to different executables.

```rust
embed_resource::compile_for(
    "app.rc",
    &["myapp", "myapp-installer"],
    &["VERSION=\"1.0.0\""])
    .manifest_required()
    .unwrap();
```

--------------------------------

### Install MinGW Windres on Windows

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Install the windres tool using the MinGW package manager for Windows resource compilation.

```bash
pacman -S mingw-w64-x86_64-binutils
```

--------------------------------

### Resource file with preprocessor directives

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

An example of a resource definition file (.rc) that utilizes preprocessor directives like #ifndef and #define.

```c
#ifndef VERSION
#define VERSION "0.0.0"
#endif

STRINGTABLE
BEGIN
    1 "Application Version: " VERSION
END

```

--------------------------------

### Compile with Macros

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

This example demonstrates how to embed resources with C preprocessor macros defined. Use this when your resource file relies on specific macro definitions for conditional compilation or versioning.

```rust
embed_resource::compile("app.rc",
    &["VERSION=\"1.0.0\"", "DEBUG"])
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Build for Windows GNU from Linux

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/platform-support.md

Example of building for a Windows GNU target from a Linux host. This requires setting the `RC_x86_64_pc_windows_gnu` environment variable to the `windres` executable for the target architecture.

```bash
export RC_x86_64_pc_windows_gnu=x86_64-w64-mingw32-windres
cargo build --target x86_64-pc-windows-gnu
```

--------------------------------

### Configure workspace for version updates

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

Example of workspace configuration in Cargo.toml, typically used for testing and CI purposes.

```toml
[workspace]
members = [
    ".github/workflows/msvc"
]

```

--------------------------------

### Test Windres Version

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Verify the installation of the windres tool by checking its version.

```bash
windres --version
```

--------------------------------

### Rust CLI Implementation

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/cli-tool.md

The main function of the embed-resource CLI tool, demonstrating environment variable setup, argument parsing, and calls to embed_resource::compile and embed_resource::compile_for.

```rust
fn main() {
    env::set_var("TARGET", if cfg!(target_arch = "x86_64") {
        "x86_64"
    } else if cfg!(target_arch = "aarch64") {
        "aarch64"
    } else {
        "irrelevant"
    });
    
    #[cfg(target_os = "windows")]
    env::set_var("HOST", env::var_os("TARGET").unwrap());
    
    env::set_var("OUT_DIR", ".");
    
    let mut args = env::args_os();
    let argv0 = args.next().map(Cow::from).unwrap_or(Cow::from(OsStr::new("rust-embed-resource")));
    let resource = args.next()
        .unwrap_or_else(|| panic!("usage: {} resource [include-dir]", Path::new(&*argv0).display()));
    let include_dir = args.next();
    
    embed_resource::compile(&resource, 
        embed_resource::ParamsMacrosAndIncludeDirs(
            ["VERSION=\"0.5.0\""],
            include_dir.as_ref()))
        .manifest_required()
        .unwrap();
    
    embed_resource::compile_for(&resource,
        ["embed_resource", "embed_resource-installer"],
        embed_resource::ParamsIncludeDirs(include_dir))
        .manifest_required()
        .unwrap();
}
```

--------------------------------

### Compile Resources for All Targets

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Use compile_for_everything to link resources to all binary types, including examples, tests, and benchmarks. Requires rustc 1.50+.

```rust
// In build.rs
embed_resource::compile_for_everything("global.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();

```

--------------------------------

### Find RC.EXE and Print Path

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/windows-sdk-tool.md

Shows how to locate the RC.EXE tool using find_windows_sdk_tool(). This example is useful for custom resource compilation workflows, although the embed_resource::compile() function typically handles RC.EXE discovery automatically.

```rust
#[cfg(all(target_os = "windows", target_env = "msvc"))]
{
    extern crate embed_resource;
    
    use std::process::Command;
    
    fn main() {
        // Note: Most build scripts don't need to call this directly,
        // as embed_resource::compile() finds RC.EXE automatically.
        // This is useful for custom resource compilation workflows.
        
        if let Some(rc_path) = embed_resource::find_windows_sdk_tool("rc.exe") {
            println!("Found RC.EXE at: {:?}", rc_path);
            // Can now use rc_path to invoke RC.EXE
        } else {
            eprintln!("RC.EXE not found in any Windows SDK installation");
        }
    }
}
```

--------------------------------

### Explicitly Set SDK Include Directory

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

When the Windows SDK headers are not found, you can explicitly provide the include directory to the `compile` function. Ensure the path to the SDK's `um` directory is correct for your installation.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(&["C:\\Program Files (x86)\\Windows Kits\\10\\Include\\10.0.22621.0\\um"]))
    .manifest_required()
    .unwrap();
```

--------------------------------

### Handle compilation errors with manifest optional

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

This example shows how to handle potential errors during resource compilation when a manifest file is optional. It prints a warning but allows the build to continue.

```rust
embed_resource::compile("icon.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap_or_else(|e| {
        eprintln!("Warning: Failed to compile icon: {}", e);
        // Build continues
    });

```

--------------------------------

### Build for Windows MSVC from Windows MSVC

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/platform-support.md

Example of compiling a Windows resource file using the native RC.EXE compiler on a Windows MSVC host. The `.manifest_optional()` method allows for optional manifest embedding.

```rust
embed_resource::compile("app.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Handle compilation errors with manifest required

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

This example demonstrates how to handle errors during resource compilation when a manifest file is required. It panics on failure, causing the build to stop.

```rust
embed_resource::compile("manifest.rc", embed_resource::NONE)
    .manifest_required()
    .unwrap_or_else(|e| {
        panic!("Failed to compile manifest: {}", e);
        // Build fails
    });

```

--------------------------------

### Cross-Compile for Windows ARM64 from Windows x64

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/platform-support.md

Shows how to cross-compile for Windows ARM64 from a Windows x64 host. It first attempts auto-discovery of the RC.EXE tool and provides an example of manually setting the `RC_aarch64_pc_windows_msvc` environment variable if auto-discovery fails.

```bash
# RC.EXE should auto-discover correctly
cargo build --target aarch64-pc-windows-msvc
```

```bash
export RC_aarch64_pc_windows_msvc="C:\\Program Files (x86)\\Windows Kits\\10\\bin\\10.0.22621.0\\arm64\\rc.exe"
cargo build --target aarch64-pc-windows-msvc
```

--------------------------------

### Find Windows SDK Tool (rc.exe)

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/windows-sdk-tool.md

This snippet demonstrates how to find the `rc.exe` tool using `find_windows_sdk_tool`. It includes error handling for cases where the tool is not found, prompting the user to install the Windows SDK or set the RC environment variable. This code is specific to Windows MSVC targets.

```rust
#[cfg(all(target_os = "windows", target_env = "msvc"))]
{
    extern crate embed_resource;
    
    fn main() {
        let rc_path = embed_resource::find_windows_sdk_tool("rc.exe")
            .expect("RC.EXE not found in any Windows SDK installation.                     Install the Windows SDK or set the RC environment variable.");
    }
}
```

--------------------------------

### Rust Integration Tests

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/modules.md

These are examples of integration tests embedded within the rust-embed-resource crate's lib.rs file. They are used to verify compatibility and argument bundle conversions.

```rust
#[cfg(test)]
fn compat_3_0_5()  // Compatibility test
```

```rust
#[test]
fn argument_bundle_into()  // Type conversion test
```

--------------------------------

### Build Script Optional Compilation

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/cli-tool.md

Example of using embed_resource::compile within a build.rs script with manifest_optional() for non-failing compilation if the compiler is unavailable. This is suitable for production builds where resource compilation is not critical.

```rust
// In build.rs
embed_resource::compile("app.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();  // Doesn't fail if compiler unavailable
```

--------------------------------

### Compile Resource for All Artifacts

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file and links it into all artifact types (binaries, cdylibs, examples, tests, benchmarks). It uses the global linker argument `cargo:rustc-link-arg`. This function is available from rustc 1.50.0 onwards.

```rust
embed_resource::compile_for_everything("global.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Check Unix Shell Environment Variables and RC Executable

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

In a Unix shell, verify the `RC` and specific target `RC_` environment variables. Use `which rc.exe` to confirm that the resource compiler is in your system's PATH. This is crucial for cross-compilation setups.

```bash
# Unix shell
echo $RC
echo $RC_x86_64_pc_windows_msvc
which rc.exe
```

--------------------------------

### Initialize ParamsMacrosAndIncludeDirs with NONE

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Demonstrates initializing ParamsMacrosAndIncludeDirs using the NONE constant for either macros or include directories.

```rust
embed_resource::ParamsMacrosAndIncludeDirs(
    &["VERSION=\"1.0.0\""],
    embed_resource::NONE)
```

--------------------------------

### Error Trait Implementation Example

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compilation-result.md

Demonstrates using CompilationResult with standard Rust error handling patterns by implementing the std::error::Error trait.

```rust
fn build_resource() -> Result<(), Box<dyn std::error::Error>> {
    embed_resource::compile("app.rc", embed_resource::NONE)
        .manifest_required()?;
    Ok(())
}
```

--------------------------------

### Find Multiple Custom SDK Tools

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/windows-sdk-tool.md

Illustrates how to iterate through a list of custom SDK tools (e.g., midl.exe, signtool.exe, mt.exe) and find their paths using find_windows_sdk_tool(). It prints the path if found or an error message if not.

```rust
#[cfg(all(target_os = "windows", target_env = "msvc"))]
{
    extern crate embed_resource;
    
    fn main() {
        let tools = vec!["midl.exe", "signtool.exe", "mt.exe"];
        
        for tool in tools {
            match embed_resource::find_windows_sdk_tool(tool) {
                Some(path) => println!("Found {}: {:?}", tool, path),
                None => eprintln!("{} not found", tool),
            }
        }
    }
}
```

--------------------------------

### Find MIDL.EXE and Use It

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/windows-sdk-tool.md

Demonstrates how to find the MIDL.EXE tool using find_windows_sdk_tool() and then use it to process an interface definition file. It requires setting the PATH environment variable to include Visual Studio executable paths for MIDL.exe to function correctly as a preprocessor.

```rust
#[cfg(all(target_os = "windows", target_env = "msvc"))]
{
    extern crate embed_resource;
    extern crate vswhom;
    
    use std::process::Command;
    use std::env;
    
    fn main() {
        let midl = embed_resource::find_windows_sdk_tool("midl.exe")
            .expect("MIDL.EXE not found");
        
        // midl.exe uses cl.exe as a preprocessor, so it needs to be in PATH
        let vs_locations = vswhom::VsFindResult::search().unwrap();
        let output = Command::new(midl)
            .env("PATH", vs_locations.vs_exe_path.unwrap())
            .arg("/out").arg(env::var("OUT_DIR").unwrap())
            .arg("interface.idl")
            .output()
            .unwrap();
        
        assert!(output.status.success());
    }
}
```

--------------------------------

### Parameter Wrappers for Compilation

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/index.md

Shows how to use parameter wrappers for passing macros, include directories, or both to compilation functions. NONE can be used when no parameters are needed.

```rust
compile("app.rc", &["VERSION=\"1.0.0\""])

compile("app.rc", ParamsIncludeDirs(&["include"]))

compile("app.rc", ParamsMacrosAndIncludeDirs(
    &["VERSION=\"1.0.0\""],
    &["include"]))

compile("app.rc", NONE)
```

--------------------------------

### Compile with Both Macros and Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/types.md

Illustrates calling the compile function with both macro definitions and include directories, utilizing the ParamsMacrosAndIncludeDirs wrapper.

```rust
compile("app.rc", ParamsMacrosAndIncludeDirs(
    &["VERSION=\"1.0.0\""],
    &["include"]))

```

--------------------------------

### Compile Resources with Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/index.md

Use this snippet in your build.rs file to compile resources and specify include directories for the C preprocessor.

```rust
// In build.rs
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(&["include", "src/headers"]))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile with Macros and Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Use ParamsMacrosAndIncludeDirs to specify both macro definitions and include directories for the resource compilation. Both can be empty.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsMacrosAndIncludeDirs(
        &["VERSION=\"1.0.0\""],
        &["src/include"]))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Accepted Iterator Types for Parameters

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/types.md

Examples of various types that can be accepted as parameters for macros and include directories, including string slices, vectors, OS strings, paths, and custom types.

```rust
// String slices
&["MACRO=VALUE"]

// String vectors
vec!["MACRO=VALUE"]

// OS string vectors
vec![OsString::from("MACRO=VALUE")]

// Paths
&[Path::new("include")]

// Path bufs
vec![PathBuf::from("include")]

// Options
Some("include")

// Custom types with IntoIterator<Item: AsRef<OsStr>>
my_custom_collection
```

--------------------------------

### CLI Tool Usage

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/modules.md

Demonstrates how to invoke the embed-resource crate as a command-line tool. This is useful for quick compilation of resource files without direct integration into a Rust project.

```bash
cargo run --bin embed-resource -- app.rc [include-dir]
```

--------------------------------

### Compile Resource File in Build Script

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/README.md

Use this in your build.rs to compile and link a resource file. Call `.manifest_optional().unwrap()` for cosmetic manifests like icons, and `.manifest_required().unwrap()` for essential manifests.

```rust
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();
}
```

--------------------------------

### Configure Cross-Compilation for Windows GNU Targets

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

For Windows GNU targets when cross-compiling from non-Windows hosts, install the `mingw-w64` toolchain. You may need to set the `RC_x86_64_pc_windows_gnu` environment variable to point to the correct `windres` executable.

```bash
# Install mingw-w64
sudo apt-get install mingw-w64  # Ubuntu/Debian
brew install mingw-w64          # macOS

# Set compiler if needed
export RC_x86_64_pc_windows_gnu=x86_64-w64-mingw32-windres
```

--------------------------------

### Enable Verbose Cargo Build Output

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

To see detailed compiler output and environment variables during a Cargo build, use the `-vv` flag. This is useful for debugging issues related to resource compilation and environment setup.

```bash
# See full compiler output
car go build -vv

# See environment variables
car go build -vv 2>&1 | grep -E "RC|INCLUDE|TARGET"
```

--------------------------------

### Build Script with Custom Version

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/cli-tool.md

Demonstrates how to compile a resource file in a build script, specifying a custom version macro derived from Cargo.toml. This allows for dynamic versioning in production builds.

```rust
// In build.rs with version from Cargo.toml
embed_resource::compile("app.rc", &[
    &format!("VERSION=\" மூல{}\"", env!("CARGO_PKG_VERSION"))
])
.manifest_optional()
.unwrap();
```

--------------------------------

### Compile Resource with Macros and Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file using the `compile` function, providing both macro definitions and include directories. Handles the compilation result.

```rust
// With both macros and include directories
embed_resource::compile("checksums.rc", 
    embed_resource::ParamsMacrosAndIncludeDirs(
        &["VERSION=\"0.5.0\""], 
        &["src/include"]))
    .manifest_required()
    .unwrap();
```

--------------------------------

### Test LLVM-RC Preprocessor with a Simple Resource File

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

To debug preprocessor errors with LLVM-RC, create a minimal resource file and attempt to compile it directly using `llvm-rc`. This helps isolate syntax or include path issues within the resource script itself.

```bash
# Create test.rc with just:
#include <windows.h>

# Try compiling manually with LLVM-RC
llvm-rc /fo test.res test.rc

# Or test the preprocessor step
# (embed-resource does this for you)
```

--------------------------------

### Compile Resource with Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file using the `compile` function, specifying an include directory for resource files. Ensures the compilation result is handled.

```rust
// With include directories
embed_resource::compile("checksums.rc", 
    embed_resource::ParamsIncludeDirs(&["src/include"]))
    .manifest_required()
    .unwrap();
```

--------------------------------

### Compile Resources with Explicit Include Directory

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Embed resources from an 'app.rc' file, explicitly specifying the Windows SDK include directory to resolve 'windows.h' errors. This is useful when the SDK is not found automatically.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(&[
        "C:\\Program Files (x86)\\Windows Kits\\10\\Include\\10.0.22621.0\\um"
    ]))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Basic Usage in build.rs

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

This snippet shows the most basic usage of embed_resource::compile in a build.rs file. It compiles a single resource file and optionally includes a manifest. Use this for simple resource embedding.

```rust
extern crate embed_resource;

fn main() {
    embed_resource::compile("app.rc", embed_resource::NONE)
        .manifest_optional()
        .unwrap();
}
```

--------------------------------

### Compile with Include Directories Only

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/types.md

Shows how to call the compile function when only include directories are specified, using the ParamsIncludeDirs wrapper.

```rust
compile("app.rc", ParamsIncludeDirs(&["include"]))
```

--------------------------------

### Compile with Only Macros

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Use ParamsMacrosAndIncludeDirs with the NONE constant for include directories when only macros are needed.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsMacrosAndIncludeDirs(
        &["FEATURE_X=1"],
        embed_resource::NONE))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile with Macros Only

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/types.md

Demonstrates how to call the compile function when only macro definitions are provided. This can be done directly or by using the ParamsMacros wrapper.

```rust
compile("app.rc", &["VERSION=\"1.0.0\""])
// or
compile("app.rc", ParamsMacros(&["VERSION=\"1.0.0\""]))
```

--------------------------------

### compile_for_everything

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file and links it into every artifact type. This function is available since rustc 1.50.0 and links the resource using `cargo:rustc-link-arg=<resource>`.

```APIDOC
## compile_for_everything()

### Description
Compiles a Windows resource file and links it into every artifact type.

### Signature
```rust
pub fn compile_for_everything<T: AsRef<Path>, Ms: AsRef<OsStr>, Mi: IntoIterator<Item = Ms>, Is: AsRef<OsStr>, Ii: IntoIterator<Item = Is>, P: Into<ParameterBundle<Ms, Mi, Is, Ii>>>(resource_file: T, parameters: P) -> CompilationResult
```

### Parameters
#### Path Parameters
- `resource_file` (AsRef<Path>) - Required - Path to the Windows resource file

#### Request Body
- `parameters` (Into<ParameterBundle<...>>) - Required - Macro definitions and include directories

### Response
#### Success Response (CompilationResult)
- Returns a `CompilationResult` indicating the outcome of the compilation.

### Example
```rust
embed_resource::compile_for_everything("global.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```
```

--------------------------------

### Compile with ParamsMacrosAndIncludeDirs Wrapper

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Use the ParamsMacrosAndIncludeDirs wrapper to pass both macro definitions and include directories.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsMacrosAndIncludeDirs(
        &["VERSION=\"1.0.0\""],
        &["include"]))

```

--------------------------------

### Compile Resource with Macro Definitions

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file using the `compile` function, providing macro definitions for version and build ID. Handles the compilation result.

```rust
// With macro definitions
embed_resource::compile("checksums.rc", &["VERSION=\"1.0.0\"", "BUILD_ID=123"])
    .manifest_required()
    .unwrap();
```

--------------------------------

### compile()

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file and updates the cargo search path if building for Windows. It handles different Windows compilers (MSVC and non-MSVC) and linker behaviors based on the Rust version.

```APIDOC
## compile()

### Description
Compile the Windows resource file and update the cargo search path if building for Windows.

### Method
```rust
pub fn compile<T: AsRef<Path>, Ms: AsRef<OsStr>, Mi: IntoIterator<Item = Ms>, Is: AsRef<OsStr>, Ii: IntoIterator<Item = Is>, P: Into<ParameterBundle<Ms, Mi, Is, Ii>>>(resource_file: T, parameters: P) -> CompilationResult
```

### Parameters

- `resource_file` (AsRef<Path>): Required - Path to the Windows resource file (e.g., `"checksums.rc"`)
- `parameters` (Into<ParameterBundle<...>>): Required - Macro definitions and include directories. Can be `NONE`, macro iterables, `ParamsMacros`, `ParamsIncludeDirs`, or `ParamsMacrosAndIncludeDirs`.

### Return Type
`CompilationResult` — An enum representing the compilation outcome. Must be converted to a `Result` using `manifest_optional()` or `manifest_required()`.

### Behavior

- On non-Windows targets: does nothing, returns `CompilationResult::NotWindows`
- On non-MSVC Windows: chains `windres` with `ar`
- On MSVC Windows: finds and uses `RC.EXE`, attempting multiple registry locations
- `$OUT_DIR` is automatically added to the include search path
- For rustc >= 1.50.0, resources are linked only to binaries (or library if no binaries exist)
- For rustc < 1.50.0 with a library present, resources are linked to the library instead

### Examples

```rust
extern crate embed_resource;

fn main() {
    // Simple resource compilation with no parameters
    embed_resource::compile("checksums.rc", embed_resource::NONE)
        .manifest_optional()
        .unwrap();
}
```

```rust
// With macro definitions
embed_resource::compile("checksums.rc", &["VERSION=\"1.0.0\"", "BUILD_ID=123"])
    .manifest_required()
    .unwrap();
```

```rust
// With include directories
embed_resource::compile("checksums.rc", 
    embed_resource::ParamsIncludeDirs(&["src/include"]))
    .manifest_required()
    .unwrap();
```

```rust
// With both macros and include directories
embed_resource::compile("checksums.rc", 
    embed_resource::ParamsMacrosAndIncludeDirs(
        &["VERSION=\"0.5.0\""], 
        &["src/include"]))
    .manifest_required()
    .unwrap();
```
```

--------------------------------

### Compile Resource with No Parameters

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file using the `compile` function with no additional parameters. Ensures the compilation result is handled.

```rust
extern crate embed_resource;

fn main() {
    // Simple resource compilation with no parameters
    embed_resource::compile("checksums.rc", embed_resource::NONE)
        .manifest_optional()
        .unwrap();
}
```

--------------------------------

### CLI Invocation with Include Directory

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/cli-tool.md

Compile a resource file while specifying an additional include directory for the resource compiler. This allows the resource file to reference other files within the specified include path.

```bash
embed-resource app.rc ./include
```

--------------------------------

### Compile with Only Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Use ParamsMacrosAndIncludeDirs with the NONE constant for macros when only include directories are needed.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsMacrosAndIncludeDirs(
        embed_resource::NONE,
        &["include"]))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile with Neither Macros nor Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/types.md

Demonstrates calling the compile function when neither macros nor include directories are needed, by passing the NONE constant.

```rust
compile("app.rc", NONE)
```

--------------------------------

### Combine Macros and Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

Use `ParamsMacrosAndIncludeDirs` to simultaneously specify macro definitions and include directories for the resource compiler. This is useful for complex build configurations.

```rust
extern crate embed_resource;

fn main() {
    embed_resource::compile("app.rc",
        embed_resource::ParamsMacrosAndIncludeDirs(
            &["VERSION=\"3.0.0\"", "BUILD_DATE=\"2025-06-13\""],
            &["include", "src/headers"]))
        .manifest_optional()
        .unwrap();
}
```

--------------------------------

### Compile Resources for Benchmarks

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Use compile_for_benchmarks to link resources specifically to benchmark binaries. Requires rustc 1.60+.

```rust
// In build.rs
embed_resource::compile_for_benchmarks("bench.rc", &["BENCH=1"])
    .manifest_optional()
    .unwrap();

```

--------------------------------

### Compile Resource for Benchmarks

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file specifically for benchmark binaries. It links the resource using `cargo:rustc-link-arg-benches`. This function is available from rustc 1.60.0 onwards.

```rust
embed_resource::compile_for_benchmarks("benches.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Embed Cosmetic Resource with Optional Manifest

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

Use this pattern for cosmetic resources like icons where the manifest is not critical for functionality. The `.manifest_optional()` method is chosen, and the result is unwrapped.

```rust
// For cosmetic resources (icons, etc.)
embed_resource::compile("icon.rc", NONE)
    .manifest_optional()      // ← Choose this...
    .unwrap();                // ← ...then unwrap
```

--------------------------------

### Basic CLI Invocation

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/cli-tool.md

Compile a resource file located in the current directory using the embed-resource CLI. The compiled resource will be output to the current directory.

```bash
embed-resource app.rc
```

--------------------------------

### Check Windows Environment Variables and RC Executable

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

On Windows, verify that the `RC` and specific target `RC_` environment variables are set correctly, and check the availability of `rc.exe` using `rc.exe /?`. This helps diagnose issues with the resource compiler path and configuration.

```bash
# Windows CMD
echo %RC%
echo %RC_x86_64_pc_windows_msvc%
echo %INCLUDE%
rc.exe /?
```

--------------------------------

### Compile resource with preprocessor macro

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

Compiles a resource file, passing a preprocessor macro to define a version string that will be substituted during compilation.

```rust
embed_resource::compile("app.rc", &["VERSION=\"1.5.0\""])
    .manifest_optional()
    .unwrap();

```

--------------------------------

### Basic app.rc for embedding an icon

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

A minimal Windows resource script (.rc file) to embed an icon into your application.

```c
#include <windows.h>

1 ICON "app.ico"

```

--------------------------------

### compile_for_benchmarks

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file specifically for benchmark binaries. This function is available since rustc 1.60.0 and links the resource using `cargo:rustc-link-arg-benches=<resource>`.

```APIDOC
## compile_for_benchmarks()

### Description
Compiles a Windows resource file for benchmark binaries only.

### Signature
```rust
pub fn compile_for_benchmarks<T: AsRef<Path>, Ms: AsRef<OsStr>, Mi: IntoIterator<Item = Ms>, Is: AsRef<OsStr>, Ii: IntoIterator<Item = Is>, P: Into<ParameterBundle<Ms, Mi, Is, Ii>>>(resource_file: T, parameters: P) -> CompilationResult
```

### Parameters
#### Path Parameters
- `resource_file` (AsRef<Path>) - Required - Path to the Windows resource file

#### Request Body
- `parameters` (Into<ParameterBundle<...>>) - Required - Macro definitions and include directories

### Response
#### Success Response (CompilationResult)
- Returns a `CompilationResult` indicating the outcome of the compilation.

### Example
```rust
embed_resource::compile_for_benchmarks("benches.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```
```

--------------------------------

### Cross-Compile for Windows MSVC from Linux

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/platform-support.md

Demonstrates cross-compiling for Windows MSVC from a Linux host. Requires setting the `RC_x86_64_pc_windows_msvc` environment variable to point to `llvm-rc` and specifying the target triple in the cargo build command.

```rust
embed_resource::compile("app.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

```bash
export RC_x86_64_pc_windows_msvc=llvm-rc
cargo build --target x86_64-pc-windows-msvc
```

--------------------------------

### ParamsIncludeDirs

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Wrapper for providing include directories to the resource compiler. Wraps an iterator of directory paths to add to the resource compiler's include search path. Include directories are passed with the `-I` (GCC/MinGW) or `/I` (MSVC) flags. Note that `$OUT_DIR` is always added automatically.

```APIDOC
## ParamsIncludeDirs

### Description

Wrapper for providing include directories to the resource compiler. Include directories are passed with the `-I` (GCC/MinGW) or `/I` (MSVC) flags. Note that `$OUT_DIR` is always added automatically.

### Generic Parameters

| Parameter | Constraint | Description |
|-----------|-----------|-------------|
| `Is` | `AsRef<OsStr>` | Type of individual path strings |
| `Ii` | `IntoIterator<Item = Is>` | Iterator type for the directory collection |

### Examples

```rust
// Explicit type usage
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(&["src/include", "third_party/include"]))
    .manifest_optional()
    .unwrap();
```

```rust
// With Path objects
use std::path::Path;
let dirs = vec![Path::new("include"), Path::new("src/include")];
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(dirs))
    .manifest_optional()
    .unwrap();
```

### From Implementation

Implements `From<ParamsIncludeDirs>` into `ParameterBundle`, internally calling `ParamsMacrosAndIncludeDirs` with empty macros.
```

--------------------------------

### Validate Resource File Syntax with RC.EXE

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/errors.md

Directly test the syntax of your `.rc` file using `rc.exe` with the `/d RC_INVOKED` flag. This command attempts to compile the resource file and will report syntax errors without creating an output file, aiding in debugging the resource script itself.

```bash
# Test RC file syntax directly
rc.exe /d RC_INVOKED /fo test.res app.rc
```

--------------------------------

### Compile with Include Directories

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/README.md

This snippet shows how to specify include directories for resource compilation. Use this when your resource file (`.rc`) or its included files are located in subdirectories.

```rust
embed_resource::compile("app.rc",
    embed_resource::ParamsIncludeDirs(&["include"]))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Specify Include Directories for Resource Compiler

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/configuration.md

Add directories to the resource compiler's include search path using `ParamsIncludeDirs`. This allows resource files to reference common headers.

```rust
extern crate embed_resource;

fn main() {
    // Single include directory
    embed_resource::compile("app.rc", 
        embed_resource::ParamsIncludeDirs(&["src/include"]))
        .manifest_optional()
        .unwrap();
    
    // Multiple include directories
    embed_resource::compile("app.rc",
        embed_resource::ParamsIncludeDirs(&["src/include", "third_party/headers"]))
        .manifest_optional()
        .unwrap();
}
```

--------------------------------

### Compile with Various Iterator Types

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/parameter-types.md

Demonstrates using different collection types like Vec<String> and Vec<&str> for macros and directories with ParamsMacrosAndIncludeDirs.

```rust
let macros: Vec<String> = vec!["VERSION=\"1.0.0\"".to_string()];
let dirs = vec!["include", "src/include"];
embed_resource::compile("app.rc",
    embed_resource::ParamsMacrosAndIncludeDirs(macros, dirs))
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile Resource for Tests

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compile-functions.md

Compiles a Windows resource file specifically for test binaries. It links the resource using `cargo:rustc-link-arg-tests`. This function is available from rustc 1.60.0 onwards.

```rust
embed_resource::compile_for_tests("tests.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Embed Version from Cargo.toml

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/index.md

This build script pattern embeds the application version from Cargo.toml into the resources. It dynamically formats the VERSION macro using the CARGO_PKG_VERSION environment variable.

```rust
// In build.rs
embed_resource::compile("app.rc",
    &[&format!("VERSION={}", env!("CARGO_PKG_VERSION"))])
    .manifest_optional()
    .unwrap();
```

--------------------------------

### Compile Resources for Tests

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/quick-start.md

Use compile_for_tests to link resources specifically to test binaries. Requires rustc 1.60+.

```rust
// In build.rs
embed_resource::compile_for_tests("test.rc", embed_resource::NONE)
    .manifest_optional()
    .unwrap();

```

--------------------------------

### manifest_required()

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/_autodocs/api-reference/compilation-result.md

Converts the CompilationResult to a Result<(), CompilationResult> for critical resources. It returns Ok(()) for NotWindows or Ok, and Err(self) for NotAttempted or Failed.

```APIDOC
## manifest_required()

### Description
Convert to `Result<(), CompilationResult>` for critical resources.

### Signature:
```rust
pub fn manifest_required(self) -> Result<(), CompilationResult>
```

### Returns:
- `Ok(())` if result is `NotWindows` or `Ok`
- `Err(self)` if result is `NotAttempted` or `Failed`

### Use When:
- Embedding critical resources like security manifests, entry point configurations, or version information
- Build failure is required if compilation cannot proceed

### Example:

```rust
embed_resource::compile("app-manifest.rc", embed_resource::NONE)
    .manifest_required()
    .unwrap();  // Fails if compilation not attempted or fails
```
```

--------------------------------

### Embed Windows Manifest with Admin Privileges

Source: https://github.com/nabijaczleweli/rust-embed-resource/blob/master/README.md

This snippet demonstrates how to embed a Windows manifest file that requests administrator privileges for the executable. Ensure the manifest file and its corresponding RC file are in your project root.

```rust
extern crate embed_resource;
fn main() {
    embed_resource::compile("app-name-manifest.rc", embed_resource::NONE).manifest_optional().unwrap();
}
```