Useful tools ------------ These aren't strictly necessary for hacking on Tor, but they can help track down bugs. Jenkins ~~~~~~~ https://jenkins.torproject.org Dmalloc ~~~~~~~ The dmalloc library will keep track of memory allocation, so you can find out if we're leaking memory, doing any double-frees, or so on. dmalloc -l ~/dmalloc.log (run the commands it tells you) ./configure --with-dmalloc Valgrind ~~~~~~~~ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor (Note that if you get a zillion openssl warnings, you will also need to pass --undef-value-errors=no to valgrind, or rebuild your openssl with -DPURIFY.) Coverity ~~~~~~~~ Nick regularly runs the coverity static analyzer on the Tor codebase. The preprocessor define __COVERITY__ is used to work around instances where coverity picks up behavior that we wish to permit. clang Static Analyzer ~~~~~~~~~~~~~~~~~~~~~ The clang static analyzer can be run on the Tor codebase using Xcode (WIP) or a command-line build. The preprocessor define __clang_analyzer__ is used to work around instances where clang picks up behavior that we wish to permit. clang Runtime Sanitizers ~~~~~~~~~~~~~~~~ To build the Tor codebase with the clang Address and Undefined Behavior sanitizers, see the file contrib/clang/sanitize_blacklist.txt. Preprocessor workarounds for instances where clang picks up behavior that we wish to permit are also documented in the blacklist file. Running lcov for unit test coverage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lcov is a utility that generates pretty HTML reports of test code coverage. To generate such a report: ----- ./configure --enable-coverage make make coverage-html $BROWSER ./coverage_html/index.html ----- This will run the tor unit test suite `./src/test/test` and generate the HTML coverage code report under the directory ./coverage_html/. To change the output directory, use `make coverage-html HTML_COVER_DIR=./funky_new_cov_dir`. Coverage diffs using lcov are not currently implemented, but are being investigated (as of July 2014). Running the unit tests ~~~~~~~~~~~~~~~~~~~~~~ To quickly run all the tests distributed with Tor: ----- make check ----- To run the fast unit tests only: ----- make test ----- To selectively run just some tests (the following can be combined arbitrarily): ----- ./src/test/test [] ... ./src/test/test .. [..] ... ./src/test/test : [:argument_names in boldface. * * \code * place_example_code(); * between_code_and_endcode_commands(); * \endcode */ 3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<", "\>", "\\", "\%", and "\#". 4. To document structure members, you can use two forms: struct foo { /** You can put the comment before an element; */ int a; int b; /**< Or use the less-than symbol to put the comment * after the element. */ }; 5. To generate documentation from the Tor source code, type: $ doxygen -g To generate a file called 'Doxyfile'. Edit that file and run 'doxygen' to generate the API documentation. 6. See the Doxygen manual for more information; this summary just scratches the surface.