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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
//! Proc-macros for `embark`: [`embed_bytes!`], [`embed_crypt!`], and the
//! [`Embed`](macro@Embed) derive. Re-exported from the `embark` crate under
//! its `derive` feature; use them via `embark::embed_bytes!` etc. rather
//! than depending on this crate directly.
// 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.
use TokenStream;
use quote;
/// Embeds a single file's bytes at build time, expanding to an
/// [`EmbeddedBytes`](https://docs.rs/embark/*/embark/struct.EmbeddedBytes.html)
/// (or, with no `codec` argument, a plain `include_bytes!`-style
/// `&'static [u8]`).
///
/// ```ignore
/// // 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);
/// ```
///
/// <div class="warning">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).</div>
///
/// `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.
/// Embeds a single file, encrypted at build time with ChaCha20-Poly1305 (or,
/// with `cipher = aes`, AES-256-GCM), expanding to an
/// [`EncryptedFile`](https://docs.rs/embark/*/embark/struct.EncryptedFile.html),
/// generic over a type-state marker
/// ([`EmbeddedKey`](https://docs.rs/embark/*/embark/struct.EmbeddedKey.html)
/// or
/// [`RuntimeKey`](https://docs.rs/embark/*/embark/struct.RuntimeKey.html))
/// that determines which decrypt methods the resulting handle has.
///
/// ```ignore
/// // Build-time embedded key (the default): obfuscation, not security --
/// // see EncryptedFile's docs. Type is EncryptedFile<EmbeddedKey>.
/// static SECRET: embark::EncryptedFile = embark::embed_crypt!("assets/config.enc");
/// let plaintext = SECRET.decrypt();
///
/// // Runtime key: real confidentiality. No key is embedded in the binary.
/// // Type is EncryptedFile<RuntimeKey> -- note the explicit annotation.
/// static SEALED: embark::EncryptedFile<embark::RuntimeKey> =
/// embark::embed_crypt!("assets/config.enc", key = runtime);
/// let plaintext = SEALED.decrypt_with(&my_key).unwrap();
/// ```
///
/// <div class="warning">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 of the embedded-key half is on
/// [`EncryptedFile`](https://docs.rs/embark/*/embark/struct.EncryptedFile.html).
/// The runtime-key half cannot be a doctest anywhere: `key = runtime`
/// reads `EMBARK_KEY` from the environment at build time.</div>
///
/// `path` is resolved relative to `CARGO_MANIFEST_DIR`, as in
/// [`embed_bytes!`]. Independent, comma-separated arguments may follow
/// the path, in any order:
///
/// - `codec = <ident>` — compress before sealing (`store`, `deflate`,
/// `lz4`, `snappy`, `zstd`, `lzma`, or one of `auto_fast` / `auto` /
/// `auto_small`). Defaults to `deflate` when omitted. The `auto` policies
/// run the same selection pass as in [`embed_bytes!`]; compression
/// happens before sealing, so the pass reads the plaintext and the cipher
/// sees no difference. The same feature-enablement caveat as
/// [`embed_bytes!`] applies: if the named codec's feature isn't enabled
/// on `embark`, the entry silently degrades to `store` instead of failing
/// to build.
/// - `cipher = <ident>` — the AEAD cipher to seal with: `chacha`
/// (ChaCha20-Poly1305, the default) or `aes` (AES-256-GCM). Both share
/// the same key/nonce/tag shape and threat model — see the module docs'
/// security note. `cipher = aes` requires the `aes` feature enabled on
/// `embark`; naming it without that feature is a build error, not a
/// silent fallback (unlike an unavailable codec).
/// - `key = runtime` — opt into the runtime-key mode: no key material is
/// embedded, and the resulting handle (an `EncryptedFile<RuntimeKey>`)
/// must be decrypted with `decrypt_with(&key)` -- it has no `decrypt()`
/// method at all, so a binding must be explicitly typed
/// `EncryptedFile<RuntimeKey>` (plain `EncryptedFile` defaults to
/// `EncryptedFile<EmbeddedKey>` and will not accept it). Omitted by
/// default, which uses the build-time embedded-key mode
/// (**obfuscation, not security** — see `EncryptedFile`'s docs for what
/// that means and why).
/// Derives [`Embed`](https://docs.rs/embark/*/embark/trait.Embed.html) for
/// a unit struct, embedding every file under a folder at build time.
///
/// ```ignore
/// #[derive(embark::Embed)]
/// #[embark(folder = "assets", codec = "auto", include = "*.png", exclude = "*.tmp")]
/// struct Assets;
///
/// let logo = Assets::get("logo.png").unwrap();
/// for path in Assets::iter() { /* ... */ }
/// ```
///
/// <div class="warning">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 a real folder, is on
/// [`Embed`](https://docs.rs/embark/*/embark/trait.Embed.html).</div>
///
/// Configured with a single `#[embark(...)]` attribute, whose keys are:
///
/// - `folder = "..."` (required) — the directory to embed, relative to
/// `CARGO_MANIFEST_DIR`. Walked recursively; every file found becomes a
/// manifest entry, keyed by its path relative to this folder (with `/`
/// separators, even on Windows).
/// - `codec = "..."` — compression for every embedded file: `"store"`,
/// `"deflate"` (the default), `"lz4"`, `"snappy"`, `"zstd"`, `"lzma"`, or
/// one of the three selection policies `"auto_fast"`, `"auto"` and
/// `"auto_small"`, described on [`embed_bytes!`]. A policy is applied per
/// file, so one folder can end up with a different codec per entry. It
/// applies under `encrypt` too, on each file's plaintext.
/// As with `embed_bytes!`, naming a codec whose feature isn't enabled on
/// `embark` does not fail the build -- affected entries silently degrade
/// to `store` (correct, just uncompressed).
/// - `encrypt` — seal every embedded file with a single build-time
/// embedded key shared by the whole derive
/// (**obfuscation, not security** -- see `EncryptedFile`'s docs).
/// `Embed::get` then returns files decryptable with the infallible
/// `EncryptedFile::decrypt()`. There is currently no per-derive
/// `key = runtime` option; use `embed_crypt!` directly for runtime-key
/// files.
/// - `cipher = "..."` — the AEAD cipher `encrypt` seals with: `"chacha"`
/// (ChaCha20-Poly1305, the default) or `"aes"` (AES-256-GCM). Ignored
/// without `encrypt`. Both share the same threat model -- see the
/// module docs' security note. `cipher = "aes"` requires the `aes`
/// feature enabled on `embark`; naming it without that feature is a
/// build error.
/// - `dev` — in debug builds only, `get()` reads the file live from disk
/// (relative to `folder`) instead of returning the compiled-in copy, for
/// fast iteration without rebuilding. Has no effect in release builds.
///
/// It serves the files the derive embedded and nothing else: a path has
/// to be one the manifest holds, exactly, or `get()` returns `None` just
/// as the release build would. A file added to the folder since the last
/// build is not served until the crate rebuilds, and one that `exclude`
/// left out is never served. This is what keeps a development server
/// that hands out assets by request path from handing out `../.env`.
/// - `follow_links` — follow symbolic links (and, on Windows, junctions)
/// found inside the folder. Off by default, and a link met without it is
/// a build error rather than a skipped file: a link can point anywhere
/// on the build machine, and following one that points at a key or a
/// credential file embeds that file into the binary. That is a plausible
/// shape for an accident and a very plausible shape for a hostile pull
/// request. With it on, each real directory is walked once, so a link
/// back to an ancestor ends the walk instead of never ending it.
/// - `include = "..."` / `exclude = "..."` — glob filters over each file's
/// path relative to `folder`; repeatable (each occurrence adds one
/// pattern). A file is embedded when it matches no `exclude` pattern and
/// (`include` is empty, or it matches at least one `include` pattern).
/// `exclude` takes priority over `include`.
///
/// `?` matches one character other than `/`, and `*` any run of them, so
/// a single `*` stays inside one path segment: `include = "*.png"`
/// matches `logo.png` but not `sub/logo.png`.
///
/// `**` crosses `/`. As a whole segment it stands for any number of
/// segments, zero included, which is what makes `**/*.png` the way to say
/// "a `.png` anywhere":
///
/// | pattern | matches |
/// |---|---|
/// | `*.png` | `logo.png` |
/// | `sub/*.png` | `sub/logo.png` |
/// | `**/*.png` | `logo.png`, `sub/logo.png`, `a/b/logo.png` |
/// | `sub/**` | everything under `sub/`, at any depth |
/// | `**` | everything |
///
/// # Rebuilds
///
/// Every embedded file is registered as a build input, so editing or
/// deleting one of them triggers a rebuild. **Adding a new file to the
/// folder does not.** Only the files that existed when the derive last
/// expanded are tracked, and a file that has never been seen cannot be
/// among them. After adding a file, force the crate to rebuild -- touch
/// any of its `.rs` files, or run `cargo clean -p <crate>`.