ubuntu-location-service  ..
An aggregating location service providing positioning and geocoding capabilities to applications.
/build/location-service-TMZAp2/location-service-3.0.0+16.10.20160613.1/doc/hacking.md
Go to the documentation of this file.
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.