Architecture

The workspace separates shared contracts from product-specific policy. Every crate is private to this workspace; the release installs commands, not Rust library packages.

Boundary	Owner
diagnostics, local-log mechanics, hashes, ELF and toolchain schemas	aros-common
repository orchestration and user-facing commands	aros-cli
embedded CMake modules and build-engine materialization	aros-cmake-engine
MetaMake translation	aros-transpiler
independent reference verification	aros-verify
two-pass linking and set collection	aros-collect
module, interface and varargs source generation	aros-genmodule
ROM package parsing, layout validation and publication	aros-romtool
physical board safety and deployment	aros-board
narrow macOS removable-disk claim lifetime	aros-macos-disk-claim
source transport, cache, extraction and patching	aros-fetch
isolated AHI configure/build/product validation	aros-ahi-runner
deterministic native archive production and verification	aros-release
experimental producer inspection and work-ownership primitives; no build execution	aros-toolchain

The CLI executes build tools as standalone programs. It does not link their implementations into one process. This preserves explicit contracts and keeps component failures attributable. The verifier intentionally does not reuse the transpiler implementation, because a shared defect must not satisfy both sides of a differential check.

The engine is compiled into the tools and materialized into the selected build directory. The AROS source is an input to that engine, not its installation location. --engine-dir is the explicit development override. A nearby or checkout-owned engine is not selected automatically.

Architecture-source overrides retain declaration-local compile flags and incextra paths from MetaMake. An explicit incextra is searched first for quoted headers of that declaration’s sources; it does not change angle-bracket lookup or unrelated sources. Ordinary quote paths remain specific to each consuming target, including when targets share a source file. Unresolvable or conflicting explicit paths fail instead of silently using the default.

Python-generated outputs declare their compile consumers explicitly. Consumers may live in a different MetaMake file: the transpiler validates their references against the complete parsed graph. CMake then checks the actual compile targets for the selected profile and binds the consumers after target creation. Missing or noncompiling consumers fail instead of silently losing the dependency. The engine does not scan arbitrary source headers to infer these ordering contracts.

Process and publication boundaries

aros resolves the complete installed tool suite from one directory, then spawns the required executable through the shared command runner. A missing or mixed installation fails before work begins. Child diagnostics and exit status remain attributable to the executable that owns the operation.

The shared runner supports cooperative cancellation without installing global signal handlers. It distinguishes requested cancellation, timeout and the child’s own status. On Unix it also bounds pipe cleanup after termination; a descendant that escapes the process group is an explicit cleanup failure, not proof of a sandbox. The experimental toolchain work guards remain separate from read-only planning and do not yet enable a public build command.

The configure/build probe checks six mandatory helpers. Release installation validates all eight public programs, including the frontend and independent verifier. These are different checks with different purposes.

New generated trees, ROM images, source checkouts and release artifacts are staged beside their destination. Validation and recursive durability complete before one no-clobber rename makes a new tree visible; an existing destination is never silently replaced. A rename that completed before a directory-sync error is retained and reported as an uncertain commit, never destructively “rolled back”.

Genmodule’s updates to several existing files use a different, explicit contract: one persistent lock serialises writers, an fsynced intent journal and identity-plus-SHA-256 proofs provide deterministic crash rollback/recovery, and the build graph orders readers after the generator. Multiple file renames are not a live atomic snapshot for an uncoordinated reader. Board media writes also cannot be atomic, so they use a stricter identity, exclusive-claim and complete-readback contract instead.

The architecture gate rejects forbidden crate dependencies and direct process execution that would bypass these boundaries. aros-common may be depended on by the product crates; it contains contracts and mechanisms, but no CLI, translation, release or board policy.

See development workflow to run the architecture and source-validation gates.