Expand description
embark embeds files into your binary at build time, with optional
compression, encryption, and metadata — a
unified embedding layer across raw, compressed, and encrypted content.
Two front-end styles are provided:
embed_bytes!— aninclude_bytes!-style single-file macro, optionally compressed with a chosen codec (seeEmbeddedBytes).Embed(via#[derive(Embed)]) — a whole-directory embed, givingEmbed::get-by-path andEmbed::iteraccess to every file under a folder.
Encrypted content (embed_crypt!, #[embark(encrypt)]) is handled by
EncryptedFile, generic over a type-state marker
(EmbeddedKey or RuntimeKey) that determines which decrypt
methods exist on it. Read its docs before using build-time
encryption: the default mode is obfuscation, not real confidentiality
— see EncryptedFile for the distinction and how to get real
confidentiality with a runtime key.
§Example
The examples throughout these docs embed this crate’s own
examples/assets folder, so they run as written. Paths are resolved
relative to your crate’s CARGO_MANIFEST_DIR.
use embark::Embed as _;
// A single file, verbatim -- exactly `include_bytes!`.
static HELLO: &[u8] = embark::embed_bytes!("examples/assets/hello.txt");
assert_eq!(HELLO, b"hello embark");
// A single file, compressed at build time and decompressed on access.
static TEXT: embark::EmbeddedBytes =
embark::embed_bytes!("examples/assets/lipsum.txt", codec = deflate);
assert!(TEXT.data().starts_with(b"Embark packs your files"));
// A whole folder, addressable by path.
#[derive(embark::Embed)]
#[embark(folder = "examples/assets/docs", codec = "auto")]
struct Docs;
assert_eq!(Docs::iter().count(), 2);
assert!(Docs::get("about.txt").unwrap().data().starts_with(b"Embark"));§Feature flags
std— enables the#[embark(dev)]read-from-disk escape hatch and thestd::error::Errorintegration. Turning it off keeps the crateno_std;allocis always required and always linked, since every accessor returns aCowor aVec. Theallocfeature still exists and does nothing, so manifests that name it keep resolving.derive— theembed_bytes!,embed_crypt!, and#[derive(Embed)]macros (viaembark-macros).deflate,lz4,snappy,zstd,lzma— compression codecs (opt-in, pay for what you use).deflateis on by default.encryption— ChaCha20-Poly1305 AEAD support (EncryptedFile).aes— adds AES-256-GCM as a second AEAD cipher, selected per entry withembed_crypt!(..., cipher = aes)or#[embark(encrypt, cipher = "aes")](impliesencryption).metadata— per-fileEmbeddedFile::hashandEmbeddedFile::mime.parallel-encode— lets the macros compress with more than one thread at build time. On by default; it never reaches the shipped binary. SetEMBARK_ENCODE_THREADS=1to turn it off for one build.
Macros§
- embed_
bytes derive - Embeds a single file’s bytes at build time, expanding to an
EmbeddedBytes(or, with nocodecargument, a plaininclude_bytes!-style&'static [u8]). - embed_
crypt derive - Embeds a single file, encrypted at build time with ChaCha20-Poly1305 (or,
with
cipher = aes, AES-256-GCM), expanding to anEncryptedFile, generic over a type-state marker (EmbeddedKeyorRuntimeKey) that determines which decrypt methods the resulting handle has.
Structs§
- Aes256
Gcm aes - The AES-256-GCM AEAD cipher, gated behind the
aesfeature. Same key (32B), nonce (12B), and tag (16B) shape asChaCha20Poly1305. - ChaCha20
Poly1305 encryption - The built-in ChaCha20-Poly1305 AEAD cipher.
- Deflate
deflate - The DEFLATE codec (via
miniz_oxide). - Embedded
Bytes - A single, unencrypted embedded file, produced by
embed_bytes!with acodec = ...argument. - Embedded
File - A single file looked up from a
#[derive(Embed)]type viaEmbed::get, obtained vialookup/lookup_encrypted, or (in debug builds, with#[embark(dev)]) read live from disk. - Embedded
Key encryption - Type-state marker selecting
EncryptedFile’s build-time embedded-key mode – the default, so plainEncryptedFilemeansEncryptedFile<EmbeddedKey>. See the type-level docs for what that means and its obfuscation-not-security caveat. - Encrypted
File encryption - An encrypted, embedded file, produced by
embed_crypt!or#[embark(encrypt)]. - Entries
- Iterator over the paths of every file embedded in a
#[derive(Embed)]manifest, in sorted order. Returned byEmbed::iter/entries. - Lz4
lz4 - The LZ4 codec (via
lz4_flex). - Lzma
lzma - The LZMA1 codec (self-implemented
.lzmaalone format). - Manifest
- One compiled-in
(path, entry)pair in a#[derive(Embed)]manifest. - Runtime
Key encryption - Type-state marker selecting
EncryptedFile’s runtime-key mode. See the type-level docs for what that means. - Snappy
snappy - The Snappy codec (self-implemented).
- Zstd
zstd - The Zstd codec: a self-written encoder, decoding via
ruzstd.
Enums§
- Error
- Everything that can go wrong decoding an entry, shared by every crate in the toolkit.
Traits§
- Aead
encryption - An AEAD (authenticated encryption with associated data) cipher.
- Codec
- Associates a built-in codec type with its on-binary
CodecId. - Embed
- Implemented by types produced with
#[derive(Embed)], giving directory access to the files embedded from#[embark(folder = "...")]. - KeyMode
encryption - The set of
EncryptedFilekey modes:EmbeddedKeyandRuntimeKey, and nothing else.
Functions§
- entries
- Iterates every path in a
#[derive(Embed)]manifest, in sorted order. Used internally by the derive’s generatediter(); not normally called directly. - lookup
- Looks up an unencrypted, compiled-in file by path (binary search) in a
#[derive(Embed)]manifest. Used internally by the derive’s generatedget(); not normally called directly. - lookup_
encrypted encryption - Looks up a build-time-encrypted, compiled-in file by path (binary
search) in a
#[derive(Embed)]manifest, attaching its per-build key-reconstruction function. Used internally by the derive’s generatedget()when#[embark(encrypt)]is set; not normally called directly. SeeEncryptedFilefor why the build-time key is obfuscation, not security. As withlookup, the manifest has to be sorted bypath.