A VIOS build has two halves that must match:

• the eZ80 resident (build/vios-resident.bin), built with Make and the AgonDev toolchain;
• the ESP32 firmware (firmware.bin), built with PlatformIO. It embeds the resident it was built with.

You also build the small boot stub (build/viosboot.bin) that MOS runs from the SD card. Everything below runs on the Mac and never touches the board.

Toolchains

None of these is installed by Make, and .tools/, .venv/ and build/ are ignored by Git. A fresh clone therefore needs this one-time setup:

# Python environment
python3 -m venv .venv
.venv/bin/pip install -r tools/requirements.txt

# AgonDev v0.22: download agondev-darwin_arm64.tar.gz from the AgonDev
# releases page (github.com/AgonPlatform/agondev) and unpack it as .tools/agondev
mkdir -p .tools
tar -xzf agondev-darwin_arm64.tar.gz -C .tools
.tools/agondev/macos_remove_quarantine.sh      # macOS: clear the download quarantine
ls .tools/agondev/bin/ez80-none-elf-clang

# PlatformIO (if you do not have it): see platformio.org; the project uses
# ~/.platformio/penv/bin/pio. The first build downloads the pinned packages.

Check that the unpacked directory is really named .tools/agondev, or pass AGONDEV=/path/to/agondev to every make. Keep the pinned versions. In particular, espressif32 6.4.0 is known to break VDP mode 3 by using more memory.

The VDP sources are vendored, so no network is needed for them. The ESP firmware is built from firmware/esp32-vios/vendor/agon-vdp (breakintoprogram/agon-vdp commit 61888ab, VDP 1.04) and vendor/vdp-gl (avalonbits/vdp-gl commit 48a0b9a, 1.0.3), with VIOS changes on top. Their archive URLs and SHA-256 values are in vendor/manifest.json.

The paired build

Build the resident first, then the ESP firmware, in that order and never at the same time, with the same internal baud rate:

make test                                    # optional, but run it before, not during
make vios-resident VIOS_INTERNAL_BAUD=1152000
make viosboot
VIOS_INTERNAL_BAUD=1152000 ~/.platformio/penv/bin/pio run -d firmware/esp32-vios -e esp32-vios

These are the reasons for the order:

• The ESP build embeds the resident. A PlatformIO pre-build script, firmware/esp32-vios/scripts/embed_vios.py, reads build/vios-resident.bin and compiles it into the firmware's flash as constant data. It also embeds the 46-byte native bootstrap build/agon-stage0.bin, the CRC stage build/agon-crc.bin and the flash stage build/agon-flash.bin, which make vios-resident builds too. If any is missing or out of bounds, the ESP build stops.
• Both ends must agree on the internal UART rate. VIOS_INTERNAL_BAUD sets the eZ80-to-ESP32 link: 1152000 (default), 384000, or 115200 (historical). Make records the rate in build/vios-resident.baud. The embed script refuses to build if that file is missing or names a different rate than the ESP build's VIOS_INTERNAL_BAUD. The USB link to the Mac is always 115200.
• Both ends must agree on the GUI. VIOS_GUI=1 (default) builds a resident whose workbench draws through the ESP display server, paired with an ESP that boots into the GUI. VIOS_GUI=0 builds the older VDU text screen. Make records the choice in build/vios-resident.gui, and the embed script checks it against its own VIOS_GUI environment variable (default 1).
• make test relinks the resident. Some host tests run make build/vios-resident.bin at the default settings. Running them while the ESP build is reading the resident can embed the wrong image.

Make forces a relink when you switch rate or GUI mode, even within the same second. macOS Make compares timestamps at one-second resolution.

To embed a different validated image, set VIOS_IMAGE=/absolute/path/image.bin for the ESP build. Its .baud and .gui sidecars must sit next to it.

What the build produces

PlatformIO also produces a bootloader and a partition table as normal intermediates. They are never installed: VIOS updates write one application slot only.

The resident build stamp

After linking, tools/vios_stamp.py writes the build's identity into the binary. kernel/vios_boot.c contains a 4-byte STMP marker followed by a zero word. The tool computes the CRC-32 of the whole binary with that word still zero, and stores the result in the word (it uses 1 if the CRC happens to be 0, because 0 means "unstamped"). Restamping gives the same value. The tool fails unless there is exactly one marker. It prints the result (the value differs for every build):

build/vios-resident.bin: build stamp 1A2B3C4D

The stamp keys the boot-module cache. On a normal boot the resident reads, checks and compiles the modules of the confirmed boot bundle, then saves the compiled result as /VIOS/CACHE_A.VIC or /VIOS/CACHE_B.VIC. Later boots restore that cache instead of compiling, which takes about 0.9 s instead of about 2.2 s for five modules. The cache is used only when its key matches the build stamp, the bundle CRC and the base dictionary. A new resident therefore never restores a cache compiled by another build: its first boot compiles and rewrites the cache, which costs about 1.4 s extra once. An image loaded straight from the ELF reads stamp 0 and never uses the cache.

Versions and releases

The version lives in one place, the VERSION file at the top of the repository (0.8.0 for this edition). make vios-resident compiles it into the resident, whose console greets you with VIOS v0.8 and the copyright line; the ESP32 build writes it into the firmware's boot log and into build-manifest.json. CHANGELOG.md lists what changed in each version.

A release is a tag vX.Y.Z on main. Pushing the tag runs the GitHub Actions workflow .github/workflows/release.yml: it checks that the tag, VERSION and CHANGELOG.md agree, runs the host tests, builds the resident, the boot stub and the ESP32 firmware as a matched pair, packages them with tools/vios_release.py, builds this manual's site, and publishes the release with three files: vios-X.Y.Z.zip, vios-X.Y.Z-SHA256SUMS and vios-X.Y.Z-manual.zip. The step-by-step process, and how to try a release build without publishing it, are in docs/RELEASING.md.

Makefile targets

make with no target builds the historical all. The targets you normally use are test, vios-resident and viosboot.

Make variables:

PlatformIO environments in firmware/esp32-vios/platformio.ini:

The ESP build reads these environment variables: VIOS_INTERNAL_BAUD (default 1152000), VIOS_GUI (default 1) and VIOS_IMAGE (default build/vios-resident.bin).

Checking a build before you install it

• firmware/esp32-vios/build-manifest.json must name the resident you just built. Its embedded_vios.sha256 equals shasum -a 256 build/vios-resident.bin. Its internal_baud and gui must be what you intended, and size must be below app0_limit.
• make test passes on a clean tree. Run it before the paired build, not during.
• After installing, the boot events end with BOOT stub runs this firmware's image and HEALTH flag 1 (see Installing).