embed_bytes!() { /* proc-macro */ }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);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:
| policy | candidates |
|---|---|
auto_fast | store, lz4, snappy |
auto | those, plus deflate and zstd |
auto_small | those, 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.