Source development

Start with build from source. The source build uses Ninja to coordinate Gnoblin, Mutter, and session files. The GTK-based portal backend is optional.

Build a component

The default command builds the standalone session. It uses the portal frontend and backend installed on your system:

make

To include Gnoblin's GTK-based portal backend, use:

./build.sh --with-portal

It requires GTK4 4.22 or newer and xdg-desktop-portal 1.21.1 or newer. You can instead configure another installed backend for Gnoblin with gnoblin.configure.portals.

To rebuild one upstream component, select its CMake target:

./build.sh --target mutter
./build.sh --target xdg-desktop-portal-gnome

Each target prepares its pinned source and checks its own development dependencies. Use the default command after rebuilding to write the complete session into the selected prefix.

Native compositor changes require a fresh session. A Lua config reload does not load rebuilt libraries. For Lua API methods, events, and operation results, use the runtime API reference and event catalog.

Preview a change

Build the nested viewer when needed and start a private Gnoblin session:

make preview

make preview runs the build that make wrote to build/stage, so run make first. It shows the stage at the install prefix inside a private mount namespace, which needs no root access and leaves the host unchanged. Inside the preview, the directory above the prefix shows only the staged build.

The preview uses a temporary home, config, data, cache, state, runtime directory, and D-Bus session. It still uses the host Wayland display and may connect to the host PipeWire socket. This is a development session, not a sandbox. See the devkit guide for options and isolation details.

Choose a prefix

make builds for the prefix /usr/local/lib/gnoblin. Set PREFIX=DIR to use another prefix. The binaries have the prefix compiled in, so use the same PREFIX for make and make install.

• make install copies the build to the prefix.
• make clean deletes build/ but leaves the installed copy.

./build.sh is separate. Its default build prefix is ./install, with libraries in lib64.

GNOBLIN_LIBDIR=lib ./build.sh --prefix /tmp/gnoblin
./build.sh --prefix /tmp/gnoblin --preview

GNOBLIN_LIBDIR is relative to the prefix. Use the same prefix for subsequent build and preview commands. System prefixes /usr and /usr/local are rejected. To add a prefix that already holds the runtime to your login screen, without a copy, run:

./build.sh --prefix /tmp/gnoblin --register-session

Portal backend

The default build uses portal services already installed on the system. To build Gnoblin's optional backend, run ./build.sh --with-portal. A GNOME session can continue using GNOME's backend. To choose another backend for Gnoblin, see gnoblin.configure.portals.

Verify changes

Run deterministic checks and the native runtime tests with:

make check
make test

Use tests/test-gnoblin-devkit.sh for an isolated live session. It requires a working Wayland desktop and a current build. A successful build or CTest run does not verify login on a real seat; see hardware verification.

Keep upstream submodules at their pinned commits. Put Gnoblin-owned behavior in src/, protocol changes in src/protocols/, and narrow upstream fixes in patches/. Export committed subproject changes with scripts/manage-patches.py so patch identity and headers stay consistent.