doc/build-helpers/special/vm-tools.section.md

   1 # vmTools {#sec-vm-tools}
   2
   3 A set of VM related utilities, that help in building some packages in more advanced scenarios.
   4
   5 ## `vmTools.createEmptyImage` {#vm-tools-createEmptyImage}
   6
   7 A bash script fragment that produces a disk image at `destination`.
   8
   9 ### Attributes {#vm-tools-createEmptyImage-attributes}
  10
  11 * `size`. The disk size, in MiB.
  12 * `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
  13 * `destination` (optional, default `$out`). Where to write the image files.
  14
  15 ## `vmTools.runInLinuxVM` {#vm-tools-runInLinuxVM}
  16
  17 Run a derivation in a Linux virtual machine (using Qemu/KVM).
  18 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)).
  19 Thus, any pure Nix derivation should run unmodified.
  20
  21 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.
  22
  23 ### Attributes {#vm-tools-runInLinuxVM-attributes}
  24
  25 * `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
  26 * `memSize` (optional, default `512`). The memory size of the VM in MiB.
  27 * `diskImage` (optional). A file system image to be attached to `/dev/sda`.
  28   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
  29
  30 ### Examples {#vm-tools-runInLinuxVM-examples}
  31
  32 Build the derivation hello inside a VM:
  33 ```nix
  34 { pkgs }: with pkgs; with vmTools;
  35 runInLinuxVM hello
  36 ```
  37
  38 Build inside a VM with extra memory:
  39 ```nix
  40 { pkgs }: with pkgs; with vmTools;
  41 runInLinuxVM (hello.overrideAttrs (_: { memSize = 1024; }))
  42 ```
  43
  44 Use VM with a disk image (implicitly sets `diskImage`, see [`vmTools.createEmptyImage`](#vm-tools-createEmptyImage)):
  45 ```nix
  46 { pkgs }: with pkgs; with vmTools;
  47 runInLinuxVM (hello.overrideAttrs (_: {
  48   preVM = createEmptyImage {
  49     size = 1024;
  50     fullName = "vm-image";
  51   };
  52 }))
  53 ```
  54
  55 ## `vmTools.extractFs` {#vm-tools-extractFs}
  56
  57 Takes a file, such as an ISO, and extracts its contents into the store.
  58
  59 ### Attributes {#vm-tools-extractFs-attributes}
  60
  61 * `file`. Path to the file to be extracted.
  62   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
  63 * `fs` (optional). Filesystem of the contents of the file.
  64
  65 ### Examples {#vm-tools-extractFs-examples}
  66
  67 Extract the contents of an ISO file:
  68 ```nix
  69 { pkgs }: with pkgs; with vmTools;
  70 extractFs { file = ./image.iso; }
  71 ```
  72
  73 ## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
  74
  75 Like [](#vm-tools-extractFs), but it makes use of a [Memory Technology Device (MTD)](https://en.wikipedia.org/wiki/Memory_Technology_Device).
  76
  77 ## `vmTools.runInLinuxImage` {#vm-tools-runInLinuxImage}
  78
  79 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.
  80
  81 ## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
  82
  83 Generate a script that can be used to run an interactive session in the given image.
  84
  85 ### Examples {#vm-tools-makeImageTestScript-examples}
  86
  87 Create a script for running a Fedora 27 VM:
  88 ```nix
  89 { pkgs }: with pkgs; with vmTools;
  90 makeImageTestScript diskImages.fedora27x86_64
  91 ```
  92
  93 Create a script for running an Ubuntu 20.04 VM:
  94 ```nix
  95 { pkgs }: with pkgs; with vmTools;
  96 makeImageTestScript diskImages.ubuntu2004x86_64
  97 ```
  98
  99 ## `vmTools.diskImageFuns` {#vm-tools-diskImageFuns}
 100
 101 A set of functions that build a predefined set of minimal Linux distributions images.
 102
 103 ### Images {#vm-tools-diskImageFuns-images}
 104
 105 * Fedora
 106   * `fedora26x86_64`
 107   * `fedora27x86_64`
 108 * CentOS
 109   * `centos6i386`
 110   * `centos6x86_64`
 111   * `centos7x86_64`
 112 * Ubuntu
 113   * `ubuntu1404i386`
 114   * `ubuntu1404x86_64`
 115   * `ubuntu1604i386`
 116   * `ubuntu1604x86_64`
 117   * `ubuntu1804i386`
 118   * `ubuntu1804x86_64`
 119   * `ubuntu2004i386`
 120   * `ubuntu2004x86_64`
 121   * `ubuntu2204i386`
 122   * `ubuntu2204x86_64`
 123 * Debian
 124   * `debian10i386`
 125   * `debian10x86_64`
 126   * `debian11i386`
 127   * `debian11x86_64`
 128
 129 ### Attributes {#vm-tools-diskImageFuns-attributes}
 130
 131 * `size` (optional, defaults to `4096`). The size of the image, in MiB.
 132 * `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
 133
 134 ### Examples {#vm-tools-diskImageFuns-examples}
 135
 136 8GiB image containing Firefox in addition to the default packages:
 137 ```nix
 138 { pkgs }: with pkgs; with vmTools;
 139 diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; }
 140 ```
 141
 142 ## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns}
 143
 144 Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`.
 145
 146 ## `vmTools.diskImages` {#vm-tools-diskImages}
 147
 148 Shorthand for `vmTools.diskImageFuns.<attr> { }`.