197.1.2
by Alan Griffiths
More docs |
1 |
Mir hacking guide
|
2 |
=================
|
|
3 |
||
636.1.3
by Alan Griffiths
Tidy up |
4 |
Getting Mir
|
446.2.2
by Alan Griffiths
A bit more HACKING |
5 |
-----------
|
6 |
||
7 |
If you're reading this file then you've probably solved this one. ;) |
|
8 |
||
636.1.3
by Alan Griffiths
Tidy up |
9 |
However, for completeness Mir is a project on LaunchPad (https://launchpad.net/mir) |
446.2.2
by Alan Griffiths
A bit more HACKING |
10 |
to grab a copy use the command: |
11 |
||
12 |
$ bzr branch lp:mir
|
|
13 |
||
14 |
||
432.2.1
by brendan-donegan
Added Getting dependencies section to HACKING.md |
15 |
Getting dependencies
|
16 |
--------------------
|
|
17 |
To succesfully build Mir there are a few packages required: |
|
18 |
||
432.2.2
by brendan-donegan
Added devscripts to the list of dependencies in HACKING.md |
19 |
$ apt-get install devscripts equivs cmake
|
446.2.2
by Alan Griffiths
A bit more HACKING |
20 |
$ mk-build-deps --install --tool "apt-get -y" --build-dep debian/control
|
21 |
||
432.2.1
by brendan-donegan
Added Getting dependencies section to HACKING.md |
22 |
|
636.1.3
by Alan Griffiths
Tidy up |
23 |
Building Mir
|
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
24 |
-----------
|
197.1.2
by Alan Griffiths
More docs |
25 |
|
26 |
Mir is built using cmake. There are other options, but here's one way to |
|
27 |
build the system: |
|
28 |
||
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
29 |
$ mkdir build
|
30 |
$ cd build
|
|
31 |
$ cmake ..
|
|
32 |
$ make -j 8
|
|
33 |
$ ctest
|
|
197.1.2
by Alan Griffiths
More docs |
34 |
|
35 |
||
636.1.3
by Alan Griffiths
Tidy up |
36 |
Coding Mir
|
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
37 |
----------
|
197.1.2
by Alan Griffiths
More docs |
38 |
|
39 |
There's a coding style guide in the guides subdirectory. To build it into an |
|
40 |
html file: |
|
41 |
||
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
42 |
$ make guides
|
43 |
||
636.1.2
by Alan Griffiths
Tidy up |
44 |
(Or if you're reading the web version [here](cppguide/index.html)). |
45 |
||
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
46 |
|
47 |
Code structure
|
|
48 |
--------------
|
|
197.1.2
by Alan Griffiths
More docs |
49 |
|
203.3.1
by Alan Griffiths
More HACKING notes |
50 |
Code structure: include |
51 |
||
52 |
The include subdirectory contains header files "published" by corresponding parts |
|
53 |
of the system. For example, include/mir/option/option.h provides a system-wide interface |
|
54 |
for accessing runtime options published by the options component. |
|
55 |
||
463.3.1
by Bryce Harrington
Remove redundant 'the' |
56 |
In many cases, there will be interfaces defined that are used by the component |
203.3.1
by Alan Griffiths
More HACKING notes |
57 |
and implemented elsewhere. E.g. the compositor uses RenderView which is implemented |
58 |
by the surfaces component. |
|
59 |
||
60 |
Files under the include directory should contain minimal implementation detail: interfaces |
|
61 |
should not expose platform or implementation technology types etc. (And as public methods |
|
62 |
are normally implementations of interfaces they do not use these types.) |
|
63 |
||
64 |
||
65 |
Code structure: src |
|
66 |
||
636.1.3
by Alan Griffiths
Tidy up |
67 |
This comprises the implementation of Mir. Header files for use within the component |
203.3.2
by Alan Griffiths
Correct gibberish |
68 |
should be put here. The only headers from the source tree that should be included are |
69 |
ones from the current component (ones that do not require a path component). |
|
203.3.1
by Alan Griffiths
More HACKING notes |
70 |
|
71 |
||
72 |
Code structure: test |
|
73 |
||
74 |
This contains unit, integration and acceptance tests written using gtest/gmock. Tests |
|
203.3.4
by Alan Griffiths
typo |
75 |
largely depend upon the public interfaces of components - but tests of units within |
203.3.3
by Alan Griffiths
Correct gibberish |
76 |
a component will include headers from within the source tree. |
203.3.1
by Alan Griffiths
More HACKING notes |
77 |
|
78 |
||
79 |
Code structure: 3rd_party |
|
80 |
||
636.1.3
by Alan Griffiths
Tidy up |
81 |
Third party code imported into our source tree for use in Mir. We try not to change |
203.3.1
by Alan Griffiths
More HACKING notes |
82 |
anything to avoid maintaining a fork. |
83 |
||
84 |
||
163.3.192
by Kevin DuBois
cleanups (revert to base branch for a lot of files) |
85 |
Error handling strategy
|
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
86 |
-----------------------
|
163.3.192
by Kevin DuBois
cleanups (revert to base branch for a lot of files) |
87 |
|
88 |
If a function cannot meet its post-conditions it throws an exception and meets |
|
89 |
AT LEAST the basic exception safety guarantee. It is a good idea to document the |
|
90 |
strong and no-throw guarantees. http://www.boost.org/community/exception_safety.html |
|
91 |
||
747.1.2
by Alan Griffiths
Some documentation on preconditions |
92 |
A function is not required to check its preconditions (there should be no |
93 |
tests that preconditions failures are reported). This means that |
|
94 |
preconditions may be verified using the "assert" macro - which may or may |
|
95 |
not report problems (depending upon the NDEBUG define). |
|
96 |
||
97 |
||
98 |
Implicit rules
|
|
99 |
--------------
|
|
100 |
||
101 |
There are a lot of pointers (mostly smart, but a few raw ones) passed |
|
102 |
around in the code. We have adopted the general rule that pointers are |
|
103 |
expected to refer to valid objects. This avoids repetitive tests for |
|
104 |
validity. Unless otherwise documented functions and constructors that |
|
105 |
take pointer parameters have validity of the referenced objects as a |
|
106 |
precondition. Exceptions to the rule must be of limited scope and |
|
107 |
documented. |
|
108 |
||
163.3.192
by Kevin DuBois
cleanups (revert to base branch for a lot of files) |
109 |
|
429.1.1
by Daniel van Vugt
Document some tips and tricks for running Mir locally, on a single machine, |
110 |
Running Mir
|
111 |
-----------
|
|
112 |
||
662.1.1
by Alan Griffiths
Dedup conflicting information |
113 |
There are some brief guides describing how to run the Mir binaries once you have |
429.1.1
by Daniel van Vugt
Document some tips and tricks for running Mir locally, on a single machine, |
114 |
them built. You might think it's obvious but there are some important things |
115 |
you need to know to get it working, and also to prevent your existing X server |
|
116 |
from dying at the same time. |
|
117 |
||
662.1.1
by Alan Griffiths
Dedup conflicting information |
118 |
- \ref using_mir_on_pc
|
119 |
- \ref using_mir_on_android
|
|
429.1.1
by Daniel van Vugt
Document some tips and tricks for running Mir locally, on a single machine, |
120 |
|
716.1.2
by Alexandros Frantzis
doc: Add documentation for component reports |
121 |
You can configure Mir to provide runtime information helpful for debugging |
122 |
by enabling component reports: |
|
123 |
||
124 |
- \ref component_reports
|
|
429.1.1
by Daniel van Vugt
Document some tips and tricks for running Mir locally, on a single machine, |
125 |
|
197.1.2
by Alan Griffiths
More docs |
126 |
Documentation
|
324.2.1
by Alan Griffiths
Add README and HACKING to doxygen input |
127 |
-------------
|
197.1.2
by Alan Griffiths
More docs |
128 |
|
129 |
There are design notes and an architecture diagram (.dia) in the design |
|
130 |
subdirectory. |
|
131 |
||
132 |