System Requirements
------------------------------------------------------------
The following dependencies are necessary to build kudu:

- gcc 4.4 or higher
- boost >= 1.41, including the following components:
  - boost::filesystem
  - boost::thread
  - boost::system
- cmake 2.8.7
- libssl-dev (Ubuntu) or openssl-devel (CentOS)
- libsasl2-dev (Ubuntu) or cyrus-sasl-devel (CentOS)

Earlier versions of each of these may work, but have not recently
been tested.

Download and build thirdparty dependencies
------------------------------------------------------------
$ thirdparty/build-if-necessary.sh

This downloads and builds the thirdparty dependencies and installs them into
thirdparty/installed/. The script is also invoked by cmake, so new thirdparty
dependencies added by other developers will be downloaded and built
automatically in subsequent builds.

If you are looking to manually run the protobuf compiler, the pprof tool,
etc, you can find these in thirdparty/installed/bin/


Building kudu
------------------------------------------------------------

# Add <root of kudu tree>/thirdparty/installed/bin to your $PATH
# before other parts of $PATH that may contain cmake, such as /usr/bin
# e.g. "export PATH=$HOME/git/kudu/thirdparty/installed/bin:$PATH"
# if using bash
$ cmake .
$ make -j4
$ make test  # or, to run tests in parallel, ctest -j8 (for 8-way parallelism)

The build artifacts, including the test binaries, will be stored in
'build/latest/', which itself is a symlink to either build/debug or
build/release.


Running tests with the clang AddressSanitizer enabled
------------------------------------------------------------

AddressSanitizer is a nice clang feature which can detect many types of memory
errors. The Jenkins setup for kudu runs these tests automatically on a regular
basis, but if you make large changes it can be a good idea to run it locally
before pushing. To do so, you'll need a local install of clang.

$ rm -Rf CMakeCache.txt CMakeFiles/
$ CC=clang CXX=clang++ cmake -DKUDU_USE_ASAN=1 .   # or whatever your path to clang++
$ make -j
$ make test

The tests will run significantly slower than without ASAN enabled, and if any
memory error occurs, the test that triggered it will fail. You can then use a
command like:

$ build/latest/failing-test 2>&1 | asan_symbolize.py | c++filt | less

to get a proper symbolized stack trace. The asan_symbolize program can be found
in the llvm source distribution:
https://llvm.org/svn/llvm-project/compiler-rt/trunk/lib/asan/scripts/asan_symbolize.py

For more information on AddressSanitizer, please see:
  http://clang.llvm.org/docs/AddressSanitizer.html


Running tests with the clang Undefined Behavior Sanitizer (UBSAN) enabled
------------------------------------------------------------

Similar to the above, you can use a special set of clang flags to enable the Undefined
Behavior Sanitizer. This will generate errors on certain pieces of code which may
not themselves crash but rely on behavior which isn't defined by the C++ standard
(and thus are likely bugs).

You'll need at least clang 3.3 to use this feature.

$ rm -Rf CMakeCache.txt CMakeFiles/
$ CC=clang CXX=clang++ cmake -DKUDU_USE_UBSAN=1 .   # or whatever your path to clang++
$ make -j
$ make test

In order to get a stack trace from UBSan, you can use gdb on the failing test, and
set a breakpoint as follows:

(gdb) b __ubsan::Diag::~Diag

Then, when the breakpoint fires, gather a backtrace as usual using 'bt'.


Running tests with the tcmalloc memory leak checker enabled
------------------------------------------------------------

You can also run the tests with a tcmalloc feature that prints an error message
and aborts if it detects memory leaks in your program.

$ rm -Rf CMakeCache.txt CMakeFiles/
$ cmake .
$ make -j
$ # Note: LP_BIND_NOW=1 required below, see: https://code.google.com/p/gperftools/issues/detail?id=497
$ PPROF_PATH=thirdparty/installed/bin/pprof HEAPCHECK=normal LD_BIND_NOW=1 ctest -j8

For more information on the heap checker, please see:
  http://google-perftools.googlecode.com/svn/trunk/doc/heap_checker.html

NOTE: The AddressSanitizer doesn't play nice with tcmalloc, so sadly the
HEAPCHECK environment has no effect if you have enabled ASAN.


Running tests with ThreadSanitizer enabled
------------------------------------------------------------
NOTE: this requires a relatively recent version of clang++, and may also require
a relatively recent version of libstdc++ on your system. It seems to work reasonably
well on Ubuntu 13.10, but YMMV.

$ rm -Rf CMakeCache.txt CMakeFiles/
$ CC=clang CXX=clang++ cmake . -DKUDU_USE_TSAN=1
$ make -j
$ ctest -j8

Note that we rely on a list of runtime suppressions in build-support/tsan-suppressions.txt.
If you simply run a unit test like build/latest/foo-test, you won't get these suppressions.
Instead, use a command like:

$ ctest -R foo-test

and then view the logs in build/test-logs/

In order for all of the suppressions to work, you need libraries with debug
symbols installed, particularly for libstdc++. On Ubuntu 13.10, the package
libstdc++6-4.8-dbg is needed for tsan builds to pass. It's not a bad idea to
install debug symbol packages for libboost, libc, and cyrus-sasl as well.

TSAN may truncate a few lines of the stack trace when reporting where the error
is. This can be bewildering. It's documented for TSANv1 here:
http://code.google.com/p/data-race-test/wiki/ThreadSanitizerAlgorithm
It is not mentioned in the documentation for TSANv2, but has been observed.
In order to find out what is _really_ happening, set a breakpoint on the TSAN
report in GDB using the following incantation:

gdb -ex 'set disable-randomization off' -ex 'b __tsan::PrintReport' ./some-test


Generating code coverage reports
------------------------------------------------------------

In order to generate a code coverage report, you must build with gcc (not clang)
and use the following flags:

$ cmake -DKUDU_GENERATE_COVERAGE=1 .
$ make clean
$ make -j4
$ ctest -j4

This will generate the code coverage files with extensions .gcno and .gcda. You can then
use a tool like lcov or gcovr to visualize the results. For example, using gcovr:

$ mkdir cov_html
$ ./thirdparty/gcovr-3.0/scripts/gcovr -r src/

Or using lcov (which seems to produce better HTML output):

$ lcov  --capture --directory src --output-file coverage.info
$ genhtml coverage.info --output-directory out


Running lint checks
------------------------------------------------------------

Kudu uses cpplint.py from Google to enforce coding style guidelines. You can run the
lint checks via cmake using the 'lint' target:

$ make lint

This may take quite some time, as it scans every file in the source tree. For local
development, it's often more convenient to only check the files which you've modified.
For this you can use the 'ilint' target:

$ make ilint

This will scan any file which is dirty in your working tree, or changed since the last
gerrit-integrated upstream change in your git log.