Build and develop
Build a local native toolchain candidate
Prepare exact inputs and an offline cache, then build and verify a local AROS compiler candidate without publication authority.
This is a maintainer workflow. It produces a local-only candidate from three exact Git checkouts and can package it locally; it does not create a tag, release, attestation, or package-manager publication. For a published compiler, use Choose and verify a toolchain instead.
The command does not discover a neighbouring checkout. All paths are explicit and the selected commits must agree with the producer declaration. Keep source, producer, tools, cache, work, output, and recipe paths separate. Use clean checkouts and absent work/output leaves.
What you need
Section titled “What you need”The native lifecycle selects LLVM or GNU from the bound source lock and profile. GNU uses source-lock v3, profiles v2 and explicit RISC-V ISA/ABI contracts; all selected identities must agree. It selects the locked GCC and binutils versions and installs the Rust collector with measured GNU tool roles. Package and verify-package accept these candidates with a schema-2 manifest and an inventory-bound executable layout. These are local development paths, not a published RISC-V compiler, native board-build qualification or boot claim. The examples below retain the existing PC/LLVM selection.
The unreleased V2 release-input collection can explicitly select a host-independent SDK identity and its required compiler profiles. Its source, target/ABI and product version stay separate from compiler and host identities. The shared index can verify selected SDK package bytes. See the SDK commands for current local generation and management options.
The unreleased explicit family-v2 path supports the full compiler/SDK generation matrix. Compiler-only evidence remains insufficient. Byte checks remain separate from original-job and signature authentication and production release gates.
SDK source profiles can declare a target-generic sdk_consumer_contract.
The transpiler uses it for strict inventory and graph export; CMake checks the
LLVM driver triples, pointer width and ARM float ABI against the source
selection. Read-only producer profile --source-dir … --source-preset …
verifies the committed contract and sealed inputs and marks SDK evidence as
required. The LLVM library adapter also measures both payload drivers and checks
their version and selected triple; this is not package authentication or SDK
link qualification. The library executes four normal C/C++ links from sealed
probes against original and relocated SDK trees and rechecks their retained
outputs. A CMake binding selects the SDK path from source configuration.
The source ABI selects compiler_arch or compiler_cpu, optional
compiler_fpu and compiler_code_model, and the optional boolean switches
compiler_red_zone, compiler_pic and compiler_pie. SDK generation and
application links use the same declared options; the tools do not infer them
from a board name. An absent switch adds no option.
Conflicting environment or configuration flags are rejected.
aros sdk build selects the source-owned LLVM SDK contract or GNU native
consumer contract matching the family-v2 compiler. It generates and packages
the SDK and can export portable compatibility evidence. Owning-job
authentication and complete release qualification remain separate gates.
- A clean AROS source checkout, an
aros-toolchainsproducer checkout, and anaros-toolscheckout at the commits selected by the producer declaration. - The
arosexecutable built from that selected tools checkout. - Cargo, the selected Rust toolchain, CMake, a compatible
make, Git, a host C/C++ compiler, and Python for the unchanged upstream AROS build. - An online cache-bootstrap step followed by an offline build. The offline build itself never falls back to transport.
The prerequisites page records measured storage from the current PC proof. Treat those values as an observed floor, not a reservation guarantee.
GNU candidates additionally require GNU Make 4.0 or newer, bison, flex, patch,
pkg-config and Ninja. On macOS select gmake; Apple’s Make 3.81 cannot execute
the source’s generated rules. With a Clang host compiler, llvm-ar and
llvm-ranlib must also be on PATH: preflight observes both before admitting
their directories to the isolated build environment. A missing tool fails
before source execution, not during a host-library build.
Mako and MarkupSafe are mandatory locked Python
imports. A selected source that also needs PyYAML must declare its yaml import
and exact archive/version in the lock; ambient Python packages are not accepted.
GCC’s format lists are narrowed to exactly one hash-verified lock entry before
the native Rust fetch bridge runs, never used as transport fallbacks. GNU
cache subdirectories are stamp namespaces, not alternative source locations.
Both compiler families give the Rust fetcher a private verified source copy and
enforce offline checksum validation. The bridge translates the source’s
MetaMake fetch arguments without executing its fetch.sh; patch paths must
remain inside the measured source snapshot. Both families use their declared,
lock-owned Python closure.
Empty source-template checksum placeholders are filled from the exact lock.
Nonempty declarations must match it; repeated checksum options fail. Direct
downloads in source recipes are not covered by this bridge and must be replaced
by declared, verified fetch inputs before an offline build can be qualified.
Prepare exact inputs
Section titled “Prepare exact inputs”Set paths outside all three checkouts. The example names only locations; obtain
the actual revisions from toolchains/producer-executor-v1.toml, not from a
moving branch name.
For declaration schema 2, use the source lock and profile matrix of the group containing your preset when creating the recipe. Planning and building verify every declared group and select only the pair bound by that recipe’s digests.
export AROS_SOURCE=/absolute/path/to/AROS-NXexport PRODUCER=/absolute/path/to/aros-toolchainsexport TOOLS=/absolute/path/to/aros-toolsexport TOOLS_TARGET=/absolute/path/to/producer-tools-targetexport AROS="$TOOLS_TARGET/release/aros"export CACHE=/absolute/path/to/producer-cacheexport WORK=/absolute/path/to/pc-candidate-workexport OUTPUT=/absolute/path/to/pc-candidate-outputexport RECIPE=/absolute/path/to/pc-candidate.recipe.json
( cd "$TOOLS" cargo build --locked --release -p aros-cli --target-dir "$TOOLS_TARGET")git -C "$AROS_SOURCE" status --shortgit -C "$PRODUCER" status --shortgit -C "$TOOLS" status --shortEach status command must print nothing. Do not place TOOLS_TARGET, CACHE,
WORK, OUTPUT, or RECIPE below one of the checked-out roots. The native
input audit also rejects ignored build artifacts; git status --short alone
does not prove a clean raw checkout.
Bootstrap and verify the cache
Section titled “Bootstrap and verify the cache”First acquire the source archives selected by the producer lock while transport is allowed. The command verifies existing objects and refuses a mismatched payload.
"$AROS" cache sources fetch \ --source-lock "$PRODUCER/toolchains/llvm-11.0.0.sources.json" \ --dir "$CACHE" --format jsonThe native build also compiles Rust helpers from the exact tools Cargo.lock.
Prepare the immutable vendor generation through aros; it selects the clean
tools Git tree, the producer’s pinned Rust channel, and the exact Cargo
executable. It runs Cargo with a private CARGO_HOME, writes a single
validated directory placeholder, checks every vendor checksum and publishes
only a complete generation under $CACHE/cargo/v1/…. It never copies a user
Cargo configuration or credential into the cache.
Cold vendor population and normal or resumed collector Cargo builds also exclude caller/work/cache ancestor configuration through the checked filesystem-root working directory. They do not rewrite global Cargo configuration.
The tools workspace’s declared minimum Rust version must not exceed the
producer’s pinned channel. An incompatible pin fails with AX0401 before
Cargo is invoked or a vendor generation is created, and before the native
configure/compiler phases. Update the producer pin explicitly; there is no
fallback to the ambient Rust toolchain.
"$AROS" cache cargo fetch \ --producer-dir "$PRODUCER" --tools-dir "$TOOLS" --dir "$CACHE" \ --format json
"$AROS" cache cargo verify \ --producer-dir "$PRODUCER" --tools-dir "$TOOLS" --dir "$CACHE" \ --format json
"$AROS" cache sources verify \ --source-lock "$PRODUCER/toolchains/llvm-11.0.0.sources.json" \ --dir "$CACHE" --format jsonUse cache cargo list when only the selected generation receipt is needed; it
does not hash the vendor tree, but it runs bounded Git and cargo --version
probes to prove the selection. A changed tools tree, lockfile, producer Rust
pin, or Cargo executable identity selects a different generation. The native
lifecycle then accepts only that exact generation, copies it into a private
runtime directory and invokes its collector with --locked --offline. Never
repair a missing generation during an offline build; use cache cargo fetch --offline only to require a previously verified one.
Check native prerequisites before compiler fan-out
Section titled “Check native prerequisites before compiler fan-out”The unreleased aros toolchain producer host-preflight command checks one
selected profile’s native tools and imports its lock-owned Python modules from
an already prepared cache. Pass explicit --source-lock, --profiles,
--preset, --host, --cache-dir and an absent --python-env-dir outside
those inputs. Its parent must already exist without symlink components.
The command writes only the private Python environment and prints a JSON
observation; it does not fetch packages, install dependencies or start a build.
If extraction or an import probe fails, its private directory remains for
diagnosis. Inspect that directory and choose a fresh destination for a retry;
the command never overwrites or automatically deletes it.
This reuses the native lifecycle’s tool and Python checks. It does not run
configure, infer undeclared Python requirements, verify Cargo generations,
authenticate a producer checkout or qualify a compiler/SDK. The workflow must
select and verify input and runtime bytes separately. Every actual build still
repeats its own checks; an earlier preflight is not transferable build evidence.
Construct the recipe and inspect readiness
Section titled “Construct the recipe and inspect readiness”Select source lock and profile files inside the producer checkout using absolute paths. The recipe records their producer-relative identities. Recipe creation never replaces an existing file.
"$AROS" toolchain producer recipe \ --source-dir "$AROS_SOURCE" --producer-dir "$PRODUCER" --tools-dir "$TOOLS" \ --source-lock "$PRODUCER/toolchains/llvm-11.0.0.sources.json" \ --profiles "$PRODUCER/toolchains/profiles-v1.json" --output "$RECIPE" --format json
"$AROS" toolchain plan --preset pc-x86_64 --recipe "$RECIPE" \ --source-dir "$AROS_SOURCE" --producer-dir "$PRODUCER" --tools-dir "$TOOLS" \ --work-dir "$WORK" --output-dir "$OUTPUT" --cache-dir "$CACHE" \ --jobs 8 --timeout-seconds 21600 --format jsonProceed only when readiness is ready. A blocked or invalid plan is a
diagnostic, not an invitation to change its identities manually.
Build and verify the local prefix
Section titled “Build and verify the local prefix”"$AROS" toolchain build --preset pc-x86_64 --recipe "$RECIPE" \ --source-dir "$AROS_SOURCE" --producer-dir "$PRODUCER" --tools-dir "$TOOLS" \ --work-dir "$WORK" --output-dir "$OUTPUT" --cache-dir "$CACHE" \ --jobs 8 --timeout-seconds 21600 --release-id local-pc-candidate \ --format json
cd "$AROS_SOURCE""$AROS" toolchain verify --preset pc-x86_64 --local "$OUTPUT/toolchain""$OUTPUT/toolchain/bin/clang" --version"$OUTPUT/toolchain/bin/ld.lld" --versionThe six phase receipts bind the selected inputs. A separate
finished-candidate.json measures the complete tree after collector installation;
the result’s finished-candidate evidence entry identifies it. Collector-only
outputs are not complete compiler evidence. These local receipts do not prove
authenticated execution or release readiness. The prefix may be used explicitly by
an AROS build with --toolchain-dir where its compiler family is supported by
that consumer; producer acceptance alone does not qualify a native GNU board
build. It remains local-only, has no release provenance, and cannot be promoted
by copying it into a consumer lock.
The separate toolchain producer package and verify-package stages accept
--package-format legacy-v1|family-v2. Omitting the option preserves the
existing family default: LLVM uses its historical schema-v1 manifest and v1
asset name, while GNU uses compiler-family schema v2. For an explicit LLVM
schema-v2 package, pass --package-format family-v2; its manifest records the
LLVM compiler family and version and its asset uses the v2 LLVM name. The
historical legacy-v1 choice remains LLVM-only. Package and release-index
formats are separate explicit selections. A family-v2 package alone does not
qualify publication or recovery.
For a package bound to the complete finished build, retain the build’s JSON
stdout as a regular file outside the checked-out and candidate roots. Record
its exact file SHA-256 separately. Pass that file, its selected digest and the
original work root through --build-result, --build-result-sha256 and
--build-work-dir, with explicit --package-format family-v2. Partial selections
are rejected. The existing --input-dir must name the original
$OUTPUT/toolchain prefix. The command verifies all retained phases, complete
raw payload and normalized package before publishing the local package directory.
Its JSON output adds finished_candidate with the joined digests and a portable
measurement string with its exact SHA-256. The string retains the build result,
six phase receipts, finished record and four package measurements. Preserve its
bytes unchanged; these receipts belong in protected evidence artifacts, not
public package metadata. This transport does not authenticate execution.
For portable readback, use producer verify-package with the existing independent
recipe, source-lock, profile, host, release and build-environment selectors.
Add all four --package-measurement FILE, --package-measurement-sha256 SHA,
--executor-contract-sha256 SHA and --executor-binary-sha256 SHA selectors
with explicit --package-format family-v2. The measurement digest binds its
exact exported bytes; executor digests identify the original build, not the
collector binary. Obtain them from independently authenticated owning-job
evidence. The native verifier joins the complete retained phase chain and
original build result to the downloaded package without reopening original
runner paths. JSON adds finished_candidate with
assurance: portable-byte-readback-only. This remains a byte-consistency check,
not job authentication, new compiler execution or release admission.
producer verify-release-evidence joins the complete indexed A/B export set to
measured packages, comparisons, compatibility reports/logs/ELFs, final checksums
and unchanged pre-attestation subjects. It requires external lane selections
and retained raw digests. Selected SDKs require an exact product map with independent
tree/archive digests and archive sizes. Identities come from release inputs.
The result retains measured SDK packages, not generation or origin proof.
It does not qualify a release or authenticate jobs.
The unreleased library checks downloaded SDK generation records against selected inputs, measured packages and complete compatibility/link evidence without opening original runner roots.
A local file hash is not authenticated execution provenance. Hashing an untrusted result does not make it trusted; a release workflow must separately verify its run/artifact origin. These options do not establish independent A/B builds or release eligibility. Ordinary local packaging without them remains available for already-built prefixes.
For GNU builds, configure records host compiler prefix maps in HOST_*FLAGS.
The compiler-build process does not export CFLAGS or CXXFLAGS: MetaMake
owns the target ISA flags, which must not reach host-built Binutils or GCC.
LLVM builds retain their existing compiler environment.
Compiler caching defaults to off, including release qualification. To reuse
host C/C++ compilation during local development, prepare a managed local
namespace and add --compiler-cache sccache (or ccache) to the build command:
aros cache compiler prepare --backend sccache# Add to the toolchain build invocation above:# --compiler-cache sccache--compiler-cache auto selects a prepared local sccache namespace first, then
ccache, or remains off. An explicit --compiler-cache-dir DIR requires an
explicit backend and an already prepared namespace outside all producer roots.
Offline execution remains mandatory; ambient cache settings and remote storage
are not imported. The compiler phase receives controlled host C/C++ launchers;
target runtime compilation, assembly, linking and the Rust collector are not
cached by this integration. Receipts bind the backend executable, host
compilers and local configuration. Resume requires the same bindings and
unchanged launchers. Use --compiler-cache off for independent A/B builds.
On Unix, sccache needs short paths for both its managed socket and the startup
socket below the owned work directory. An oversized path is rejected before
configure; select shorter roots or use ccache instead.
GNU configure and MetaMake also resolve recursive make through a private
alias to the exact preflight-selected GNU Make, rather than a second executable
found elsewhere on the host PATH.
The v3 source lock can declare source-owned patches for target build dependencies outside the compiler directory. Recipe creation reads each patch from the exact clean source commit and binds its SHA-256; missing, unsafe or duplicate paths and an incomplete recipe patch set are rejected. Compiler component patches remain restricted to their selected family directory.
Failure and recovery boundary
Section titled “Failure and recovery boundary”producer materialize-engine-free-source requires a clean committed source.
Use --recipe to bind its identity to the compiler build source, or both
--source-commit and --source-tree for a separately pinned SDK consumer.
The two selections cannot be mixed. A different consumer does not change the
compiler package’s recipe or provenance. The snapshot is recursively audited,
has its source-tree engine removed and receives a measured content digest;
it is not compatibility evidence until the actual consumer phases pass.
The six-phase adapter accepts GNU packages with an explicit --source-preset
from the measured consumer source’s aros-targets.toml. That preset selects
source rules and maps to the compiler profile through toolchain_profile.
When that preset binds a validated native_consumer_contract, the CMake
consumer phase configures the source and then builds only the SDK roots named
by the contract in the same phase. GNU inputs without that contract and the
existing LLVM adapters remain configure-only. This verifies the declared
source/build flow; it makes no board or hardware qualification claim.
A verified SDK consumer does not publish guest runtime selections such as
Mesa’s GL.default or add dependencies on the guest GL implementation.
The full-build runtime checks remain separate.
New source-v2 SDK executions require --consumer-source-date-epoch SECONDS.
Select it explicitly for the consumer/SDK source; do not substitute the
compiler recipe’s epoch when the sources differ. It is passed as
SOURCE_DATE_EPOCH to CMake and upstream Make and bound in their recorded
environment digest. Retained read-back derives the same selected environment;
a changed or omitted epoch rejects new evidence. Historical receipts retain
their original environment. Standalone collector commands stay PATH-only.
Use this same epoch for the SDK package identity. The range is zero through
8,589,934,591 seconds, matching the portable SDK tar timestamp contract.
After SDK packaging, aros sdk sbom writes the supplemental
<archive>.spdx.json into a separate distribution directory. Pass the exact
identity, tree and archive selections used for package verification and an
absent absolute --output path. The three-member SDK package remains unchanged;
the shared release inventory owns the supplemental metadata. This local step
does not authenticate the producing job or admit a release.
If the source contract declares host file generators, --ports-cache-dir must
also contain their raw input files. Each declaration supplies the exact filename,
size and SHA-256. The adapter verifies them before configuration and supplies
private read-only copies to CMake, not the mutable cache. A missing or modified
file fails without a download. Supply an absolute cache path.
Driver roles and RISC-V flags come from the verified package and profile, not
PATH or board-name inference. GNU receipts use schema v3, LLVM family-v2 uses
package-bound schema v4, and legacy LLVM v1 retains schema v2. Family-v2
execution checks the source/profile binding, both complete inventories and
compiler-bound standalone ELF outputs. Complete V2 release-evidence and read-only
recovery checks admit GNU v3 and LLVM v4 receipts. Explicit family-v2 repackage
also supports both families. Successful packaging or synthetic adapter tests
are not a real consumer qualification.
Family-v2 compatibility also checks the exact retained report/log inventory
against pre-execution source and environment expectations, then reparses the
standalone outputs. This local read-back is not signature verification or
recovery admission.
For a complete local export, add --package-format family-v2 --evidence-dir /absolute/path/to/absent-export to producer compatibility. The export parent
must exist and have no symlink components. Inputs and execution roots must be
separate. After all six phases and read-back pass, one no-clobber directory
publication exposes the exact pre-execution inputs.json and closed
evidence/ reports, logs and ELF files. Existing output is never replaced.
Overlap checks recognize filesystem aliases and conservatively reject missing
path suffixes that differ only by ASCII case.
JSON adds the output directory, input-document digest and evidence-manifest
digest under local_evidence; retain those digests outside the uploaded files.
Keep this evidence private, outside the public release inventory.
producer release-plan --directory DIR --inputs-sha256 SHA --format json
projects the complete selected V2 input collection before any builds. Its
groups retain each source revision and exact document names/digests; lanes
contains every selected group/host/profile combination. Derive scheduling from
this result rather than copying profile lists into the workflow. Runner labels
and A/B scheduling are workflow policy. The command is read-only and its
assurance: input-binding-only result does not qualify execution or release.
producer verify-release-evidence reads the complete evidence on a collector
host without reopening original runner roots. Supply --directory,
--release-id, --base-url, --inputs-sha256, --index-sha256, --selection,
--selection-sha256, --subject-manifest and --subject-manifest-sha256.
The selection schema is aros-toolchain-release-evidence-selection-v2; it
contains every indexed archive’s independent environment/required-path map,
two build exports and executor digests, comparison and compatibility inputs.
The lane set comes from release inputs, not discovered reports. JSON reports
assurance: byte-consistency-only; authentication, qualification and recovery
remain separate gates.
producer verify-qualification additionally requires --qualification-evidence,
--qualification-sha256, --policy and --policy-sha256. It joins complete V2
claims to that same actual evidence: raw A/B exports, comparison, compatibility
manifest, final checksums, subject list and provenance bytes. Diagnostic coverage
and self-hashes substituted for raw exports/manifests are rejected. It writes
nothing and remains assurance: byte-consistency-only; the run attempt,
signatures and producing jobs still need independent authentication.
producer verify-recovery uses those same complete selections and adds
--recovery-request and --recovery-request-sha256. It checks the exact V2
qualification digest, external run-attempt/tag/signer observations and a fresh
absent packaging handoff. It reacquires all original bytes and writes nothing.
Replay allows a compatibility-harness failure, not an actual compatibility
failure; compilation and comparison failures are also ineligible. Observations
still require external authentication; this check executes no recovery. The
historical prepare-recovery and validate-recovery commands remain V1-only.
For packaging-only execution, use producer repackage --release-format family-v2
with the same complete selection and independent digests. Rename --directory
to --release-dir and --release-id to --source-release-id; select one exact
archive basename with --asset. Add --first-extraction-dir,
--second-extraction-dir, --first-output-dir, --second-output-dir and
--comparison-output. Every destination must be absent, absolute and normalized,
with an existing nonsymlink parent, outside all selected evidence and the other
destinations. Declared forbidden build roots are also protected, including
existing aliases and prospective suffixes. The caller must exclusively own
quiescent inputs and outputs.
The command revalidates the complete original qualification, extracts the
selected package twice and packages both copies under the fresh recovery
identity. Only release identity changes; qualified payload and other manifest
fields remain unchanged. It compares all four package members, checks the
original closure again and writes a no-clobber comparison receipt. JSON includes
the fresh and original release IDs, original archive hash/size, output paths,
comparison digest and package-set digest. build_count and lanes describe
the original evidence, not new compiler executions.
This operation neither signs nor publishes, and it does not authenticate
GitHub observations. Replay requests are ineligible for packaging. A failure
after output creation preserves the selected new directories for diagnosis;
never treat them as a completed recovery or adopt them on a retry. Use fresh
paths. Without explicit format, repackage keeps the V1 contract; V1 context
flags and V2 complete-selection flags cannot be mixed.
producer record-qualification --release-format family-v2 acquires that same
complete closure before deriving the claim file. Supply --release-dir, the
independent input/index/selection/subject digests and paths, and source
repository/workflow/run ID/positive attempt/tag object/peeled producer commit.
The index digest binds release ID and download URL. Add the selected signer
claims, creation/expiry times and an absent absolute --output outside every
input and evidence root, with an existing nonsymlink parent. The complete file
is written atomically without replacement; JSON includes its raw digest and
assurance: byte-consistency-only. External authentication remains mandatory.
Default recording and explicit legacy-v1 keep the historical layout; legacy
report-root arguments cannot be combined with the V2 selection.
The v2 library also binds comparison-report claims for all four package members to measured final checksum entries. This check does not authenticate independent builds or authorize release publication; CLI release admission is still a separate integration step.
producer index --release-format family-v2 measures all compiler groups selected
by toolchain-release-inputs-v2.json. Supply --lane-inputs with independent
archive environment and required-path maps, plus an external --subject-manifest.
The pre-attestation stage writes the index and subject list, not final checksums.
After external attestation supplies provenance, final requires the original
--subject-manifest-sha256, verifies unchanged subjects and writes final checksums.
These local byte checks do not authenticate signatures. The default legacy-v1
index path remains available. Qualification recording and read-only recovery
verification and explicit repackage --release-format family-v2 support V2.
Historical request creation and default V1 execution keep their original
contracts; no format is inferred from filenames or failed verification.
The producer preserves owned work/output roots on failure, cancellation, and deadline expiry. Inspect their lifecycle receipts and logs, correct the exact input problem, and start with fresh roots. Do not delete or reuse retained directories as an implicit resume mechanism. Packaging-only recovery and release qualification have distinct evidence requirements; see the release reference for the published-product boundary.