rapidproto_build/lib.rs
1//! Generates Rust decoders for Protobuf schemas in a build script, without `protoc`.
2//!
3//! The decoders use the [`rapidproto`] runtime. Add `rapidproto` to your dependencies and
4//! `rapidproto-build` to your build dependencies, both pinned to the same version with `=`. The
5//! runtime's [`example`] module shows a schema and the code generated for it.
6//!
7//! Use [`Config`] in `build.rs`:
8//!
9//! ```no_run
10//! // build.rs
11//! rapidproto_build::Config::new("crate::schema")
12//! .include("proto")
13//! .compile(&["proto/message.proto"])
14//! .expect("generate decoders");
15//! ```
16//!
17//! [`Config::compile`] writes `message.rs` to `OUT_DIR`, named after the first entry. Include it at the
18//! path you passed to [`Config::new`], and decode with it:
19//!
20//! ```ignore
21//! mod schema {
22//! include!(concat!(env!("OUT_DIR"), "/message.rs"));
23//! }
24//!
25//! // For `package shop;` and `message Order` in message.proto:
26//! let arena = rapidproto::Arena::new();
27//! let order = schema::arena::shop::Order::decode(&input, &arena)?;
28//! ```
29//!
30//! `Config` generates arena decoders by default. It can also generate [stream decoders], apply a
31//! [decode profile], and implement [`serde::Serialize`]. To get the code as a string instead of a
32//! file, use [`Config::generate`]. Imports of the well-known types, such as
33//! `google/protobuf/timestamp.proto`, resolve without the files.
34//!
35//! The command-line tool `rapidproto-rust` generates the same code, for projects that commit it.
36//! Install it with `cargo install rapidproto-build --version 0.1.0-alpha.2`, and see
37//! `rapidproto-rust --help` for its options.
38//!
39//! # How the generator runs
40//!
41//! The generator is written in C++, and two features choose how it runs. With `native`, this crate's
42//! build script compiles it, which needs a C++17 compiler. With `wasm`, it runs as an embedded
43//! WebAssembly module in the `wasmi` interpreter, which needs no compiler. Both produce the same
44//! output.
45//!
46//! Both features are on by default. The native generator is used when it builds, and the wasm one
47//! otherwise, which [`Config::compile`] then warns about. If you have a C++ compiler,
48//! `default-features = false, features = ["native"]` avoids building the interpreter. To use the wasm
49//! generator on purpose, without the warning, enable only `wasm`.
50//!
51//! Cargo builds build-time code without optimization, so the interpreter is slow by default. It takes
52//! seconds for a small schema and minutes for a very large one. If you use the wasm generator,
53//! optimize build-time code in your workspace:
54//!
55//! ```toml
56//! [profile.dev.build-override]
57//! opt-level = 3
58//! [profile.release.build-override]
59//! opt-level = 3
60//! ```
61//!
62//! [`rapidproto`]: https://docs.rs/rapidproto/latest/rapidproto/
63//! [`example`]: https://docs.rs/rapidproto/latest/rapidproto/example/index.html
64//! [stream decoders]: Config::stream
65//! [decode profile]: Config::field_modes
66//! [`serde::Serialize`]: Config::serde
67#![warn(missing_docs)]
68
69use std::collections::btree_map::Entry;
70use std::collections::{BTreeMap, BTreeSet};
71use std::env;
72use std::path::{Component, Path, PathBuf};
73use std::sync::{Mutex, PoisonError};
74
75/// Why this build uses the wasm generator although the `native` feature is on: the reason the
76/// native one did not build. `None` when it built, or was not asked for.
77#[doc(hidden)]
78pub const NATIVE_FALLBACK: Option<&str> = option_env!("RAPIDPROTO_BUILD_FALLBACK");
79
80/// One in-memory source file: `name` is how an `import` refers to it (e.g. `"types.proto"`), and
81/// `body` is its text.
82#[doc(hidden)]
83pub struct SourceFile {
84 /// How an `import` statement spells this file (e.g. `"types.proto"`).
85 pub name: String,
86 /// The file's `.proto` text.
87 pub body: String,
88}
89
90/// The inputs for one generation: the entry files (the roots of the import closure, each named the
91/// way an `import` would spell it), the sources those entries and their imports may pull in (a
92/// superset is fine — only what the closure reaches is used), and the generation options.
93#[doc(hidden)]
94pub struct Request {
95 /// The entry `.proto`s, named as an `import` would spell them.
96 pub entries: Vec<String>,
97 /// The entries and every file they may import (a superset is fine).
98 pub sources: Vec<SourceFile>,
99 /// A decode profile — the text of a `.modes` file (`drop` / `raw` / `unknown-fields` lines) — or
100 /// empty for the default (decode every field).
101 pub modes: String,
102 /// Reserve space to track unknown fields on every message (see [`Config::unknown_present`]).
103 pub unknown_present: bool,
104 /// Emit the random-access `arena` decoder model (default on; see [`Config::arena`]).
105 pub arena: bool,
106 /// Emit the `stream` visitor model (default off; see [`Config::stream`]).
107 pub stream: bool,
108 /// Implement `serde::Serialize` (default off; see [`Config::serde`]).
109 pub serde: bool,
110 /// Where the generated file is included (see [`Config::new`]).
111 pub module_path: String,
112}
113
114impl Default for Request {
115 /// No entries or sources, no decode profile, the `arena` model only, included at the crate root.
116 fn default() -> Self {
117 Request {
118 entries: Vec::new(),
119 sources: Vec::new(),
120 modes: String::new(),
121 unknown_present: false,
122 arena: true,
123 stream: false,
124 serde: false,
125 module_path: "crate".to_owned(),
126 }
127 }
128}
129
130/// An error from the generator.
131#[derive(Debug)]
132pub struct GenError {
133 /// The generator's status: 2 for a malformed request, 3 for a schema that does not resolve, 4 for
134 /// a bad decode profile; negative for an I/O or internal failure. The tests and the CLI read it.
135 #[doc(hidden)]
136 pub code: i32,
137 /// A description of the failure.
138 pub message: String,
139}
140
141impl std::fmt::Display for GenError {
142 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
143 write!(
144 f,
145 "generator failed (status {}): {}",
146 self.code, self.message
147 )
148 }
149}
150
151impl std::error::Error for GenError {}
152
153/// Encodes a [`Request`] into the byte frame the generator takes, through either backend: a `RPWF5`
154/// magic, then little-endian-u32-counted entry names, u32-counted `{name, body}` sources, the
155/// `.modes` text, a one-byte unknown-present flag, two one-byte model flags (arena, stream), a one-byte
156/// serde flag, and the module path. Bodies are length-prefixed, so a proto's newlines/quotes need no
157/// escaping. The generator validates the options; the decode side is `rapidproto/rustgen/frame.hpp`
158/// in the repository.
159mod frame {
160 use super::{GenError, Request};
161
162 /// Write a u32 little-endian count/length, rejecting (never truncating) a value past u32::MAX --
163 /// so a pathologically large source can't silently wrap its length prefix and corrupt the frame.
164 fn put_len(buf: &mut Vec<u8>, n: usize) -> Result<(), GenError> {
165 let len = u32::try_from(n).map_err(|_| GenError {
166 code: -1,
167 message: format!("frame field too large: {n} bytes (max {})", u32::MAX),
168 })?;
169 buf.extend_from_slice(&len.to_le_bytes());
170 Ok(())
171 }
172
173 fn put_bytes(buf: &mut Vec<u8>, bytes: &[u8]) -> Result<(), GenError> {
174 put_len(buf, bytes.len())?;
175 buf.extend_from_slice(bytes);
176 Ok(())
177 }
178
179 pub(super) fn encode(request: &Request) -> Result<Vec<u8>, GenError> {
180 let mut buf = Vec::new();
181 buf.extend_from_slice(b"RPWF5\n");
182 put_len(&mut buf, request.entries.len())?;
183 for entry in &request.entries {
184 put_bytes(&mut buf, entry.as_bytes())?;
185 }
186 put_len(&mut buf, request.sources.len())?;
187 for source in &request.sources {
188 put_bytes(&mut buf, source.name.as_bytes())?;
189 put_bytes(&mut buf, source.body.as_bytes())?;
190 }
191 put_bytes(&mut buf, request.modes.as_bytes())?;
192 buf.push(u8::from(request.unknown_present));
193 buf.push(u8::from(request.arena));
194 buf.push(u8::from(request.stream));
195 buf.push(u8::from(request.serde));
196 put_bytes(&mut buf, request.module_path.as_bytes())?;
197 Ok(buf)
198 }
199}
200
201/// A way to run the generator (see [How the generator runs](crate#how-the-generator-runs)).
202#[doc(hidden)]
203#[derive(Clone, Copy, Debug, PartialEq, Eq)]
204pub enum Backend {
205 #[cfg(rp_native)]
206 Native,
207 #[cfg(feature = "wasm")]
208 Wasm,
209}
210
211/// The backends this build has, the one [`Config`] uses first.
212#[doc(hidden)]
213pub const BACKENDS: &[Backend] = &[
214 #[cfg(rp_native)]
215 Backend::Native,
216 #[cfg(feature = "wasm")]
217 Backend::Wasm,
218];
219
220/// Run the generator on `request` through a given backend. Public for checking that the backends agree.
221#[doc(hidden)]
222pub fn generate_with(backend: Backend, request: &Request) -> Result<String, GenError> {
223 let frame = frame::encode(request)?;
224 let (status, text) = match backend {
225 #[cfg(rp_native)]
226 Backend::Native => native::run(&frame)?,
227 #[cfg(feature = "wasm")]
228 Backend::Wasm => wasm::run(frame)?,
229 };
230 if status == 0 {
231 Ok(String::from_utf8_lossy(&text).into_owned())
232 } else {
233 Err(GenError {
234 code: status,
235 message: String::from_utf8_lossy(&text).trim_end().to_owned(),
236 })
237 }
238}
239
240/// The generator compiled by the build script, called in-process through its C ABI
241/// (src/rustgen/native_entry.cpp in the repository).
242#[cfg(rp_native)]
243mod native {
244 use std::ffi::{c_char, c_int, c_void};
245
246 use super::{internal, GenError};
247
248 type Sink = extern "C" fn(context: *mut c_void, data: *const c_char, len: usize);
249
250 extern "C" {
251 fn rapidproto_rustgen_run(
252 frame: *const c_char,
253 frame_len: usize,
254 sink: Sink,
255 context: *mut c_void,
256 ) -> c_int;
257 }
258
259 // The stack the generator gets, as much as the wasm module links with: room for the parser's and
260 // resolver's depth-capped recursion on a deep schema, whatever thread the caller is on.
261 const STACK_BYTES: usize = 8 << 20;
262
263 /// The generator's status and its output (the generated Rust, or the error message).
264 pub(super) fn run(frame: &[u8]) -> Result<(i32, Vec<u8>), GenError> {
265 std::thread::scope(|scope| {
266 std::thread::Builder::new()
267 .stack_size(STACK_BYTES)
268 .spawn_scoped(scope, || call(frame))
269 .map_err(internal)?
270 .join()
271 .map_err(|_| internal("the native generator panicked"))
272 })
273 }
274
275 fn call(frame: &[u8]) -> (i32, Vec<u8>) {
276 // Copies the output the generator hands over; `context` is the `Vec` below.
277 extern "C" fn sink(context: *mut c_void, data: *const c_char, len: usize) {
278 // SAFETY: `context` is the `&mut Vec<u8>` passed to the call, alive and unaliased for its
279 // duration; `data` is valid for `len` bytes during this callback.
280 unsafe {
281 let out = &mut *context.cast::<Vec<u8>>();
282 out.extend_from_slice(std::slice::from_raw_parts(data.cast::<u8>(), len));
283 }
284 }
285 let mut text = Vec::new();
286 // SAFETY: `frame` is valid for `frame.len()` bytes, and `sink` and `context` fit each other;
287 // the generator calls `sink` once, before returning, and lets no exception escape.
288 let status = unsafe {
289 rapidproto_rustgen_run(
290 frame.as_ptr().cast(),
291 frame.len(),
292 sink,
293 std::ptr::from_mut(&mut text).cast(),
294 )
295 };
296 if status == -1 {
297 let detail = String::from_utf8_lossy(&text);
298 text = format!("internal error in the native generator: {detail}").into_bytes();
299 }
300 (status, text)
301 }
302}
303
304/// The embedded wasm generator in the wasmi interpreter: the frame as stdin, the output on stdout or
305/// stderr, the status as the exit code.
306#[cfg(feature = "wasm")]
307mod wasm {
308 use std::io::Cursor;
309 use std::sync::OnceLock;
310
311 use wasmi::{Engine, Linker, Module, Store};
312 use wasmi_wasi::sync::WasiCtxBuilder;
313 use wasmi_wasi::wasi_common::pipe::{ReadPipe, WritePipe};
314 use wasmi_wasi::WasiCtx;
315
316 use super::{internal, GenError};
317
318 /// The embedded generator. Rebuilt by `wasm/build-wasm.sh` and byte-checked in CI, so it stays
319 /// in sync with the generator source.
320 const RUSTGEN_WASM: &[u8] = include_bytes!("../wasm/rustgen.wasm");
321
322 /// The generator's status and its output (the generated Rust, or the error message).
323 pub(super) fn run(frame: Vec<u8>) -> Result<(i32, Vec<u8>), GenError> {
324 // Validating the embedded generator is the one expensive step, and it never changes, so
325 // compile it once and reuse it: a caller that generates many files pays that cost once, not
326 // per file. Only the lightweight Store/instance is per-call.
327 let (engine, module) = compiled();
328
329 // In-memory stdio: feed the frame as stdin, capture stdout/stderr. The pipes are cloneable
330 // handles over a shared buffer; the WasiCtx holds one clone, we keep one to read afterwards.
331 let stdout = WritePipe::new_in_memory();
332 let stderr = WritePipe::new_in_memory();
333 let wasi = WasiCtxBuilder::new()
334 .stdin(Box::new(ReadPipe::from(frame)))
335 .stdout(Box::new(stdout.clone()))
336 .stderr(Box::new(stderr.clone()))
337 .build();
338
339 let mut store = Store::new(engine, wasi);
340 let mut linker: Linker<WasiCtx> = Linker::new(engine);
341 wasmi_wasi::sync::add_to_linker(&mut linker, |ctx| ctx).map_err(internal)?;
342
343 let instance = linker
344 .instantiate_and_start(&mut store, module)
345 .map_err(internal)?;
346 let start = instance
347 .get_typed_func::<(), ()>(&store, "_start")
348 .map_err(internal)?;
349 let run = start.call(&mut store, ());
350
351 // Drop the store so its clone of the pipe buffers is released; then we are the sole owner
352 // and can take the captured bytes out.
353 drop(store);
354 let exit = match run {
355 Ok(()) => 0,
356 // A WASI `proc_exit(n)` surfaces as this; anything else is a real trap, not a clean exit.
357 Err(error) => match error.i32_exit_status() {
358 Some(code) => code,
359 None => return Err(internal(error)),
360 },
361 };
362 Ok((exit, take(if exit == 0 { stdout } else { stderr })))
363 }
364
365 /// The embedded generator, compiled once and reused across calls. It is a fixed, build-time
366 /// asset, so a compile failure here means a broken build, not a runtime condition -- hence the
367 /// panic.
368 fn compiled() -> &'static (Engine, Module) {
369 static CELL: OnceLock<(Engine, Module)> = OnceLock::new();
370 CELL.get_or_init(|| {
371 let engine = Engine::default();
372 let module = Module::new(&engine, RUSTGEN_WASM)
373 .expect("the embedded generator is a valid module");
374 (engine, module)
375 })
376 }
377
378 /// Take the bytes a finished in-memory pipe captured (sole owner by now).
379 fn take(pipe: WritePipe<Cursor<Vec<u8>>>) -> Vec<u8> {
380 pipe.try_into_inner()
381 .expect("pipe still shared after the store was dropped")
382 .into_inner()
383 }
384}
385
386/// A failure inside the runtime (not a clean generator error): no exit code, so report it as -1.
387fn internal(error: impl std::fmt::Display) -> GenError {
388 GenError {
389 code: -1,
390 message: error.to_string(),
391 }
392}
393
394/// Options for generating decoders.
395///
396/// The [crate docs](crate) show how to use it in `build.rs`.
397#[derive(Debug)]
398pub struct Config {
399 module_path: String,
400 includes: Vec<PathBuf>,
401 modes: String,
402 unknown_present: bool,
403 arena: bool,
404 stream: bool,
405 serde: bool,
406 backend: Backend,
407}
408
409impl Config {
410 /// Creates a config for code included at `module_path`.
411 ///
412 /// The config generates arena decoders with no decode profile, and resolves imports in the current
413 /// directory, which is the package root in a build script.
414 ///
415 /// `module_path` is `crate` for the crate root, or a path from it such as `crate::schema`. Its
416 /// segments are ASCII identifiers. Write a keyword as a raw identifier, such as `r#type`.
417 ///
418 /// The generated code names its own types through this path, so it must lead to where you
419 /// `include!` the file. A wrong path fails to compile.
420 ///
421 /// Include a file once per crate, and not inside a function. A doctest counts as a function unless
422 /// it declares `fn main`. Each generated file needs its own path, so two files in one crate need
423 /// two `Config`s. A lib, a bin and each file in `tests/` are separate crates, so each can include
424 /// the same file at the same path.
425 pub fn new(module_path: impl Into<String>) -> Self {
426 Config {
427 module_path: module_path.into(),
428 includes: Vec::new(),
429 modes: String::new(),
430 unknown_present: false,
431 arena: true,
432 stream: false,
433 serde: false,
434 backend: BACKENDS[0],
435 }
436 }
437
438 /// Adds a directory to search for `.proto` files.
439 ///
440 /// Once you add one, the current directory is no longer searched. If several directories have the
441 /// same file, the first one added wins.
442 pub fn include(mut self, dir: impl Into<PathBuf>) -> Self {
443 self.includes.push(dir.into());
444 self
445 }
446
447 /// Sets a decode profile, which changes what the arena decoders store.
448 ///
449 /// `modes` holds one directive per line, and `#` starts a comment:
450 ///
451 /// - `drop pkg.Msg.field` removes the field and its accessor.
452 /// - `raw pkg.Msg.field` keeps a message or group field as its encoded message. The accessor
453 /// returns it as [`ProtoBytes`], in an `Option` for a singular field and in a slice for a
454 /// `repeated` one, ready for the field type's `decode`.
455 /// - `unknown-fields pkg.Msg` adds `has_unknown_fields()` to the message.
456 ///
457 /// `drop` and `raw` also take a message type, `pkg.Msg`, to cover every field of that type, and
458 /// `drop` takes an enum type the same way. A directive for a field wins over one for its type.
459 /// Neither applies to a `oneof` member, `raw` does not apply to a `map` field, and `drop` does
460 /// not apply to a `required` field. Naming such a field fails, and a directive for its type
461 /// leaves it as it is. Stream decoders ignore the profile.
462 ///
463 /// ```no_run
464 /// // build.rs
465 /// rapidproto_build::Config::new("crate::schema")
466 /// .field_modes("drop shop.Order.notes\nraw shop.Order.items")
467 /// .compile(&["shop.proto"])
468 /// .expect("generate decoders");
469 /// ```
470 ///
471 /// [`ProtoBytes`]: https://docs.rs/rapidproto/latest/rapidproto/struct.ProtoBytes.html
472 pub fn field_modes(mut self, modes: impl Into<String>) -> Self {
473 self.modes = modes.into();
474 self
475 }
476
477 /// Adds `has_unknown_fields()` to every arena message.
478 ///
479 /// It returns `true` if the encoded message had a field the schema does not declare. Unknown
480 /// fields inside a sub-message do not count.
481 pub fn unknown_present(mut self, yes: bool) -> Self {
482 self.unknown_present = yes;
483 self
484 }
485
486 /// Generates arena decoders, which decode the whole message into an [`Arena`].
487 ///
488 /// They are on by default. At least one of `arena` and [`stream`](Config::stream) must be on.
489 ///
490 /// [`Arena`]: https://docs.rs/rapidproto/latest/rapidproto/struct.Arena.html
491 pub fn arena(mut self, yes: bool) -> Self {
492 self.arena = yes;
493 self
494 }
495
496 /// Generates stream decoders, which pass the fields you select to your handlers.
497 ///
498 /// They are off by default. The [`rapidproto::stream`] docs show how to use them.
499 ///
500 /// Each message gets a `msg_stream!` macro, which builds a visitor from your handlers. The macro
501 /// expands where you call it and reaches the rest of the generated code through the path given to
502 /// [`Config::new`], so each module on that path must be visible from the call. Make the
503 /// modules `pub` to call it from `tests/` or another crate. To call it from elsewhere in the
504 /// crate, a module nested below the crate root needs `pub(crate)`.
505 ///
506 /// A `proc-macro` crate cannot export macros, so stream decoders do not compile there. Put the
507 /// generated code in a separate crate instead.
508 ///
509 /// [`rapidproto::stream`]: https://docs.rs/rapidproto/latest/rapidproto/stream/index.html
510 pub fn stream(mut self, yes: bool) -> Self {
511 self.stream = yes;
512 self
513 }
514
515 /// Implements `serde::Serialize` for the arena messages and the types generated for the schema's
516 /// enums.
517 ///
518 /// It is off by default. When it is on, the generated code needs the `serde` feature of
519 /// `rapidproto`, and does not compile without it. The [`rapidproto` docs] describe the output.
520 ///
521 /// To make this optional in your own crate, declare a `serde` feature that enables
522 /// `rapidproto/serde`, and read it in `build.rs`:
523 ///
524 /// ```no_run
525 /// // build.rs
526 /// rapidproto_build::Config::new("crate::schema")
527 /// .serde(std::env::var_os("CARGO_FEATURE_SERDE").is_some())
528 /// .compile(&["message.proto"])
529 /// .expect("generate decoders");
530 /// ```
531 ///
532 /// [`rapidproto` docs]: https://docs.rs/rapidproto/latest/rapidproto/#serde
533 pub fn serde(mut self, yes: bool) -> Self {
534 self.serde = yes;
535 self
536 }
537
538 /// Generate through `backend` instead of the default one -- for checking that the backends agree.
539 #[doc(hidden)]
540 pub fn backend(mut self, backend: Backend) -> Self {
541 self.backend = backend;
542 self
543 }
544
545 /// Generates decoders for `entries` and everything they import, and returns the code.
546 ///
547 /// Imports resolve against every `.proto` file under the include directories. An entry is named by
548 /// its path relative to the first include directory that holds it, or by its file name if none
549 /// does. [`Config::compile`] also writes the file and tells cargo when to re-run the build script.
550 pub fn generate(&self, entries: &[impl AsRef<Path>]) -> Result<String, GenError> {
551 // Canonicalize the include dirs once, so the source walk and the entry-key derivation compare
552 // paths in the same absolute/normalized/symlink-resolved terms. Without this a `./`-prefixed
553 // or relative-vs-absolute entry path would key differently from how an import names the same
554 // file, splitting the closure into two entries.
555 let includes: Vec<PathBuf> = self
556 .include_dirs()
557 .iter()
558 .map(|dir| {
559 dir.canonicalize()
560 .map_err(|e| internal(format!("include dir {}: {e}", dir.display())))
561 })
562 .collect::<Result<_, _>>()?;
563
564 let mut sources: BTreeMap<String, String> = BTreeMap::new();
565 for include in &includes {
566 collect_protos(include, include, &mut sources).map_err(internal)?;
567 }
568 let mut entry_names = Vec::with_capacity(entries.len());
569 for entry in entries {
570 let entry = entry.as_ref();
571 let canonical = entry
572 .canonicalize()
573 .map_err(|e| internal(format!("entry {}: {e}", entry.display())))?;
574 let name = import_relative_name(&canonical, &includes);
575 let body = read(&canonical).map_err(internal)?;
576 sources.insert(name.clone(), body);
577 entry_names.push(name);
578 }
579 let request = Request {
580 entries: entry_names,
581 sources: sources
582 .into_iter()
583 .map(|(name, body)| SourceFile { name, body })
584 .collect(),
585 modes: self.modes.clone(),
586 unknown_present: self.unknown_present,
587 arena: self.arena,
588 stream: self.stream,
589 serde: self.serde,
590 module_path: self.module_path.clone(),
591 };
592 generate_with(self.backend, &request)
593 }
594
595 /// Generates decoders for `entries` and everything they import, writes them to `OUT_DIR`, and
596 /// returns the file's path.
597 ///
598 /// The file is named after the first entry, so `proto/message.proto` gives `message.rs`. A second
599 /// call whose first entry has the same name, such as `other/message.proto`, fails. Use
600 /// [`Config::generate`] to write such files under names of your own.
601 ///
602 /// Cargo re-runs the build script when an entry or a `.proto` file under the include directories
603 /// changes.
604 pub fn compile(&self, entries: &[impl AsRef<Path>]) -> Result<PathBuf, GenError> {
605 // Warned from here, the consumer's own build script, because cargo hides the warnings of a
606 // dependency's build script.
607 if let Some(reason) = NATIVE_FALLBACK {
608 static WARNED: std::sync::Once = std::sync::Once::new();
609 WARNED.call_once(|| {
610 println!(
611 "cargo:warning=rapidproto-build uses the slower wasm generator: the native one \
612 did not build, {reason}. To use the wasm one on purpose, depend on \
613 rapidproto-build with `default-features = false, features = [\"wasm\"]`."
614 );
615 });
616 }
617 let out_dir = env::var_os("OUT_DIR").ok_or_else(|| GenError {
618 code: -1,
619 message: "compile(): OUT_DIR is unset -- call it from a cargo build script".to_owned(),
620 })?;
621 // One file covers the whole closure; name it after the first entry's stem, so several
622 // compile() calls in one build script land in distinct files.
623 let stem = entries
624 .first()
625 .and_then(|e| e.as_ref().file_stem())
626 .map_or_else(|| "schema".to_owned(), |s| s.to_string_lossy().into_owned());
627 let out_path = PathBuf::from(out_dir).join(format!("{stem}.rs"));
628 // A build script runs once per process, so this remembers the files of this build only.
629 // Checked before generating, so a clash fails fast.
630 static WRITTEN: Mutex<BTreeSet<PathBuf>> = Mutex::new(BTreeSet::new());
631 let first = WRITTEN
632 .lock()
633 .unwrap_or_else(PoisonError::into_inner)
634 .insert(out_path.clone());
635 if !first {
636 return Err(GenError {
637 code: -1,
638 message: format!(
639 "compile(): an earlier call in this build script also writes {stem}.rs, \
640 since each call names its file after its first entry. Use generate() and \
641 write the files under names of your own"
642 ),
643 });
644 }
645 let code = self.generate(entries)?;
646 std::fs::write(&out_path, code).map_err(|e| GenError {
647 code: -1,
648 message: format!("compile(): cannot write {}: {e}", out_path.display()),
649 })?;
650
651 // Rebuild tracking: the entries themselves, plus every proto on the include path. Watching the
652 // whole include path (not just the resolved closure, which the generator does not report) is
653 // deliberately broad: a build never goes stale, at the cost of an occasional rebuild when an
654 // unrelated proto on the path changes.
655 for entry in entries {
656 println!("cargo:rerun-if-changed={}", entry.as_ref().display());
657 }
658 for dir in &self.include_dirs() {
659 track_protos(dir);
660 }
661 Ok(out_path)
662 }
663
664 /// The include path: the added directories, or the cwd (the crate root in a build script) when
665 /// none was added.
666 fn include_dirs(&self) -> Vec<PathBuf> {
667 if self.includes.is_empty() {
668 vec![PathBuf::from(".")]
669 } else {
670 self.includes.clone()
671 }
672 }
673}
674
675/// Emit `cargo:rerun-if-changed` for every `.proto` under `dir` (recursively). An unreadable dir is
676/// skipped silently -- it just means nothing there is tracked, and a real missing include surfaces as
677/// a generation error, not here.
678fn track_protos(dir: &Path) {
679 let Ok(entries) = std::fs::read_dir(dir) else {
680 return;
681 };
682 for entry in entries.flatten() {
683 let path = entry.path();
684 if path.is_dir() {
685 track_protos(&path);
686 } else if path.extension().is_some_and(|e| e == "proto") {
687 println!("cargo:rerun-if-changed={}", path.display());
688 }
689 }
690}
691
692/// The name an `import` would use for `entry`: its path relative to the first `includes` directory
693/// that contains it, otherwise its file name. `entry` and `includes` must already be canonicalized
694/// (see [`Config::generate`]) so the prefix comparison is done in matching terms.
695fn import_relative_name(entry: &Path, includes: &[PathBuf]) -> String {
696 for include in includes {
697 if let Ok(rel) = entry.strip_prefix(include) {
698 return to_slash(rel);
699 }
700 }
701 entry
702 .file_name()
703 .map(|n| n.to_string_lossy().into_owned())
704 .unwrap_or_default()
705}
706
707/// Recursively add every `.proto` under `dir`, keyed by its path relative to `root` (the include
708/// dir), in forward-slash form so the key matches an `import` string on any platform. Only `dir`
709/// itself must be readable: below it, a directory or file that cannot be read (or is not UTF-8) is
710/// skipped -- over-inclusion is harmless, and an import that needed it still fails as a missing
711/// import. So pointing the include path at a large tree (the CLI's cwd default) cannot fail on an
712/// unrelated file.
713fn collect_protos(
714 root: &Path,
715 dir: &Path,
716 out: &mut BTreeMap<String, String>,
717) -> Result<(), String> {
718 let entries = std::fs::read_dir(dir)
719 .map_err(|e| format!("cannot read include dir {}: {e}", dir.display()))?;
720 for entry in entries.flatten() {
721 let path = entry.path();
722 let Ok(file_type) = entry.file_type() else {
723 continue;
724 };
725 if file_type.is_dir() {
726 let _ = collect_protos(root, &path, out); // an unreadable subdirectory is skipped
727 } else if path.extension().is_some_and(|e| e == "proto") {
728 let rel = path.strip_prefix(root).unwrap_or(&path);
729 // First include dir wins (like protoc): read and keep this file only if an earlier
730 // include dir has not already provided the same key.
731 if let Entry::Vacant(slot) = out.entry(to_slash(rel)) {
732 if let Ok(body) = std::fs::read_to_string(&path) {
733 slot.insert(body);
734 }
735 }
736 }
737 }
738 Ok(())
739}
740
741fn read(path: &Path) -> Result<String, String> {
742 std::fs::read_to_string(path).map_err(|e| format!("cannot read {}: {e}", path.display()))
743}
744
745/// Forward-slash rendering of a relative path (import keys are `/`-separated regardless of OS).
746fn to_slash(path: &Path) -> String {
747 path.components()
748 .filter_map(|c| match c {
749 Component::Normal(s) => Some(s.to_string_lossy()),
750 _ => None,
751 })
752 .collect::<Vec<_>>()
753 .join("/")
754}