1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
| | = Developing Built-in Application VMs
:page-nav_order: 3
// SPDX-FileCopyrightText: 2023-2025 Alyssa Ross <hi@alyssa.is>
// SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
Spectrum comes with some built-in application VMs, to demonstrate
certain aspects of the system.
These VMs are defined inside the
https://spectrum-os.org/git/spectrum/tree/vm/app[vm/app directory].
The built-in VMs all use a common template,
https://spectrum-os.org/git/tree/img/app[img/app], and supply a script
of their own for the template to run that starts the appropriate
application. Unlike user-defined VMs, Nix store paths inside built-in
VMs are deduplicated against the template's store. The template
provides the root filesystem. It mounts a filesystem from a second
block device containing the application-specific parts, overlays that
filesystem's Nix store onto its own, then runs the provided script.
It's possible to run these VMs directly from your development system,
without needing to start a whole Spectrum system, and then start the
VM inside that system. This is done using the development shell for
the template. For example, to run the built-in gnome-text-editor VM,
run the following in the img/app directory:
[source,shell]
----
nix-shell \
-I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz \
--arg run ../../vm/app/gnome-text-editor.nix \
--run 'make clean && make -j$NIX_BUILD_CORES run'
----
If you're working on the template itself, you can keep a single
development shell session open, and just `make run` every time you
want to test a new version. Make will only track changes to the
template, though, so if you change any Nix files, you'll have to
re-enter the development shell, and run `make clean` if they affected
the template.
NOTE: As a special convenience, it's not necessary to run `make clean`
if the only change to the Nix files is modifying the packages
installed in the VM.
The list of files used for images is stored in a separate file,
file-list.mk. To update it, run scripts/genfiles.sh, which will
regenerate it from the output of `git ls-files`. This script uses
Git's index to generate the list, so only staged changes will be
reflected in its output.
By default, `make run` runs the VM in Cloud Hypervisor, to match the
Spectrum environment. You can also add `VMM=crosvm` or `VMM=qemu` to
your command line to run the VM in a different VMM. One reason to do
this would be to test networking using QEMU's
https://www.qemu.org/docs/master/system/devices/net.html#using-the-user-mode-network-stack[user
mode network stack].
|