Skip to content

doc: document source-collection prerequisites and release archives #458

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 1 commit into from
Oct 10, 2026
Merged

doc: document source-collection prerequisites and release archives #458

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions doc/distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Package and source delivery

`package` stages a release directory, `dist/<version>` 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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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-<version>-<platform>` 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.
Loading