Update vmTools docs after rebase (a6c19474) · Commits · mdf / nixpkgs

doc/builders/special/vm-tools.section.md

+57 −25

Original line number	Diff line number	Diff line
		@@ -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; }
		```

Admin message