0.1.2: the runner is dirun; the specification by its minor version

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.2
+
+- `tools/vm-runner` runs the program by dirun with the image's profile (beside the image, as
+  `freebsd-disk-image` installs it, else `tools/freebsd.toml`); `tools/vm-run.py` is removed.
+- The specification is declared as `^0.25.0` (openkal clause 8): a consumer that names a
+  later patch release resolves with this implementation.
+
 ## 0.1.1
 
 - `tools/vm-run.py` boots each run from a temporary overlay of the image

README.md

@@ -5,9 +5,24 @@ written on the kernel's own system-call interface.
 
 ```toml
 [target.'cfg(os = "freebsd")'.dependencies]
-openkal-freebsd = "0.1.1"
+openkal-freebsd = "0.1.2"
 ```
 
+## What 0.1.2 changes
+
+**The runner is dirun.** `tools/vm-runner` boots the machine by dirun, the one
+program that runs a command inside a booted disk image, with the image's profile
+(`dirun.toml` beside the image, as the package `freebsd-disk-image` installs it,
+else `tools/freebsd.toml`); `tools/vm-run.py`, a second implementation of the same
+conversation, is removed. What it did is dirun's: the overlay, the program
+delivered on a read-only FAT disk and run from its copy, `OPENKAL_*` and `KAL_*`
+passed, and a test runner's events read back from the machine.
+
+**The specification by its minor version.** The manifest declares `openkal =
+"^0.25.0"`: an implementation written against a patch release conforms to every
+later patch of that minor version (openkal clause 8), and a consumer that names
+openkal 0.25.1 resolves with it.
+
 ## What it is
 
 FreeBSD's kernel interface is stable: a program built for FreeBSD 14 runs on
@@ -105,12 +120,11 @@ runs above openkal-musl on the `*-freebsd-musl` rows.
 
 - `tools/defer-runner` puts the suite and the variables it is run with in a
   directory, where CI runs it inside a FreeBSD VM.
-- `tools/vm-run.py` runs a program in a local FreeBSD VM image for development
-  (`OKF_VM_IMAGE`, `tools/vm-runner`). It forwards `OPENKAL_*`, `KAL_*` and the
-  mtest protocol's variables, so the suite can report through mtest once the
-  runner's listing pass honours `--run-under` (mtest 0.6.0). Each run boots a
-  temporary overlay of the image, so the image is never written to and two runs
-  at once do not meet.
+- `tools/vm-runner` runs a program in a local FreeBSD VM image for development
+  (`OKF_VM_IMAGE`), by dirun. It passes `OPENKAL_*` and `KAL_*`, and a test
+  runner's events come back from the machine. Each run boots a temporary overlay
+  of the image, so the image is never written to and two runs at once do not
+  meet.
 
 ### The runner declaration
 
@@ -123,15 +137,18 @@ runner = ["/path/to/openkal-freebsd/tools/vm-runner", "{}"]
 ```
 
 The declaration's `{}` is the built artefact. `vm-runner` boots the FreeBSD
-image that `OKF_VM_IMAGE` names under `qemu-system-x86_64` (KVM where the host
-has it, the software machine otherwise), offers the artefact on a read-only
-drive, runs it as root on the serial console, writes what it writes to the
-standard output and error, answers with its exit status, and shuts the machine
-down; the temporary overlay it booted from is discarded. The disk is the
-FreeBSD 14.5-RELEASE boot disk of the `xim` package `freebsd-disk` (The
-FreeBSD Project's release, installed from the official installer disc;
-published separately), and `qemu-system-x86_64` with `qemu-img` are the
-host's dependencies.
+image that `OKF_VM_IMAGE` names by `dirun` (under `qemu-system-x86_64`, KVM
+where the host has it, the software machine otherwise), delivers the artefact
+on a read-only FAT disk, runs it as root on the serial console, writes what it
+writes to the standard output, and answers with its exit status; the temporary
+overlay it booted from is discarded. The disk is the FreeBSD 14.5-RELEASE boot
+disk of the `xim` package `freebsd-disk-image` (The FreeBSD Project's release,
+installed from the official installer disc), which installs the profile beside
+it; `dirun`, `qemu-system-x86_64` and `qemu-img` are the host's dependencies.
+Without a declaration, mcpp states the same runner for the FreeBSD rows of an
+x86_64 Linux or macOS host itself: `dirun --profile
+{pkg:freebsd-disk-image}/dirun.toml -- {}`, its packages installed by the first
+run.
 
 The targets need mcpp 2026.11.10.1 or later.
 

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-freebsd"
-version     = "0.1.1"
+version     = "0.1.2"
 description = "An implementation of openkal for FreeBSD, written on the kernel's own system-call interface."
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]
@@ -36,7 +36,8 @@ provides-interfaces = [
 ]
 
 [dependencies]
-openkal = "0.25.0"
+# Every patch release of the specification's minor version (openkal clause 8).
+openkal = "^0.25.0"
 
 [build]
 sources = ["src/*.cpp"]

tools/freebsd.toml

@@ -0,0 +1,57 @@
+# How tools/vm-runner boots a FreeBSD 14.5-RELEASE x86_64 image by dirun: the loader's menu is left
+# for its prompt, the console moved to the serial line, root logs in, the files disk is mounted at
+# /mnt/dirun, and a test runner's events come back. It is the profile the package
+# freebsd-disk-image ships beside its image, without the image's name: the image is OKF_VM_IMAGE.
+name = "freebsd-14.5-x86_64"
+
+[machine]
+arch   = "x86_64"
+memory = 1024
+smp    = 2
+
+[[boot]]
+expect  = "Autoboot in"
+send    = " 3"            # any key stops the countdown; 3 leaves the menu for the loader's prompt
+line    = false
+pace    = 300             # the loader polls its console: faster input is dropped
+timeout = 120
+
+[[boot]]
+expect = "OK "
+send   = "set console=comconsole"
+pace   = 50
+
+[[boot]]
+expect = "OK "
+send   = "boot"
+pace   = 50
+
+[[boot]]
+expect  = "login: "
+send    = "root"
+timeout = 300
+
+[[boot]]
+expect   = "Password:"
+send     = "root"
+optional = true
+
+[[boot]]
+expect = "# |\\$ "
+
+[command]
+prepare = ["stty -echo"]
+line    = "echo @@BEGIN@@; {env}{argv} < /dev/null; echo @@STATUS=$?@@"
+env     = "env {assignments} "
+quote   = "posix"
+begin   = "@@BEGIN@@"
+status  = "@@STATUS=(\\d+)@@"
+line-max = 200            # a longer line is written to the files disk and run from there
+script   = "sh {script}"
+
+[files]
+mount = ["mkdir -p /mnt/dirun", "mount -r -t msdosfs /dev/vtbd1s1 /mnt/dirun"]
+at    = "/mnt/dirun"
+
+[relay]
+report = "/tmp/dirun-mtest.ndjson"

tools/vm-runner

@@ -1,5 +1,13 @@
 #!/bin/sh
-# The runner a runner declaration names on a Linux host: the program, run in
-# the FreeBSD virtual machine whose disk OKF_VM_IMAGE names (tools/vm-run.py).
-# The declaration's payload is the first argument, as with any command.
-exec python3 "$(dirname "$0")/vm-run.py" --image "${OKF_VM_IMAGE:?the FreeBSD disk image}" -- "$@"
+# The runner a runner declaration names on a Linux or macOS host: the program, run in a FreeBSD
+# virtual machine by dirun. The machine boots the image OKF_VM_IMAGE names (a temporary overlay of
+# it; the image is never written), with the profile beside it (dirun.toml, as the package
+# freebsd-disk-image ships it) or else tools/freebsd.toml. The program is delivered and run from its
+# copy; OPENKAL_* and KAL_* are passed to it, and a test runner's events come back. The run is
+# limited to OKF_VM_TIMEOUT seconds (1800).
+here=$(dirname "$0")
+image=${OKF_VM_IMAGE:?the FreeBSD disk image (the package freebsd-disk-image installs one)}
+profile=$(dirname "$image")/dirun.toml
+[ -f "$profile" ] || profile=$here/freebsd.toml
+exec dirun --image "$image" --profile "$profile" --timeout "${OKF_VM_TIMEOUT:-1800}" \
+    --pass 'OPENKAL_*' --pass 'KAL_*' -- "$@"