From 0eff947d0b8c28338d9c082485c346f5028deb53 Mon Sep 17 00:00:00 2001 From: Leandro Reina Date: Sat, 22 Oct 2022 18:27:42 +0200 Subject: [PATCH 1/3] doc: add vmTools --- doc/builders/special.xml | 1 + doc/builders/special/vm-tools.section.md | 116 +++++++++++++++++++++++ doc/manpage-urls.json | 1 + 3 files changed, 118 insertions(+) create mode 100644 doc/builders/special/vm-tools.section.md diff --git a/doc/builders/special.xml b/doc/builders/special.xml index c97113481981..18cf6cfd39c7 100644 --- a/doc/builders/special.xml +++ b/doc/builders/special.xml @@ -9,4 +9,5 @@ + diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md new file mode 100644 index 000000000000..c838f3efbf45 --- /dev/null +++ b/doc/builders/special/vm-tools.section.md @@ -0,0 +1,116 @@ +# 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). 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. + +### 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). + +### Examples + +```nix +# Build the derivation hello inside a VM +runInLinuxVM hello + +# Build inside a VM with extra memory +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"; }; })) +``` + + + +## `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. + +## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript} + +Generate a script that can be used to run an interactive session in the given image. + +### Examples + +```nix +# Create a script for running a Fedora 27 VM +makeImageTestScript diskImages.fedora27x86_64 + +# Create a script for running an Ubuntu 20.04 VM +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` +* Debian + * `debian9i386` + * `debian9x86_64` + * `debian10i386` + * `debian10x86_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. + +### Examples + +```nix +# 8G image containing Firefox in addition to the default packages. +diskImageFuns.ubuntu2004x86_64 { extraPackages = [ "firefox" ]; size = 8192; } +``` + +## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns} + +Shorthand for `vmTools.diskImageFuns. { extraPackages = ... }`. + +## `vmTools.diskImages` {#vm-tools-diskImages} + +Shorthand for `vmTools.diskImageFuns. { }`. diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json index e83708dd64d6..09dabe98aac4 100644 --- a/doc/manpage-urls.json +++ b/doc/manpage-urls.json @@ -3,6 +3,7 @@ "mpd(1)": "https://mpd.readthedocs.io/en/latest/mpd.1.html", "mpd.conf(5)": "https://mpd.readthedocs.io/en/latest/mpd.conf.5.html", "nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html", + "mount(5)": "https://linux.die.net/man/8/mount", "journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html", "logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html", From 6c4d780599e97e33d9f79997afcd661e3131c0ea Mon Sep 17 00:00:00 2001 From: Leandro Reina Date: Sat, 22 Oct 2022 18:36:18 +0200 Subject: [PATCH 2/3] Remove unused reference --- doc/manpage-urls.json | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json index 09dabe98aac4..e83708dd64d6 100644 --- a/doc/manpage-urls.json +++ b/doc/manpage-urls.json @@ -3,7 +3,6 @@ "mpd(1)": "https://mpd.readthedocs.io/en/latest/mpd.1.html", "mpd.conf(5)": "https://mpd.readthedocs.io/en/latest/mpd.conf.5.html", "nix.conf(5)": "https://nixos.org/manual/nix/stable/command-ref/conf-file.html", - "mount(5)": "https://linux.die.net/man/8/mount", "journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html", "logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html", From a6c19474bd52555e575343c2d4d51888e5b592fa Mon Sep 17 00:00:00 2001 From: Leandro Emmanuel Reina Kiperman Date: Mon, 10 Apr 2023 00:43:31 +0200 Subject: [PATCH 3/3] Update vmTools docs after rebase --- doc/builders/special/vm-tools.section.md | 88 ++++++++++++++++-------- 1 file changed, 60 insertions(+), 28 deletions(-) diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md index c838f3efbf45..3b6fb0d2556b 100644 --- a/doc/builders/special/vm-tools.section.md +++ b/doc/builders/special/vm-tools.section.md @@ -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 -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"; }; })) ``` - + +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; } ```