1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
//! `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`.
//!
//! ```
//! # #[cfg(all(feature = "derive", feature = "deflate", feature = "std"))] {
//! 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.
// docs.rs builds with `--cfg docsrs` (see each manifest's
// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
// every item with the feature that gates it. Nearly all of this API is
// behind one, so without the label the rendered docs read as though it were
// all unconditional. Inert on stable, where `docsrs` is never set.
extern crate alloc;
pub use EmbeddedBytes;
pub use ;
pub use __dev_file;
pub use lookup_encrypted;
pub use ;
pub use ;
// Re-exported for advanced users who want to call a codec or cipher
// directly, or implement one of these traits for manual (non-macro) use.
// `#[derive(Embed)]` and the `embed_*!` macros only ever pick a built-in
// codec/cipher by on-binary id — they cannot use a custom implementation.
pub use Codec;
pub use Deflate;
pub use Lz4;
pub use Lzma;
pub use Snappy;
pub use Zstd;
pub use Aes256Gcm;
pub use ;
pub use ;