Month: September 2025

Posted on

Testing and developing SWT on GTK

I have recently started working on improved support of GTK4 in SWT and I have been trying to untangle the various options that affect SWT + GTK and how everything goes together.

Environment Variables

These are key environment variables that control where and how SWT draws in GTK land.

  • SWT_GTK4: If this is set to 1 then SWT will attempt to use GTK4 libraries
  • GDK_BACKEND: Which backend the GDK layer (a layer below GTK) uses to draw. Can be set to x11 or wayland.
  • DISPLAY: when GDK_BACKEND is x11, controls which display the program is drawn on.

If SWT_GTK4 or GDK_BACKEND is set to a value that is not supported, then generally the code gracefully falls back to the other value. For example, setting SWT_GTK4=1 without GTK4 libraries will attempt to load GTK3 libraries.

If DISPLAY is set to an invalid value, you will generally get a org.eclipse.swt.SWTError: No more handles [gtk_init_check() failed] exception (although there are other reasons you can get that exception).

GDK_BACKEND is often set by unexpected places. For example on my machine I often find GDK_BACKEND set to x11, even though I have not requested that. Other places, such as VSCode may force setting GDK_BACKEND depending on different circumstances. Therefore I recommend being explicit/careful with GDK_BACKEND to ensure that SWT is using the backend you expect.

X11 and Wayland

When Wayland is in use, and GDK_BACKEND=x11, then Xwayland is used to bridge the gap between an application written to use X11 and the user’s display. Sometimes the behaviour of Xwayland and its interactions can differ from using a machine with X as the real display. To test this you may want to install a machine (or VM) with a distro that uses X11 natively, such as Xubuntu. The alternative is to use a VNC server (see below section).

X11 VNC Server

Rather than installing a VM or otherwise setting up a different machine you can use a VNC Server running an X server. This has the added benefit of giving a mostly accurate X11 experience, but also benefits from maintaining its own focus and drawing, allowing X11 tests to run without interrupting your development environment.

In the past I have recommended using Xvfb as documented in CDT’s testing manual. However, for my current SWT development I have used tiger VNC so I can see and interact with the window under test.

When I was experimenting on setting this up I seemed to have accidentally changed my Ubuntu theme. I was doing a bunch of experimenting, so I’m not sure what exactly I did. I have included the steps I believe are necessary below, but I may have edited out an important step – if so, please comment below and I can update the document.

These are the steps to setup and configure tiger vnc that worked for me on my Ubuntu 25.04 machine:

  • sudo apt install tigervnc-standalone-server tigervnc-common Install the VNC tools
  • sudo apt install xfce4 xfce4-goodies Install an X11 based window manager and basic tools (there are probably some more minimal sets of things that could be installed here)
  • vncpasswd Configure VNC with a password access control
  • sudo vi /etc/X11/Xtigervnc-session Edit how X11 session is started. I found that the default didn’t work well, probably because xfce4 was not the only thing installed on my machine and the Xsession script didn’t quite know what to do. The exec /etc/X11/Xsession "$@" didn’t launch successfully, so I replaced that line with these lines:
    unset SESSION_MANAGER
    unset DBUS_SESSION_BUS_ADDRESS
    exec startxfce4
    The SESSION_MANAGER and DBUS_SESSION_BUS_ADDRESS are unset because I wanted to keep this session independent of other things running on my machine and I was getting errors without them unset.
  • vncserver :99 Start the VNC Server – adjust :99 for the display you want to use, you set DISPLAY environment variable to :99 in this case.
  • xtigervncviewer -SecurityTypes VncAuth -passwd /tmp/pathhere/passwd :99 Start the viewer, use the command that vncserver output as part of its startup

Wayland Remote connection

I have not had the opportunity to use this much yet, but recent Ubuntu machines come with desktop sharing using RDP based on gnome-remote-desktop. This should allow connecting to a Ubuntu machine and use Wayland remotely. Enable it from Settings -> System -> Remote Desktop and connect to the machine using Remote Desktop.

What to test?

Now that I am developing SWT, specifically targetting GTK4 work, there are different configurations of the above to test. My primary focus is to test:

  • SWT_GTK4=0 with GDK_BACKEND=x11 running on the default DISPLAY that is connected to Xwayland
  • SWT_GTK4=1 with GDK_BACKEND=wayland (in this case DISPLAY is unused)

However these additional settings seem useful to test, especially as x11 backend sometimes seems to be used unexpectedly on wayland:

  • SWT_GTK4=0 with GDK_BACKEND=x11 running on the DISPLAY connected to my VNC. This is really useful for when I want to leave tests running in the background
  • SWT_GTK4=1 with GDK_BACKEND=x11 the behaviour of various things (such as the Clipboard) is different when using GTK4 with wayland. I don’t know how important this use case is long term
  • SWT_GTK4=0 with GDK_BACKEND=wayland – I don’t know if this really adds anything and have hardly tried this combination.

Run Configurations

Here is what a few of my run configurations look like