depot/third_party/nixpkgs/doc/builders/special/vm-tools.section.md

vmTools

A set of VM related utilities, that help in building some packages in more advanced scenarios.

vmTools.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

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/--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 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:

{ pkgs }: with pkgs; with vmTools;
runInLinuxVM hello

Build inside a VM with extra memory:

{ pkgs }: with pkgs; with vmTools;
runInLinuxVM (hello.overrideAttrs (_: { memSize = 1024; }))

Use VM with a disk image (implicitly sets diskImage, see vmTools.createEmptyImage):

{ pkgs }: with pkgs; with vmTools;
runInLinuxVM (hello.overrideAttrs (_: {
  preVM = createEmptyImage {
    size = 1024;
    fullName = "vm-image";
  };
}))

vmTools.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:

{ pkgs }: with pkgs; with vmTools;
extractFs { file = ./image.iso; }

vmTools.extractMTDfs

Like , but it makes use of a Memory Technology Device (MTD).

vmTools.runInLinuxImage

Like , 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-based Linux distribution.

vmTools.makeImageTestScript

Generate a script that can be used to run an interactive session in the given image.

Examples

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:

{ pkgs }: with pkgs; with vmTools;
makeImageTestScript diskImages.ubuntu2004x86_64

vmTools.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
  • ubuntu2204i386
  • ubuntu2204x86_64
• Debian
  • debian10i386
  • debian10x86_64
  • debian11i386
  • debian11x86_64

Attributes

• 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:

{ pkgs }: with pkgs; with vmTools;
diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; }

vmTools.diskImageExtraFuns

Shorthand for vmTools.diskImageFuns.<attr> { extraPackages = ... }.

vmTools.diskImages

Shorthand for vmTools.diskImageFuns.<attr> { }.