Skip to main content

miniextendr_api/
wasm_registry_writer.rs

1//! Host-time generator of `wasm_registry.rs` — the WASM-side replacement for
2//! `linkme`'s runtime distributed-slice gather.
3//!
4//! On native installs, `tools/write-wrappers.R` loads the linked package `.so`, which runs
5//! [`crate::wasm_registry_writer::write_wasm_registry_to_file`] to emit
6//! Rust source listing every registered `.Call` routine
7//! ([`crate::registry::call_defs`]: `MX_CALL_DEFS` and the sidecar setters R
8//! may reach) and every `MX_ALTREP_REGISTRATIONS` / `MX_TRAIT_DISPATCH` entry
9//! as `extern "C-unwind" {}` declarations + ordinary `&[T]` static slices,
10//! plus the crate's `MX_CONVERSION_ERROR_CLASS` classes.
11//! On `wasm32-*` targets, the user crate compiles that
12//! file in place of the linkme distributed_slices (`miniextendr_init!` emits
13//! the wasm32-gated `mod __miniextendr_wasm_registry;` that includes it).
14//!
15//! The writer is intentionally pure-text-formatting — no `syn`, no
16//! `proc-macro2`, no template engine. Registration rows are sorted so linker
17//! table order does not affect the output; conversion-error classes retain
18//! their dispatch precedence. The generated `wasm_registry.rs` is
19//! **gitignored** (regenerated on every host `R CMD INSTALL`); determinism is
20//! what lets `just r-cmd-build` reproduce it into the tarball and lets CI
21//! assert a non-stub snapshot rather than git-diffing a committed copy.
22
23use crate::abi::mx_tag;
24use crate::registry::{
25    AltrepRegistration, MX_ALTREP_REGISTRATIONS, MX_TRAIT_DISPATCH, TraitDispatchEntry,
26};
27use std::ffi::CStr;
28use std::fmt::Write as _;
29
30// Bumped whenever the generated-file shape changes in a way the receiving
31// `build.rs` version check must reject (e.g. registry struct fields renamed
32// so an old file no longer compiles). Cosmetic changes — import lines,
33// qualified paths, formatting — are NOT part of the checked contract and
34// don't warrant a bump (#1307). The receiving `build.rs` (step 5) refuses
35// to compile a `wasm_registry.rs` whose header doesn't match.
36//
37// 2: `MX_CONVERSION_ERROR_CLASS_WASM`, which `miniextendr_init!` passes to
38//    `install_wasm_runtime_slices` (#1768).
39// 3: ALTREP registration function pointers use the C-unwind ABI.
40// 4: Trait vtable symbols preserve crate, trait and type spelling (#1778).
41const GENERATOR_VERSION: u32 = 4;
42
43/// Pre-extracted, host-side view of one `R_CallMethodDef`.
44///
45/// `R_CallMethodDef` carries `name` as a raw `*const c_char`; safely walking
46/// it requires `unsafe`. The formatter takes already-extracted, owned values
47/// so it can be unit-tested without globals.
48pub struct CallDefRow {
49    pub name: String,
50    pub num_args: i32,
51}
52
53/// Pre-extracted view of one `MX_ALTREP_REGISTRATIONS` entry.
54pub struct AltrepRegRow {
55    pub symbol: String,
56}
57
58/// Pre-extracted view of one `MX_TRAIT_DISPATCH` entry.
59pub struct TraitDispatchRow {
60    pub concrete_tag: mx_tag,
61    pub trait_tag: mx_tag,
62    pub vtable_symbol: String,
63}
64
65/// Format a `wasm_registry.rs` source file from extracted runtime data.
66///
67/// Output structure:
68/// ```text
69/// // header (auto-generated marker, generator-version, content-hash)
70/// use ...;
71/// unsafe extern "C-unwind" { fn <wrapper>(...); ... }
72/// unsafe extern "C-unwind" { fn <altrep_reg>(); ... static <vtable>: u8; ... }
73/// pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[ ... ];
74/// pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &[ ... ];
75/// pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &[ ... ];
76/// pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &[ ... ];
77/// ```
78///
79/// Every fn / static referenced from a slice gets a matching `extern` decl —
80/// the WASM linker resolves them against the user crate's `#[no_mangle]`
81/// exports. `conversion_error_class` is the crate's `conversion_error_class`
82/// (the `MX_CONVERSION_ERROR_CLASS` entry), which the raising guards resolve
83/// an `arg_error!`'s classes from (#1768).
84pub fn format_wasm_registry(
85    call_defs: &[CallDefRow],
86    altrep_regs: &[AltrepRegRow],
87    trait_dispatches: &[TraitDispatchRow],
88    conversion_error_class: &[&str],
89) -> String {
90    // Linkme does not promise a stable order across linking configurations.
91    // Sort borrowed rows without cloning their owned symbol names. Condition
92    // classes are deliberately not sorted: R dispatch uses their input order.
93    let mut call_defs: Vec<_> = call_defs.iter().collect();
94    call_defs.sort_unstable_by(|a, b| (&a.name, a.num_args).cmp(&(&b.name, b.num_args)));
95    let mut altrep_regs: Vec<_> = altrep_regs.iter().collect();
96    altrep_regs.sort_unstable_by(|a, b| a.symbol.cmp(&b.symbol));
97    let mut trait_dispatches: Vec<_> = trait_dispatches.iter().collect();
98    trait_dispatches.sort_unstable_by_key(|row| {
99        (
100            &row.vtable_symbol,
101            row.concrete_tag.lo,
102            row.concrete_tag.hi,
103            row.trait_tag.lo,
104            row.trait_tag.hi,
105        )
106    });
107
108    let body = format_body(
109        &call_defs,
110        &altrep_regs,
111        &trait_dispatches,
112        conversion_error_class,
113    );
114    let content_hash = fnv1a_64(body.as_bytes());
115
116    let mut out = String::new();
117    (&mut out).write_fmt(format_args!("// AUTO-GENERATED — DO NOT EDIT.\n"))writeln!(&mut out, "// AUTO-GENERATED — DO NOT EDIT.").unwrap();
118    (&mut out).write_fmt(format_args!("//\n"))writeln!(&mut out, "//").unwrap();
119    (&mut out).write_fmt(format_args!("// Produced on host by `miniextendr_write_wasm_registry`. Compiled on\n"))writeln!(
120        &mut out,
121        "// Produced on host by `miniextendr_write_wasm_registry`. Compiled on"
122    )
123    .unwrap();
124    (&mut out).write_fmt(format_args!("// wasm32-* targets in place of the linkme distributed_slices.\n"))writeln!(
125        &mut out,
126        "// wasm32-* targets in place of the linkme distributed_slices."
127    )
128    .unwrap();
129    (&mut out).write_fmt(format_args!("//\n"))writeln!(&mut out, "//").unwrap();
130    (&mut out).write_fmt(format_args!("// generator-version: {0}\n",
        GENERATOR_VERSION))writeln!(&mut out, "// generator-version: {GENERATOR_VERSION}").unwrap();
131    (&mut out).write_fmt(format_args!("// content-hash:      {0:016x}\n",
        content_hash))writeln!(&mut out, "// content-hash:      {content_hash:016x}").unwrap();
132    (&mut out).write_fmt(format_args!("\n"))writeln!(&mut out).unwrap();
133    out.push_str(&body);
134    out
135}
136
137fn format_body(
138    call_defs: &[&CallDefRow],
139    altrep_regs: &[&AltrepRegRow],
140    trait_dispatches: &[&TraitDispatchRow],
141    conversion_error_class: &[&str],
142) -> String {
143    let mut out = String::new();
144
145    // `mx_tag` and `c_void` are referenced only by trait-dispatch entries and
146    // deliberately NOT imported here: a minimal package with an empty dispatch
147    // table would get `unused_imports` warnings on wasm32 (#1307). The
148    // dispatch entries spell both fully qualified instead. `SEXP` appears only
149    // in the call-table entries, so it is imported only when there are some.
150    if !call_defs.is_empty() {
151        (&mut out).write_fmt(format_args!("use ::miniextendr_api::SEXP;\n"))writeln!(&mut out, "use ::miniextendr_api::SEXP;").unwrap();
152    }
153    (&mut out).write_fmt(format_args!("use ::miniextendr_api::sys::R_CallMethodDef;\n"))writeln!(&mut out, "use ::miniextendr_api::sys::R_CallMethodDef;").unwrap();
154    (&mut out).write_fmt(format_args!("use ::miniextendr_api::registry::{{AltrepRegistration, TraitDispatchEntry}};\n"))writeln!(
155        &mut out,
156        "use ::miniextendr_api::registry::{{AltrepRegistration, TraitDispatchEntry}};"
157    )
158    .unwrap();
159    (&mut out).write_fmt(format_args!("\n"))writeln!(&mut out).unwrap();
160
161    format_extern_unwind_block(&mut out, call_defs);
162    format_extern_registration_block(&mut out, altrep_regs, trait_dispatches);
163    format_call_defs_slice(&mut out, call_defs);
164    format_altrep_regs_slice(&mut out, altrep_regs);
165    format_trait_dispatch_slice(&mut out, trait_dispatches);
166    format_conversion_error_class_slice(&mut out, conversion_error_class);
167
168    out
169}
170
171fn format_extern_unwind_block(out: &mut String, call_defs: &[&CallDefRow]) {
172    out.write_fmt(format_args!("unsafe extern \"C-unwind\" {{\n"))writeln!(out, "unsafe extern \"C-unwind\" {{").unwrap();
173    for row in call_defs {
174        let params = sexp_param_list(row.num_args);
175        out.write_fmt(format_args!("    pub fn {0}({1}) -> SEXP;\n", row.name,
        params))writeln!(out, "    pub fn {}({params}) -> SEXP;", row.name).unwrap();
176    }
177    out.write_fmt(format_args!("}}\n"))writeln!(out, "}}").unwrap();
178    out.write_fmt(format_args!("\n"))writeln!(out).unwrap();
179}
180
181fn format_extern_registration_block(
182    out: &mut String,
183    altrep_regs: &[&AltrepRegRow],
184    trait_dispatches: &[&TraitDispatchRow],
185) {
186    out.write_fmt(format_args!("unsafe extern \"C-unwind\" {{\n"))writeln!(out, "unsafe extern \"C-unwind\" {{").unwrap();
187    // ALTREP register fns get the 2024-edition `safe` qualifier so the fn
188    // type stays `extern "C-unwind" fn()` (not `unsafe extern "C-unwind" fn()`), allowing
189    // direct assignment to `AltrepRegistration.register`. The dispatcher
190    // calls them on R's main thread inside the package-init unwind boundary.
191    for row in altrep_regs {
192        out.write_fmt(format_args!("    pub safe fn {0}();\n", row.symbol))writeln!(out, "    pub safe fn {}();", row.symbol).unwrap();
193    }
194    // Vtable shape is opaque from wasm_registry.rs' perspective — we only
195    // need the address. Declaring as `u8` is the convention used in the
196    // plan sketch and keeps the file independent of trait-specific types.
197    for row in trait_dispatches {
198        out.write_fmt(format_args!("    #[allow(non_upper_case_globals)]\n"))writeln!(out, "    #[allow(non_upper_case_globals)]").unwrap();
199        out.write_fmt(format_args!("    pub static {0}: u8;\n", row.vtable_symbol))writeln!(out, "    pub static {}: u8;", row.vtable_symbol).unwrap();
200    }
201    out.write_fmt(format_args!("}}\n"))writeln!(out, "}}").unwrap();
202    out.write_fmt(format_args!("\n"))writeln!(out).unwrap();
203}
204
205fn format_call_defs_slice(out: &mut String, call_defs: &[&CallDefRow]) {
206    out.write_fmt(format_args!("pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[\n"))writeln!(out, "pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[").unwrap();
207    for row in call_defs {
208        // The transmute target signature here is positional-only — Rust's
209        // `extern fn` *type* doesn't carry parameter names, only types — so
210        // it differs from the `extern { fn ... }` declaration form, which
211        // does require named or `_`-bound parameters.
212        let arg_types = sexp_type_list(row.num_args);
213        out.write_fmt(format_args!("    R_CallMethodDef {{\n"))writeln!(out, "    R_CallMethodDef {{").unwrap();
214        out.write_fmt(format_args!("        name: c\"{0}\".as_ptr(),\n", row.name))writeln!(out, "        name: c\"{}\".as_ptr(),", row.name).unwrap();
215        out.write_fmt(format_args!("        fun: Some(unsafe {{ ::core::mem::transmute::<unsafe extern \"C-unwind\" fn({1}) -> SEXP, _>({0}) }}),\n",
        row.name, arg_types))writeln!(
216            out,
217            "        fun: Some(unsafe {{ ::core::mem::transmute::<unsafe extern \"C-unwind\" fn({arg_types}) -> SEXP, _>({}) }}),",
218            row.name
219        )
220        .unwrap();
221        out.write_fmt(format_args!("        numArgs: {0},\n", row.num_args))writeln!(out, "        numArgs: {},", row.num_args).unwrap();
222        out.write_fmt(format_args!("    }},\n"))writeln!(out, "    }},").unwrap();
223    }
224    out.write_fmt(format_args!("];\n"))writeln!(out, "];").unwrap();
225    out.write_fmt(format_args!("\n"))writeln!(out).unwrap();
226}
227
228fn format_altrep_regs_slice(out: &mut String, altrep_regs: &[&AltrepRegRow]) {
229    out.write_fmt(format_args!("pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &[\n"))writeln!(
230        out,
231        "pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &["
232    )
233    .unwrap();
234    for row in altrep_regs {
235        out.write_fmt(format_args!("    AltrepRegistration {{\n"))writeln!(out, "    AltrepRegistration {{").unwrap();
236        out.write_fmt(format_args!("        register: {0},\n", row.symbol))writeln!(out, "        register: {},", row.symbol).unwrap();
237        out.write_fmt(format_args!("        symbol: {0:?},\n", row.symbol))writeln!(out, "        symbol: {:?},", row.symbol).unwrap();
238        out.write_fmt(format_args!("    }},\n"))writeln!(out, "    }},").unwrap();
239    }
240    out.write_fmt(format_args!("];\n"))writeln!(out, "];").unwrap();
241    out.write_fmt(format_args!("\n"))writeln!(out).unwrap();
242}
243
244fn format_trait_dispatch_slice(out: &mut String, trait_dispatches: &[&TraitDispatchRow]) {
245    out.write_fmt(format_args!("pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &[\n"))writeln!(
246        out,
247        "pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &["
248    )
249    .unwrap();
250    for row in trait_dispatches {
251        out.write_fmt(format_args!("    TraitDispatchEntry {{\n"))writeln!(out, "    TraitDispatchEntry {{").unwrap();
252        // `mx_tag` / `c_void` are fully qualified (no header import) so
253        // dispatch-free files carry no unused imports — see format_body.
254        out.write_fmt(format_args!("        concrete_tag: ::miniextendr_api::abi::mx_tag::new(0x{0:016x}, 0x{1:016x}),\n",
        row.concrete_tag.lo, row.concrete_tag.hi))writeln!(
255            out,
256            "        concrete_tag: ::miniextendr_api::abi::mx_tag::new(0x{:016x}, 0x{:016x}),",
257            row.concrete_tag.lo, row.concrete_tag.hi
258        )
259        .unwrap();
260        out.write_fmt(format_args!("        trait_tag: ::miniextendr_api::abi::mx_tag::new(0x{0:016x}, 0x{1:016x}),\n",
        row.trait_tag.lo, row.trait_tag.hi))writeln!(
261            out,
262            "        trait_tag: ::miniextendr_api::abi::mx_tag::new(0x{:016x}, 0x{:016x}),",
263            row.trait_tag.lo, row.trait_tag.hi
264        )
265        .unwrap();
266        out.write_fmt(format_args!("        vtable: unsafe {{ ::core::ptr::from_ref(&{0}).cast::<::core::ffi::c_void>() }},\n",
        row.vtable_symbol))writeln!(
267            out,
268            "        vtable: unsafe {{ ::core::ptr::from_ref(&{}).cast::<::core::ffi::c_void>() }},",
269            row.vtable_symbol
270        )
271        .unwrap();
272        out.write_fmt(format_args!("        vtable_symbol: {0:?},\n",
        row.vtable_symbol))writeln!(out, "        vtable_symbol: {:?},", row.vtable_symbol).unwrap();
273        out.write_fmt(format_args!("    }},\n"))writeln!(out, "    }},").unwrap();
274    }
275    out.write_fmt(format_args!("];\n"))writeln!(out, "];").unwrap();
276    out.write_fmt(format_args!("\n"))writeln!(out).unwrap();
277}
278
279fn format_conversion_error_class_slice(out: &mut String, classes: &[&str]) {
280    out.write_fmt(format_args!("pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &[\n"))writeln!(
281        out,
282        "pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &["
283    )
284    .unwrap();
285    for class in classes {
286        // `{:?}` renders a valid Rust string literal (quotes, backslashes and
287        // control characters escaped).
288        out.write_fmt(format_args!("    {0:?},\n", class))writeln!(out, "    {class:?},").unwrap();
289    }
290    out.write_fmt(format_args!("];\n"))writeln!(out, "];").unwrap();
291}
292
293/// Comma-joined `_: SEXP` parameter list for an `extern { fn ...; }` decl.
294///
295/// Extern fn declarations require parameter bindings — bare `SEXP, SEXP`
296/// is parsed as pattern-typed which fails. Each slot is `_: SEXP`.
297fn sexp_param_list(num_args: i32) -> String {
298    if num_args <= 0 {
299        return String::new();
300    }
301    std::iter::repeat_n("_: SEXP", num_args as usize)
302        .collect::<Vec<_>>()
303        .join(", ")
304}
305
306/// Comma-joined `SEXP` type list for an `extern fn(...)` *type* expression
307/// (e.g. inside `transmute::<...>`). Function pointer types don't carry
308/// parameter names, so `_:` would be invalid here.
309fn sexp_type_list(num_args: i32) -> String {
310    if num_args <= 0 {
311        return String::new();
312    }
313    std::iter::repeat_n("SEXP", num_args as usize)
314        .collect::<Vec<_>>()
315        .join(", ")
316}
317
318/// FNV-1a 64-bit hash. Matches the implementation in
319/// `miniextendr-macros/src/miniextendr_impl_trait.rs::type_to_symbol_name`
320/// so a future build.rs check can recompute it portably.
321fn fnv1a_64(data: &[u8]) -> u64 {
322    const OFFSET_BASIS: u64 = 0xcbf29ce484222325;
323    const PRIME: u64 = 0x00000100000001b3;
324    let mut h = OFFSET_BASIS;
325    for &b in data {
326        h ^= b as u64;
327        h = h.wrapping_mul(PRIME);
328    }
329    h
330}
331
332/// Read the live linkme distributed slices and return rows safe to pass to
333/// [`format_wasm_registry`].
334///
335/// The routines are the ones the package registers on a native load
336/// ([`crate::registry::call_defs`]), so the snapshot leaves out the sidecar
337/// setters of a read-only type there too (#2292).
338fn read_runtime_slices() -> (Vec<CallDefRow>, Vec<AltrepRegRow>, Vec<TraitDispatchRow>) {
339    let call_defs: Vec<CallDefRow> = crate::registry::call_defs()
340        .iter()
341        .map(|d| {
342            // SAFETY: every emission site sets `name` from a static CStr literal
343            // (see `c_wrapper_builder.rs` and friends), so the pointer is valid
344            // for the program lifetime and points to a NUL-terminated UTF-8
345            // ASCII string.
346            let name = unsafe { CStr::from_ptr(d.name) }
347                .to_str()
348                .expect("a registered routine name is not valid UTF-8")
349                .to_string();
350            CallDefRow {
351                name,
352                num_args: d.numArgs,
353            }
354        })
355        .collect();
356
357    let altrep_regs: Vec<AltrepRegRow> = MX_ALTREP_REGISTRATIONS
358        .iter()
359        .map(|r: &AltrepRegistration| AltrepRegRow {
360            symbol: r.symbol.to_string(),
361        })
362        .collect();
363
364    let trait_dispatches: Vec<TraitDispatchRow> = MX_TRAIT_DISPATCH
365        .iter()
366        .map(|t: &TraitDispatchEntry| TraitDispatchRow {
367            concrete_tag: t.concrete_tag,
368            trait_tag: t.trait_tag,
369            vtable_symbol: t.vtable_symbol.to_string(),
370        })
371        .collect();
372
373    (call_defs, altrep_regs, trait_dispatches)
374}
375
376/// Read the live distributed slices, format `wasm_registry.rs`, and write it
377/// to `path`. No-op when content is unchanged (matches `write_r_wrappers_to_file`).
378pub fn write_wasm_registry_to_file(path: &str) {
379    let (call_defs, altrep_regs, trait_dispatches) = read_runtime_slices();
380    let content = format_wasm_registry(
381        &call_defs,
382        &altrep_regs,
383        &trait_dispatches,
384        crate::registry::conversion_error_class(),
385    );
386
387    let existing = std::fs::read_to_string(path).unwrap_or_default();
388    if existing == content {
389        return;
390    }
391
392    // Write via a sibling temp file then rename for atomicity.
393    //
394    // Matches the strategy in `write_r_wrappers_to_file`: `rename(2)` is atomic
395    // on POSIX, so concurrent readers always see a complete file. On Windows,
396    // `rename` fails when the destination exists, so we remove it first.
397    let dest = std::path::Path::new(path);
398    let tmp = dest.with_extension("tmp");
399    std::fs::write(&tmp, content.as_bytes())
400        .unwrap_or_else(|e| {
    ::core::panicking::panic_fmt(format_args!("failed to write {0}: {1}",
            tmp.display(), e));
}panic!("failed to write {}: {e}", tmp.display()));
401    #[cfg(windows)]
402    let _ = std::fs::remove_file(dest);
403    std::fs::rename(&tmp, dest).unwrap_or_else(|e| {
404        {
    ::core::panicking::panic_fmt(format_args!("failed to rename {0} → {1}: {2}",
            tmp.display(), dest.display(), e));
}panic!(
405            "failed to rename {} → {}: {e}",
406            tmp.display(),
407            dest.display()
408        )
409    });
410}
411
412#[cfg(test)]
413mod tests;