Skip to content

Commit

Permalink
docs: update the tutorial to include less unnecessary cruft for newco…
Browse files Browse the repository at this point in the history 
…mers
  • Loading branch information
@mattkae
mattkae committed Jul 8, 2024
1 parent eec03e0 commit 5becb95
Showing 1 changed file with 64 additions and 79 deletions.
143 changes: 64 additions & 79 deletions doc/sphinx/tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,86 +3,100 @@ discourse: 4911,5164,5603,6756,8037
---

# Tutorial
This tutorial will instruct you on how to get started building your first
Wayland compositor with Mir. Additionally, we will provide information on how
to install some demo compositors that will give you a sense of what you can
build with Mir.

Mir is a library for building things, not an end-user product, but it does come
with some demos to illustrate the possibilities.

## Getting Mir demos

The Mir libraries and demos are available on Ubuntu, Fedora and Arch. It has
also been built and tested on Debian but, at the time or writing, is not in the
archive.

For Linux distributions that don't currently package Mir you need to build it
yourself. (See [Getting Involved in Mir](how-to/getting_involved_in_mir)).

## Getting Mir on Ubuntu

You can install the Mir examples along with the Mir graphics drivers as follows:

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

It is also useful to install Wayland support for Qt and qterminal:

sudo apt install qterminal qtwayland5

### Getting the latest Mir release on Ubuntu
## Installing Mir Libraries
The Mir libraries and demos are available on Ubuntu, Fedora, Debian and Arch.

### Installing Mir on Ubuntu
As a matter of policy Ubuntu does not routinely update packages after a series
is released. This means the Mir team cannot reasonably guarantee that all series
will have the latest Mir release available at all times.

The latest Mir release is available for all supported Ubuntu series from the
Mir team's "release PPA". To add the PPA to your system:

sudo add-apt-repository --update ppa:mir-team/release
```sh
sudo add-apt-repository --update ppa:mir-team/release
```

Afterwards, you will be able to install any of the libraries that are published
by the project. The library that one might be interested in as a compositor author
is `libmiral`. To install it, you may run:


```sh
sudo apt install libmiral7 libmiral-dev mir-graphics-drivers-desktop
```

To remove the PPA from your system:

sudo ppa-purge mir-team/release
```sh
sudo ppa-purge mir-team/release
```

## Getting Mir on Fedora
### Installing Mir on Fedora

On Fedora Mir is available from the archive:
On Fedora, Mir is available from the archive:

sudo dnf install mir-demos
```sh
sudo dnf install mir-devel mir-server-libs
```

It is also useful to install qterminal:
### Installing Mir on Debian
On Debian, Mir is available as `mir` (https://tracker.debian.org/pkg/mir):

sudo dnf install qterminal
```
sudo apt install mir
```

## Getting Mir on Arch

On Arch Linux, you can install the [mir](https://aur.archlinux.org/packages/mir/) package from the AUR.
### Installing Mir on Arch

## Using Mir demos
On Arch Linux, you can install the [mir](https://aur.archlinux.org/packages/mir/) package from the AUR.

For convenient testing under X11 there's a "miral-app" script that wraps the
commands used to start a server and then launches a terminal (as the current
user):
## Installing and Running Demo Compositors
Mir provides a number of few example compositors in the
[examples folder](https://github.com/canonical/mir/tree/main/examples) of the Mir project.
Each folder in the "examples" folder is an independent Wayland compositor.

miral-app
### Installing demos on Ubuntu

If you're using a desktop that supports X11 then you can run this in a terminal
window. In that case Mir will automatically select a "Mir-on-X11" backend and
run in a Window.
```sh
sudo apt install mir-demos mir-graphics-drivers-desktop
```

Alternatively, to run Mir "natively" you can run the same command in a Virtual
Terminal.
### Installing Mir demos manually
For Linux distributions that don't currently package Mir you need to build it
yourself. (See [Getting Involved in Mir](how-to/getting_involved_in_mir)).

### Running applications on Mir
### Running Mir demos
The main mir demo that you might be interested in is `miral-app`, which provides
access to a number of different window manager demos depending on which arguments
are provided to it. By default, it runs `miral-shell`, which is a floating window manager
with pleasant startup screen. To run the demos, you can simply run `miral-app`
from a terminal in your current session (e.g. a gnome-shell session):

If you use the terminal launched by `miral-app` Wayland applications can be
started as usual:
```sh
miral-app
```

kate
neverputt
gedit
This will open up a new window in your compositor that contains a nested
"floating window manager" compositor.
Likewise, you can switch to a different VT (using `Ctrl + Alt + F<NUMBER>`). From
there, you may log in and run:

### Options when running the Mir example shell
```sh
miral-app
```

#### Script Options
In both cases, you should see a startup screen with information on how to use the
compositor. The compositor should behave like a typical floating window manager.

#### Options to `miral-app`
The `miral-app` script provides options for using an alternative shell
(e.g. `miral-kiosk` as used by the mir-kiosk snap) and an alternative terminal.

Expand All @@ -98,32 +112,3 @@ For example:

There are some additional options (listed with "-h") but those are the important
ones.

#### `miral-shell` Options

The script will pass everything on the command-line following the first thing it
doesn't understand to `miral-shell`. The options can be listed by
`miral-shell --help`. The following are likely to be of interest:

--window-management-trace log trace message

Probably the main use for `miral-shell` is to test window-management (either of
a client toolkit or of a server) and this logs all calls to and from the window
management policy. This option is supported directly in the MirAL library and
works for any MirAL based shell - even one you write yourself.

--window-manager arg (=floating) window management strategy
[{floating|tiling|system-compositor}]

This allows an alternative "tiling" window manager to be selected. *Note:
`--window-manager` is only supported by `miral-shell` (not `miral-kiosk`).*

For example:

miral-app --window-manager tiling

These options can also be specified in a configuration file. For example:

$ cat ~/.config/miral-shell.config
keymap=gb
window-manager=tiling

0 comments on commit 5becb95

Please sign in to comment.