Skip to main content

Crate arcature_build

Crate arcature_build 

Source
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.