[Pedro Henrique Penna (ppenna)]

Summary

doc/build.md described release packages as if they shipped only the Alpine guest. Since the Ubuntu and Azure Linux guests became release artifacts, scripts/nvx.py package also stages the Ubuntu initramfs, the Ubuntu EROFS distro layer, their manifests, and in binary-only packages the Azure Linux initramfs, and it requires these files to exist. This PR updates the release section of the build guide to match the packaging code, and lists the Azure Linux build outputs next to the Alpine and Ubuntu ones.

Changes

All changes are in doc/build.md.

Statement	Before	After	Evidence
Binary release layout	Listed only guest/vmlinux, vmlinux.config, and the Alpine initramfs and its manifest	Also lists guest/initramfs-ubuntu.cpio.gz and its .packages.json, guest/ubuntu-distro.erofs and its .manifest.json, and guest/initramfs-azurelinux.cpio.gz and its .packages.json	ReleaseBuildConstants.GUEST_ARTIFACT_NAMES in scripts/nvx_tools/build_constants.py; package_release copies each name into guest/ (scripts/nvx_tools/release.py)
What packaged SOURCE-MANIFEST.json hashes	OpenVMM, Linux, the kernel config, and "the unchanged Alpine initramfs"	Also each packaged guest initramfs and its package manifest, plus the Ubuntu distro layer and its manifest	_packaged_source_manifest in scripts/nvx_tools/release.py writes the ubuntu hashes and, in binary-only packages, the azurelinux hashes
Packaging prerequisites (new)	Not stated	Needs the OpenVMM binary, the guest artifacts in the layout, and the OpenVMM, kernel, and Alpine initramfs provenance sidecars, so run build-openvmm and build-guest --guest all first. A source-inclusive package does not need the Azure Linux artifacts.	_guest_release_inputs and _require_runtime_provenance_paths in release.py; build_docker_artifacts maps --guest all to the all-guest-artifacts target in docker/Dockerfile; test_source_package_omits_azure_linux_artifacts in scripts/test_nvx_tools.py
Replacing an existing dist/ version (new)	Not stated	Requires --force	_validate_release_replacement in release.py; python scripts/nvx.py package --help
Azure Linux build outputs (new)	Not listed	build/initramfs-azurelinux.cpio.gz and its .packages.json, built only in Docker	build_docker_initramfs in scripts/nvx_tools/build.py, azurelinux-initramfs-artifacts target in docker/Dockerfile, native_build_supported=False in scripts/nvx_tools/guests.py

doc/distribution.md already says that --include-source drops the Azure Linux artifacts and the azurelinux manifest section. I didn't repeat that in doc/build.md.

The design docs are unchanged, so there is no OpenVMM SHA to report. The base is origin/dev at 75df18412a7b991c51e4511dc3da1502be218702.

Follow-ups (out of scope)

• scripts/setup/README.md is documentation that lives outside doc/. It could move to doc/ (for example, into doc/setup.md), but open PR Adopt bind-once microVM image slots #406 modifies doc/setup.md, so I didn't touch it.
• doc/design/time-abi.md (around the CPU-profile restore rule) still says an explicit restore --cpu-profile must name the recorded profile or host, without mentioning auto. The doc: add CPU profiles and the RAM overlay to the configuration boundary #454 review noted that the pinned implementation accepts auto on restore. Open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406 modify that file, so I left it alone.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: 110 tests passed (1 skipped).
• A throwaway link checker kept outside the repo checked doc/build.md and the files that link to it (README.md, doc/benchmarks.md, doc/guests/ubuntu-guest.md, doc/project-structure.md, doc/usage.md): every relative link and anchor resolves, doc/build.md has one H1 and balanced code fences, and doc/design.md links every chapter in doc/design/.
• git diff --check: clean.
• python scripts\nvx.py verify: passed. The openvmm submodule HEAD matches the gitlink f4566bab0a30324de0a2ac292a65d0081ba319e0.
• Scope: one Markdown file under doc/ (22 lines added, 4 removed), with no code, workflow, or gitlink changes. The file is not touched by any open PR.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the artifact constants and release packaging logic.

0 open findings

What changed in this PR

Updates the build guide to match the current release packaging implementation.

Changes:

• Documents Azure Linux build outputs.
• Lists all Ubuntu and Azure Linux packaged artifacts.
• Clarifies packaging prerequisites, manifest hashes, and --force behavior.

File	Description
doc/​build.md	Aligns guest build and release layout documentation with packaging behavior.

🧠 Review effort: Balanced

---

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