1
Building and using MirAL {#building_and_using_miral}
2
========================
1
Getting and Using MirAL {#getting_and_using_miral}
2
=======================
7
Depending upon your needs you can:
9
1. Install and use the MirAL examples [Using MirAL examples];
10
2. Use MirAL to develop your own Mir server [Using MirAL for development]; or,
11
3. Build MirAL yourself [Building MirAL].
16
You can install the MirAL examples as follows:
18
$ sudo apt install libmiral-examples
19
$ sudo apt install mir-graphics-drivers-desktop qtubuntu-desktop
21
For convenient testing there's a "miral-app" script that wraps the commands used
22
in the last section to start the server and then launches the gnome-terminal (as
27
To run independently of X11 you need to grant access to the graphics hardware
28
(by running as root) and specify a VT to run in. There's a "miral-desktop"
29
script that wraps to start the server (as root) and then launch gnome-terminal
30
(as the current user):
34
For more options see [Options when running the MirAL example shell] below.
36
### Running applications on MirAL
38
If you use the command-line launched by miral-app or miral-desktop native Mir
39
applications (which include native Mir clients and those that use SDL or the
40
GTK+, Qt toolkits) can be started as usual:
42
$ sudo apt install mir-demos kate neverball
43
$ mir_demo_client_egltriangle
48
From outside the MirAL session GTK+, Qt and SDL applications can still be run
49
using the miral-run script:
54
### Running for X11 applications
56
If you want to run X11 applications that do not have native Mir support in the
57
toolkit they use then the answer is Xmir: an X11 server that runs on Mir. First
58
you need Xmir installed:
60
$ sudo apt install xmir
62
Then once you have started a miral shell (as above) you can use miral-xrun to
63
run applications under Xmir:
67
This automatically starts a Xmir X11 server on a new $DISPLAY for the
68
application to use. You can use miral-xrun both from a command-line outside the
69
miral-shell or, for example, from the terminal running in the shell.
71
### Options when running the MirAL example shell
75
Both the "miral-app" and "miral-desktop" scripts provide options for using an
76
alternative example shell (miral-kiosk) and an alternative to gnome-terminal.
78
-kiosk use miral-kiosk instead of miral-shell
79
-launcher <launcher> use <launcher> instead of
80
'gnome-terminal --app-id com.canonical.miral.Terminal'
82
In addition miral-desktop has the option to set the VT that is used:
84
-vt <termid> set the virtual terminal [4]
86
There are some additional options (listed with "-h") but those are the important
91
The scripts can also be used to pass options to MirAL: they pass everything on
92
the command-line following the first thing they don't understand. These can be
93
listed by `miral-shell --help`. Most of these options are inherited from Mir,
94
but the following MirAL specific are likely to be of interest:
96
--window-management-trace log trace message
98
Probably the main use for MirAL is to test window-management (either of a
99
toolkit or of a server) and this logs all calls to and from the window
100
management policy. This option is supported directly in the MirAL library and
101
works for any MirAL based shell - even one you write yourself.
103
--keymap arg (=us) keymap <layout>[+<variant>[+<options>]]
104
, e,g, "gb" or "cz+qwerty" or
107
For those of us not in the USA this is very useful. Both the -shell and -kiosk
108
examples support this option.
110
--window-manager arg (=titlebar) window management strategy
111
[{titlebar|tiling|system-compositor}]
113
Is only supported by miral-shell and its main use is to allow an alternative
114
"tiling" window manager to be selected.
116
Using MirAL for development
117
---------------------------
119
Install the headers and libraries for using libmiral in development:
121
$ sudo apt install libmiral-dev
123
A `miral.pc` file is provided for use with `pkg-config` or other tools. For
124
example: `pkg-config --cflags miral`
126
The MirAL documentation can be installed and read like this:
128
$ sudo apt install miral-doc
129
$ xdg-open /usr/share/doc/miral-doc/html/index.html
4
134
These instructions assume that you’re using Ubuntu 16.04LTS or later, I’ve not
5
135
earlier Ubuntu versions or other distributions.
42
172
To exit from miral-shell press Ctrl-Alt-BkSp.
44
To run independently of X11 you need to grant access to the graphics hardware
45
(by running as root) and specify a VT to run in. For example:
47
$ sudo bin/miral-shell --vt 4 --arw-file --file $XDG_RUNTIME_DIR/mir_socket
49
For convenient testing there's a "miral-desktop" script that wraps this command
50
to start the server (as root) and then launches the gnome-terminal (as the
53
$ bin/miral-desktop -bindir bin
55
Support for X11 applications
56
----------------------------
58
If you want to run X11 applications that do not have native Mir support in the
59
toolkit they use then the answer is Xmir: an X11 server that runs on Mir. First
60
you need Xmir installed:
62
$ sudo apt install xmir
64
Then once you have started miral-shell (as above) you can use miral-xrun to run
65
applications under Xmir:
67
$ bin/miral-xrun firefox
69
This automatically starts a Xmir X11 server on a new $DISPLAY for the
70
application to use. You can use miral-xrun both from a command-line outside the
71
miral-shell or, for example, from a terminal running in the shell.
73
Running applications on Miral
74
-----------------------------
76
Assuming you have a Mir server running, native Mir applications can be started
77
from the command-line:
79
$ sudo apt-get install mir-demos
80
$ mir_demo_client_egltriangle
82
Similarly, GTK+, Qt and SDL applications can be run with the miral-run script:
90
You can list the configuration options for miral-shell with "--help":
92
$ bin/miral-shell --help
94
Most of these options are inherited from Mir. These can be set on the command
95
line, by environment variables or in a config file. For example, if you want to
96
start the gnome-terminal when you run miral-shell you can:
98
Set supply the option on the command line:
100
$ bin/miral-shell --startup-apps gnome-terminal
102
Set the corresponding MIR_SERVER_<option> environment variable:
104
$ export MIR_SERVER_STARTUP_APPS=gnome-terminal
108
Create a miral-shell config file:
110
$ echo startup-apps=gnome-terminal > ~/.config/miral-shell.config
114
Running Qt applications
115
-----------------------
117
To run Qt applications under Mir you may need to install qtubuntu-desktop:
119
$ sudo apt-get install qtubuntu-desktop
124
MirAL comes with a set of tests, if you intend to build these then add the
127
$ sudo apt-get install cmake-extras google-mock mirtest-dev mir-test-tools
128
$ sudo apt-get install libboost-filesystem-dev libboost-system-dev
130
Note that this is not possible for Mir versions prior to 0.24 as there were
131
bugs in mirtest-dev. At the time of writing Ubuntu 16.4 has Mir-0.21.
174
You can install the MirAL examples, headers and libraries you've built with:
178
Otherwise, you just need to add "bin/" to the beginning of the commands shown
179
in the previous section.
added
removed
getting_and_using_miral.md
