Getting started with Mir

This tutorial will guide you through Mir’s basic functionality.

By the end of the tutorial, you will install and run a demo application, learn how to use Mir in different environments, and learn about features that Mir provides for Mir-based compositors.

If you are unfamiliar with Mir, start with this tutorial, and then proceed to a developer tutorial which will guide you through the process of writing a compositor.

Installing demo applications

Mir demos are available on Debian derivatives, Fedora, and Alpine. For distros that don’t have pre-built binaries, examples can be built from source.

On Debian and its derivatives

sudo apt install mir-demos mir-graphics-drivers-desktop

On Fedora

sudo dnf install mir-demos

On Alpine

sudo apk add mir-demos mir

Running applications on X11 or Wayland

We’ll work with miral-app, a script that handles running a Mir shell with a basic GUI.

Mir allows you to run a graphical shell in desktop mode or in kiosk mode.

Desktop mode means that application windows that are opened are floating, you can move them around the screen, maximize, or minimize them. Kiosk mode means that the application is opened in fullscreen mode. You are unable to move or resize it.

To run the script in desktop mode:

miral-app

To run the script in kiosk mode:

miral-app -kiosk

Running shells natively

Mir compositors support running “natively” by launching them from a virtual terminal or a login screen.

Launching from a virtual terminal

  1. Switch to a virtual terminal by pressing CTRL+ALT+F<Number> and log in.

  2. Run the script:

miral-app

Launching from a login screen

Open the window manager list, choose Mir Shell, log in, and miral-shell will be running fullscreen.

Using on-screen keyboards

Mir-based compositors support on-screen keyboards.

Note: Due to security reasons, some Wayland extensions needed by on-screen keyboards are disabled by default. In this tutorial, we override this setting by passing --add-wayland-extensions all when launching miral-app. passing a --add-wayland-extensions all flag when launching an example application.

You can use any Wayland compatible on-screen keyboard but as an example, we’ll use ubuntu-frame-osk.

  1. Install ubuntu-frame-osk:

sudo snap install ubuntu-frame-osk
sudo snap connect ubuntu-frame-osk:wayland

  1. Start miral-app:

miral-app --add-wayland-extensions all

  1. Once the shell loads, start the terminal (with Ctrl-Alt-Shift-T) and start your on-screen keyboard:

ubuntu-frame-osk&

An on-screen keyboard will pop up.

Mixing Wayland and X11 clients

You can run X11 applications inside Mir-based compositors. As an example, let’s run xclock - an X11 application that displays the time.

  1. Enable X11 support in miral-shell:

miral-app --enable-x11 true

  1. Once the shell loads, run xclock:

xclock

A window with a clock will pop up.

Remote desktop

Mir supports remote desktops via the VNC protocol. To demo this, you’ll use wayvnc - a VNC server.

  1. Install wayvnc:

sudo apt install wayvnc

  1. Install your preferred VNC client.

  2. Start the shell with all extensions enabled:

miral-app --add-wayland-extensions all

  1. In the shell, open the terminal and run wayvnc:

wayvnc

A wayvnc server will start and will listen to localhost.

  1. Run your VNC client and connect to localhost. You will see the exact same view in both the Mir compositor and the VNC viewer.