Skip to content

Reference

Native media inputs

Explicit offline inputs for experimental source-selected external media preparation.

aros image prepare builds external media inputs, not the AROS kernel, BSP or Developer volume. Its current provider is esp-idf-bootloader-v1. Preset, chip, silicon interval, flash geometry and partition CSV come from the selected source’s inventoried native contract. There are no board-name defaults.

Terminal window
aros image prepare --preset esp32p4-d1001 \
--source-root /work/AROS-P4 \
--inputs /work/p4-media-inputs.json --inputs-sha256 REVIEWED_SHA256 \
--work-parent /work/private-media-runs \
--jobs 12 --timeout-seconds 900 --format json

The parent must already be a private directory, separate from every input. Every attempt creates a fresh retained child. This command is always offline; prepare and review source archives, patches, vendor tools and wheels separately. It does not download, install host packages, use an ambient IDF environment, replace an existing artifact or write a device. The deadline includes input verification. Ctrl-C cancels supervised children and is checked between local input checks. A single bounded filesystem/tree measurement is not interruptible; cancel or timeout can therefore wait for that measurement to finish before refusing the next phase. No producer starts after an expired preflight budget.

All fields below are required; unknown fields and unsafe paths are rejected. SHA-256 values are explicit 64-character digests, never inferred from a missing pin. All paths are absolute and must not contain parent traversal.

Field Meaning
schema_version 1
format aros-native-media-inputs-v1
qualification local-byte-lock-only
provider esp-idf-bootloader-v1
target_profiles_sha256 Exact raw source aros-targets.toml digest
native_contract_sha256 Exact raw native contract selected by that preset
wheel_lock, idf_lock Objects with regular-file path and raw sha256
interpreter, runtime_prefix Exact CPython executable and measured prefix
wheel_cache Prepared directory containing every exact locked wheel
idf_source, compiler_source, cmake_source, ninja_source Prepared archive receipt declarations below
idf_root, compiler_root, cmake_root Exact extracted prefixes within their bound source trees
cmake, ninja, git Explicit measured executables; no PATH discovery
constraints Exact local Python constraints file bound by the IDF lock

Selected CMake, Ninja and Git executables must be regular executable files, not symlinks. Use their explicit canonical paths rather than package-manager aliases.

Each prepared source object has destination, archive (basename without suffix), suffix, archive sha256 and ordered patches. Each patch has name, nullable relative subdirectory, options and sha256. Only the fetch parser’s closed patch options are accepted. These declarations must match an existing .aros-fetch receipt and the live tree. They neither fetch nor authenticate an archive origin. Vendor compiler/CMake/Ninja archives must be unpatched and match the unique recommended host entries in the locked IDF tools/tools.json.

The wheel document is aros-python-wheels-v1: it binds host, CPython executable and prefix digests, the pip bootstrap filename and exact wheel name/version/filename/SHA-256/size entries. A fresh environment is built from these bytes, without dependency resolution or network access. The aros-idf-bootloader-v1 document binds the IDF version, compiler prefix, source receipts, IDF/compiler/CMake trees, Ninja/Git executables, requirements, constraints and wheel-document digest. Both use schema version 1 and local-byte-lock-only qualification. They are local consistency locks, not release provenance. The typed schemas are maintained in aros-toolchain.

A CPython prefix mismatch reports the expected and measured whole-tree digests. Preserve the original lock and inspect or restore the runtime before preparing new inputs; the command never updates a mismatched pin automatically.

An experimental source-native build contract may declare make_include_bindings: a source-relative original include mapped to an inventoried source-relative .mk fragment. A self-binding reads the inventoried original; a different path selects a source-native projection. Both endpoints must match the contract’s hashes. The fragment is evaluated at the include’s position; later source make.opts assignments retain their order. It is not an ignored include or an ambient Make configuration. Unmapped includes and unresolved values still refuse KOBJ consumption.

Source-local configuration and make.opts files are read in include order against the selected source contract. Present files, including nested fragments, must match its input hashes. An optional include may be absent only at an exact, symlink-free source path; missing required files fail. Source option files cannot be replaced by .mk projections, and configuration fragments cannot declare build owners. Native parsing does not glob other architectures’ option files. Existing plain source inventories and declaration-proved fetched-port/header scopes keep their own provenance rules; global native configuration does not replace them. If they consume source options, the sealed native path applies. Directory expressions use config/make.cfg.in only when it is a sealed input; its bounded, no-follow snapshot shares the include read budget. An unresolved variable can hide an options path even with a .mk suffix and remains an error. Fully resolved generated paths retain their separate capability ownership.

generated_make_templates reconstructs a generated Make include from a sealed .in template, its literal AC_CONFIG_FILES declaration and explicit profile substitutions. It never reads the generated file. Only plain assignments and an optional leading %common marker are supported; quotes are preserved. Duplicate fields, changed input hashes, target-selector overrides and overlapping paths are rejected. The declaration check does not execute Autoconf or evaluate its shell conditions; substitution values come from the source contract.

The P4 projection selects source-default KOBJ flags and disables function instrumentation. Generated global make.opts/make.defaults, environment overrides and Make-built outputs are not imported. This remains experimental; configuration binding alone does not qualify the complete kernel or BSP.

Native SDK objects must have source-declared compile and staging rules. Explicit native configuration supplies their variable and compiler context. The compile, copy and aggregate owners must remain in the physical recipe; an included configuration cannot create providers. Unbound configuration or unsupported object/staging roots fail rather than falling back to an ordinary Make scope. The supported subset is a finite ordinary Make aggregate, local C/C++ sources, %rule_compile/%rule_compile_cxx, and an exact object-copy pattern. Declaration-time flags and generated-header prerequisites are retained. CMake produces private objects; it does not adopt existing Make objects. Unsupported recipes or conflicting output owners stop translation.

SDK file assets support finite source-declared copies under Developer/bin and literal one-line manpage stubs under Developer/man/man1. Each copied input must bind to one concrete file producer for the selected architecture. Existing files and similarly named targets are not producer evidence. Ambiguous producers, cycles, overlapping roots and symlink paths are rejected. The engine also rejects executable output paths changed after registration.

Literal compile-only rules are separate from SDK object staging. A finite ordinary Make aggregate may own local C/C++ inputs and explicit generated object outputs. The native compiler command preserves the source’s ordered arguments, including repeated flag lanes; it does not inject CMake global flags. Bound configuration supplies the source-owned flags and fresh native Developer sysroot. Unknown flags, unmodelled commands and unsafe paths fail. Direct compiler calls preserve the selected language driver’s target and validated SDK ABI options separately from those source arguments. A conflicting target, ABI or Developer sysroot is rejected; arbitrary CMAKE_<LANG>_FLAGS are not imported.

Standalone C %rule_compile_multi calls require verified GenMF templates and mkdep, bound compiler roles, one physical phony owner with the complete object list, and its exact %include_deps list. The mmake argument is a variable namespace, not an owner. Source lookup follows the template’s ordered vpath search; shadowing sources, Make exports and unproven adjacent macros are rejected. Multi-batch and multi-owner forms remain unsupported, as do host/kernel compiler selection and custom source-tree layouts.

The source .d file retains its separate dependency flags and names its object. A private Ninja tracker regenerates it when its headers change; the object’s private depfile combines both contexts. This does not qualify a complete SDK.

Archive, HIDD-compile and layered-header projections may appear in the graph audit before their full producer contracts are implemented. These partial records do not admit targets. Header recipes with unevaluated conditional commands are not treated as simple copies.

GenMF text expansion, MetaMake owner selection and dependency-only Make overlays are separate evidence components. They do not waive unsupported rules or prove compile producers. Object/depfile identities and normal versus order-only prerequisites must be bound before native graph admission.

Source archives accept %mklib_q from=$^ or an explicit finite from= expression that exactly matches the declared prerequisites. The output needs one ordinary #MM owner and a verified archive command. Additional rules for that output, unresolved target aliases and ambiguous paths are rejected. Known one-stem target patterns must be provably disjoint from the archive; the check preserves GNU Make’s directory-stripping semantics. Explicit expressions also require stable variable origins: ambient ?= assignments, later overrides and unproved GenMF or Make effects are refused. Recognizing the archive recipe does not prove its object producers.

Literal generated text has a separate source-owned capability. A nonvirtual #MM owner must name one direct file under its recipe’s gen/<directory> lane, with that mmakefile.src as its prerequisite. Only directory creation and ordered, bounded $(ECHO) text writes with a proven echo binding are supported. Native configuration supplies values, not executable owners. Source and payload hashes are rechecked at build time; arbitrary shell commands and conflicting producers are rejected.

Source-local Python output aggregates require an explicit effective .PHONY declaration and a dependency-only #MM rule. Every prerequisite must bind to one exact script output in the same recipe. Bare #MM alone is insufficient: GNU Make can otherwise apply an implicit recipe. Unknown conditions, opaque commands, custom recipe prefixes and incomplete generator bindings are rejected. Generator target identities include the full output path, so equal basenames in different directories remain separate producers.

With a sealed MetaMake invocation policy, native selection preserves reachable GenMF virtual aliases and their exact source dependencies. Aliases are metadata routes, not executable producers. Existing real providers remain mandatory. An already-known native aggregate cannot hide additional source virtual edges: they are unioned as prerequisites, including uncontracted required edges. The source-owned optional_meta_dependencies contract is the explicit authority for optional architecture hooks: each Selector record must match its captured recipe, original selector expression and bound native edge. A selector spelling alone grants no omission. Absent selector leaves below a contracted virtual route can be omitted only when every declaration agrees and no independent required path reaches that route. Literal collisions, native prerequisites, known providers and rejected capabilities cannot borrow another edge’s proof. The audit and invocation sidecar record source_meta_semantics: imported aliases, verified contracts and exact omitted hook edges.

Without that sealed proof, active dependencies remain required. A commented-out owner never establishes an optional edge; DisabledOwner declarations cannot enable it or waive its consumers. Missing required endpoints fail export and source preparation with the declaring recipe and a fix upstream hint. Classic MetaMake’s tolerance of unknown targets is not an absence proof. Unsupported translation capabilities are reported separately and do not, by themselves, imply an upstream source defect. Rejected rules need an exact source consumer chain to establish a MetaMake owner. Unmodeled includes (including optional generated .d files) and unknown conditional consumers keep ownership unresolved; a path alone is not proof.

Native owner projection and parsing consume the same recipe inputs: mmakefile.src takes precedence over a generated mmakefile; direct fragments remain inputs. Before admission, the tool rechecks recipe discovery and captured bytes against the source-owned ignore policy. A diagnostic graph audit retains source failures and sibling evidence but publishes no build graph or inventory. When a sealed MetaMake policy proves the complete invocation, unowned parser capability failures from uninvoked recipes are recorded separately. Selection uses all actual parser origins, not architecture names or displayed paths. The protected inputs include both the classic source-owner traversal and every required native producer, including implicit link dependencies. Unbound native producer origins prevent all capability exclusions. Every failure from a selected recipe remains checked. Missing source endpoints, unknown origins and global failures cannot be waived by this scope proof. The *.native-invocation.json sidecar records successful export/preparation scope; excluded capabilities remain unsupported, including unsealed .d includes.

A source profile can separately declare native_consumer_contract, using aros-native-consumer-contract-v1 or aros-native-consumer-contract-v2. This experimental contract lists real, sorted graph roots, an explicit ABI and measured invocation inputs, including aros-targets.toml and a sealed MetaMake policy. It has no core, package or media fields. Parsing it does not qualify a compiler, boot medium or board.

The transpiler selects it explicitly with --native-consumer-profile and can bind its exact bytes with --native-consumer-contract-sha256. This mode cannot be combined with the full-build --native-profile selection. Both use the same strict dependency closure and source-owner checks; missing required endpoints, selected capability errors and unknown/global errors remain fatal. Optional edges use a literal selected owner and its exact source selector expression; owner selectors resolve from the same native context. Contract files are limited to 1 MiB, inputs to 16 MiB each, and symlink or hardlinked input aliases are rejected. Native invocation sidecars identify the contract kind; they are scope evidence, not build or release evidence.

The GNU compatibility runner selects a declared consumer contract for its SDK test. If the same source profile also declares a full-build contract, that contract is not used for this test. An invalid consumer contract fails; the runner does not fall back to a full or unscoped build.

Consumer-v2 also seals C and C++ application sources and their additional SDK libraries. After the SDK build, compatibility requires normal driver links at the original and relocated SDK roots. Missing libraries, wrong ABI, stale source bindings or old SDK paths in relocated link evidence fail the run. This integration is not a separately released SDK product or a board boot test.

Direct CMake callers pass AROS_NATIVE_CONSUMER_CONTRACT and its AROS_NATIVE_CONSUMER_CONTRACT_SHA256, an explicit source profile and selectors, and the owned transpiler path. The engine checks the binding before compiler detection and the GNU ISA/ABI/code-model options afterwards. Both graph passes and the saved replay arguments retain the same selection. A configured tree cannot switch contracts or drop its retained binding; use a fresh build tree.

aros-transpiler --validate-native-consumer-only emits read-only JSON for this pre-compiler check. It does not export a graph or prove that the selected roots build. aros build selects the consumer contract when the selected source profile declares only native_consumer_contract. A profile declaring both a build and a consumer contract is ambiguous and fails before toolchain resolution. A complete compiler-consumer run remains a separate qualification step.

SDK consumers must seal config/make.cfg.in. The engine derives the public header root from its AROS_INCLUDES and AROS_DEVELOPER assignments and requires AROS_DEVELOPER/include, matching the GNU driver’s explicit Developer sysroot. Bootstrap headers, source-declared header producers and target include paths use that same root. Unsafe or unresolved paths, incompatible layouts and native Make overrides of the SDK root variables fail validation. Nonconsumer builds retain the internal SDK/include layout.

LLVM SDK contracts may declare an explicit companion compiler role for a separate Developer library, such as x86-64’s i386 lib32. cpu32 alone does not authorize it. The source descriptor must bind the triple, ELF ABI, compiler options and required runtime. Companion objects use that context, not the primary target’s inherited flags; staging checks their ELF identity and unchanged bytes on incremental builds too.

Architecture client-linklib sources remain separate from runtime module sources. They replace matching generic client sources in both normal and relative archives. A source-owned linklib leaf builds its architecture objects, not the whole archive. Compile-multi neighbors require verified template effects, disjoint outputs and a physical owner; AVX flags are retained. These graph capabilities do not prove a complete SDK build or release.

The engine passes the build directory to aros-genmodule --output-root, keeping the Developer includes, generated sources and symbol audit in one publication transaction. Every output must remain strictly below that root; symlinked parents and escaping paths are rejected.

This resolves the native source-definition subset, not a configured GNU Make build. Build-local make.opts customizations are not imported.

Directory-only producers support finite %mkdirs_q recipes and explicit %rule_makedirs dirs=... setuptarget=... declarations. They create directories under the configured generated, include or Developer-library roots; they do not execute source-provided shell commands. Unresolved conditions, root overrides and paths crossing symlinks are rejected.

Named handwritten GENMODULE writefiles stamps use the same manifest-backed writer as normal and relative client archives. CMake tracks concrete generated sources and private headers; a missing output reruns the writer. Configuration paths must remain regular and source-confined, without symlink components. Shell additions, unresolved conditions and conflicting selected owners refuse translation. This capability does not import Make-generated stubs or qualify a complete native payload.

Source contracts may also declare host_file_generators: an inventoried C utility, its matching Make recipes, a generated-file owner and exact raw inputs. Each input has a versioned HTTPS URL, SHA-256 and size. The CLI prepares the verified input cache; offline builds require those bytes to be present. The transpiler rejects declarations that do not match the source recipes. CMake compiles the host utility and generates the file locally, without running Make or fetching inputs. This is experimental build support, not a qualification of the complete kernel, BSP or Developer volume.

The JSON result and retained preparation.receipt.json bind the input document, source selector, media geometry, isolated Python receipt, bootloader receipt and verified bootloader/table bytes. The private IDF execution copy preserves the prepared source; logs and failed attempts remain available for diagnosis. Native AROS output roles are not invented: complete_flash_plan is false.

Wrong chip/revision/capacity, altered checksums, mismatched source inventories, overlapping slots or changed receipts fail. Verification does not prove secure boot, a complete P4 native build, physical boot or permission to flash. Full native core/BSP/Developer integration remains experimental.