diff options
author | Valentin Gagarin <valentin.gagarin@tweag.io> | 2023-04-14 00:30:10 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-04-14 00:30:10 +0200 |
commit | 18ffde75672565776df78d159e373ee6b5f71415 (patch) | |
tree | ef0491d2dda25c4af65e14c1e57e06cebae8409f | |
parent | 23498545ab46e53a42e8748958429bc1a2f8c0e1 (diff) | |
parent | a6c19474bd52555e575343c2d4d51888e5b592fa (diff) |
Merge pull request #197247 from kip93/vmTools-docs
Documentation: add vmTools
-rw-r--r-- | doc/builders/special.xml | 1 | ||||
-rw-r--r-- | doc/builders/special/vm-tools.section.md | 148 |
2 files changed, 149 insertions, 0 deletions
diff --git a/doc/builders/special.xml b/doc/builders/special.xml index c971134819818..18cf6cfd39c70 100644 --- a/doc/builders/special.xml +++ b/doc/builders/special.xml @@ -9,4 +9,5 @@ <xi:include href="special/makesetuphook.section.xml" /> <xi:include href="special/mkshell.section.xml" /> <xi:include href="special/darwin-builder.section.xml" /> + <xi:include href="special/vm-tools.section.xml" /> </chapter> diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md new file mode 100644 index 0000000000000..3b6fb0d2556b8 --- /dev/null +++ b/doc/builders/special/vm-tools.section.md @@ -0,0 +1,148 @@ +# 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 + +* `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 + +* `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: +```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 + +* `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 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} + +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: +```nix +{ pkgs }: with pkgs; with vmTools; +makeImageTestScript diskImages.fedora27x86_64 +``` + +Create a script for running an Ubuntu 20.04 VM: +```nix +{ pkgs }: with pkgs; with vmTools; +makeImageTestScript diskImages.ubuntu2004x86_64 +``` + +## `vmTools.diskImageFuns` {#vm-tools-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: +```nix +{ pkgs }: with pkgs; with vmTools; +diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; } +``` + +## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns} + +Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`. + +## `vmTools.diskImages` {#vm-tools-diskImages} + +Shorthand for `vmTools.diskImageFuns.<attr> { }`. |