Mir

Merge lp:~alan-griffiths/mir/update-docs into lp:mir

Proposed by Alan Griffiths on 2017-09-07
Status: Merged
Approved by: Michał Sawicz on 2017-09-08
Approved revision: no longer in the source branch.
Merged at revision: 4245
Proposed branch: lp:~alan-griffiths/mir/update-docs
Merge into: lp:mir
Diff against target: 756 lines (+282/-399)
10 files modified
HACKING.md (+1/-33)
doc/Doxyfile.in (+3/-1)
doc/building_source_for_pc.md (+0/-101)
doc/demo_server_controls.md (+0/-69)
doc/getting_and_using_mir.md (+106/-0)
doc/getting_involved_in_mir.md (+106/-0)
doc/installing_prebuilt_on_pc.md (+0/-8)
doc/introducing_the_miral_api.md (+25/-0)
doc/mainpage.md (+41/-96)
doc/using_mir_on_pc.md (+0/-91)
To merge this branch: bzr merge lp:~alan-griffiths/mir/update-docs
Reviewer Review Type Date Requested Status
Michał Sawicz 2017-09-07 Approve on 2017-09-08
Mir CI Bot continuous-integration Approve on 2017-09-07
Review via email: mp+330343@code.launchpad.net

Commit message

Updating docs (including integrating MirAL documentation)

To post a comment you must log in.
Alan Griffiths (alan-griffiths) wrote :

To test the generated docs:

$ make doc-show

Mir CI Bot (mir-ci-bot) wrote :

PASSED: Continuous integration, rev:4242
https://mir-jenkins.ubuntu.com/job/mir-ci/3640/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/4979
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/5207
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=artful/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=zesty/5195
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=artful/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=artful/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/5018/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial/5018
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial/5018/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/3640/rebuild

review: Approve (continuous-integration)
lp:~alan-griffiths/mir/update-docs updated on 2017-09-07
4244. By Chris Halse Rogers on 2017-09-07

First round of Wayland support

This is sufficient to
a) Not break unrelated tests, and
b) Provide enough protocol to run es2gears_wayland
c) Provide input support to Wayland clients.

Approved by Alan Griffiths, mir-ci-bot.

Michał Sawicz (saviq) wrote :

All good!

review: Approve
lp:~alan-griffiths/mir/update-docs updated on 2017-09-08
4245. By Alan Griffiths on 2017-09-08

Updating docs (including integrating MirAL documentation).

Approved by Michał Sawicz, mir-ci-bot.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file 'HACKING.md'
--- HACKING.md 2017-05-08 03:04:26 +0000
+++ HACKING.md 2017-09-07 10:01:02 +0000
@@ -1,38 +1,6 @@
1Mir hacking guide1Mir hacking guide
2=================2=================
33
4Getting Mir
5-----------
6
7If you're reading this file then you've probably solved this one. ;)
8
9However, for completeness Mir is a project on LaunchPad (https://launchpad.net/mir)
10to grab a copy use the command:
11
12 $ bzr branch lp:mir
13
14
15Getting dependencies
16--------------------
17To succesfully build Mir there are a few packages required:
18
19 $ apt-get install devscripts equivs cmake
20 $ mk-build-deps --install --tool "apt-get -y" --build-dep debian/control
21
22
23Building Mir
24-----------
25
26Mir is built using cmake. There are other options, but here's one way to
27build the system:
28
29 $ mkdir build
30 $ cd build
31 $ cmake ..
32 $ make -j 8
33 $ ctest
34
35
36Coding Mir4Coding Mir
37----------5----------
386
@@ -109,7 +77,7 @@
109you need to know to get it working, and also to prevent your existing X server77you need to know to get it working, and also to prevent your existing X server
110from dying at the same time.78from dying at the same time.
11179
112 - \ref using_mir_on_pc80 - \ref getting_and_using_mir
11381
114You can configure Mir to provide runtime information helpful for debugging82You can configure Mir to provide runtime information helpful for debugging
115by enabling component reports:83by enabling component reports:
11684
=== modified file 'doc/Doxyfile.in'
--- doc/Doxyfile.in 2017-08-25 10:02:30 +0000
+++ doc/Doxyfile.in 2017-09-07 10:01:02 +0000
@@ -876,7 +876,9 @@
876# exclude all test directories for example use the pattern */test/*876# exclude all test directories for example use the pattern */test/*
877877
878EXCLUDE_PATTERNS = *.capnp.c++ \878EXCLUDE_PATTERNS = *.capnp.c++ \
879 */examples/multi_stream.cpp879 @CMAKE_CURRENT_SOURCE_DIR@/include/server/* \
880 @CMAKE_CURRENT_SOURCE_DIR@/include/test/mir/* \
881 @CMAKE_CURRENT_SOURCE_DIR@/examples/multi_stream.cpp
880882
881# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names883# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
882# (namespaces, classes, functions, etc.) that should be excluded from the884# (namespaces, classes, functions, etc.) that should be excluded from the
883885
=== removed file 'doc/building_source_for_pc.md'
--- doc/building_source_for_pc.md 2017-05-08 03:04:26 +0000
+++ doc/building_source_for_pc.md 1970-01-01 00:00:00 +0000
@@ -1,101 +0,0 @@
1Building the source for a PC {#building_source_for_pc}
2============================
3
4Getting Mir
5-----------
6
7Mir is a project on Launchpad (https://launchpad.net/mir). To grab a copy use
8the command:
9
10 $ bzr branch lp:mir
11
12The command above will download the latest development version of Mir into
13the 'mir' directory (called the 'project directory' from now on).
14
15Getting dependencies
16--------------------
17
18To succesfully build Mir there are a few packages required. The easiest way
19to get them is to use the packaging build dependencies:
20
21 $ sudo apt-get install devscripts equivs cmake
22
23Then, in the project directory:
24
25 $ sudo mk-build-deps -i
26
27
28Building Mir
29------------
30
31Mir is built using CMake. You first need to create the build directory and
32configure the build. In the project directory do:
33
34 $ mkdir build
35 $ cd build
36 $ cmake .. (possibly passing configuration options to CMake)
37
38There are many configuration options for the Mir project. The default options
39will work fine, but you may want to customize the build depending on your
40needs. The best way to get an overview and set them is to use the cmake-gui
41tool:
42
43 $ cmake-gui ..
44
45The next step is to build the source and run the tests:
46
47 $ make (-j8)
48 $ ctest
49
50
51Running Mir
52-----------
53
54The binaries created in the bin subdirectory of the project directory can be
55used directly. For example,
56
57 $ bin/mir_demo_server --launch-client bin/mir_demo_client_multiwin
58
59Other examples described elsewhere in this documentation assume you're using the
60installed version and simply need "bin/" adding to specify the local build.
61
62
63Install Mir
64-----------
65
66*It should not be necessary to install Mir for experimental purposes (see
67"Running Mir" above).* Further, if you are using an Ubuntu derived disto then
68there's likely to be existing Mir binaries elsewhere that may interact badly
69with a second install.
70
71To install Mir just use the normal make install command:
72
73 $ sudo make install
74
75This will install the Mir libraries, executable, example clients and header
76files to the configured installation location (/usr/local by default).
77
78NB You may need "sudo ldconfig" to refresh the cache before the installed
79programs work.
80
81If you install to a non-standard location, keep in mind that you will probably
82need to properly set the PKG_CONFIG_PATH environment variable to allow other
83applications to build against Mir, and LD_LIBRARY_PATH to allow applications to
84find the Mir libraries at runtime.
85
86
87Building Mesa
88-------------
89
90*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
91and should work out of the box with Mir.*
92
93For GL accelerated clients to use Mir they need to use a patched version of Mesa
94that supports Mir.
95
96The patch is hosted on GitHub:
97
98 $ git clone https://github.com/RAOF/mesa.git
99
100Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
101the configure options. You will need libmirclient installed as shown above.
1020
=== removed file 'doc/demo_server_controls.md'
--- doc/demo_server_controls.md 2017-05-08 03:04:26 +0000
+++ doc/demo_server_controls.md 1970-01-01 00:00:00 +0000
@@ -1,69 +0,0 @@
1Demo Server {#demo_server}
2===========
3
4Mir's demo server (`mir_demo_server`) is an example of using the Mir to
5build a server. It uses only functionality supported by the public Mir API.
6
7Running Demo Server
8-------------------
9
10Remember to always run `mir_demo_server` as root on PC (not required on
11Android), as this is required for input device support (open bug
12https://bugs.launchpad.net/mir/+bug/1286252);
13
14 sudo mir_demo_server
15
16And if you're not already on the VT you wish to use, that needs to be
17specified:
18
19 sudo mir_demo_server --vt 1
20
21There are plenty more options available if you run:
22
23 mir_demo_server --help
24
25The following operations are supported:
26
27 - Quit (shut down the Mir server): *Ctrl-Alt-Backspace*
28 - Switch back to X: *Ctrl-Alt-F7*
29 - Switch virtual terminals (VTs): *Ctrl-Alt-(F1-F12)*
30 - Switch apps: *Alt-Tab*, tap or click on the corresponding app
31 - Close app: *Alt-F4*
32 - Switch window within app: *Alt-`*, tap or click on the window
33 - Close surface: *Ctrl-F4*
34 - Move window: *Alt-leftmousebutton* drag
35 - Resize window: *Alt-middle_button* drag
36 - Maximize/restore current window: *Alt-F11*
37 - Vertically maximize/restore current window: *Shift-F11*
38 - Horizontally maximize/restore current window: *Ctrl-F11*
39
40For those writing client code request to set the surface attribute
41`mir_surface_attrib_state` are honoured:
42 - `mir_window_state_restored`: restores the window
43 - `mir_window_state_maximized`: maximizes size
44 - `mir_window_state_vertmaximized`: maximizes height
45 - `mir_window_state_horizmaximized`: maximizes width
46
47For a quick demo try:
48
49 sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
50 --test-client bin/mir_demo_client_multiwin --test-timeout 60
51
52(Remember to unwrap the line)
53
54### Tiling Window Manager
55
56One option that needs elaboration is "--window-manager tiling".
57
58This starts a (rather primitive) tiling window manager. It tracks the available
59displays and splits the available workspace into "tiles" (one per client).
60
61For a quick demo try:
62
63 sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
64 --test-client bin/mir_demo_client_multiwin --test-timeout 60\
65 --window-manager tiling
66
67(Remember to unwrap the line)
68
69Want more? Log your requests at: https://bugs.launchpad.net/mir/+filebug
700
=== added file 'doc/getting_and_using_mir.md'
--- doc/getting_and_using_mir.md 1970-01-01 00:00:00 +0000
+++ doc/getting_and_using_mir.md 2017-09-07 10:01:02 +0000
@@ -0,0 +1,106 @@
1Getting and Using Mir {#getting_and_using_mir}
2=====================
3
4Getting Mir examples
5--------------------
6
7You can install the Mir examples as follows:
8
9 $ sudo apt install mir-demos qterminal
10 $ sudo apt install mir-graphics-drivers-desktop qtubuntu-desktop
11
12Using Mir examples
13------------------
14
15For convenient testing there's a "miral-app" script that wraps the commands used
16to start a server and then launches a terminal (as the current user):
17
18 $ miral-app
19
20To run independently of X11 you need to grant access to the graphics hardware
21(by running as root) and specify a VT to run in. There's a "miral-desktop"
22script that wraps to start the server (as root) and then launch a terminal
23(as the current user):
24
25 $ miral-desktop
26
27For more options see *Options when running the Mir example shell* below.
28
29### Running applications on Mir
30
31If you use the command-line launched by miral-app or miral-desktop native Mir
32applications (which include native Mir clients and those that use SDL or the
33GTK+, Qt toolkits) can be started as usual:
34
35 $ mir_demo_client_egltriangle
36 $ gedit
37 $ sudo apt install kate neverball
38 $ kate
39 $ neverball
40
41From outside the MirAL session GTK+, Qt and SDL applications can still be run
42using the miral-run script:
43
44 $ miral-run gedit
45 $ miral-run 7kaa
46
47### Running for X11 applications
48
49If you want to run X11 applications that do not have native Mir support in the
50toolkit they use then the answer is Xmir: an X11 server that runs on Mir. First
51you need Xmir installed:
52
53 $ sudo apt install xmir
54
55Then once you have started a miral shell (as above) you can use miral-xrun to
56run applications under Xmir:
57
58 $ miral-xrun firefox
59
60This automatically starts a Xmir X11 server on a new $DISPLAY for the
61application to use. You can use miral-xrun both from a command-line outside the
62miral-shell or, for example, from the terminal running in the shell.
63
64### Options when running the Mir example shell
65
66#### Script Options
67
68Both the "miral-app" and "miral-desktop" scripts provide options for using an
69alternative example shell (miral-kiosk) and an alternative to gnome-terminal.
70
71 -kiosk use miral-kiosk instead of miral-shell
72 -launcher <launcher> use <launcher> instead of qterminal
73
74In addition miral-desktop has the option to set the VT that is used:
75
76 -vt <termid> set the virtual terminal [4]
77
78There are some additional options (listed with "-h") but those are the important
79ones.
80
81#### miral-shell Options
82
83The scripts can also be used to pass options to Mir: they pass everything on
84the command-line following the first thing they don't understand. These can be
85listed by `miral-shell --help`. Most of these options are inherited from Mir,
86but the following MirAL specific are likely to be of interest:
87
88 --window-management-trace log trace message
89
90Probably the main use for MirAL is to test window-management (either of a
91toolkit or of a server) and this logs all calls to and from the window
92management policy. This option is supported directly in the MirAL library and
93works for any MirAL based shell - even one you write yourself.
94
95 --keymap arg (=us) keymap <layout>[+<variant>[+<options>]]
96 , e,g, "gb" or "cz+qwerty" or
97 "de++compose:caps"
98
99For those of us not in the USA this is very useful. Both the -shell and -kiosk
100examples support this option.
101
102 --window-manager arg (=floating) window management strategy
103 [{floating|tiling|system-compositor}]
104
105Is only supported by miral-shell and its main use is to allow an alternative
106"tiling" window manager to be selected.
0107
=== added file 'doc/getting_involved_in_mir.md'
--- doc/getting_involved_in_mir.md 1970-01-01 00:00:00 +0000
+++ doc/getting_involved_in_mir.md 2017-09-07 10:01:02 +0000
@@ -0,0 +1,106 @@
1Getting Involved in Mir {#getting_involved_in_mir}
2=======================
3
4Getting involved
5----------------
6
7The best place to ask questions and discuss about the Mir project is
8the \#ubuntu-mir IRC channel on freenode.
9
10The Mir project is hosted on Launchpad: https://launchpad.net/mir
11
12Building Mir
13------------
14
15These instructions assume that you’re using Ubuntu 16.04LTS or later, I’ve not
16earlier Ubuntu versions or other distributions.
17
18You’ll need a few development and utility packages installed, along with the
19Mir graphics drivers:
20
21 $ sudo apt install devscripts equivs bzr
22 $ sudo apt install mir-graphics-drivers-desktop
23
24If you’re working on a phone or tablet use mir-graphics-drivers-android in
25place of mir-graphics-drivers-desktop. (See \ref building_source_for_arm for
26more on this.)
27
28With these installed you can checkout and build Mir:
29
30 $ bzr branch lp:mir
31 $ sudo mk-build-deps -i
32 $ mkdir mir/build
33 $ cd mir/build
34 $ cmake ..
35 $ make
36
37This creates an example shell (miral-shell) in the bin directory. This can be
38run directly:
39
40 $ bin/miral-shell
41
42With the default options this runs in a window on X (which is convenient for
43development).
44
45The miral-shell example is simple, don’t expect to see a sophisticated launcher
46by default. You can start mir apps from the command-line. For example:
47
48 $ bin/miral-run gnome-terminal
49
50That’s right, a lot of standard GTK+ applications will “just work” (the GDK
51toolkit has a Mir backend). Any that assume the existence of an X11 and bypass
52the toolkit my making X11 protocol calls will have problems though.
53
54To exit from miral-shell press Ctrl-Alt-BkSp.
55
56You can install the Mir examples, headers and libraries you've built with:
57
58 $ sudo make install
59
60### Preparing a VM to run Mir
61
62Especially if you want to debug the shell without locking your system this might be a helpful setup:
63
64- \ref setup_kvm_for_mir
65- \ref setup_vmware_for_mir
66
67### Contributing to Mir
68
69Currently, the Mir code activity is performed on a development branch:
70lp:~mir-team/mir/development-branch
71
72This development branch is promoted to the branch used for the ubuntu archive
73and touch images. Please submit any merge proposals against the development
74branch.
75
76Please file bug reports at: https://bugs.launchpad.net/mir
77
78The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
79
80The Mir coding guidelines are [here](cppguide/index.html).
81
82### Working on Mir code
83
84 - \ref md_README "Mir Read me"
85 - \ref md_HACKING "Mir hacking guide"
86 - \ref component_reports
87 - \ref dso_versioning_guide
88 - \ref abi_compatibility_tools
89 - \ref performance_framework
90 - \ref latency "Measuring visual latency"
91
92Building Mesa
93-------------
94
95*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
96and should work out of the box with Mir.*
97
98For GL accelerated clients to use Mir they need to use a patched version of Mesa
99that supports Mir.
100
101The patch is hosted on GitHub:
102
103 $ git clone https://github.com/RAOF/mesa.git
104
105Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
106the configure options. You will need libmirclient installed as shown above.
0107
=== removed file 'doc/installing_prebuilt_on_pc.md'
--- doc/installing_prebuilt_on_pc.md 2016-01-29 08:18:22 +0000
+++ doc/installing_prebuilt_on_pc.md 1970-01-01 00:00:00 +0000
@@ -1,8 +0,0 @@
1Installing pre-built packages on a PC {#installing_prebuilt_on_pc}
2=====================================
3
4Install Ubuntu 13.10 or later if you haven't done so already. Uninstall any
5proprietary drivers (-nvidia, -fglrx) and reboot on the FOSS drivers.
6
7 sudo apt-get update
8 sudo apt-get install mir-demos
90
=== added file 'doc/introducing_the_miral_api.md'
--- doc/introducing_the_miral_api.md 1970-01-01 00:00:00 +0000
+++ doc/introducing_the_miral_api.md 2017-09-07 10:01:02 +0000
@@ -0,0 +1,25 @@
1Introducing the Miral API {#introducing_the_miral_api}
2=========================
3
4The main() program
5------------------
6
7The main() program from miral-shell looks like this:
8
9\include shell_main.cpp
10
11This shell is providing FloatingWindowManagerPolicy, TilingWindowManagerPolicy
12and SpinnerSplash. The rest is from MirAL.
13
14If you look for the corresponding code in lp:qtmir and lp:mir you’ll find it
15less clear, more verbose and scattered over multiple files.
16
17A shell has to provide a window management policy (miral-shell provides two:
18FloatingWindowManagerPolicy and TilingWindowManagerPolicy). A window management
19policy needs to implement the \ref miral::WindowManagementPolicy interface for
20handling a set of window management events.
21
22The way these events are handled determines the behaviour of the shell.
23
24The \ref miral::WindowManagerTools interface provides the principle methods for
25a window management policy to control Mir.
026
=== modified file 'doc/mainpage.md'
--- doc/mainpage.md 2017-09-06 11:04:56 +0000
+++ doc/mainpage.md 2017-09-07 10:01:02 +0000
@@ -3,103 +3,48 @@
33
4Mir is a next generation display server targeted as a replacement for the X4Mir is a next generation display server targeted as a replacement for the X
5window server system to unlock next-generation user experiences for devices5window server system to unlock next-generation user experiences for devices
6ranging from Linux desktop to mobile devices powered by Ubuntu. The primary6ranging from Linux desktop to mobile and IoT devices powered by Ubuntu.
7purpose of Mir is to enable the development of the next generation7
8[Unity](http://unity.ubuntu.com).8 - If you just want to try out the Mir demos, see: \ref getting_and_using_mir
9
10 - If you want to get involved in Mir development, see: \ref getting_involved_in_mir
11
12Using Mir for client development
13--------------------------------
14
15Install the headers and libraries for using libmirclient in development:
16
17 $ sudo apt install libmirclient-dev
18
19A `miral.pc` file is provided for use with `pkg-config` or other tools. For
20example:
21
22 $ pkg-config --cflags mirclient
23
24The client API documentation is here: \ref mir_toolkit
25
26Using Mir for server development
27--------------------------------
28
29Install the headers and libraries for using libmiral in development:
30
31 $ sudo apt install libmirserver-dev
32
33A `miral.pc` file is provided for use with `pkg-config` or other tools. For
34example:
35
36 $ pkg-config --cflags miral
37
38The server API is introduced here: \ref introducing_the_miral_api
39
40The Mir Documentation
41---------------------
42
43The Mir documentation can be installed and read like this:
44
45 $ sudo apt install mir-doc
46 $ xdg-open /usr/share/doc/mir-doc/html/index.html
947
10More detailed information about the motivation, scope, and high-level design48More detailed information about the motivation, scope, and high-level design
11of Mir can be found at http://wiki.ubuntu.com/MirSpec .49of Mir can be found at http://wiki.ubuntu.com/MirSpec .
1250
13Getting and installing Mir
14--------------------------
15
16### Using pre-built packages
17
18If you just want to try out mir, or write client applications, then the easiest
19way is to use the pre-built packages:
20
21 - \ref installing_prebuilt_on_pc
22
23### Building and installing from source
24
25If you are curious about Mir internals or intend to contribute to it, you should
26get the source and build it:
27
28 - \ref building_source_for_pc
29 - \ref building_source_for_arm
30
31### Preparing a VM to run Mir
32
33Especially if you want to debug the shell without locking your system this might be a helpful setup:
34
35- \ref setup_kvm_for_mir
36- \ref setup_vmware_for_mir
37
38Using Mir
39---------
40
41 - \ref using_mir_on_pc
42 - \ref demo_server
43
44Getting involved
45----------------
46
47The best place to ask questions and discuss about the Mir project is
48the \#ubuntu-mir IRC channel on freenode.
49
50The Mir project is hosted on Launchpad: https://launchpad.net/mir
51
52Currently, the Mir code activity is performed on a development branch:
53lp:~mir-team/mir/development-branch
54
55Approximately fortnightly, this development branch is promoted to the branch
56used for the ubuntu archive and touch images. Please submit any merge proposals
57against the development branch.
58
59Please file bug reports at: https://bugs.launchpad.net/mir
60
61The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
62
63The Mir coding guidelines are [here](cppguide/index.html).
64
65Writing client applications
66---------------------------
67
68 - \ref mir_toolkit "Mir API Documentation"
69 - \subpage basic.c "basic.c: A basic Mir client (which does nothing)"
70
71Writing server applications
72---------------------------
73
74Mir server is written as a library which allows the server code to be adapted
75for bespoke applications.
76
77 - \subpage server_example.cpp
78 "server_example.cpp: a test executable hosting the following"
79 - \subpage server_example_input_event_filter.cpp
80 "server_example_input_event_filter.cpp: provide a Quit command"
81 - \subpage server_example_display_configuration_policy.cpp
82 "server_example_display_configuration_policy.cpp: configuring display layout"
83 - \subpage server_example_input_filter.cpp
84 "server_example_input_filter.cpp: print input events to stdout"
85 - \subpage server_example_log_options.cpp
86 "server_example_log_options.cpp: replace Mir logger with glog"
87 - \subpage server_example_basic_window_manager.h
88 "server_example_basic_window_manager.h: How to wire up a window manager"
89 - \subpage server_example_window_management.cpp
90 "server_example_window_management.cpp: simple window management examples"
91 - \subpage server_example_canonical_window_manager.cpp
92 "server_example_canonical_window_manager.cpp: canonical window management policy"
93 - \subpage server_example_custom_compositor.cpp
94 "server_example_custom_compositor.cpp: demonstrate writing an alternative GL rendering code"
95
96Working on Mir code
97-------------------
98
99 - \ref md_README "Mir Read me"
100 - \ref md_HACKING "Mir hacking guide"
101 - \ref component_reports
102 - \ref dso_versioning_guide
103 - \ref abi_compatibility_tools
104 - \ref performance_framework
105 - \ref latency "Measuring visual latency"
10651
=== removed file 'doc/using_mir_on_pc.md'
--- doc/using_mir_on_pc.md 2016-01-29 08:18:22 +0000
+++ doc/using_mir_on_pc.md 1970-01-01 00:00:00 +0000
@@ -1,91 +0,0 @@
1Using Mir on a PC {#using_mir_on_pc}
2=================
3
4Before you begin
5----------------
6
7Make sure your hardware is supported. That means you're using a Mesa driver,
8of which intel, radeon, and nouveau families are supported. If you're logged
9in to X then run this command to verify an appropriate DRI driver is active:
10
11 sudo pmap `pidof X` | grep dri.so
12
13or
14
15 lsmod | grep drm
16
17Before you can use Mir you need to ensure you have the proper custom Mesa
18build installed. If you are running Ubuntu 13.10 or later
19(see \ref installing_prebuilt_on_pc), you should be good to go.
20
21If you built Mir from source code (see \ref building_source_for_pc), you
22need to ensure you are using the proper Mesa at runtime. You can do that by
23installing the Mesa packages from Ubuntu 13.10 (or later) or by building the
24custom Mesa yourself and ensuring it can be found by Mir, e.g., by using
25`LD_LIBRARY_PATH`.
26
27### Getting some example client applications
28
29You can get some example programs by installing the `mir-demos` package:
30
31 $ sudo apt-get install mir-demos
32
33If you are building from source you can find client applications in the `bin/`
34subdirectory of the build directory.
35
36Running Mir
37-----------
38
39Mir can run run either natively on mesa-kms or as an X application.
40
41### Running Mir on X
42
43To run Mir as an X client start it from an X terminal:
44
45 $ mir_demo_server --launch-client mir_demo_client_multiwin
46
47You can start additional Mir clients, for example (in a new terminal):
48
49 $ mir_demo_egltriangle
50
51To exit from Mir:
52
53 <Ctrl+Alt+BkSp>
54
55Note: up to Mir 0.18 it is also necessary to specify `--platform-input-lib` when
56starting the server:
57 - for Mir-0.17 add: `--platform-input-lib server-mesa-x11.so.6`
58 - for Mir-0.18 add: `--platform-input-lib server-mesa-x11.so.7`
59
60### Running Mir natively
61
62To run Mir natively on a PC/desktop/laptop:
63
64 $ sudo DISPLAY= mir_demo_server --vt 1 --arw-file
65
66This will switch you to a Mir session on VT1. Switch back to your X-based
67desktop:
68
69 <Ctrl+Alt+F7>
70
71In a new terminal:
72
73 $ mir_demo_client_multiwin -m /tmp/mir_socket
74
75Switch back to Mir.
76
77 <Ctrl+Alt+F1>
78
79Watch your friends be amazed!
80
81To exit from Mir:
82
83 <Ctrl+Alt+BkSp>
84
85In case you accidentally killed your X login and ended up with a failsafe
86screen, you might find on subsequent reboots you can't log in to X at all any
87more (it instantly and silently takes you back to the login screen). The fix
88for this is to log in to a VT and:
89
90 $ rm .Xauthority
91 $ sudo restart lightdm

Subscribers

People subscribed via source and target branches