Using the test VM

A lightweight virtual machine has been introduced in #982 which allows quickly testing the latest GNOME Shell (on NixOS) with PaperWM installed and default settings.

To run the VM, you need to have Nix installed on your system, and permissions to run a KVM virtual machine. I strongly recommend using Nix Flakes, which involves adding the following line to $HOME/.config/nix/nix.conf (or /etc/nix/nix.conf):

extra-experimental-features = nix-command flakes

The following command spawns the VM without graphical acceleration:

nix run .\#vm

To enable graphical acceleration, due to limitations with Nix, you need to install NixGL and run the VM within it:

nixGLIntel nix run .\#vm -- -device virtio-gpu-gl -display gtk,gl=on

# Alternatively, on Nvidia:
nixGLNvidia nix run .\#vm -- -device virtio-gpu-gl -display gtk,gl=on

Non-standard devices

QEMU can be used to test hardware configurations which do not necessarily reflect what you are currently running. Below are some options tested for hardware setups which PaperWM aims to support.

Tip

Unless mentioned otherwise, the options below can be combined with other QEMU options, including the video acceleration tip above.

Touch screen

You can connect a touch screen to the VM, which will copy all touch screen events into the VM:

nix run .\#vm -- ... -device virtio-multitouch-pci

# Without hardware touch screen, simulate touch events
#FIXME: remove usb-tablet from QEMU to let simulated touch events happen
env GTK_DEBUG=touchscreen nix run .\#vm -- ... -device virtio-multitouch-pci -display gtk,gl=on,grab-on-hover=off,show-cursor=on

Multiple displays

You can add another screen to the VM, using a device option.

Note

The graphical acceleration tip above already adds a secondary display, which can be activated from the "View" menu

# You can repeat this option for each additional display
nix run .\#vm -- ... -device qxl

Preserved state across reboots

The virtual machine will automatically preserve configuration changes to PaperWM inside the virtual machine. To reset the VM or run concurrent instances, move/delete the nixos.qcow2 file in the current directory.

Changing NixOS/GNOME version

Thanks to the Nix flakes system, we can change which version of NixOS the VM is based on relatively easily.

Upgrading to latest

Simply run the following command:

# Nix 2.21 or later
nix flake update nixpkgs

# Older versions (you should really upgrade!)
nix flake lock --update-input nixpkgs

This will update the flake.lock file in this repository to point to the latest Nixpkgs, updating all packages in the VM. This is a regular maintenance task, which will ideally be carried out by a bot in the near future.

Targeting a specific GNOME version

1. Locate the desired GNOME version on this page (or here for versions prior to 46)
2. Copy the "Nixpkgs reference" associated with it
3. Add the hash to the end of the nixpkgs input spec, in flake.nix

The start of your flake.nix should now look like this (here, GNOME 46.4):

{ description = "Tiled, scrollable window management for GNOME Shell";

  inputs."nixpkgs".url = github:NixOS/nixpkgs/30c9efeef01e2ad4880bff6a01a61dd99536b3c9;
  ...

Saving storage space

Running the VM requires around 4GB of local storage. To delete the VM's files and save space, run the following command:

nix-collect-garbage -d