guide: document standalone OpenVMM releases

Guide/src/SUMMARY.md

@@ -61,7 +61,9 @@
   - [Coding Conventions](./dev_guide/contrib/code.md)
   - [Save State](./dev_guide/contrib/save-state.md)
   - [Snapshot Format](./dev_guide/snapshot_format.md)
-  - [Releases & Code Flow](./dev_guide/contrib/release.md)
+  - [OpenVMM Release Model and Support](./dev_guide/contrib/openvmm_release.md)
+    - [Packaging OpenVMM for a Linux Distribution](./dev_guide/contrib/openvmm_packaging.md)
+  - [OpenHCL Release Management](./dev_guide/contrib/openhcl_release.md)
   - [Submitting Changes](./dev_guide/contrib/pr.md)
   - [Code Review Process](./dev_guide/contrib/code_review.md)
   - [Guide Updates](./dev_guide/contrib/guide.md)

Guide/src/dev_guide/contrib/release.md → Guide/src/dev_guide/contrib/openhcl_release.md

@@ -1,16 +1,35 @@
-# Release Management
+# OpenHCL Release Management
 
-Occasionally, the OpenVMM project will declare upcoming release milestones. We
-stabilize the code base in a `release/<MAJOR>.<MINOR>.<YYMM>` branch, typically
-named for the YYMM when the branch was forked. Future references to the release
-number will be shortened to `<RELEASE>` in this doc. We expect a high quality
-bar for all code that goes into the OpenVMM main branch, and we ask developers
-to hold these release branches to the highest quality standards. The OpenVMM
-maintainers will gradually slow the rate of churn into these branches as we get
-closer to a close date.
+This page describes the OpenHCL release branch, stabilization, and servicing
+process.
 
-> **Note:** Some older release branches use the format `release/<YYMM>` without
-> the major and minor version numbers (e.g., `release/2411`, `release/2505`).
+```admonish note title="See also"
+[OpenVMM Release Model and Support](./openvmm_release.md) describes standalone
+OpenVMM releases. OpenVMM tags and versions are independent from the OpenHCL
+release branches described below.
+```
+
+```admonish warning
+The `release/*` branches on this page service OpenHCL. They are not standalone
+OpenVMM release branches. OpenVMM releases directly from `main`. Post-`1.0` it
+may also create an on-demand patch branch when its currently supported release
+requires a security or release-blocking fix; see
+[OpenVMM Release Model and Support](./openvmm_release.md).
+```
+
+Occasionally, the OpenHCL project will declare upcoming release milestones.
+We stabilize the code base in a `release/<MAJOR>.<MINOR>.<YYMM>` branch,
+typically named for the YYMM when the branch was forked. Future references to
+the release number will be shortened to `<RELEASE>` in this doc. We expect a
+high quality bar for all code that goes into the repository's main branch, and
+we ask developers to hold these release branches to the highest quality
+standards. The OpenHCL maintainers will gradually slow the rate of churn into
+these branches as we get closer to a close date.
+
+```admonish note
+Some older release branches use the format `release/<YYMM>` without the major
+and minor version numbers, such as `release/2411` and `release/2505`.
+```
 
 This process should not impact your typical workflow; all new work should go
 into the `main` branch. But, to ease the cherry-picks, we may ask that you hold
@@ -19,10 +38,8 @@ process.
 
 ## Marking, Approval Process, Code Flow
 
-The OpenVMM maintainers will publish various dates for the upcoming releases.
-Currently, these dates are driven by a Microsoft-internal process and can, and
-do, often change. Microsoft does not mean to convey any new product launches by
-choices of these dates.
+The OpenHCL maintainers will publish various dates for upcoming releases. These
+dates may change as release needs evolve and do not convey new product launches.
 
 Releases naturally fall into several phases:
 
@@ -42,7 +59,9 @@ We track the state of candidates for a given release by tagging the PRs with the
   * N.B.: A maintainer will _remove_ this tag if the fix is not accepted into the release.
 * `backported_<RELEASE>`: This PR (to `main`) has been cherry-picked to the release branch.
 
-The [`repo_support/relabel_backported.py`](https://github.com/microsoft/openvmm/blob/main/repo_support/relabel_backported.py) script can be used to automatically transition PRs from `backport_<RELEASE>` to `backported_<RELEASE>` once they have been cherry-picked to the release branch.
+The [`repo_support/relabel_backported.py`][relabel-backported] script can
+automatically transition PRs from `backport_<RELEASE>` to
+`backported_<RELEASE>` once they have been cherry-picked to the release branch.
 
 #### Seeking Approval for Backport
 
@@ -66,7 +85,7 @@ When creating a backport PR to a release branch:
   resolution or additional modifications), clearly indicate this in the PR
   description. This signals to the reviewer that extra care is needed during
   the review process.
-  
+
 ## Existing Release Branches
 
 | Release          | Phase              | Notes                                                                                |
@@ -81,3 +100,5 @@ When creating a backport PR to a release branch:
 
 We welcome feedback, especially if you would like to depend on a reliable
 release process. Please reach out!
+
+[relabel-backported]: https://github.com/microsoft/openvmm/blob/main/repo_support/relabel_backported.py

Guide/src/dev_guide/contrib/openvmm_packaging.md

@@ -0,0 +1,228 @@
+# Packaging OpenVMM for a Linux Distribution
+
+This page describes building the `openvmm` binary as a Linux distribution
+package, from public source only. It is aimed at downstream packagers (for
+example, an RPM or `.deb` maintainer) who build from the official OpenVMM source
+release rather than from the in-repo `cargo xflowey` provisioning flow.
+
+The examples target [Azure Linux](https://github.com/microsoft/azurelinux), but
+the requirements generalize to any glibc distribution.
+
+```admonish note title="See also"
+[OpenVMM Release Model and Support](./openvmm_release.md) describes the source
+release archive and version identity that a distribution package builds from.
+[Crypto Backends](./crypto_backends.md) explains the backend selection that
+determines the native dependencies below.
+```
+
+## What a distribution package builds
+
+A distribution package builds the host `x86_64-unknown-linux-gnu` target:
+dynamically linked against the system glibc and OpenSSL. Building from the
+official source release is the supported way to consume OpenVMM today, and this
+is the configuration to use. It differs from the statically linked `musl`
+binaries that the repository's own provisioning tooling produces, which is what
+the project will ship if and when it publishes prebuilt Linux archives.
+
+The gnu build deliberately avoids the repository's `.packages/` provisioning
+(`cargo xflowey restore-packages`), which fetches prebuilt native libraries a
+distribution build cannot consume. A packager instead supplies every native
+dependency from distribution packages and overrides the few build settings that
+otherwise point into `.packages/`.
+
+```admonish tip title="Only two overrides are required"
+Building the `openvmm` binary for the gnu target needs no source patches. It
+needs the distribution build packages below, plus two environment overrides
+(`PROTOC` and `OPENSSL_NO_VENDOR`).
+```
+
+OpenVMM's CI builds this configuration on every change and checks that the
+resulting binary links the distribution's OpenSSL, so a change that only works
+against `.packages/` is caught upstream rather than by a packager. The CI job is
+the executable form of this page: if the two descriptions ever disagree, the job
+is the one that is right.
+
+## Obtaining and verifying the source release
+
+Each OpenVMM release publishes `openvmm-<VERSION>-source.tar.gz` together with a
+`SHA256SUMS` file covering it. Download both, and verify the archive before
+building from it:
+
+```bash
+sha256sum -c SHA256SUMS
+```
+
+Every published asset also carries a GitHub build provenance attestation, which
+binds the artifact to the repository, workflow, and commit that produced it.
+Unlike the checksum file, it cannot be regenerated by whoever replaced the
+archive, so verify it as well:
+
+```bash
+gh attestation verify openvmm-<VERSION>-source.tar.gz --repo microsoft/openvmm
+```
+
+The archive is assembled reproducibly: the same release tag always produces
+byte-identical bytes, so an independently assembled archive can be compared
+against the published checksum.
+
+```admonish warning title="Use the published archive, not GitHub's"
+GitHub generates its own "Source code (tar.gz)" link on every release page.
+That archive is **not** the OpenVMM source release: it omits
+`.openvmm-release.json`, so a build from it cannot recover its release identity,
+and it is not covered by `SHA256SUMS` or the attestation.
+```
+
+## Toolchain
+
+The workspace declares a minimum supported Rust version (MSRV) in the root
+`Cargo.toml` (`rust-version`). Building requires a Rust toolchain at least that
+new. The MSRV advances over time, so confirm the current value in the source
+you are packaging and require at least that Rust version in the package.
+
+```admonish warning title="Distribution Rust may lag the MSRV"
+If the distribution's packaged `rust` is older than the workspace MSRV, `cargo`
+fails during resolution — for example:
+
+    error: package `x86emu@0.0.0` cannot be built because it requires
+    rustc 1.95 or newer, while the currently active rustc version is 1.90.0
+
+Target a distribution whose packaged Rust meets the MSRV, or arrange a newer
+toolchain in the package build environment.
+```
+
+## Native build dependencies
+
+The `openvmm` gnu binary compiles a small amount of C through build scripts and
+shells out to `protoc`. The native build dependencies are:
+
+- a C toolchain (`gcc`, the glibc development headers, and `binutils`);
+- the Linux UAPI headers (`kernel-headers`), for the bundled SQLite compiled by
+  `libsqlite3-sys`;
+- the OpenSSL development headers, for `openssl-sys`;
+- a Protocol Buffers compiler providing `protoc`, for `prost` / `pbjson`.
+
+```admonish note title="SymCrypt is not needed for the gnu build"
+The `crypto` crate selects the OpenSSL backend on `target_os = "linux"` for
+non-`musl` targets, and SymCrypt only on `musl`. The `openvmm` gnu binary
+therefore does not depend on SymCrypt, `ms-tpm-20-ref`, or `mimalloc` — none of
+them appear in `cargo tree -p openvmm` for the host target. Only `musl`
+(OpenHCL) builds link SymCrypt. See [Crypto Backends](./crypto_backends.md).
+```
+
+### Azure Linux package names
+
+Package names differ between Azure Linux versions:
+
+| Need | Azure Linux 3.0 | Azure Linux 4.0 |
+| --- | --- | --- |
+| C toolchain | `gcc`, `glibc-devel`, `binutils` | same |
+| Linux UAPI headers | `kernel-headers` | `kernel-headers` |
+| OpenSSL headers | `openssl-devel` | `openssl-devel` |
+| `protoc` | `protobuf` | `protobuf-compiler`, `protobuf-devel` |
+
+Azure Linux 3.0 ships a newer `protoc` that embeds the well-known types, so its
+`protobuf` package is sufficient. Azure Linux 4.0 ships an older `protoc`, so
+`protobuf-devel` is also required to supply `google/protobuf/*.proto` on disk.
+
+## Environment overrides
+
+The in-repo `.cargo/config.toml` sets `PROTOC` to a path under `.packages/`
+unconditionally. A distribution build must point it at the system `protoc`.
+Setting `OPENSSL_NO_VENDOR` makes `openssl-sys` link the system OpenSSL rather
+than building a vendored copy:
+
+```bash
+export PROTOC="$(command -v protoc)"
+export OPENSSL_NO_VENDOR=1
+```
+
+## Offline vendored build
+
+A package build should be reproducible and offline. The OpenVMM source release
+is a source archive only: it does not carry the crate dependency tree, so the
+packager produces the vendored tarball and covers it with the distribution's
+own integrity metadata alongside the source archive.
+
+Vendor all dependencies — including the Git dependencies and the
+`[patch.crates-io]` pins — into a tarball alongside the source archive:
+
+```bash
+cargo vendor vendor/ > vendor-config.toml
+```
+
+`cargo vendor` captures the Git dependencies and their Git submodule C sources
+(for example the `ms-tpm-20-ref` and SymCrypt submodules), so the vendored tree
+is self-contained. Append the generated `[source]` redirection to
+`.cargo/config.toml`, then build without network access:
+
+```bash
+cargo build --release -p openvmm --offline
+```
+
+```admonish note title="Vendoring covers the whole workspace"
+`cargo vendor` has no per-package scoping: it vendors every dependency in the
+workspace, not just the ones the `openvmm` binary needs. A measured run
+vendored 498 crates where the binary requires 254, and a large share of the
+resulting tree is Windows-only crates that a Linux package never compiles.
+Expect the vendored tree to be substantially larger than the build requires.
+```
+
+## Runtime dependencies
+
+The resulting binary links a small, stable set of shared libraries. Confirm the
+exact set for your build with `ldd`:
+
+- glibc (`libc`, `libm`);
+- OpenSSL (`libssl`, `libcrypto`);
+- `libgcc_s`.
+
+Depending on the OpenSSL build, `libz` may also appear transitively; a measured
+Ubuntu build did not link it. The bundled SQLite is linked statically and adds
+no runtime dependency. RPM automatic dependency generation derives these from
+the ELF `NEEDED` entries, so confirm the set for your own build rather than
+copying a fixed list.
+
+## Worked example: Azure Linux RPM
+
+This uses a common Rust-packaging pattern: a source tarball, a `cargo vendor`
+tarball, and an offline build. The distribution package version is independent
+from the OpenVMM product version (see
+[Independent version spaces](./openvmm_release.md#independent-version-spaces)).
+
+Use `openvmm-<VERSION>-source.tar.gz` from the release as `Source0` so the build
+retains its release identity through `.openvmm-release.json` — see
+[Obtaining and verifying the source release](#obtaining-and-verifying-the-source-release).
+
+Declare the build and runtime dependencies. Require a Rust toolchain at least as
+new as the workspace MSRV — read the current value from `rust-version` in the
+source you are packaging rather than copying the one below:
+
+```spec
+BuildRequires:  rust >= <MSRV>
+BuildRequires:  cargo >= <MSRV>
+BuildRequires:  gcc glibc-devel binutils kernel-headers
+BuildRequires:  openssl-devel
+BuildRequires:  protobuf-compiler protobuf-devel
+
+Requires:       glibc
+Requires:       openssl-libs
+```
+
+Build offline and install the single binary:
+
+```spec
+%build
+export PROTOC="$(command -v protoc)"
+export OPENSSL_NO_VENDOR=1
+cargo build --release --offline -p openvmm \
+    --target x86_64-unknown-linux-gnu
+
+%install
+install -D -m0755 \
+    target/x86_64-unknown-linux-gnu/release/openvmm \
+    %{buildroot}%{_bindir}/openvmm
+```
+
+On Azure Linux 3.0, replace `protobuf-compiler protobuf-devel` with `protobuf`,
+and confirm the packaged `rust` meets the workspace MSRV before adopting a base
+version.