Florian Müllner 6871b7aa20 docs: Document how to build and run gnome-shell

While we use the standard meson build steps, our dependencies
are non-trivial and running the shell can be tricky; it's
certainly worth documenting.

This is also a good opportunity for plugging out toolbox tooling.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3122>

2024-01-27 22:23:24 +01:00

2.8 KiB

Raw Blame History

Building and Running

Building gnome-shell

gnome-shell uses the meson build system, and can be compiled with the following commands:

$ meson setup _build
$ meson compile -C _build

Unfortunately gnome-shell has a non-trivial number of dependencies that cannot always be satisfied by distribution packages.

This is particular true for mutter, which is developed in lock-step with gnome-shell and always has to be built from source.

Toolbox

Toolbox is a container tool for Linux, which allows the use of interactive command line environments for development, without having to install software on the host.

It is suitable for gnome-shell development, and we maintain a number of scripts to make its use easier and more convenient.

You can set up a new container that satisfies all build- and runtime dependencies with the following script:

$ tools/toolbox/create-toolbox.sh

The script will download the container image and build mutter, so it is expected that it will take a while.

Once you have a working container, the following scripts can be used to build and run gnome-shell:

$ tools/toolbox/meson-build.sh
$ tools/toolbox/run-gnome-shell.sh

If building or running fails with errors about meta, clutter or cogl, there was probably an incompatible change in mutter. You can update the dependency with the following command:

$ toolbox run --container gnome-shell-devel update-mutter

Refer to the README for further information on the scripts.

Running a nested instance

It is possible to run gnome-shell as "nested" instance in a window.

The run-gnome-shell script will automatically do that when run from a graphical session, or you can run the following command:

$ WAYLAND_DISPLAY=shell-test-1 dbus-run-session \
    gnome-shell --wayland-display=shell-test-1 --nested

There are limitations to the nested instance, such as keyboard shortcuts usually not getting to the nested compositor.

In order to still bring up the Looking Glass debugger, you can use an extension as workaround.

Native

Sometimes it's necessary to run the "native backend", on real display hardware.

To do that, switch to a tty and either use the run-gnome-shell script or run the following command:

$ dbus-run-session gnome-shell --wayland

Some functionality is not available when running gnome-shell outside a GNOME session, including logout. To exit gnome-shell, bring up the run dialog with Alt F2 and enter debugexit.

2.8 KiB Raw Blame History