= Developing Built-in Application VMs
:page-parent: Development
:page-nav_order: 3

// SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
// 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 mg 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/mg.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.

By default, `make run` runs the VM in QEMU, because it can do
https://www.qemu.org/docs/master/system/devices/net.html#using-the-user-mode-network-stack[user
mode networking].  For a more Spectrum-like environment, you can
instead run VMs in cloud-hypervisor by running Make with
`VMM=cloud-hypervisor`.