docs: improve README so things are a little easier to understand

Sponsored-by: author

1 files changed, 63 insertions, 0 deletions

diff --git a/README.md b/README.md
index 44587db..a03cb49 100644
--- a/README.md
+++ b/README.md
@@ -18,9 +18,72 @@ ever been tested on Debian 12 (bookworm). To try this:
   - this will write the build log to `log` and any artifacts produced
     by the build to `output.tar`
 
+## The virtual machine
+
+You need to prepare a virtual machine image to use with `ambient-run`.
+The provided `ambient-build-debian-image` builds a Debian one, but any
+operating system will work, if prepared the right way.
+
+The VM will get be run using QEMU (the `kvm` command), and probably
+only works for x86-64, for now. (This can be fixed, at a cost of
+speed.) The VM will be given two extra devices, one with the source
+files, and one for the output files. On Linux, these devices are `vdb`
+and `vdc`. The input device will contain a tar archive with the source
+tree. The build shall write a tar archive of the exported artifacts to
+the output device. The output device has a size limit, and the build
+can't write more than that. `ambient-run` extracts the tar archive
+from the output device.
+
+The operating system in the virtual machine must run the build by
+extracting the source tar, and run `.ambient-script` from there. The
+script must be given the output device as its only argument. See
+`ambient-run-script` in the source file for how the Debian image does
+it. See also `ambient.service` for the systemd unit that invokes the
+script. The build is non-interactive.
+
+The first serial port (`/dev/ttyS0` in the Debian image) can be used
+for a build log. It is captured to a file by `ambient-run` (see the
+`--log` option). For now, the log is unstructured and just contains
+the raw output from the serial port.
+
+
+## Building Rust programs
+
+The `rust.yml` extra playbook installs a Rust toolchain with `rustup`.
+A Rust project might have an `.ambient-script` like this (assuming the
+output binary is `helloworld`):
+
+~~~sh
+#!/bin/bash
+
+set -xeuo pipefail
+
+output="$1"
+
+export PATH="/root/.cargo/bin:$PATH"
+export CARGO_HOME=cargo-home
+
+cargo build
+
+tar -cf "$output" -C target/debug helloworld
+~~~
+
+The build in the VM has no network access at all. To provide
+dependencies, you can use `cargo fetch`:
+
+~~~sh
+$ mkdir cargo-home
+$ CARGO_HOME=cargo-home cargo fetch
+~~~
+
+This will mean the dependencies get downloaded into `cargo-home` in
+the source tree, and `ambient-run` will provide them to the build VM
+with the rest of the sources.
 
 ## Links
 
+These were an inspiration:
+
 * <https://asylum.madhouse-project.org/blog/2022/08/02/the-big-ci-hunt/>
 * <https://asylum.madhouse-project.org/blog/2022/08/05/the-ideal-ci-part-one/>
 * <https://asylum.madhouse-project.org/blog/2022/08/07/the-ideal-ci-part-two/>