Update vmTools docs after rebase

1 files changed, 57 insertions, 25 deletions

diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md
index c838f3efbf45..3b6fb0d2556b 100644
--- a/doc/builders/special/vm-tools.section.md
+++ b/doc/builders/special/vm-tools.section.md
@@ -14,43 +14,69 @@ A bash script fragment that produces a disk image at `destination`.
 
 ## `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.
+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](https://wiki.qemu.org/Documentation/9p#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.
+If the build fails and Nix is run with the `-K/--keep-failed` 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).
+* `memSize` (optional, default `512`). The memory size of the VM in MiB.
+* `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
 
+Build the derivation hello inside a VM:
 ```nix
-# Build the derivation hello inside a VM
+{ pkgs }: with pkgs; with vmTools;
 runInLinuxVM hello
+```
 
-# Build inside a VM with extra memory
+Build inside a VM with extra memory:
+```nix
+{ pkgs }: with pkgs; with vmTools;
 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"; }; }))
+Use VM with a disk image (implicitly sets `diskImage`, see [`vmTools.createEmptyImage`](#vm-tools-createEmptyImage)):
+```nix
+{ pkgs }: with pkgs; with vmTools;
+runInLinuxVM (hello.overrideAttrs (_: {
+  preVM = createEmptyImage {
+    size = 1024;
+    fullName = "vm-image";
+  };
+}))
 ```
 
-<!-- TODO
 ## `vmTools.extractFs` {#vm-tools-extractFs}
+
+Takes a file, such as an ISO, and extracts its contents into the store.
+
+### Attributes
+
+* `file`. Path to the file to be extracted.
+  Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
+* `fs` (optional). Filesystem of the contents of the file.
+
+### Examples
+
+Extract the contents of an ISO file:
+```nix
+{ pkgs }: with pkgs; with vmTools;
+extractFs { file = ./image.iso; }
+```
+
 ## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
--->
+
+Like [](#vm-tools-extractFs), but it makes use of a [Memory Technology Device (MTD)](https://en.wikipedia.org/wiki/Memory_Technology_Device).
 
 ## `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.
+Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix store, run the build using the tools provided by `/bin`, `/usr/bin`, etc. from the specified filesystem image, which typically is a filesystem containing a [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)-based Linux distribution.
 
 ## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
 
@@ -58,11 +84,15 @@ Generate a script that can be used to run an interactive session in the given im
 
 ### Examples
 
+Create a script for running a Fedora 27 VM:
 ```nix
-# Create a script for running a Fedora 27 VM
+{ pkgs }: with pkgs; with vmTools;
 makeImageTestScript diskImages.fedora27x86_64
+```
 
-# Create a script for running an Ubuntu 20.04 VM
+Create a script for running an Ubuntu 20.04 VM:
+```nix
+{ pkgs }: with pkgs; with vmTools;
 makeImageTestScript diskImages.ubuntu2004x86_64
 ```
 
@@ -88,22 +118,24 @@ A set of functions that build a predefined set of minimal Linux distributions im
   * `ubuntu1804x86_64`
   * `ubuntu2004i386`
   * `ubuntu2004x86_64`
+  * `ubuntu2204i386`
+  * `ubuntu2204x86_64`
 * Debian
-  * `debian9i386`
-  * `debian9x86_64`
   * `debian10i386`
   * `debian10x86_64`
+  * `debian11i386`
+  * `debian11x86_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.
+* `size` (optional, defaults to `4096`). The size of the image, in MiB.
+* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
 
 ### Examples
 
+8GiB image containing Firefox in addition to the default packages:
 ```nix
-# 8G image containing Firefox in addition to the default packages.
+{ pkgs }: with pkgs; with vmTools;
 diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; }
 ```