BoomMicrophone/nixpkgs-suyu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update vmTools docs after rebase

Browse source
This commit is contained in:
Leandro Emmanuel Reina Kiperman 2023-04-10 00:43:31 +02:00
parent 6c4d780599
commit a6c19474bd
1 changed files with 60 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
doc/builders/special/vm-tools.section.md
View file

@ -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"; }; }))
```
<!-- TODO
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 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; }
```