#[derive(Embed)]
{
// Attributes available to this derive:
#[embark]
}
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() { /* ... */ }Configured with a single #[embark(...)] attribute, whose keys are:
-
folder = "..."(required) — the directory to embed, relative toCARGO_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 onembed_bytes!. A policy is applied per file, so one folder can end up with a different codec per entry. It applies underencrypttoo, on each file’s plaintext. As withembed_bytes!, naming a codec whose feature isn’t enabled onembarkdoes not fail the build – affected entries silently degrade tostore(correct, just uncompressed). -
encrypt— seal every embedded file with a single build-time embedded key shared by the whole derive (obfuscation, not security – seeEncryptedFile’s docs).Embed::getthen returns files decryptable with the infallibleEncryptedFile::decrypt(). There is currently no per-derivekey = runtimeoption; useembed_crypt!directly for runtime-key files. -
cipher = "..."— the AEAD cipherencryptseals with:"chacha"(ChaCha20-Poly1305, the default) or"aes"(AES-256-GCM). Ignored withoutencrypt. Both share the same threat model – seeEncryptedFile’s docs.cipher = "aes"requires theaesfeature enabled onembark; naming it without that feature is a build error. -
dev— in debug builds only,get()reads the file live from disk (relative tofolder) 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()returnsNonejust as the release build would. A file added to the folder since the last build is not served until the crate rebuilds, and one thatexcludeleft 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 tofolder; repeatable (each occurrence adds one pattern). A file is embedded when it matches noexcludepattern and (includeis empty, or it matches at least oneincludepattern).excludetakes priority overinclude.?matches one character other than/, and*any run of them, so a single*stays inside one path segment:include = "*.png"matcheslogo.pngbut notsub/logo.png.**crosses/. As a whole segment it stands for any number of segments, zero included, which is what makes**/*.pngthe way to say “a.pnganywhere”:pattern matches *.pnglogo.pngsub/*.pngsub/logo.png**/*.pnglogo.png,sub/logo.png,a/b/logo.pngsub/**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>.