include_dir

include_dir is a Rust procedural macro that extends the standard library’s include_str!()/include_bytes!() pattern from a single file to an entire directory tree. Passing a path to include_dir!() recursively embeds every file’s contents into the binary at compile time as a static Dir structure that can be queried at runtime for files and subdirectories.

The resulting Dir value supports looking up a file by path, walking the tree, and — behind the optional glob feature — searching entries with glob patterns like **/*.rs. An optional metadata feature additionally captures file modification/access timestamps at compile time. It is commonly used to bundle static assets, templates, or configuration directories into a single self-contained binary.

What You Get

• The include_dir!() macro that recursively embeds a directory tree at compile time into a static Dir value
• A Dir/File/DirEntry API for looking up embedded files by path and walking subdirectories at runtime
• Optional glob-pattern searching over the embedded tree via the glob feature
• Optional file metadata (modified/accessed timestamps) captured at compile time via the metadata feature
• UTF-8 and raw-byte content access (contents_utf8(), contents()) for embedded files

Common Use Cases

• Bundling static web assets (HTML/CSS/JS) directly into a single-binary Rust web server
• Embedding default configuration files or templates so a CLI tool ships as one self-contained executable
• Shipping a fixed set of test fixtures or sample data alongside a compiled binary without external file dependencies
• Distributing a game or app’s asset directory (icons, shaders, levels) inside the executable

Under The Hood

Architecture: The project is a two-crate workspace: macros/ (356 lines) implements the include_dir!() procedural macro, walking the filesystem at compile time and generating the static Dir/File tree as Rust code; include_dir/ (415 lines across lib.rs, dir.rs, file.rs, dir_entry.rs, metadata.rs, globs.rs) defines the small runtime types the macro-generated code instantiates — Dir for directories, File for embedded file content, DirEntry as an enum unifying both, plus optional glob-search and metadata support gated behind Cargo features.

Tech Stack: Pure Rust with a minimal dependency footprint — the only non-dev dependency is the optional glob crate for pattern search; the macro crate itself depends on standard proc-macro tooling. tempfile is used only in dev-dependencies for the integration test suite. No async runtime or heavier dependencies are involved since all embedding work happens at compile time.

Code Quality: include_dir/tests/integration_test.rs (96 lines) exercises the public Dir/File API end-to-end (lookups, glob search) using a real embedded test directory, though the crate has seen no commits since mid-2024 (activity_status: inactive), meaning bug fixes or new Rust edition compatibility may lag. The code is compact and single-purpose, keeping the amount of logic that could hide bugs small relative to typical libraries of its download volume.

API Design: The macro deliberately mirrors the standard library’s existing include_str!()/include_bytes!() idiom — one macro call, assigned to a static, no builder or configuration object — so Rust developers already familiar with those macros need essentially zero onboarding to use include_dir!() for whole directories. Optional features (glob, metadata) are opt-in via Cargo feature flags rather than baked into the default API, keeping the default embed-and-lookup path lightweight.