← Back to branch summary

~thomas-voss/location-service/generalize-glue-code-for-agps-operation

« back to all changes in this revision

Viewing changes to doc/hacking.md

  • Committer: thomas-voss
  • Date: 2015-02-02 15:05:32 UTC
  • mto: This revision was merged to the branch mainline in revision 196.
  • Revision ID: thomas.voss@canonical.com-20150202150532-9jm6l7ctsey92zka
Add documentation for debugging, hacking and debugging the location service.
Pull manual testing instructions over from the wiki.
Add tools for formatting the source.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/hacking.md
 
1
# Hacking
 
2
 
 
3
 
 
4
## Building the code
 
5
 
 
6
By default, the code is built in release mode. To build a debug version, use
 
7
 
 
8
    $ mkdir builddebug
 
9
    $ cd builddebug
 
10
    $ cmake -DCMAKE_BUILD_TYPE=debug ..
 
11
    $ make
 
12
 
 
13
For a release version, use -DCMAKE_BUILD_TYPE=release
 
14
 
 
15
## Running the tests
 
16
 
 
17
    $ make
 
18
    $ make test
 
19
 
 
20
Note that "make test" alone is dangerous because it does not rebuild
 
21
any tests if either the library or the test files themselves need
 
22
rebuilding. It's not possible to fix this with cmake because cmake cannot
 
23
add build dependencies to built-in targets. To make sure that everything
 
24
is up-to-date, run "make" before running "make test"!
 
25
 
 
26
## Coverage
 
27
 
 
28
To build with the flags for coverage testing enabled and get coverage:
 
29
 
 
30
    $ mkdir buildcoverage
 
31
    $ cd buildcoverage
 
32
    $ cmake -DCMAKE_BUILD_TYPE=coverage
 
33
    $ make
 
34
    $ make test
 
35
    $ make coverage
 
36
 
 
37
Unfortunately, it is not possible to get 100% coverage for some files,
 
38
mainly due to gcc's generation of two destructors for dynamic and non-
 
39
dynamic instances. For abstract base classes and for classes that
 
40
prevent stack and static allocation, this causes one of the destructors
 
41
to be reported as uncovered.
 
42
 
 
43
There are also issues with some functions in header files that are
 
44
incorrectly reported as uncovered due to inlining, as well as
 
45
the impossibility of covering defensive assert(false) statements,
 
46
such as an assert in the default branch of a switch, where the
 
47
switch is meant to handle all possible cases explicitly.
 
48
 
 
49
If you run a binary and get lots of warnings about a "merge mismatch for summaries",
 
50
this is caused by having made changes to the source that add or remove code
 
51
that was previously run, so the new coverage output cannot sensibly be merged
 
52
into the old coverage output. You can get rid of this problem by running
 
53
 
 
54
    $ make clean-coverage
 
55
 
 
56
This deletes all the .gcda files, allowing the merge to (sometimes) succeed again.
 
57
If this doesn't work either, the only remedy is to do a clean build.
 
58
 
 
59
If lcov complains about unrecognized lines involving '=====',
 
60
you can patch geninfo and gcovr as explained here:
 
61
 
 
62
https://bugs.launchpad.net/gcovr/+bug/1086695/comments/2
 
63
 
 
64
## Code style
 
65
 
 
66
We use a format tool that fixes a whole lot of issues
 
67
regarding code style. The formatting changes made by
 
68
the tool are generally sensible (even though they may not be your
 
69
personal preference in all cases). If there is a case where the formatting
 
70
really messes things up, consider re-arranging the code to avoid the problem.
 
71
The convenience of running the entire code base through the pretty-printer
 
72
far outweighs any minor glitches with pretty printing, and it means that
 
73
we get consistent code style for free, rather than endlessly having to
 
74
watch out for formatting issues during code reviews.
 
75
 
 
76
As of clang-format-3.7, you can use
 
77
 
 
78
    // clang-format off
 
79
    void    unformatted_code  ;
 
80
    // clang-format on
 
81
 
 
82
to suppress formatting for a section of code.
 
83
 
 
84
To format specific files:
 
85
 
 
86
    ${CMAKE_BINARY_DIR}/tools/formatcode x.cpp x.h
 
87
 
 
88
If no arguments are provided, formatcode reads stdin and writes
 
89
stdout, so you can easily pipe code into the tool from within an
 
90
editor. For example, to reformat the entire file in vi (assuming
 
91
${CMAKE_BINARY_DIR}/tools is in your PATH):
 
92
 
 
93
    1G!Gformatcode
 
94
 
 
95
To re-format all source and header files in the tree:
 
96
 
 
97
    $ make formatcode
 
98
 
 
99
## Thread and address sanitizer
 
100
 
 
101
Set SANITIZER to "thread" or "address" to build with the
 
102
corresponding sanitizer enabled.
 
103
 
 
104
## Updating symbols file
 
105
 
 
106
To easily spot new/removed/changed symbols in the library, the debian
 
107
package maintains a .symbols file that lists all exported symbols
 
108
present in the library .so. If you add new public symbols to the library,
 
109
it's necessary to refresh the symbols file, otherwise the package will
 
110
fail to build. The easiest way to do that is using bzr-builddeb:
 
111
 
 
112
    $ bzr bd -- -us -uc -j8  # Don't sign source package or changes file, 8 compiles in parallel
 
113
    $ # this will exit with an error if symbols file isn't up-to-date
 
114
    $ cd ../build-area/location-service-[version]
 
115
    $ ./obj-[arch]/tools/symbol_diff
 
116
 
 
117
This creates a diff of the symbols in /tmp/symbols.diff.
 
118
(The demangled symbols from the debian build are in ./new_symbols.)
 
119
 
 
120
Review any changes in /tmp/symbols.diff. If they are OK:
 
121
 
 
122
    $ cd -
 
123
    $ patch -p0 < /tmp/symbols.diff
 
124
 
 
125
## ABI compliance test
 
126
 
 
127
To use this, install abi-compliance-checker package from the archives.
 
128
 
 
129
You can use abi-compliance-checker to test whether a particular build
 
130
is ABI compatible with another build. The tool does some source-level
 
131
analysis in addition to checking library symbols, so it catches things
 
132
that are potentially dangerous, but won't be picked up by just looking
 
133
at the symbol table.
 
134
 
 
135
Assume you have built devel in src/devel, and you have a later build
 
136
in src/mybranch and want to check that mybranch is still compatible.
 
137
To run the compliance test:
 
138
 
 
139
    $ cd src
 
140
    $ abi-compliance-checker -lib libunity-scopes.so -old devel/build/test/abi-compliance/abi.xml -new mybranch/build/test/abi-compliance/abi.xml
 
141
 
 
142
The script will take about two minutes to run. Now point your browser at 
 
143
 
 
144
    src/compat_reports/libunity-scopes.so/[version]_to_[version]/compat_report.html
 
145
 
 
146
The report provides a nicely layed-out page with all the details.