Testing Applications on Ubuntu Frame


Developers use different tools and processes to build their graphic applications. For the purpose of this guide, we assume that you have an application that supports the Wayland protocol that you can test on your Linux-based desktop.

It is possible to work in a container or on a different computer (if snapd and X forwarding work well enough). But those options are outside the current scope.

For some of the later steps, you will need an Ubuntu One account. This will let you enable remote-build on your Launchpad account and publish on the Snap Store.

Setting up your test environment

Ubuntu Frame provides a tool for developers to simulate how their end application will look and respond in your development environment. So, you don’t need to work directly on your target device to perform the first design and usability iterations.

Open a terminal window and type:

sudo snap install ubuntu-frame

Snapcraft is a command-line utility for building snaps. This software allows users to build their own applications or software packages, and then publish them to the Snap Store.

In the same terminal window type:

sudo snap install snapcraft --classic

If you don’t have git installed, now is a good time to install it (on Ubuntu, use the command sudo apt install git).

Checking your application works with Ubuntu Frame

There can be problems with both getting your application to work well with Ubuntu Frame and getting your application to work in a snap. To avoid confusion, we recommend first testing your application with Ubuntu Frame before packaging it as a snap. In this section, you will test your application, explore some common issues you might run into, and learn how to fix them.

Enabling Ubuntu Frame simulator

The key thing to know about connecting an app to Ubuntu Frame is that the connection is controlled by the WAYLAND_DISPLAY environment variable. You need to set that to the same value for both processes and, because you may be using a Wayland-based desktop environment (which uses the default of wayland-0), set it to wayland-99.

In a terminal window (that you’ll use for this section and the next section) type:

export WAYLAND_DISPLAY=wayland-99


You should see a “Mir on X” window containing a graduated grey background. Mir is the library on which Ubuntu Frame is based, and for testing your app in a window, you should use it’s “Mir on X” simulator.

Testing your application on Ubuntu Frame simulator

You can use Electron, Flutter, Qt, or any other toolkit or programming language to develop your graphic application. There is no sole path for checking all of them. Instead, this guide will use some example applications using GTK, QT, and SDL2.

The examples used here are game applications, such as Mastermind, Neverputt, and Bomber. We’ve chosen these applications as they are easily installable and are designed to work without a full desktop session. But they can be replaced by your kiosk application, industrial GUI, smart fridge GUI, digital sign and more.

So, the first step is to download these applications and execute them. If you are able to see it on the “Mir on X” window, then you know that your application works with Ubuntu Frame.

Now, still in the same terminal window, type:

GTK Example: Mastermind

sudo apt install gnome-mastermind


Now Frame’s “Mir on X” window should contain the “Mastermind” game.

If your application doesn’t appear or look right at this stage, then this is the time to work out the fix, before packaging as a snap. You will see some examples of the problems you might encounter in the following examples.

Close Mastermind (Ctrl-C) and try the next example:

Qt Example: Bomber

sudo apt install bomber


What you see now is that Bomber appears in its own window, not in the Ubuntu Frame window. The problem is that Qt does not default to using Wayland and that QT_QPA_PLATFORM needs to be set to get that behaviour. Close it and try again with:

QT_QPA_PLATFORM=wayland bomber

Now Frame’s “Mir on X” window should contain the “Bomber” game as shown in the next image.

You will incorporate setting QT_QPA_PLATFORM in the “environment” of the snap recipe later.

Close that (Ctrl-C) and try the next example.

SDL2 Example: Neverputt

sudo apt install neverputt

SDL_VIDEODRIVER=wayland neverputt

Now Frame’s “Mir on X” window should contain the “Neverputt” game. Note that SDL2 does not default to using Wayland and that SDL_VIDEODRIVER needs to be set to get that behaviour.

The other thing you’ll see is that the game doesn’t fill the display. That’s because the application doesn’t understand Ubuntu Frame telling it to fill the screen. This is a problem with some applications and, in this case, can be fixed by editing ~/.neverball/neverballrc [sic] to say “fullscreen 1” and restarting the game. (The same file works for neverball, but you may need to figure out the right configuration file for your application.) This is what you will see:

You will incorporate setting SDL_VIDEODRIVER and the neverballrc setting in the snap recipe later.

You can now close the app (Ctrl-C).

Further Reading

To learn how to package and deploy Ubuntu Frame snaps on the desktop, read this how-to.