include_dir Rust Crate

The include_dir! macro allows you to embed an entire directory tree into your Rust binary at compile time, extending the functionality of include_str! and include_bytes!.

Best Practice: Use Environment Variables

Because rustc does not guarantee the current working directory when running procedural macros, you should avoid using relative paths. Instead, use environment variable interpolation to ensure paths are absolute and reliable. Common variables provided by Cargo include $CARGO_MANIFEST_DIR and $OUT_DIR.

Example of including a folder relative to your crate root: include_dir!("$CARGO_MANIFEST_DIR/assets")

use include_dir::{include_dir, Dir};

// Embed the crate's source directory
static PROJECT_DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR");

// Retrieve a file by its path within the directory
let lib_rs = PROJECT_DIR.get_file("src/lib.rs").unwrap();

// Access contents as UTF-8
let body = lib_rs.contents_utf8().unwrap();

The Dir struct is the primary interface for interacting with embedded files and directories included via the include_dir!() macro. It provides methods to navigate the embedded filesystem, retrieve specific files or sub-directories, and extract the entire embedded structure to the host filesystem.

Key Capabilities:

• Navigation: Access the relative path of the directory using .path() and iterate over its contents using .entries(), .files(), or .dirs().
• Lookup: Use .get_entry(path), .get_file(path), or .get_dir(path) to find specific items. These methods perform a recursive search.
• Verification: Use .contains(path) to check if a specific path exists within the embedded directory.
• Extraction: Use .extract(base_path) to write all embedded files and directories to the actual filesystem starting at base_path.

// Example of navigating and extracting a Dir
let embedded_dir = include_dir!("my_assets");

// Look up a specific file
if let Some(file) = embedded_dir.get_file("images/logo.png") {
    println!("Found file with size: {}", file.contents().len());
}

// Extract everything to a local folder named "output"
embedded_dir.extract("output").expect("Failed to extract files");

The include_dir! macro allows you to embed the entire contents of a directory into your Rust binary at compile time. This is useful for bundling assets, configuration files, or static data directly within your executable.

Usage

Pass a single string literal representing the path to the directory you wish to include. The macro supports environment variable expansion using the $VAR syntax.

Key Features

• Recursive Embedding: Automatically traverses subdirectories and embeds them as include_dir::Dir entries.
• Environment Variables: You can use $VARIABLE_NAME within the path string to resolve paths dynamically based on environment variables.
• Metadata Support: If the metadata feature is enabled, the macro will also embed file metadata (accessed, created, and modified timestamps).
• Path Normalization: Paths are normalized to use forward slashes (/) regardless of the host operating system (Windows or Linux).

// Example usage of the include_dir! macro
let my_dir = include_dir!("assets");

// You can also use environment variables
let dynamic_dir = include_dir!("$ASSET_PATH/data");

The DirEntry<'a> enum represents an item within the embedded directory tree, acting as a wrapper for either a directory (Dir) or a file (File). It provides a unified interface to access common properties like the path, regardless of whether the underlying item is a file or a directory.

Key methods:

• path(): Returns a reference to the Path of the entry.
• as_dir(): Returns Some(&Dir) if the entry is a directory, otherwise None.
• as_file(): Returns Some(&File) if the entry is a file, otherwise None.
• children(): Returns a slice of DirEntry items if the entry is a directory; returns an empty slice if it is a file.

use include_dir::DirEntry;

// Assuming `entry` is a DirEntry<'a> obtained from the tree
let path = entry.path();

if let Some(dir) = entry.as_dir() {
    // Handle directory logic
    let children = entry.children();
}

if let Some(file) = entry.as_file() {
    // Handle file logic
}