Yesterday, I wanted to debug a glycin (or Shell) issue on GNOME OS. Turns out, there is currently no documentation that works or includes all necessary steps.

Here is the simplest variant if you don’t develop on GNOME OS and have an internet connection that can download 16 GB in a reasonable amount of time.

First we get a toolbox image to build our code.

$ toolbox create gnomeos-nightly -i quay.io/gnome_infrastructure/gnome-build-meta:gnomeos-devel-nightly

After entering the toolbox with

$ toolbox enter gnomeos-nightly

we can clone and build our project with sysext-utils that are included in our image:

$ meson setup ./build --prefix /usr --libdir="lib/$(gcc -print-multiarch)"
$ sysext-build example ./build

This creates a example.sysext.raw file.

Now, we need a GNOME OS to test our build. We can download the image and install it in Boxes. After logging in, we can just drag and drop the example.sysext.raw into the VM.

Before we can install it, we need to get the development tools for our VM:

$ run0 updatectl enable devel --now

After that, we need to restart the VM.

Finally, we can test our build:

$ run0 sysext-add ~/Downloads/example.sysext.raw

Adding the --persistent flag to this command will make the changes stay active across reboots.

If the changes made it impossible to boot into the VM again, we can start the VM in “Safe mode” from the boot menu. After logging in, we can manually remove the extension:

$ run0 rm /var/lib/extensions/example.raw

Happy hacking!