Skip to main content

Crate embark

Crate embark 

Source
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! — an include_bytes!-style single-file macro, optionally compressed with a chosen codec (see EmbeddedBytes).
  • Embed (via #[derive(Embed)]) — a whole-directory embed, giving Embed::get-by-path and Embed::iter access 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 the std::error::Error integration. Turning it off keeps the crate no_std; alloc is always required and always linked, since every accessor returns a Cow or a Vec. The alloc feature still exists and does nothing, so manifests that name it keep resolving.
  • derive — the embed_bytes!, embed_crypt!, and #[derive(Embed)] macros (via embark-macros).
  • deflate, lz4, snappy, zstd, lzma — compression codecs (opt-in, pay for what you use). deflate is on by default.
  • encryption — ChaCha20-Poly1305 AEAD support (EncryptedFile).
  • aes — adds AES-256-GCM as a second AEAD cipher, selected per entry with embed_crypt!(..., cipher = aes) or #[embark(encrypt, cipher = "aes")] (implies encryption).
  • metadata — per-file EmbeddedFile::hash and EmbeddedFile::mime.
  • parallel-encode — lets the macros compress with more than one thread at build time. On by default; it never reaches the shipped binary. Set EMBARK_ENCODE_THREADS=1 to turn it off for one build.

Macros§

embed_bytesderive
Embeds a single file’s bytes at build time, expanding to an EmbeddedBytes (or, with no codec argument, a plain include_bytes!-style &'static [u8]).
embed_cryptderive
Embeds a single file, encrypted at build time with ChaCha20-Poly1305 (or, with cipher = aes, AES-256-GCM), expanding to an EncryptedFile, generic over a type-state marker (EmbeddedKey or RuntimeKey) that determines which decrypt methods the resulting handle has.

Structs§

Aes256Gcmaes
The AES-256-GCM AEAD cipher, gated behind the aes feature. Same key (32B), nonce (12B), and tag (16B) shape as ChaCha20Poly1305.
ChaCha20Poly1305encryption
The built-in ChaCha20-Poly1305 AEAD cipher.
Deflatedeflate
The DEFLATE codec (via miniz_oxide).
EmbeddedBytes
A single, unencrypted embedded file, produced by embed_bytes! with a codec = ... argument.
EmbeddedFile
A single file looked up from a #[derive(Embed)] type via Embed::get, obtained via lookup / lookup_encrypted, or (in debug builds, with #[embark(dev)]) read live from disk.
EmbeddedKeyencryption
Type-state marker selecting EncryptedFile’s build-time embedded-key mode – the default, so plain EncryptedFile means EncryptedFile<EmbeddedKey>. See the type-level docs for what that means and its obfuscation-not-security caveat.
EncryptedFileencryption
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 by Embed::iter / entries.
Lz4lz4
The LZ4 codec (via lz4_flex).
Lzmalzma
The LZMA1 codec (self-implemented .lzma alone format).
Manifest
One compiled-in (path, entry) pair in a #[derive(Embed)] manifest.
RuntimeKeyencryption
Type-state marker selecting EncryptedFile’s runtime-key mode. See the type-level docs for what that means.
Snappysnappy
The Snappy codec (self-implemented).
Zstdzstd
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§

Aeadencryption
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 = "...")].
KeyModeencryption
The set of EncryptedFile key modes: EmbeddedKey and RuntimeKey, and nothing else.

Functions§

entries
Iterates every path in a #[derive(Embed)] manifest, in sorted order. Used internally by the derive’s generated iter(); 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 generated get(); not normally called directly.
lookup_encryptedencryption
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 generated get() when #[embark(encrypt)] is set; not normally called directly. See EncryptedFile for why the build-time key is obfuscation, not security. As with lookup, the manifest has to be sorted by path.

Type Aliases§

Result
The toolkit’s Result, defaulting its error type to Error.

Derive Macros§

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