Update vmTools docs after rebase
This commit is contained in:
Leandro Emmanuel Reina Kiperman
parent
6c4d780599
commit
a6c19474bd
|
|
@ -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; }
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue