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
1=== modified file 'HACKING.md'
2--- HACKING.md 2017-05-08 03:04:26 +0000
3+++ HACKING.md 2017-09-07 10:01:02 +0000
4@@ -1,38 +1,6 @@
5 Mir hacking guide
6 =================
7
8-Getting Mir
9------------
10-
11-If you're reading this file then you've probably solved this one. ;)
12-
13-However, for completeness Mir is a project on LaunchPad (https://launchpad.net/mir)
14-to grab a copy use the command:
15-
16- $ bzr branch lp:mir
17-
18-
19-Getting dependencies
20---------------------
21-To succesfully build Mir there are a few packages required:
22-
23- $ apt-get install devscripts equivs cmake
24- $ mk-build-deps --install --tool "apt-get -y" --build-dep debian/control
25-
26-
27-Building Mir
28------------
29-
30-Mir is built using cmake. There are other options, but here's one way to
31-build the system:
32-
33- $ mkdir build
34- $ cd build
35- $ cmake ..
36- $ make -j 8
37- $ ctest
38-
39-
40 Coding Mir
41 ----------
42
43@@ -109,7 +77,7 @@
44 you need to know to get it working, and also to prevent your existing X server
45 from dying at the same time.
46
47- - \ref using_mir_on_pc
48+ - \ref getting_and_using_mir
49
50 You can configure Mir to provide runtime information helpful for debugging
51 by enabling component reports:
52
53=== modified file 'doc/Doxyfile.in'
54--- doc/Doxyfile.in 2017-08-25 10:02:30 +0000
55+++ doc/Doxyfile.in 2017-09-07 10:01:02 +0000
56@@ -876,7 +876,9 @@
57 # exclude all test directories for example use the pattern */test/*
58
59 EXCLUDE_PATTERNS = *.capnp.c++ \
60- */examples/multi_stream.cpp
61+ @CMAKE_CURRENT_SOURCE_DIR@/include/server/* \
62+ @CMAKE_CURRENT_SOURCE_DIR@/include/test/mir/* \
63+ @CMAKE_CURRENT_SOURCE_DIR@/examples/multi_stream.cpp
64
65 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
66 # (namespaces, classes, functions, etc.) that should be excluded from the
67
68=== removed file 'doc/building_source_for_pc.md'
69--- doc/building_source_for_pc.md 2017-05-08 03:04:26 +0000
70+++ doc/building_source_for_pc.md 1970-01-01 00:00:00 +0000
71@@ -1,101 +0,0 @@
72-Building the source for a PC {#building_source_for_pc}
73-============================
74-
75-Getting Mir
76------------
77-
78-Mir is a project on Launchpad (https://launchpad.net/mir). To grab a copy use
79-the command:
80-
81- $ bzr branch lp:mir
82-
83-The command above will download the latest development version of Mir into
84-the 'mir' directory (called the 'project directory' from now on).
85-
86-Getting dependencies
87---------------------
88-
89-To succesfully build Mir there are a few packages required. The easiest way
90-to get them is to use the packaging build dependencies:
91-
92- $ sudo apt-get install devscripts equivs cmake
93-
94-Then, in the project directory:
95-
96- $ sudo mk-build-deps -i
97-
98-
99-Building Mir
100-------------
101-
102-Mir is built using CMake. You first need to create the build directory and
103-configure the build. In the project directory do:
104-
105- $ mkdir build
106- $ cd build
107- $ cmake .. (possibly passing configuration options to CMake)
108-
109-There are many configuration options for the Mir project. The default options
110-will work fine, but you may want to customize the build depending on your
111-needs. The best way to get an overview and set them is to use the cmake-gui
112-tool:
113-
114- $ cmake-gui ..
115-
116-The next step is to build the source and run the tests:
117-
118- $ make (-j8)
119- $ ctest
120-
121-
122-Running Mir
123------------
124-
125-The binaries created in the bin subdirectory of the project directory can be
126-used directly. For example,
127-
128- $ bin/mir_demo_server --launch-client bin/mir_demo_client_multiwin
129-
130-Other examples described elsewhere in this documentation assume you're using the
131-installed version and simply need "bin/" adding to specify the local build.
132-
133-
134-Install Mir
135------------
136-
137-*It should not be necessary to install Mir for experimental purposes (see
138-"Running Mir" above).* Further, if you are using an Ubuntu derived disto then
139-there's likely to be existing Mir binaries elsewhere that may interact badly
140-with a second install.
141-
142-To install Mir just use the normal make install command:
143-
144- $ sudo make install
145-
146-This will install the Mir libraries, executable, example clients and header
147-files to the configured installation location (/usr/local by default).
148-
149-NB You may need "sudo ldconfig" to refresh the cache before the installed
150-programs work.
151-
152-If you install to a non-standard location, keep in mind that you will probably
153-need to properly set the PKG_CONFIG_PATH environment variable to allow other
154-applications to build against Mir, and LD_LIBRARY_PATH to allow applications to
155-find the Mir libraries at runtime.
156-
157-
158-Building Mesa
159--------------
160-
161-*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
162-and should work out of the box with Mir.*
163-
164-For GL accelerated clients to use Mir they need to use a patched version of Mesa
165-that supports Mir.
166-
167-The patch is hosted on GitHub:
168-
169- $ git clone https://github.com/RAOF/mesa.git
170-
171-Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
172-the configure options. You will need libmirclient installed as shown above.
173
174=== removed file 'doc/demo_server_controls.md'
175--- doc/demo_server_controls.md 2017-05-08 03:04:26 +0000
176+++ doc/demo_server_controls.md 1970-01-01 00:00:00 +0000
177@@ -1,69 +0,0 @@
178-Demo Server {#demo_server}
179-===========
180-
181-Mir's demo server (`mir_demo_server`) is an example of using the Mir to
182-build a server. It uses only functionality supported by the public Mir API.
183-
184-Running Demo Server
185--------------------
186-
187-Remember to always run `mir_demo_server` as root on PC (not required on
188-Android), as this is required for input device support (open bug
189-https://bugs.launchpad.net/mir/+bug/1286252);
190-
191- sudo mir_demo_server
192-
193-And if you're not already on the VT you wish to use, that needs to be
194-specified:
195-
196- sudo mir_demo_server --vt 1
197-
198-There are plenty more options available if you run:
199-
200- mir_demo_server --help
201-
202-The following operations are supported:
203-
204- - Quit (shut down the Mir server): *Ctrl-Alt-Backspace*
205- - Switch back to X: *Ctrl-Alt-F7*
206- - Switch virtual terminals (VTs): *Ctrl-Alt-(F1-F12)*
207- - Switch apps: *Alt-Tab*, tap or click on the corresponding app
208- - Close app: *Alt-F4*
209- - Switch window within app: *Alt-`*, tap or click on the window
210- - Close surface: *Ctrl-F4*
211- - Move window: *Alt-leftmousebutton* drag
212- - Resize window: *Alt-middle_button* drag
213- - Maximize/restore current window: *Alt-F11*
214- - Vertically maximize/restore current window: *Shift-F11*
215- - Horizontally maximize/restore current window: *Ctrl-F11*
216-
217-For those writing client code request to set the surface attribute
218-`mir_surface_attrib_state` are honoured:
219- - `mir_window_state_restored`: restores the window
220- - `mir_window_state_maximized`: maximizes size
221- - `mir_window_state_vertmaximized`: maximizes height
222- - `mir_window_state_horizmaximized`: maximizes width
223-
224-For a quick demo try:
225-
226- sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
227- --test-client bin/mir_demo_client_multiwin --test-timeout 60
228-
229-(Remember to unwrap the line)
230-
231-### Tiling Window Manager
232-
233-One option that needs elaboration is "--window-manager tiling".
234-
235-This starts a (rather primitive) tiling window manager. It tracks the available
236-displays and splits the available workspace into "tiles" (one per client).
237-
238-For a quick demo try:
239-
240- sudo DISPLAY= mir_demo_server --vt 1 --launch bin/mir_demo_client_egltriangle\
241- --test-client bin/mir_demo_client_multiwin --test-timeout 60\
242- --window-manager tiling
243-
244-(Remember to unwrap the line)
245-
246-Want more? Log your requests at: https://bugs.launchpad.net/mir/+filebug
247
248=== added file 'doc/getting_and_using_mir.md'
249--- doc/getting_and_using_mir.md 1970-01-01 00:00:00 +0000
250+++ doc/getting_and_using_mir.md 2017-09-07 10:01:02 +0000
251@@ -0,0 +1,106 @@
252+Getting and Using Mir {#getting_and_using_mir}
253+=====================
254+
255+Getting Mir examples
256+--------------------
257+
258+You can install the Mir examples as follows:
259+
260+ $ sudo apt install mir-demos qterminal
261+ $ sudo apt install mir-graphics-drivers-desktop qtubuntu-desktop
262+
263+Using Mir examples
264+------------------
265+
266+For convenient testing there's a "miral-app" script that wraps the commands used
267+to start a server and then launches a terminal (as the current user):
268+
269+ $ miral-app
270+
271+To run independently of X11 you need to grant access to the graphics hardware
272+(by running as root) and specify a VT to run in. There's a "miral-desktop"
273+script that wraps to start the server (as root) and then launch a terminal
274+(as the current user):
275+
276+ $ miral-desktop
277+
278+For more options see *Options when running the Mir example shell* below.
279+
280+### Running applications on Mir
281+
282+If you use the command-line launched by miral-app or miral-desktop native Mir
283+applications (which include native Mir clients and those that use SDL or the
284+GTK+, Qt toolkits) can be started as usual:
285+
286+ $ mir_demo_client_egltriangle
287+ $ gedit
288+ $ sudo apt install kate neverball
289+ $ kate
290+ $ neverball
291+
292+From outside the MirAL session GTK+, Qt and SDL applications can still be run
293+using the miral-run script:
294+
295+ $ miral-run gedit
296+ $ miral-run 7kaa
297+
298+### Running for X11 applications
299+
300+If you want to run X11 applications that do not have native Mir support in the
301+toolkit they use then the answer is Xmir: an X11 server that runs on Mir. First
302+you need Xmir installed:
303+
304+ $ sudo apt install xmir
305+
306+Then once you have started a miral shell (as above) you can use miral-xrun to
307+run applications under Xmir:
308+
309+ $ miral-xrun firefox
310+
311+This automatically starts a Xmir X11 server on a new $DISPLAY for the
312+application to use. You can use miral-xrun both from a command-line outside the
313+miral-shell or, for example, from the terminal running in the shell.
314+
315+### Options when running the Mir example shell
316+
317+#### Script Options
318+
319+Both the "miral-app" and "miral-desktop" scripts provide options for using an
320+alternative example shell (miral-kiosk) and an alternative to gnome-terminal.
321+
322+ -kiosk use miral-kiosk instead of miral-shell
323+ -launcher <launcher> use <launcher> instead of qterminal
324+
325+In addition miral-desktop has the option to set the VT that is used:
326+
327+ -vt <termid> set the virtual terminal [4]
328+
329+There are some additional options (listed with "-h") but those are the important
330+ones.
331+
332+#### miral-shell Options
333+
334+The scripts can also be used to pass options to Mir: they pass everything on
335+the command-line following the first thing they don't understand. These can be
336+listed by `miral-shell --help`. Most of these options are inherited from Mir,
337+but the following MirAL specific are likely to be of interest:
338+
339+ --window-management-trace log trace message
340+
341+Probably the main use for MirAL is to test window-management (either of a
342+toolkit or of a server) and this logs all calls to and from the window
343+management policy. This option is supported directly in the MirAL library and
344+works for any MirAL based shell - even one you write yourself.
345+
346+ --keymap arg (=us) keymap <layout>[+<variant>[+<options>]]
347+ , e,g, "gb" or "cz+qwerty" or
348+ "de++compose:caps"
349+
350+For those of us not in the USA this is very useful. Both the -shell and -kiosk
351+examples support this option.
352+
353+ --window-manager arg (=floating) window management strategy
354+ [{floating|tiling|system-compositor}]
355+
356+Is only supported by miral-shell and its main use is to allow an alternative
357+"tiling" window manager to be selected.
358
359=== added file 'doc/getting_involved_in_mir.md'
360--- doc/getting_involved_in_mir.md 1970-01-01 00:00:00 +0000
361+++ doc/getting_involved_in_mir.md 2017-09-07 10:01:02 +0000
362@@ -0,0 +1,106 @@
363+Getting Involved in Mir {#getting_involved_in_mir}
364+=======================
365+
366+Getting involved
367+----------------
368+
369+The best place to ask questions and discuss about the Mir project is
370+the \#ubuntu-mir IRC channel on freenode.
371+
372+The Mir project is hosted on Launchpad: https://launchpad.net/mir
373+
374+Building Mir
375+------------
376+
377+These instructions assume that you’re using Ubuntu 16.04LTS or later, I’ve not
378+earlier Ubuntu versions or other distributions.
379+
380+You’ll need a few development and utility packages installed, along with the
381+Mir graphics drivers:
382+
383+ $ sudo apt install devscripts equivs bzr
384+ $ sudo apt install mir-graphics-drivers-desktop
385+
386+If you’re working on a phone or tablet use mir-graphics-drivers-android in
387+place of mir-graphics-drivers-desktop. (See \ref building_source_for_arm for
388+more on this.)
389+
390+With these installed you can checkout and build Mir:
391+
392+ $ bzr branch lp:mir
393+ $ sudo mk-build-deps -i
394+ $ mkdir mir/build
395+ $ cd mir/build
396+ $ cmake ..
397+ $ make
398+
399+This creates an example shell (miral-shell) in the bin directory. This can be
400+run directly:
401+
402+ $ bin/miral-shell
403+
404+With the default options this runs in a window on X (which is convenient for
405+development).
406+
407+The miral-shell example is simple, don’t expect to see a sophisticated launcher
408+by default. You can start mir apps from the command-line. For example:
409+
410+ $ bin/miral-run gnome-terminal
411+
412+That’s right, a lot of standard GTK+ applications will “just work” (the GDK
413+toolkit has a Mir backend). Any that assume the existence of an X11 and bypass
414+the toolkit my making X11 protocol calls will have problems though.
415+
416+To exit from miral-shell press Ctrl-Alt-BkSp.
417+
418+You can install the Mir examples, headers and libraries you've built with:
419+
420+ $ sudo make install
421+
422+### Preparing a VM to run Mir
423+
424+Especially if you want to debug the shell without locking your system this might be a helpful setup:
425+
426+- \ref setup_kvm_for_mir
427+- \ref setup_vmware_for_mir
428+
429+### Contributing to Mir
430+
431+Currently, the Mir code activity is performed on a development branch:
432+lp:~mir-team/mir/development-branch
433+
434+This development branch is promoted to the branch used for the ubuntu archive
435+and touch images. Please submit any merge proposals against the development
436+branch.
437+
438+Please file bug reports at: https://bugs.launchpad.net/mir
439+
440+The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
441+
442+The Mir coding guidelines are [here](cppguide/index.html).
443+
444+### Working on Mir code
445+
446+ - \ref md_README "Mir Read me"
447+ - \ref md_HACKING "Mir hacking guide"
448+ - \ref component_reports
449+ - \ref dso_versioning_guide
450+ - \ref abi_compatibility_tools
451+ - \ref performance_framework
452+ - \ref latency "Measuring visual latency"
453+
454+Building Mesa
455+-------------
456+
457+*The Mesa packages shipped with Ubuntu are already built with the relevant Mir patches
458+and should work out of the box with Mir.*
459+
460+For GL accelerated clients to use Mir they need to use a patched version of Mesa
461+that supports Mir.
462+
463+The patch is hosted on GitHub:
464+
465+ $ git clone https://github.com/RAOF/mesa.git
466+
467+Compile as per normal instructions and pass --with-egl-platforms="mir,drm" to
468+the configure options. You will need libmirclient installed as shown above.
469
470=== removed file 'doc/installing_prebuilt_on_pc.md'
471--- doc/installing_prebuilt_on_pc.md 2016-01-29 08:18:22 +0000
472+++ doc/installing_prebuilt_on_pc.md 1970-01-01 00:00:00 +0000
473@@ -1,8 +0,0 @@
474-Installing pre-built packages on a PC {#installing_prebuilt_on_pc}
475-=====================================
476-
477-Install Ubuntu 13.10 or later if you haven't done so already. Uninstall any
478-proprietary drivers (-nvidia, -fglrx) and reboot on the FOSS drivers.
479-
480- sudo apt-get update
481- sudo apt-get install mir-demos
482
483=== added file 'doc/introducing_the_miral_api.md'
484--- doc/introducing_the_miral_api.md 1970-01-01 00:00:00 +0000
485+++ doc/introducing_the_miral_api.md 2017-09-07 10:01:02 +0000
486@@ -0,0 +1,25 @@
487+Introducing the Miral API {#introducing_the_miral_api}
488+=========================
489+
490+The main() program
491+------------------
492+
493+The main() program from miral-shell looks like this:
494+
495+\include shell_main.cpp
496+
497+This shell is providing FloatingWindowManagerPolicy, TilingWindowManagerPolicy
498+and SpinnerSplash. The rest is from MirAL.
499+
500+If you look for the corresponding code in lp:qtmir and lp:mir you’ll find it
501+less clear, more verbose and scattered over multiple files.
502+
503+A shell has to provide a window management policy (miral-shell provides two:
504+FloatingWindowManagerPolicy and TilingWindowManagerPolicy). A window management
505+policy needs to implement the \ref miral::WindowManagementPolicy interface for
506+handling a set of window management events.
507+
508+The way these events are handled determines the behaviour of the shell.
509+
510+The \ref miral::WindowManagerTools interface provides the principle methods for
511+a window management policy to control Mir.
512
513=== modified file 'doc/mainpage.md'
514--- doc/mainpage.md 2017-09-06 11:04:56 +0000
515+++ doc/mainpage.md 2017-09-07 10:01:02 +0000
516@@ -3,103 +3,48 @@
517
518 Mir is a next generation display server targeted as a replacement for the X
519 window server system to unlock next-generation user experiences for devices
520-ranging from Linux desktop to mobile devices powered by Ubuntu. The primary
521-purpose of Mir is to enable the development of the next generation
522-[Unity](http://unity.ubuntu.com).
523+ranging from Linux desktop to mobile and IoT devices powered by Ubuntu.
524+
525+ - If you just want to try out the Mir demos, see: \ref getting_and_using_mir
526+
527+ - If you want to get involved in Mir development, see: \ref getting_involved_in_mir
528+
529+Using Mir for client development
530+--------------------------------
531+
532+Install the headers and libraries for using libmirclient in development:
533+
534+ $ sudo apt install libmirclient-dev
535+
536+A `miral.pc` file is provided for use with `pkg-config` or other tools. For
537+example:
538+
539+ $ pkg-config --cflags mirclient
540+
541+The client API documentation is here: \ref mir_toolkit
542+
543+Using Mir for server development
544+--------------------------------
545+
546+Install the headers and libraries for using libmiral in development:
547+
548+ $ sudo apt install libmirserver-dev
549+
550+A `miral.pc` file is provided for use with `pkg-config` or other tools. For
551+example:
552+
553+ $ pkg-config --cflags miral
554+
555+The server API is introduced here: \ref introducing_the_miral_api
556+
557+The Mir Documentation
558+---------------------
559+
560+The Mir documentation can be installed and read like this:
561+
562+ $ sudo apt install mir-doc
563+ $ xdg-open /usr/share/doc/mir-doc/html/index.html
564
565 More detailed information about the motivation, scope, and high-level design
566 of Mir can be found at http://wiki.ubuntu.com/MirSpec .
567
568-Getting and installing Mir
569---------------------------
570-
571-### Using pre-built packages
572-
573-If you just want to try out mir, or write client applications, then the easiest
574-way is to use the pre-built packages:
575-
576- - \ref installing_prebuilt_on_pc
577-
578-### Building and installing from source
579-
580-If you are curious about Mir internals or intend to contribute to it, you should
581-get the source and build it:
582-
583- - \ref building_source_for_pc
584- - \ref building_source_for_arm
585-
586-### Preparing a VM to run Mir
587-
588-Especially if you want to debug the shell without locking your system this might be a helpful setup:
589-
590-- \ref setup_kvm_for_mir
591-- \ref setup_vmware_for_mir
592-
593-Using Mir
594----------
595-
596- - \ref using_mir_on_pc
597- - \ref demo_server
598-
599-Getting involved
600-----------------
601-
602-The best place to ask questions and discuss about the Mir project is
603-the \#ubuntu-mir IRC channel on freenode.
604-
605-The Mir project is hosted on Launchpad: https://launchpad.net/mir
606-
607-Currently, the Mir code activity is performed on a development branch:
608-lp:~mir-team/mir/development-branch
609-
610-Approximately fortnightly, this development branch is promoted to the branch
611-used for the ubuntu archive and touch images. Please submit any merge proposals
612-against the development branch.
613-
614-Please file bug reports at: https://bugs.launchpad.net/mir
615-
616-The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
617-
618-The Mir coding guidelines are [here](cppguide/index.html).
619-
620-Writing client applications
621----------------------------
622-
623- - \ref mir_toolkit "Mir API Documentation"
624- - \subpage basic.c "basic.c: A basic Mir client (which does nothing)"
625-
626-Writing server applications
627----------------------------
628-
629-Mir server is written as a library which allows the server code to be adapted
630-for bespoke applications.
631-
632- - \subpage server_example.cpp
633- "server_example.cpp: a test executable hosting the following"
634- - \subpage server_example_input_event_filter.cpp
635- "server_example_input_event_filter.cpp: provide a Quit command"
636- - \subpage server_example_display_configuration_policy.cpp
637- "server_example_display_configuration_policy.cpp: configuring display layout"
638- - \subpage server_example_input_filter.cpp
639- "server_example_input_filter.cpp: print input events to stdout"
640- - \subpage server_example_log_options.cpp
641- "server_example_log_options.cpp: replace Mir logger with glog"
642- - \subpage server_example_basic_window_manager.h
643- "server_example_basic_window_manager.h: How to wire up a window manager"
644- - \subpage server_example_window_management.cpp
645- "server_example_window_management.cpp: simple window management examples"
646- - \subpage server_example_canonical_window_manager.cpp
647- "server_example_canonical_window_manager.cpp: canonical window management policy"
648- - \subpage server_example_custom_compositor.cpp
649- "server_example_custom_compositor.cpp: demonstrate writing an alternative GL rendering code"
650-
651-Working on Mir code
652--------------------
653-
654- - \ref md_README "Mir Read me"
655- - \ref md_HACKING "Mir hacking guide"
656- - \ref component_reports
657- - \ref dso_versioning_guide
658- - \ref abi_compatibility_tools
659- - \ref performance_framework
660- - \ref latency "Measuring visual latency"
661
662=== removed file 'doc/using_mir_on_pc.md'
663--- doc/using_mir_on_pc.md 2016-01-29 08:18:22 +0000
664+++ doc/using_mir_on_pc.md 1970-01-01 00:00:00 +0000
665@@ -1,91 +0,0 @@
666-Using Mir on a PC {#using_mir_on_pc}
667-=================
668-
669-Before you begin
670-----------------
671-
672-Make sure your hardware is supported. That means you're using a Mesa driver,
673-of which intel, radeon, and nouveau families are supported. If you're logged
674-in to X then run this command to verify an appropriate DRI driver is active:
675-
676- sudo pmap `pidof X` | grep dri.so
677-
678-or
679-
680- lsmod | grep drm
681-
682-Before you can use Mir you need to ensure you have the proper custom Mesa
683-build installed. If you are running Ubuntu 13.10 or later
684-(see \ref installing_prebuilt_on_pc), you should be good to go.
685-
686-If you built Mir from source code (see \ref building_source_for_pc), you
687-need to ensure you are using the proper Mesa at runtime. You can do that by
688-installing the Mesa packages from Ubuntu 13.10 (or later) or by building the
689-custom Mesa yourself and ensuring it can be found by Mir, e.g., by using
690-`LD_LIBRARY_PATH`.
691-
692-### Getting some example client applications
693-
694-You can get some example programs by installing the `mir-demos` package:
695-
696- $ sudo apt-get install mir-demos
697-
698-If you are building from source you can find client applications in the `bin/`
699-subdirectory of the build directory.
700-
701-Running Mir
702------------
703-
704-Mir can run run either natively on mesa-kms or as an X application.
705-
706-### Running Mir on X
707-
708-To run Mir as an X client start it from an X terminal:
709-
710- $ mir_demo_server --launch-client mir_demo_client_multiwin
711-
712-You can start additional Mir clients, for example (in a new terminal):
713-
714- $ mir_demo_egltriangle
715-
716-To exit from Mir:
717-
718- <Ctrl+Alt+BkSp>
719-
720-Note: up to Mir 0.18 it is also necessary to specify `--platform-input-lib` when
721-starting the server:
722- - for Mir-0.17 add: `--platform-input-lib server-mesa-x11.so.6`
723- - for Mir-0.18 add: `--platform-input-lib server-mesa-x11.so.7`
724-
725-### Running Mir natively
726-
727-To run Mir natively on a PC/desktop/laptop:
728-
729- $ sudo DISPLAY= mir_demo_server --vt 1 --arw-file
730-
731-This will switch you to a Mir session on VT1. Switch back to your X-based
732-desktop:
733-
734- <Ctrl+Alt+F7>
735-
736-In a new terminal:
737-
738- $ mir_demo_client_multiwin -m /tmp/mir_socket
739-
740-Switch back to Mir.
741-
742- <Ctrl+Alt+F1>
743-
744-Watch your friends be amazed!
745-
746-To exit from Mir:
747-
748- <Ctrl+Alt+BkSp>
749-
750-In case you accidentally killed your X login and ended up with a failsafe
751-screen, you might find on subsequent reboots you can't log in to X at all any
752-more (it instantly and silently takes you back to the login screen). The fix
753-for this is to log in to a VT and:
754-
755- $ rm .Xauthority
756- $ sudo restart lightdm

Subscribers

People subscribed via source and target branches