From 62ed40c43e45f1ffd8b3ae5af1418a5f9fc550c3 Mon Sep 17 00:00:00 2001 From: Pedro Henrique Penna Date: Fri, 9 Oct 2026 20:09:06 -0300 Subject: [PATCH] doc: document source-collection prerequisites and release archives Remove the claim that collect-sources picks up Python initramfs variants; no such variant exists, and it reads only the built Alpine and Ubuntu manifests. State that collect-sources needs the built kernel, Alpine, and Ubuntu artifacts, Docker, and gpgv, and add the archive-release step that CI runs after packaging each platform. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- doc/distribution.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/doc/distribution.md b/doc/distribution.md index 19bdb8f16..7cdbd87b0 100644 --- a/doc/distribution.md +++ b/doc/distribution.md @@ -1,5 +1,12 @@ # Package and source delivery +`package` stages a release directory, `dist/` by default, from the +built OpenVMM binary and guest artifacts. [Build](build.md) lists the +artifacts and provenance it requires and the binary release layout. Every +package is either binary-only or source-inclusive, and you must choose one. + +## Binary-only packages + Stage a binary release and SHA-256 manifest: ```bash @@ -9,12 +16,21 @@ python3 scripts/nvx.py package --binary-only Binary-only mode requires an explicit acknowledgement because the matching Linux, Alpine, Ubuntu, and Azure Linux source must be published separately. +## Source-inclusive packages + First materialize the release sources: ```bash python3 scripts/nvx.py collect-sources ``` +`collect-sources` reads the package manifests of the built guest artifacts, so +run `build-guest --guest all` first. It requires the kernel, Alpine, and Ubuntu +artifacts, but not the Azure Linux ones. It also needs Docker with the Linux +engine, which fetches and verifies the Alpine upstream sources in an Alpine +container and builds the Linux source archive, and `gpgv`, which authenticates +the Ubuntu source indexes. + This produces a patched Linux corresponding-source archive under `build/sources/linux`, exact Alpine recipes/upstream sources under `build/sources/alpine`, and exact Ubuntu `.dsc` plus referenced source members @@ -46,8 +62,6 @@ licenses. The collector uses the exact aports commit embedded in every installed APK and runs `abuild fetch` plus `abuild verify`. Its manifest lists the executable recipe files, and the Alpine source archive takes its file modes from that list rather than from the collecting host, which may not store them. -If Python initramfs variants are present, `collect-sources` includes their -package manifests automatically. Ubuntu artifacts use Ubuntu userland with the NVX kernel. The collector deduplicates exact source package name/version pairs from both Ubuntu @@ -65,3 +79,25 @@ Newer source versions are never substituted. OpenVMM is MIT licensed: retain its notice, but its source does not have to be published merely because it is aggregated with Linux. See `THIRD_PARTY_NOTICES.md`. + +## Release archives + +Turn a staged release directory into one deterministic archive: + +```bash +python3 scripts/nvx.py archive-release \ + --source dist/0.1.0 \ + --destination dist/nvx-0.1.0.tar.gz +``` + +`archive-release` checks the staged files against their `SHA256SUMS` before +it writes a `.tar.gz` or `.zip` archive outside the staged directory; see +[`archive-release`](usage.md#archive-release). + +CI follows the binary-only path. On `dev` pushes, the `linux-kvm`, +`linux-mshv`, and `windows-whp` platform jobs each stage +`dist/nvx--` with `--binary-only`, then archive it as +`.tar.gz` on Linux and `.zip` on Windows through the +[`package-release`](../.github/actions/package-release/action.yml) action. +[Continuous integration](ci.md) describes the jobs that gate and publish the +resulting development release.