Skip to main content

embark_format/
lib.rs

1//! The on-binary layout shared by every crate in the `embark` toolkit.
2//!
3//! An *entry* is one embedded file as it appears in the compiled binary: a
4//! header naming how the bytes were transformed, followed by the transformed
5//! bytes themselves. [`write_entry`] produces one at build time and
6//! [`read_header`] parses one back at runtime; the payload starts at
7//! [`Header::payload_offset`].
8//!
9//! # Entry layout
10//!
11//! | bytes | meaning |
12//! |---|---|
13//! | 1 | tag: [`CodecId`] in the low nibble, [`CryptoId`] in the high nibble |
14//! | 1..=10 | original (pre-compression) length, LEB128 varint |
15//! | 12 | AEAD nonce, present only when the crypto id is not [`CryptoId::None`] |
16//! | 16 | AEAD tag, present under the same condition |
17//! | rest | payload: compressed, then encrypted, in that order |
18//!
19//! Nothing here compresses or encrypts anything. This crate only decides
20//! where the bytes go and what the ids mean, so that `embark-codec`,
21//! `embark-crypt`, `embark-macros` and `embark` all agree on it without
22//! depending on each other.
23//!
24//! # Features
25//!
26//! `enc` compiles the build-time writing half, `dec` the runtime reading
27//! half. A consumer that only reads embedded files (the common case) needs
28//! `dec` alone. Both imply `alloc`; `std` is the default and additionally
29//! implies `alloc`.
30
31// docs.rs builds with `--cfg docsrs` (see each manifest's
32// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
33// every item with the feature that gates it. Nearly all of this API is
34// behind one, so without the label the rendered docs read as though it were
35// all unconditional. Inert on stable, where `docsrs` is never set.
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![cfg_attr(not(feature = "std"), no_std)]
38
39#[cfg(feature = "alloc")]
40extern crate alloc;
41
42mod entry;
43mod error;
44mod ids;
45mod varint;
46
47pub use entry::Header;
48#[cfg(feature = "dec")]
49pub use entry::read_header;
50#[cfg(feature = "enc")]
51pub use entry::{write_entry, write_header};
52pub use error::{Error, Result};
53pub use ids::{CodecId, CryptoId};
54pub use varint::read_varint;
55#[cfg(feature = "alloc")]
56pub use varint::write_varint;