Skip to main content

Embed

Derive Macro Embed 

Source
#[derive(Embed)]
{
    // Attributes available to this derive:
    #[embark]
}
Available on crate feature derive only.
Expand description

Derives Embed for a unit struct, embedding every file under a folder at build time.

ⓘ
#[derive(embark::Embed)]
#[embark(folder = "assets", codec = "auto", include = "*.png", exclude = "*.tmp")]
struct Assets;

let logo = Assets::get("logo.png").unwrap();
for path in Assets::iter() { /* ... */ }
Not run as a doctest: expanding this macro needs the `embark` crate, and `embark-macros` cannot depend on it without a dependency cycle. A runnable version, embedding a real folder, is on [`Embed`](https://docs.rs/embark/*/embark/trait.Embed.html).

Configured with a single #[embark(...)] attribute, whose keys are:

  • folder = "..." (required) — the directory to embed, relative to CARGO_MANIFEST_DIR. Walked recursively; every file found becomes a manifest entry, keyed by its path relative to this folder (with / separators, even on Windows).

  • codec = "..." — compression for every embedded file: "store", "deflate" (the default), "lz4", "snappy", "zstd", "lzma", or one of the three selection policies "auto_fast", "auto" and "auto_small", described on embed_bytes!. A policy is applied per file, so one folder can end up with a different codec per entry. It applies under encrypt too, on each file’s plaintext. As with embed_bytes!, naming a codec whose feature isn’t enabled on embark does not fail the build – affected entries silently degrade to store (correct, just uncompressed).

  • encrypt — seal every embedded file with a single build-time embedded key shared by the whole derive (obfuscation, not security – see EncryptedFile’s docs). Embed::get then returns files decryptable with the infallible EncryptedFile::decrypt(). There is currently no per-derive key = runtime option; use embed_crypt! directly for runtime-key files.

  • cipher = "..." — the AEAD cipher encrypt seals with: "chacha" (ChaCha20-Poly1305, the default) or "aes" (AES-256-GCM). Ignored without encrypt. Both share the same threat model – see EncryptedFile’s docs. cipher = "aes" requires the aes feature enabled on embark; naming it without that feature is a build error.

  • dev — in debug builds only, get() reads the file live from disk (relative to folder) instead of returning the compiled-in copy, for fast iteration without rebuilding. Has no effect in release builds.

    Combined with encrypt, a debug build serves the file as it is on disk, in the clear: the copy there was never sealed, and this mode is for a developer’s own machine. The release build is unaffected.

    It serves the files the derive embedded and nothing else: a path has to be one the manifest holds, exactly, or get() returns None just as the release build would. A file added to the folder since the last build is not served until the crate rebuilds, and one that exclude left out is never served. This is what keeps a development server that hands out assets by request path from handing out ../.env.

  • follow_links — follow symbolic links (and, on Windows, junctions) found inside the folder. Off by default, and a link met without it is a build error rather than a skipped file: a link can point anywhere on the build machine, and following one that points at a key or a credential file embeds that file into the binary. That is a plausible shape for an accident and a very plausible shape for a hostile pull request. With it on, each real directory is walked once, so a link back to an ancestor ends the walk instead of never ending it.

  • include = "..." / exclude = "..." — glob filters over each file’s path relative to folder; repeatable (each occurrence adds one pattern). A file is embedded when it matches no exclude pattern and (include is empty, or it matches at least one include pattern). exclude takes priority over include.

    ? matches one character other than /, and * any run of them, so a single * stays inside one path segment: include = "*.png" matches logo.png but not sub/logo.png.

    ** crosses /. As a whole segment it stands for any number of segments, zero included, which is what makes **/*.png the way to say “a .png anywhere”:

    patternmatches
    *.pnglogo.png
    sub/*.pngsub/logo.png
    **/*.pnglogo.png, sub/logo.png, a/b/logo.png
    sub/**everything under sub/, at any depth
    **everything

§Rebuilds

Every embedded file is registered as a build input, so editing or deleting one of them triggers a rebuild. Adding a new file to the folder does not. Only the files that existed when the derive last expanded are tracked, and a file that has never been seen cannot be among them. After adding a file, force the crate to rebuild – touch any of its .rs files, or run cargo clean -p <crate>.