Build and develop
Physical boards
Match a local profile to real hardware, validate boot inputs, and preview deployment before writing.
A board profile identifies one physical device. Its name is your local label; its model, backend and transport determine the supported operations. A profile or successful image build is not proof of a UART boot.
Implemented models and transports
Section titled “Implemented models and transports”| Model | Backend | Supported transport | Required core inputs |
|---|---|---|---|
rpi3 (Pi 3B+ DTB contract) |
raspberry-pi |
native-tftp |
ARM KOBJ triplet and model DTB |
rpi4 |
raspberry-pi |
native-tftp, uboot-usb-ecm |
AArch64 KOBJ triplet and model DTB |
rpi5 |
raspberry-pi |
native-tftp |
AArch64 KOBJ triplet and model DTB |
milk-v-titan |
opensbi-uefi |
uefi-esp |
RISC-V legacy core objects |
The validator rejects USB-ECM on Pi 3/5 and rejects a Pi transport for the OpenSBI/UEFI backend. Debug transport and power-control fields are metadata; the CLI does not automate JTAG, SWD or power equipment.
Source: board schema and validation.
The portable board registry
contains the four stable model IDs used by the CLI and template generator.
Those IDs resolve from the registry embedded in the tools build; the CLI does
not discover an external registry. A local profile name is an alias and stays
separate from the model ID. No ESP32-P4 model or support is advertised.
The --model help and generated Bash, Zsh and Fish completions use the same
catalog as the parser.
Experimental ESP32-P4 integration
Section titled “Experimental ESP32-P4 integration”Native P4 development is tracked in RV3.
Local checks cover source-bound contracts, compiler isolation without the old
Make SDK, ESP image inspection and byte-identical partition-table generation.
The internal planner checks source-declared partition types and separate BSP /
Developer erase slots. aros image prepare prepares a hash-locked
Python environment and builds a fresh bootloader with controlled vendor tools.
Archive/patch receipts bind prepared source bytes. Vendor tool archives are
checked against the locked IDF manifest and their selected executable trees.
IDF uses a private verified
working copy so its Git index refresh cannot mutate those inputs. Independent
image checks pass; local receipts are not release provenance.
Native SDK header generation follows the selected source rules, including
host-C generators and GENMODULE recipes. GUI selection belongs to the source profile;
there is no ESP32-specific MUI switch in Rust. Required headers may still be
generated for nongraphical builds.
Bounded source-text recipes also preserve ordered header edits and generated
cross-configuration scripts. Both FreeType products pass local byte comparisons
against the source’s GNU sed rules; this is not a complete native P4 build.
Finite SDK file copies preserve the exact source file list and bytes. The
Codesets FD copy passes local staging, missing-output repair and rebuild probes.
Developer-library copies use only the configured library root and regular local
inputs. Source Make defaults and finite file lists are retained; private CMake
recipes bind the input hashes. These bounded capabilities do not qualify the
complete P4 SDK.
Full resource macros also select public GENMODULE ABI production; runtime-only
macros do not. A full declaration can retain its source-bound header generation
when its runtime compiler capability is unsupported. That projection creates
no runtime module or client archive; selecting either still fails. The native
graph remains incomplete.
Finite static-pattern header copies preserve nested paths and their single
source-declared include destination. Directory lists follow the recipe’s Make
variable state; local include-root redirection is rejected.
Named host-header aggregates retain all declared outputs and only explicit
include mirrors. Incremental builds recheck their paths and sealed recipes;
an unchanged valid build does not rewrite the headers.
Handwritten SFDC header recipes retain their source-declared mode, target,
input hash and SDK output. The private host compiler and actual CIA headers
match direct reference generation. Input drift, unsafe paths and a successful
process without a new output are rejected. This is header evidence, not CIA
runtime or complete P4 qualification.
Optional MetaMake selector edges must be declared in the source contract and
proven in their hash-bound recipe. Only absent providers are omitted and
recorded. Literal dependencies, unknown selectors and rejected real producers
still stop native selection.
The source-owned MetaMake policy can also select the supported module,
linklib and set-archincludes template-hook families. Each omission requires
the sealed macro definition and exact source callsite, not a target-name
allowlist. The base module family includes the reviewed module, archive and
program callers; it does not admit their quick or other suffix-specific hooks.
Physical architecture objects and include-flag files retain their
own producers and prerequisites; a missing source implementation is not an
optional hook. Unsupported declarations retain source-line diagnostics.
Continued #MM declarations use the same grammar for parsing and source
verification; their required prerequisites are preserved.
Architecture effects use the profile’s explicit Make configuration and replay
with the same captured values. CLI selectors must match the source profile;
a declared Mesa version cannot be overridden. Unknown feature switches remain
errors, not implicit defaults. A verified physical architecture producer can have an
optional generated variant hook; the producer and its required edges remain.
KOBJ integration preserves the source macro form and separates partial linking
from GNU symbol localization. Source groups retain Make’s architecture-object
ordering, including fetched-source proxies, and copy the module’s compilation
state. The CMake partial-link helper matches a separate real RV32 link and GNU
localization recipe byte-for-byte. Declaration-scoped extra objects, libraries
and linker flags retain ordered metadata; unknown inputs cannot be consumed as
empty lists. The native core consumes registered collected/localized KOBJ
intermediates, not raw module objects. Its source binding also retains the macro
libraries, global partial-link values and instrumentation selector. Missing
configuration proof and unsupported instrumentation stop configuration. Global
configuration and a fresh P4 core remain unqualified. These are host-only
contracts, not a complete P4 build.
An empty module uselibs list can leave the literal prefix linklibs- in
GenMF metadata. Native selection normalizes this only with an exact sealed
module-template definition, an empty resolved argument and matching callsite
provenance for every claim. Handwritten collisions, independent required
edges, declared endpoints and nonempty or unresolved lists remain required.
Imported metadata records provenance per dependency: another recipe declaring
a different prerequisite on the same target does not become its origin.
Classic MetaMake’s general tolerance of missing targets is not reproduced.
uselibs names library interfaces, not necessarily Make targets. A generated
prerequisite can bind to a different archive target only when its sealed
callsite, typed consumer and unique source-owned %build_linklib agree.
Handwritten dependencies, name collisions and ambiguous providers still fail.
The source contract’s optional make_variables object supplies literal
configuration defaults. An explicit empty value is known; an omitted variable
remains unknown. Local Make assignments can replace these defaults. Unknown
conditional writes still prevent publishing a partial native graph.
Uninstantiated GNU define bodies cannot supply live assignments. An opaque
definition also prevents reuse of an older value or configuration default.
Architecture declarations use bounded Make expressions and source-bound
include scopes at their declaration positions. They preserve ordered include
paths and -D definitions; filesystem enumeration is not allowed in this
proof. A configured value with an unknown Make assignment flavor cannot
justify a later append.
A source-defined C-to-assembly header pipeline requires exact compiler-role, sysroot, flags and include metadata. Its generated file is not producer proof. Unsupported recipes remain diagnostics; native selection does not replace them with an empty target or borrow a bootstrap output. The current P4 source profile is not yet sufficient to qualify that complete pipeline.
Local compiler admission uses byte-verified metadata, not release provenance. CLI and CMake admission are tested with a real RV32 compiler; they do not qualify a P4 payload. SDK-text generation binds its source recipe and preserves first-match substitutions and line endings; changed recipes stop the build.
Local native builds record source, compiler, engine, executable and configure input hashes before execution. Dirty edits and initialized submodule files are included. Changed inputs or cached Ninja rules stop reuse; unstamped historical trees are refused. This stamp is not a successful-build or media receipt.
A native source contract may explicitly declare a disabled MetaMake metadata owner. Its comment and dependency must be in the same hash-verified recipe. The translator reports absent metadata without enabling the commented rule; active producers and other missing dependencies retain their normal checks.
The device-free external preparation uses an explicit native source preset, closed local input document, positive jobs/deadline and fresh private work root. See native media inputs for its command and byte-lock contract. It is not exposed as a physical P4 board model.
Still open: fresh native kernel/BSP/Developer builds, reviewed external-input provenance, complete flash-artifact composition and the full public workflow. Older Make outputs, container checks and host-only tests do not qualify device readiness or flashing.
Create and diagnose a profile
Section titled “Create and diagnose a profile”For a Pi 4 USB-ECM profile, preview the generated template:
aros board init --profile rpi4-usb --model rpi4 --transport uboot-usb-ecmThen create a new config file explicitly:
aros board init --profile rpi4-usb --model rpi4 --transport uboot-usb-ecm --applyaros board scanThe generated build defaults come from the embedded reviewed registry. The example file at support/rpi-debug/boards.example.toml is a legacy local-profile example; it is not discovered as a model registry. Network addresses and MAC values in generated or example profiles are placeholders. Adapt them to the local network and the actual device identity; do not infer network or device values from a model ID. Unsupported model/transport pairs fail before a file is written. For example, Pi 3 and Pi 5 cannot select USB-ECM, and Titan cannot select a Pi TFTP path.
Edit the printed file (normally ~/.config/aros/boards.toml) with the real
paths, interfaces, serial device and device identity. Use a matching target
preset declared by your selected AROS checkout. The built-in four toolchain
profiles are not the example registry’s board-specific debug presets.
For Pi 4 USB-ECM, copy the stable USB descriptor values from board scan;
do not persist a guessed dynamic interface name. Then, inside the AROS tree:
aros board doctor --profile rpi4-usbBuild, deploy and serve
Section titled “Build, deploy and serve”With the profile’s exact DTB and legacy core objects present:
aros board build --profile rpi4-usbaros board deploy --profile rpi4-usbaros board deploy --profile rpi4-usb --applyaros board serve --profile rpi4-usb --dry-runaros board serve --profile rpi4-usbDeploy previews by default; --apply stages the bundle to the configured
TFTP destination. The configured tftp_prefix must resolve through real
directories below tftp_root; symbolic links in that path are rejected.
Serve binds restricted DHCP and read-only TFTP to the validated interface and
board identity. The host address must already be configured. These network
commands are not the Milk-V UEFI-ESP boot path.
Open a serial console separately:
aros board console --profile rpi4-usb --dry-runaros board console --profile rpi4-usb --program picocomSupported terminal programs are picocom, screen and minicom.
Auto mode searches in that order. Save and interpret the resulting UART
evidence using your board’s bring-up procedure.
SD-card safety sequence
Section titled “SD-card safety sequence”Image creation needs an external boot-bundle.toml plus its hash-declared
firmware and artifact inputs. A build directory alone is not a boot bundle.
Use the prepared bundle for the exact model/transport. The reviewed Pi 4
U-Boot USB-ECM and Milk-V Titan UEFI file layouts are defined in the
media-profile registry;
the local board name does not select a different layout. Native Pi SD and PC
ISO profiles are not yet available through this SD command.
aros board sd image --profile rpi4-usb --boot-bundle /verified/bundle --output /new/artifactaros board sd image --profile rpi4-usb --boot-bundle /verified/bundle --output /new/artifact --applyaros board sd scan --artifact /new/artifactIf the intended removable disk is mounted, inspect and explicitly unmount it:
aros board sd unmountaros board sd unmount --device SCAN_ID --applyRun sd scan --artifact again after unmounting. Substitute its exact scan
ID and confirmation token in the write sequence:
aros board sd write --profile rpi4-usb --artifact /new/artifact --device SCAN_ID --dry-runaros board sd write --profile rpi4-usb --artifact /new/artifact --device SCAN_ID --confirm TOKENThe final command writes the selected medium. Candidates must be whole, removable, writable and unmounted. Raw device paths are rejected; the token binds the measured image and device identity. The writer performs read-back verification. SD image creation uses the implemented MBR/FAT32 format; it is not a general disk-partitioning frontend.
Evidence still required
Section titled “Evidence still required”For a physical-boot claim, record the model, firmware, source commit, cross-toolchain identity, legacy core inputs, artifact digests and UART log. Do not infer boot support from an available profile or compiler.
The detailed Raspberry Pi lab guide covers the prepared firmware and external-debugger workflow.