nvx: hide NVX's programs from the public API

nvx-rs/Cargo.toml

@@ -39,10 +39,10 @@ host = [
 # `Artifacts::bundled`. The build script downloads the release pinned in `artifacts.json`, or
 # copies the release directory named by `NVX_BUNDLE_DIR`.
 bundled = ["host", "dep:sha2"]
-# Test doubles: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary.
+# NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests. It adds no API.
 testing = ["dep:getrandom", "dep:serde", "dep:serde_json", "dep:nix", "dep:windows-sys"]
-# The `nvx-rs` command-line interface of `host::cli` and its `nvx-rs` binary, which runs NVX's
-# microVMs and sandboxes, compiles egress policies, looks up artifacts, and downloads releases.
+# NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and sandboxes,
+# compiles egress policies, looks up artifacts, and downloads releases. It adds no API.
 cli = ["host"]
 # The serde form of `Hypervisor`. The `host` feature enables it.
 serde = ["dep:serde"]

nvx-rs/README.md

@@ -131,8 +131,6 @@ changes only when the module's purpose does.
 | [`nvx::host::seal`](#nvxhostseal) | `FileSeal`: what the host reports about an open file from its metadata alone, without reading it |
 | [`nvx::host::session`, `platform`, `report`](#nvxhostsession-platform-report) | The authenticated control session, Linux and Windows primitives, and OpenVMM's outcome report |
 | [`nvx::host::sandbox`](#nvxhostsandbox) | The launch profile of `nvx-rs sandbox`: its plans, live shares, option checks, bindings, and prepared launches |
-| [`nvx::testing::fake_openvmm`](#nvxtestingfake_openvmm) | A fake OpenVMM that serves the control console and runs scripted workloads without a VM |
-| [`nvx::host::cli`](#nvxhostcli) | Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli) |
 | [`nvx::guest`](#nvxguest) | The programs that run in Linux guests; see [Guest binaries](#guest-binaries) |
 | [`nvx::guest::mappings`](#nvxguestmappings) | `Mapper` and `MappingTable`: apply host mappings beneath the descriptors of their roots, and a host's mapping table, for any guest init or agent |
 | [`nvx::guest::nvxs`](#nvxguestnvxs) | `GuestConnection`: the guest's role of the NVXS session over a byte stream, such as the control console |
@@ -1068,17 +1066,6 @@ arguments of the launch: the plan's, those that export the adapter's shares,
 and those of the launch's `VmmLaunch`, and refuses a command line that Windows
 would not start OpenVMM with.
 
-### `nvx::testing::fake_openvmm`
-
-A fake OpenVMM that serves the control console and runs scripted workloads
-without a VM, for direct launches and for the managed and one-shot sandboxes of
-`nvx-rs sandbox`, and runs the VMs of templates' captures, which publish a
-snapshot, or fail, as a scenario asks.
-
-### `nvx::host::cli`
-
-Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli).
-
 ### `nvx::guest`
 
 The programs that run in Linux guests; see [Guest binaries](#guest-binaries).
@@ -2356,7 +2343,7 @@ that its snapshot saved, a cold boot with `--network-profile` alone or with
 explicit `--host-loopback allow` without `--restore-network-policy`. Kernel
 command-line tokens make it fail: `fake_exit_on_start=STATUS`,
 `fake_exit_status=STATUS`, `fake_guest_features=MASK`, and
-`fake_legacy_guest=1`, among others; see `nvx::testing::fake_openvmm`. Like
+`fake_legacy_guest=1`, among others; see `src/testing/fake_openvmm.rs`. Like
 OpenVMM, it opens the sandbox's block devices at the paths that its options
 name and holds them until it exits, after `fake_block_delay_ms=MS` if asked,
 and records what each held in `fake-openvmm-TOKEN-blocks.json` next to the
@@ -2421,8 +2408,8 @@ caller owner.
 | --- | --- |
 | `host` (default) | The `host` module. It enables `serde`, and `sha2`, which names the children of a sandbox's aggregate share and hashes distro layers in their explicit verification |
 | `bundled` | Stages a release at build time; see [Bundled artifacts](#bundled-artifacts) |
-| `testing` | The fake OpenVMM and the `nvx-fake-openvmm` binary |
-| `cli` | The `nvx-rs` CLI of `host::cli` and its `nvx-rs` binary; it enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) |
+| `testing` | NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests; see [Test hooks](#test-hooks). It adds no API |
+| `cli` | NVX's own `nvx-rs` binary; it adds no API, and enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) |
 | `serde` | The serde form of `Hypervisor` |
 | `guest` | The `guest` module and the guest binaries; see [Guest binaries](#guest-binaries) |
 

nvx-rs/public-api/linux.txt

@@ -833,10 +833,10 @@ field nvx::guest::clone::RootTemplate::scratch
 field nvx::guest::clone::RootTemplate::timeout
 fn nvx::guest::clone::apply
 fn nvx::guest::clone::repair
-mod nvx::guest::console_pending
-fn nvx::guest::console_pending::main
-mod nvx::guest::device_io
-fn nvx::guest::device_io::main
+mod nvx::guest::console_pending (hidden)
+fn nvx::guest::console_pending::main (hidden)
+mod nvx::guest::device_io (hidden)
+fn nvx::guest::device_io::main (hidden)
 mod nvx::guest::entry
 struct nvx::guest::entry::Account
 method nvx::guest::entry::Account::home
@@ -1060,8 +1060,8 @@ variant nvx::guest::exec::binding::Event::Message
 field nvx::guest::exec::binding::Event::Message::0
 variant nvx::guest::exec::binding::Event::SettlementFailed
 field nvx::guest::exec::binding::Event::SettlementFailed::0
-mod nvx::guest::exit
-fn nvx::guest::exit::main
+mod nvx::guest::exit (hidden)
+fn nvx::guest::exit::main (hidden)
 mod nvx::guest::gpt
 enum nvx::guest::gpt::DeviceError
 variant nvx::guest::gpt::DeviceError::LogicalBlockSize
@@ -1089,9 +1089,9 @@ variant nvx::guest::ingress::StartError::Socket
 field nvx::guest::ingress::StartError::Socket::0
 variant nvx::guest::ingress::StartError::Spawn
 field nvx::guest::ingress::StartError::Spawn::0
-fn nvx::guest::ingress::main
-mod nvx::guest::managed_agent
-fn nvx::guest::managed_agent::main
+fn nvx::guest::ingress::main (hidden)
+mod nvx::guest::managed_agent (hidden)
+fn nvx::guest::managed_agent::main (hidden)
 mod nvx::guest::mappings
 enum nvx::guest::mappings::Access
 variant nvx::guest::mappings::Access::ReadOnly
@@ -1197,8 +1197,8 @@ struct nvx::guest::mappings::UnmountFailure
 method nvx::guest::mappings::UnmountFailure::error
 method nvx::guest::mappings::UnmountFailure::target
 fn nvx::guest::mappings::bind
-mod nvx::guest::mmio_write
-fn nvx::guest::mmio_write::main
+mod nvx::guest::mmio_write (hidden)
+fn nvx::guest::mmio_write::main (hidden)
 mod nvx::guest::nvxs
 struct nvx::guest::nvxs::GuestConnection
 method nvx::guest::nvxs::GuestConnection::acknowledge
@@ -1245,7 +1245,7 @@ const nvx::guest::reseed::Seed::LENGTH
 method nvx::guest::reseed::Seed::from_bytes
 method nvx::guest::reseed::Seed::generation_id
 method nvx::guest::reseed::Seed::read
-fn nvx::guest::reseed::main
+fn nvx::guest::reseed::main (hidden)
 fn nvx::guest::reseed::reseed
 mod nvx::guest::root
 struct nvx::guest::root::Assembly
@@ -1595,9 +1595,9 @@ struct nvx::guest::time::Violation
 method nvx::guest::time::Violation::code
 method nvx::guest::time::Violation::detail
 method nvx::guest::time::Violation::status
-fn nvx::guest::time::main
-mod nvx::guest::time_probe
-fn nvx::guest::time_probe::main
+fn nvx::guest::time::main (hidden)
+mod nvx::guest::time_probe (hidden)
+fn nvx::guest::time_probe::main (hidden)
 fn nvx::guest_path
 mod nvx::host
 mod nvx::host::artifacts
@@ -1678,8 +1678,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX
 fn nvx::host::artifacts::absolute
 fn nvx::host::artifacts::check_manifest
 fn nvx::host::artifacts::openvmm_executable
-mod nvx::host::cli
-fn nvx::host::cli::main
+mod nvx::host::cli (hidden)
+fn nvx::host::cli::main (hidden)
 mod nvx::host::filesystem
 struct nvx::host::filesystem::Bind
 field nvx::host::filesystem::Bind::child
@@ -3411,9 +3411,9 @@ const nvx::protocol::status::TIME_STATUSES
 const nvx::protocol::status::TIME_VIOLATION
 fn nvx::protocol::status::describe
 fn nvx::resolve_guest_path
-mod nvx::testing
-mod nvx::testing::fake_openvmm
-fn nvx::testing::fake_openvmm::main
+mod nvx::testing (hidden)
+mod nvx::testing::fake_openvmm (hidden)
+fn nvx::testing::fake_openvmm::main (hidden)
 mod nvx::uuid
 struct nvx::uuid::ParseUuidError
 struct nvx::uuid::Uuid

nvx-rs/public-api/windows.txt

@@ -669,8 +669,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX
 fn nvx::host::artifacts::absolute
 fn nvx::host::artifacts::check_manifest
 fn nvx::host::artifacts::openvmm_executable
-mod nvx::host::cli
-fn nvx::host::cli::main
+mod nvx::host::cli (hidden)
+fn nvx::host::cli::main (hidden)
 mod nvx::host::filesystem
 struct nvx::host::filesystem::Bind
 field nvx::host::filesystem::Bind::child
@@ -2401,9 +2401,9 @@ const nvx::protocol::status::TIME_STATUSES
 const nvx::protocol::status::TIME_VIOLATION
 fn nvx::protocol::status::describe
 fn nvx::resolve_guest_path
-mod nvx::testing
-mod nvx::testing::fake_openvmm
-fn nvx::testing::fake_openvmm::main
+mod nvx::testing (hidden)
+mod nvx::testing::fake_openvmm (hidden)
+fn nvx::testing::fake_openvmm::main (hidden)
 mod nvx::uuid
 struct nvx::uuid::ParseUuidError
 struct nvx::uuid::Uuid

nvx-rs/src/guest/ingress/mod.rs

@@ -205,6 +205,7 @@ struct UdpSocket {
 /// and exits with 1 when it cannot open or bind its socket, or take the one that it inherited, or
 /// with 2 for a usage error. `start` exits with 0 once the announcer runs, or with 1 when it does
 /// not start.
+#[doc(hidden)]
 pub fn main() -> ExitCode {
     run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr()))
 }

nvx-rs/src/guest/mod.rs

@@ -94,18 +94,23 @@ pub use generation::GenerationId;
 pub mod cgroup;
 #[cfg(target_arch = "x86_64")]
 pub mod clone;
+#[doc(hidden)]
 pub mod console_pending;
 #[cfg(target_arch = "x86_64")]
+#[doc(hidden)]
 pub mod device_io;
 pub mod entry;
 pub mod exec;
 #[cfg(target_arch = "x86_64")]
+#[doc(hidden)]
 pub mod exit;
 pub mod gpt;
 pub mod ingress;
+#[doc(hidden)]
 pub mod managed_agent;
 pub mod mappings;
 #[cfg(target_arch = "x86_64")]
+#[doc(hidden)]
 pub mod mmio_write;
 pub mod nvxs;
 pub mod process;
@@ -116,4 +121,5 @@ pub mod terminal;
 #[cfg(target_arch = "x86_64")]
 pub mod time;
 #[cfg(target_arch = "x86_64")]
+#[doc(hidden)]
 pub mod time_probe;

nvx-rs/src/guest/reseed.rs

@@ -254,6 +254,7 @@ fn reseed_through(random: &CStr, seed: &Seed) -> Result<(), ReseedError> {
 
 /// Runs `nvx-reseed` with the process's arguments. It exits with 0, 1 when an operation or a
 /// check fails, or 2 for a usage error.
+#[doc(hidden)]
 pub fn main() -> ExitCode {
     run_main(|args| {
         run(

nvx-rs/src/guest/time/mod.rs

@@ -149,6 +149,7 @@ const USAGE: &[u8] = br#"usage: nvx-time [--report-only] COMMAND
 
 /// Runs `nvx-time` with the process's arguments. It exits with 0 on success, 1 when a command
 /// or a check fails, or 2 for an invalid command line.
+#[doc(hidden)]
 pub fn main() -> ExitCode {
     run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr()))
 }

nvx-rs/src/host/mod.rs

@@ -62,6 +62,7 @@
 
 pub mod artifacts;
 #[cfg(feature = "cli")]
+#[doc(hidden)]
 pub mod cli;
 pub mod filesystem;
 pub mod instance;

nvx-rs/src/lib.rs

@@ -36,8 +36,6 @@
 //!   platform primitives, the supervision of VM instances: starting, reattaching, executing
 //!   workloads, and stopping, the store of a sandbox's runtime records and launch journal, and the
 //!   manifests, compatibility keys, store, and leases of templates.
-//! - `testing` (feature `testing`): a fake OpenVMM that serves the control console without
-//!   running a VM.
 //! - `guest` (feature `guest`, Linux): the programs that run in NVX guests, such as
 //!   `nvx-console-pending`, the guest's NVXS connection, the libraries through which any guest
 //!   init or agent opens the terminal on which it serves its session (`guest::terminal`), starts
@@ -119,7 +117,10 @@
 //! - `bundled`: stages the OpenVMM executable, guest kernel, and control initramfs at build time;
 //!   see `Artifacts::bundled`. The build script downloads the release that `artifacts.json` pins,
 //!   or copies the release directory that `NVX_BUNDLE_DIR` names.
-//! - `testing`: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary.
+//! - `testing`: NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM that serves the control
+//!   console without running a VM. It adds no API.
+//! - `cli`: NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and
+//!   sandboxes. It adds no API, and enables `host`.
 //! - `serde`: the serde form of [`Hypervisor`].
 //! - `guest`: the `guest` module and the guest binaries, which the `guest` profile builds as
 //!   static `x86_64-unknown-linux-musl` executables.
@@ -139,6 +140,7 @@ pub mod guest;
 #[cfg(feature = "host")]
 pub mod host;
 #[cfg(feature = "testing")]
+#[doc(hidden)]
 pub mod testing;
 #[cfg(test)]
 mod tests;