doc: add vmTools

3 files changed, 118 insertions, 0 deletions

diff --git a/doc/builders/special.xml b/doc/builders/special.xml
index c971134819818..18cf6cfd39c70 100644
--- a/doc/builders/special.xml
+++ b/doc/builders/special.xml
@@ -9,4 +9,5 @@
  <xi:include href="special/makesetuphook.section.xml" />
  <xi:include href="special/mkshell.section.xml" />
  <xi:include href="special/darwin-builder.section.xml" />
+ <xi:include href="special/vm-tools.section.xml" />
 </chapter>
diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md
new file mode 100644
index 0000000000000..c838f3efbf454
--- /dev/null
+++ b/doc/builders/special/vm-tools.section.md
@@ -0,0 +1,116 @@
+# vmTools {#sec-vm-tools}
+
+A set of VM related utilities, that help in building some packages in more advanced scenarios.
+
+## `vmTools.createEmptyImage` {#vm-tools-createEmptyImage}
+
+A bash script fragment that produces a disk image at `destination`.
+
+### Attributes
+
+* `size`. The disk size, in MiB.
+* `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
+* `destination` (optional, default `$out`). Where to write the image files.
+
+## `vmTools.runInLinuxVM` {#vm-tools-runInLinuxVM}
+
+Run a derivation in a Linux virtual machine (using Qemu/KVM). By default, there is no disk image; the root filesystem is
+a `tmpfs`, and the nix store is shared with the host (via the 9P protocol). Thus, any pure Nix derivation should run
+unmodified.
+
+If the build fails and Nix is run with the `-K` option, a script `run-vm` will be left behind in the temporary build
+directory that allows you to boot into the VM and debug it interactively.
+
+### Attributes
+
+* `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
+* `memSize` (optional, default `512`). The memory size of the VM in megabytes.
+* `diskImage` (optional). A file system image to be attached to `/dev/sda` (Note that currently we expect the image to
+  contain a filesystem, not a full disk image with a partition table etc).
+
+### Examples
+
+```nix
+# Build the derivation hello inside a VM
+runInLinuxVM hello
+
+# Build inside a VM with extra memory
+runInLinuxVM (hello.overrideAttrs (_: { memSize = 1024; }))
+
+# Use VM with a disk image (implicitly sets `diskImage`, see `vmTools.createEmptyImage`)
+runInLinuxVM (hello.overrideAttrs (_: { preVM = createEmptyImage { size = 1024; fullName = "vm-image"; }; }))
+```
+
+<!-- TODO
+## `vmTools.extractFs` {#vm-tools-extractFs}
+## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
+-->
+
+## `vmTools.runInLinuxImage` {#vm-tools-runInLinuxImage}
+
+Like [](#vm-tools-runInLinuxVM), but run the build not using the `stdenv` from the Nix store, but using the tools
+provided by `/bin`, `/usr/bin`, etc. from the specified filesystem image, which typically is a filesystem containing a
+non-NixOS Linux distribution.
+
+## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
+
+Generate a script that can be used to run an interactive session in the given image.
+
+### Examples
+
+```nix
+# Create a script for running a Fedora 27 VM
+makeImageTestScript diskImages.fedora27x86_64
+
+# Create a script for running an Ubuntu 20.04 VM
+makeImageTestScript diskImages.ubuntu2004x86_64
+```
+
+## `vmTools.diskImageFuns` {#vm-tools-diskImageFuns}
+
+A set of functions that build a predefined set of minimal Linux distributions images.
+
+### Images
+
+* Fedora
+  * `fedora26x86_64`
+  * `fedora27x86_64`
+* CentOS
+  * `centos6i386`
+  * `centos6x86_64`
+  * `centos7x86_64`
+* Ubuntu
+  * `ubuntu1404i386`
+  * `ubuntu1404x86_64`
+  * `ubuntu1604i386`
+  * `ubuntu1604x86_64`
+  * `ubuntu1804i386`
+  * `ubuntu1804x86_64`
+  * `ubuntu2004i386`
+  * `ubuntu2004x86_64`
+* Debian
+  * `debian9i386`
+  * `debian9x86_64`
+  * `debian10i386`
+  * `debian10x86_64`
+
+### Attributes
+
+* `size` (optional, defaults to `4096`). The size of the image, in megabytes.
+* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the
+  image.
+
+### Examples
+
+```nix
+# 8G image containing Firefox in addition to the default packages.
+diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; }
+```
+
+## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`.
+
+## `vmTools.diskImages` {#vm-tools-diskImages}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { }`.
diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json
index e83708dd64d68..09dabe98aac46 100644
--- a/doc/manpage-urls.json
+++ b/doc/manpage-urls.json
@@ -3,6 +3,7 @@
   "mpd(1)": "https://mpd.readthedocs.io/en/latest/mpd.1.html",
   "mpd.conf(5)": "https://mpd.readthedocs.io/en/latest/mpd.conf.5.html",
   "nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html",
+  "mount(5)": "https://linux.die.net/man/8/mount",
 
   "journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
   "logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html",