Configuration

aros-tools separates versioned checkout configuration from machine-local state. Repository files may select reproducible inputs; local files may identify hardware and storage but must not redefine release integrity.

Checkout-owned files

File	Owner	Purpose
aros-targets.toml	optional selected-checkout override	Target profiles, MetaMake selectors and host-compiler transport
aros-toolchains.lock.toml	selected AROS checkout	Exact release archive, host/profile, size and SHA-256
build/<preset>/cmake-engine/	installed tools	Materialized embedded CMake engine
generated CMake graph	configured build	Transactional output of the selected transpiler version

Unknown fields and unsupported schema versions fail closed. Relative paths are resolved against the discovered checkout, not the caller’s arbitrary working directory.

When aros-targets.toml is absent, aros-tools uses its embedded four-profile contract for pc-x86_64, rpi-aarch64, arm-raspi and opensbi-riscv64, including the complete MetaMake selector context and host LLVM declaration. This is the documented default for a pristine upstream checkout and is never written into it. An existing file is a complete, authoritative override: unreadable, malformed or incomplete content fails instead of falling back to the embedded contract. aros info reports which source supplied the effective profiles.

Each target may declare the complete MetaMake selector set directly:

[[targets]]
name = "pc-x86_64"
arch = "x86_64"
platform = "pc"
bsp = "generic"

[targets.transpiler]
family = ""
variant = ""
toolchain = "llvm"
cpu32 = "i386"
use_mmu = true

float_abi, when needed, remains a target-level field. These selectors are configuration, not architecture guesses: source sync passes every value to the isolated transpiler validation. For already-published AROS-NX revisions without this table, a compatibility bridge accepts only explicit matching CMakePresets.json values and the reviewed CMake defaults known to that tools version. If those defaults change, synchronization stops with a request to add the explicit table or update aros-tools; it never silently invents a new target context.

This example is a target block, not a complete host-compiler or release-lock configuration. Optional features describe the profile; they are not evidence that every named driver works. bootloader is another target-level field: when absent it defaults to grub2gfx for platform pc and an empty value for other platforms. An explicit value overrides that rule.

The embedded host LLVM declaration has asset names but no SHA-256 values. Managed host-compiler installation requires reviewed digest-bearing metadata.

Source: target schema and defaults.

Tools-owned source contract

contracts/aros-source-v1.toml pins development integration under [integration]. Its separate [source] and [producer] tables preserve the matching source and producer identities of the qualified toolchain. CI verifies both relationships; updating integration does not change a released toolchain. The historical Mesa 20 test oracle is separate from current-source tests. None of these development pins requires users to rename or relocate their AROS checkout.

Local board profiles

Board profiles default to ~/.config/aros/boards.toml. Override the file with --config PATH or AROS_BOARDS_FILE. The file may contain local interface, serial and physical-device identity, so it should not be committed to an AROS source repository.

Use aros board init --profile NAME --model MODEL to print a schema-correct template and add --apply only when you intend to create the file. Existing profiles are never silently overwritten.

NAME is only the local profile label. MODEL is required and selects the hardware contract; supported values are rpi3, rpi4, rpi5 and milk-v-titan. Use --transport to select a reviewed non-default transport, such as Pi 4 uboot-usb-ecm. Use board configuration for the model and transport matrix.

Environment variables

contracts/public-environment-v1.toml is the versioned allowlist for every environment value read by shipped Rust code. The workspace gate compares that allowlist with code and this page, so a new hidden override fails CI. Public, ambient-host and test-only names are deliberately separate.

Where a command offers the same setting directly, the explicit command-line option wins. Otherwise the order is the documented environment variable, versioned checkout configuration, then the documented default. Setting an explicit directory override is fail-closed: an invalid override is reported; the command does not continue searching a lower-priority location.

Frontend, source and integrity controls

Variable	Effect
AROS_OFFLINE	Set to 1 to forbid network access and require verified local content
AROS_FETCH_OFFLINE	Standalone aros-fetch equivalent of offline mode
AROS_FETCH_REQUIRE_CHECKSUMS	Set to 1 to reject third-party AROS sources without SHA-256
AROS_UPSTREAM_URL	Expected canonical URL for aros source sync; an explicit --upstream wins
AROS_HOME	Absolute root for tools-owned state; defaults to $HOME/.aros
AROS_CACHE_DIR	Absolute archive-cache override
AROS_HOST_COMPILER_DIR	Absolute managed host-compiler location override
AROS_CROSS_TOOLCHAINS_DIR	Absolute content-addressed cross-toolchain store override
AROS_BUILD_TOOLS_DIR	Exact binary suite directory; all required programs must pass bounded version probes
AROS_TOOLS_SOURCE_DIR	Select a reviewed aros-tools source workspace for helper builds
AROS_HOST_COMPILER_URL	Credential-free HTTPS base override for the checkout-selected host LLVM asset; the checkout’s exact version and SHA-256 remain mandatory
AROS_BOARDS_FILE	Local board-profile file; explicit --config wins, then this value, XDG_CONFIG_HOME, and HOME
AROS_DIAGNOSTIC_FORMAT	human or json frontend diagnostics
AROS_LOG_LEVEL, AROS_LOG_FORMAT, AROS_LOG_FILE	Explicit local frontend logging
AROS_VERIFY_GENMF_TIMEOUT_SECONDS	Verifier GenMF deadline in seconds (1–3600; default 30)
AROS_CACHE_GENMF_TIMEOUT_SECONDS	aros cache genmf per-generation lock and GenMF deadline in seconds (1–3600; default 30)
SOURCE_DATE_EPOCH	Standard deterministic timestamp consumed by release assembly

AROS_HOST_COMPILER_URL changes transport location, not artifact identity. Downloads and redirects remain within credential-free HTTPS and the selected checkout’s SHA-256 must verify before extraction. AROS_BUILD_TOOLS_DIR is a code-execution boundary: use only a directory you control. Every required tool must be executable, report the running aros-tools version within the bounded probe deadline, and the explicit directory never falls back to ambient PATH. AROS_BOARDS_FILE may describe physical devices and network interfaces; keep it machine-local and review it before deploy or removable-media operations.

The same host-compiler transport override is honored by aros cache archives when it selects --host-compiler; the result records whether its URL came from this environment override or aros-targets.toml. Cross-toolchain archive selection always uses the checkout lock’s declared URL. Neither path changes an archive SHA-256 identity or installed compiler state.

Component diagnostics and logging

Each component uses the same DIAGNOSTIC_FORMAT, LOG_LEVEL, LOG_FORMAT, and LOG_FILE suffix contract. The exact public names are:

• AROS_AHI_DIAGNOSTIC_FORMAT, AROS_AHI_LOG_LEVEL, AROS_AHI_LOG_FORMAT, AROS_AHI_LOG_FILE
• AROS_COLLECT_DIAGNOSTIC_FORMAT, AROS_COLLECT_LOG_LEVEL, AROS_COLLECT_LOG_FORMAT, AROS_COLLECT_LOG_FILE
• AROS_FETCH_DIAGNOSTIC_FORMAT, AROS_FETCH_LOG_LEVEL, AROS_FETCH_LOG_FORMAT, AROS_FETCH_LOG_FILE
• AROS_GENMODULE_DIAGNOSTIC_FORMAT, AROS_GENMODULE_LOG_LEVEL, AROS_GENMODULE_LOG_FORMAT, AROS_GENMODULE_LOG_FILE
• AROS_RELEASE_DIAGNOSTIC_FORMAT, AROS_RELEASE_LOG_LEVEL, AROS_RELEASE_LOG_FORMAT, AROS_RELEASE_LOG_FILE
• AROS_ROMTOOL_DIAGNOSTIC_FORMAT, AROS_ROMTOOL_LOG_LEVEL, AROS_ROMTOOL_LOG_FORMAT, AROS_ROMTOOL_LOG_FILE
• AROS_TRANSPILER_DIAGNOSTIC_FORMAT, AROS_TRANSPILER_LOG_LEVEL, AROS_TRANSPILER_LOG_FORMAT, AROS_TRANSPILER_LOG_FILE
• AROS_VERIFY_DIAGNOSTIC_FORMAT, AROS_VERIFY_LOG_LEVEL, AROS_VERIFY_LOG_FORMAT, AROS_VERIFY_LOG_FILE

Logging is off by default and requires an explicit local file. Across the frontend and every companion, a selected file without a selected level uses info, while an explicit command-line or environment off disables logging and creates no sink. Command-line values override their environment equivalents. COLLECT_AROS_DEBUG is the collector’s public debugging switch for retaining its temporary directory; it can disclose intermediate object and link state and should not be set in routine or release builds.

Ambient host fallbacks

HOME supplies the default AROS state/configuration roots, XDG_CONFIG_HOME supplies the preferred board-config root, PATH is searched only for a complete version-matched build-tool suite when no AROS_BUILD_TOOLS_DIR is set, and CARGO selects the Cargo executable for the explicit aros build-tools build source workflow. RUSTUP_HOME, when it is an absolute existing directory, supplies the installed Rust toolchain store to an isolated local toolchain-producer collector build; its Cargo configuration and registry remain private and lock-verified. These ambient variables do not replace checkout locks, source identities, or artifact digests.

aros cache compiler status passively observes these existing backend configuration variables without reading their values or invoking a backend: CCACHE_CONFIGPATH, CCACHE_DIR, CCACHE_REMOTE_STORAGE, CCACHE_SECONDARY_STORAGE, SCCACHE_AZURE_BLOB_CONTAINER, SCCACHE_CONF, SCCACHE_DIR, SCCACHE_ENDPOINT, SCCACHE_GCS_BUCKET, SCCACHE_MEMCACHED, SCCACHE_REDIS, SCCACHE_S3_BUCKET, and SCCACHE_SERVER_UDS. They remain backend-owned ambient configuration, not AROS cache settings: current status output reports only their names and marks effective storage scope as uninspected. --dir DIR on aros cache compiler status is a separate absolute, status-only root selector; it never rewrites or overrides any of these backend-owned variables.

Qualification-only variables

The following names are explicitly test-internal, are not supported user configuration, and may be compiled out or inert in release builds:

• AROS_TEST_MESA20_SOURCE_ROOT, AROS_TEST_MESA26_SOURCE_ROOT, AROS_TEST_PC_SYS_ROOT, AROS_TEST_SOURCE_ROOT, AROS_TEST_TOOLS_DIR
• AROS_PUBLICATION_TEST_FAIL_AT, AROS_PUBLICATION_TEST_FAIL_PATH, AROS_PUBLICATION_TEST_PAUSE_AT, AROS_PUBLICATION_TEST_PAUSE_MS, AROS_PUBLICATION_TEST_CRASH_AT
• AROS_FETCH_TEST_LOG_FAIL_AT, AROS_FETCH_TEST_PAUSE_AT, AROS_FETCH_TEST_PAUSE_MS
• AROS_CARGO_VENDOR_CREDENTIAL_TEST_CHILD
• AROS_HOST_GENMODULE selects a classic host genmodule executable for differential tests.
• AROS_TEST_LOG_FAIL_EVENT
• AROS_GUARD_TEST_BUSY, AROS_GUARD_TEST_PATH
• AROS_PROCESS_TEST_ESCAPE_PID, AROS_PROCESS_TEST_ESCAPE_STYLE

The guard, process-escape, Cargo-vendor credential-isolation and final-log-failure names are used only by integration-test executables to coordinate isolated filesystem/process fixtures; no supported released command configuration reads them.

The host LLVM version comes exclusively from the effective [host_compiler] contract (checkout override or embedded pristine-upstream default); no ambient version variable overrides it. The toolchain lock is always <checkout>/aros-toolchains.lock.toml, and an unlocked local cross-toolchain is selected only with the explicit --local or --toolchain-dir command-line option. There are no hidden environment variables that replace either selection.

Precedence and inspection

The effective order is explicit CLI option, documented environment variable, versioned checkout configuration, then a documented constant default. There is no fallback to a neighboring checkout or an arbitrary compiler on PATH.

Use aros info, aros cache status, aros cache compiler status, aros cache archives status, aros cache cargo status --dir DIR, aros toolchain list, aros toolchain inventory and aros board doctor to inspect selected values without mutating source or hardware. Cache-status commands do not create roots, traverse their contents, start a compiler-cache daemon, or read backend configuration values; see cache inspection for their precise boundary. inventory works without a checkout and reads only bounded store metadata; it does not run a compiler or assert payload integrity. The checkout-independent toolchain import, toolchain register, toolchain remove and toolchain gc commands use explicit absolute state paths and a preview token before they publish or remove managed local state. remove and gc never target an external prefix or a released archive envelope. aros info prints the effective state root, archive cache, cross-toolchain store, and whether a managed host compiler was verified against the current checkout’s digest.

Managed-import cleanup assumes a private, single-user store. It fails closed when an ancestor, managed directory or regular payload file is group- or world-writable, or when a payload file has multiple links. Do not place a cleanup-managed store on a multi-writer shared path.