Skip to main content

embed_bytes

Macro embed_bytes 

Source
embed_bytes!() { /* proc-macro */ }
Available on crate feature derive only.
Expand description

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]).

ⓘ
// Zero-cost, uncompressed -- identical to include_bytes!.
static RAW: &[u8] = embark::embed_bytes!("assets/logo.png");

// Compressed with a specific codec.
static GZ: embark::EmbeddedBytes = embark::embed_bytes!("assets/data.json", codec = deflate);

// Compressed with the best size/decode-speed trade among the enabled
// codecs; `auto_fast` and `auto_small` move that balance either way.
static BEST: embark::EmbeddedBytes = embark::embed_bytes!("assets/data.json", codec = auto);
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 real files, is on [`EmbeddedBytes`](https://docs.rs/embark/*/embark/struct.EmbeddedBytes.html).

path is resolved relative to the crate’s CARGO_MANIFEST_DIR. The optional codec = <ident> argument names either one codec – store, deflate, lz4, snappy, zstd or lzma – or one of the three auto policies, which compress with a tier of candidates at build time and keep the smallest output among that tier:

policycandidates
auto_faststore, lz4, snappy
autothose, plus deflate and zstd
auto_smallthose, plus lzma

Compression runs once, here; decompression runs in the shipped binary on every access. The tiers are cut along that second axis. On a 468 KiB executable, auto_fast picks LZ4 at 312,340 bytes and 1,744 MB/s, auto picks DEFLATE at 228,157 bytes and 305 MB/s, and auto_small picks LZMA at 191,493 bytes and 45 MB/s. All three fall back to store when nothing shrinks the file.

A policy encodes only with its own candidates, so auto_fast never pays LZMA’s build-time encode cost to then throw the result away.

Codecs and enabled features: the codec ident you name here must correspond to a codec feature enabled on the embark crate you decode with. If it isn’t enabled, encoding does not fail – the entry silently degrades to store (uncompressed) instead, since encoding never fails and correct but uncompressed output is still correct. Enable the matching feature (deflate, lz4, snappy, zstd, lzma) if you expect compression to actually happen. The auto policies can only pick an enabled codec by construction, and a policy whose whole tier is disabled widens to the next one rather than degrading to store: with only lzma on, auto_fast still compresses.