HACKING

Building the code
-----------------

By default, the code is built in release mode. To build a debug version, use

    $ mkdir builddebug
    $ cd builddebug
    $ cmake -DCMAKE_BUILD_TYPE=debug ..
    $ make

For a release version, use -DCMAKE_BUILD_TYPE=release


Running the tests
-----------------

    $ make
    $ make test

Note that "make test" alone is dangerous because it does not rebuild
any tests if either the library or the test files themselves need
rebuilding. It's not possible to fix this with cmake because cmake cannot
add build dependencies to built-in targets. To make sure that everything
is up-to-date, run "make" before running "make test"!

To run the tests with valgrind:

    $ make valgrind

It doesn't make sense for some tests to run them with valgrind. For
example, the header compilation tests don't need valgrind because
we'd just be testing that Python doesn't leak. There are also some
tests that run too slow and time out under valgrind and, occasionally,
valgrind crashes for a particular test.

There are two ways to suppress tests:

You can add a test name to CTestCustom.cmake.in to suppress that
test completely. That makes sense for the header compilation tests,
for example.

If a specific test case in a test program causes a valgrind problem,
you can selectively disable a section of code like this:

    #include <valgrind/valgrind.h>

    if (!RUNNING_ON_VALGRIND)
    {
        // Code here crashes valgrind...
    }

That way, the test will still be run as part of the normal "make test"
target, but will be ommitted when running "make valgrind".


Coverage
--------

To build with the flags for coverage testing enabled and get coverage:

    $ mkdir buildcoverage
    $ cd buildcoverage
    $ cmake -DCMAKE_BUILD_TYPE=coverage
    $ make
    $ make test
    $ make coverage

Unfortunately, it is not possible to get 100% coverage for some files,
mainly due to gcc's generation of two destructors for dynamic and non-
dynamic instances. For abstract base classes and for classes that
prevent stack and static allocation, this causes one of the destructors
to be reported as uncovered.

There are also issues with some functions in header files that are
incorrectly reported as uncovered due to inlining, as well as
the impossibility of covering defensive assert(false) statements,
such as an assert in the default branch of a switch, where the
switch is meant to handle all possible cases explicitly.

If you run a binary and get lots of warnings about a "merge mismatch for summaries",
this is caused by having made changes to the source that add or remove code
that was previously run, so the new coverage output cannot sensibly be merged
into the old coverage output. You can get rid of this problem by running

    $ make clean-coverage

This deletes all the .gcda files, allowing the merge to (sometimes) succeed again.
If this doesn't work either, the only remedy is to do a clean build.


Code style
----------

Please maintain the existing coding style. For details
on the style, see lp:canonical-client-development-guidelines.

We use a format tool that fixes a whole lot of issues
regarding code style. See the HACKING file of lp:unity-scopes-api
for details on the tool.


Undefined behavior and address sanitizer
----------------------------------------

Set SANITIZER to "ub" or "address" to build with the
corresponding sanitizer enabled.

If a test runs too slowly under address sanitizer, you can
hide a section of code from address sanitzer with:

#if defined(__has_feature)
    #if !__has_feature(address_sanitizer)

    // Code here takes forever under address sanitizer...

    #endif
#endif