= 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].