Skip to main content

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}