Expand description
arcature-build — Arcature build/dev-time application intelligence.
This crate owns the canonical Arcature Unified Application Graph (UAG):
a deterministic, serializable, schema-versioned view of an application
aggregated from the &'static compile-time metadata the arcature-dx
macros (module!, application!, routes!, #[controller], #[page],
…) already generate. It is the single graph consumed by the CLI, the
frontend virtual modules, the Inspector, MCP, system checks, packaging,
and deployment (ADR-0006 §2: “Same graph everywhere”).
§Two disjoint paths
§1. Build-script entry (default features, no arcature dependency)
A generated application lists arcature-build as a [build-dependencies]
entry and calls compile from a tiny build.rs:
fn main() {
arcature_build::compile();
}compile performs only build-script-safe work: it emits Cargo
rerun-if-changed / rerun-if-env-changed directives, a build-time cfg,
and a framework-version env. It does not aggregate proc-macro
metadata — a build script runs before the package’s proc-macros expand,
so it cannot observe the &'static graph the macros produce this compile.
Aggregation is a dev-time concern (path 2).
§2. Dev-time UAG aggregation (uag / uag-schema features)
The uag feature pulls arcature (for the ApplicationGraph types) and
exposes the UAG schema, the ApplicationGraph -> Uag conversion, and the
manifest emitter. An application’s arcature-metadata binary (or
arc inspect app) links the compiled application, calls the generated
<name>_graph() accessor that application! emits, converts the result
to a [uag::Uag], and serializes it to .arcature/app-manifest.json.
The uag-schema feature is the serde-only subset: it exposes the
serializable schema types ([uag::Uag] and the uag::schema entry types)
and the schema-version constant, with serde / serde_json and no
arcature dependency. A consumer that only needs to read the
canonical manifest JSON — notably arcature-cli, which shells out to the
app’s arcature-metadata binary and deserializes its stdout — depends on
arcature-build with uag-schema alone (AGENTS.md §16 standalone-first).
uag implies uag-schema, so the dev-time serializer and the read-only
consumer never disagree on the schema (ADR-0006 §2: “Same graph
everywhere”).
This split keeps [build-dependencies] light (no arcature in the build
script) while giving dev-time tooling a single canonical, deterministic,
schema-versioned artifact. Both paths are side-effect-free from the
crate’s perspective: no filesystem source scanning, no Rust parsing, no
runtime discovery, no inventory/linkme/ctor, no global mutable state
(ADR-0006 §2; AGENTS.md §17/§20).
§Determinism
The UAG is ordered with BTreeMap / BTreeSet and sorted vectors; the
manifest emitter writes stable JSON (no timestamps, no absolute
OUT_DIR / CARGO_MANIFEST_DIR paths). A drift-check test (not a build
script) enforces a checked-in .arcature/app-manifest.json stays current
(ADR-0006 §2; official Cargo build-script-examples “generated file”
guidance).
See ADR-0006 and docs/ap2-1/PROGRAM.md (AP2.1-1).
Functions§
- compile
- The build-script entry. Emits Cargo directives to stdout; never panics.