doc: document native guest builds and their download cache

[Pedro Henrique Penna (ppenna)]

Summary

The build guide never explained build-guest --native. That workflow builds guest artifacts on Linux without Docker, and it is how agents and offline hosts rebuild guests from staged archives. This PR adds a short section to doc/build.md that covers which guests the native build supports, why it never produces the Ubuntu EROFS distro layer, and how it reuses pinned archives staged in the download cache.

Changes

All changes are in doc/build.md, right after the Docker --guest all example:

Statement	Evidence
--native builds the kernel and the selected Alpine or Ubuntu initramfs on Linux without Docker.	build_guest in scripts/nvx_tools/build.py (native branch calls build_kernel/build_initramfs, both _require_linux); python scripts/nvx.py build-guest --help
A native build rejects --guest azurelinux and --guest all.	native_build_supported=False for Azure Linux in scripts/nvx_tools/guests.py; selected_guests() returns every guest for all; python scripts/nvx.py build-guest --native --guest all and --guest azurelinux both exit 1 with error: Azure Linux initramfs builds require Docker
Only --guest all builds the Ubuntu EROFS distro layer, so build it after a native build with build-distro-layer.	Native branch builds the distro layer only when guest == "all"; Docker single-guest targets in build_docker_artifacts expect no EROFS output
The Linux archive, Ubuntu Base archive, and supplemental Ubuntu packages are kept under downloads/ in .cache/ or $NVX_CACHE_DIR. A file there that matches its pinned SHA-256 is reused; any other file is downloaded again.	prepare_kernel_source in build.py, ubuntu.py (Ubuntu Base and ubuntu-packages/), cache_root and download_verified in common.py, BuildConstants.CACHE_ENVIRONMENT_VARIABLE
The Alpine minirootfs and packages still come from Alpine's servers.	_prepare_alpine_root downloads the minirootfs into the build work directory, and _apk_add runs the minirootfs's apk add

The design docs are unchanged, so no OpenVMM SHA applies. The pin is e5bf79776bb32f8fa29a69e7b3c9bf668477a13a.

Follow-ups (out of scope)

• Suspected dead code: native build_guest calls build_distro_layer when guest == "all", but the Azure Linux check rejects all before that line runs. Either the branch is unreachable, or a native all should build the Alpine and Ubuntu artifacts plus the distro layer. Code was not changed.
• doc/project-structure.md labels doc/guests/ "(Ubuntu)", but it also holds azurelinux-guest.md.
• unittest_results.txt is a tracked test log from the initial commit and appears to be stray. Consider removing it.
• scripts/setup/README.md is documentation outside doc/. Relocating it means editing links in doc/setup.md and doc/ci.md, which open PRs filesystem: map host paths from any volume, each with its own access #459, Adopt bind-once microVM image slots #406, and test-microvm: pause and resume a microVM through OpenVMM state control #405 touch, so it was deferred.
• doc/openvmm-upstream-roadmap.md is a dated planning snapshot. Its fork tip 2728f33ea predates many pin updates since 2026-10-02, and a refresh exceeds one run's budget.

Files touched by open PRs (#459, #417, #406, #405) were left alone.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: Ran 110 tests, OK (skipped=1)
• Throwaway link checker kept outside the repo: every relative link and anchor in doc/build.md and the 7 files that link to it resolves; the file has one H1 and balanced fences; doc/design.md links every chapter in doc/design/. A negative probe with a bad anchor was caught.
• git diff --check: clean
• python scripts/nvx.py verify: source tree and submodule metadata are consistent
• Base: origin/dev at dcde299f70ad237a8bc04df62afc88d2172c091a. The change is documentation-only (doc/build.md).

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the implemented native build and cache behavior.

0 open findings

What changed in this PR

Documents native Linux guest builds and offline cache reuse.

Changes:

• Explains supported native guest targets and Ubuntu EROFS handling.
• Documents verified archive caching and Alpine network requirements.

File	Description
doc/​build.md	Adds native build and download-cache guidance.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.