# 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 {#vm-tools-createEmptyImage-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](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/--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 {#vm-tools-runInLinuxVM-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 (1024×1024 bytes).
* `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 {#vm-tools-runInLinuxVM-examples}

Build the derivation hello inside a VM:
```nix
{ pkgs }: with pkgs; with vmTools; runInLinuxVM hello
```

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`](#vm-tools-createEmptyImage)):
```nix
{ pkgs }:
with pkgs;
with vmTools;
runInLinuxVM (
  hello.overrideAttrs (_: {
    preVM = createEmptyImage {
      size = 1024;
      fullName = "vm-image";
    };
  })
)
```

## `vmTools.extractFs` {#vm-tools-extractFs}

Takes a file, such as an ISO, and extracts its contents into the store.

### Attributes {#vm-tools-extractFs-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 {#vm-tools-extractFs-examples}

Extract the contents of an ISO file: