diff options
Diffstat (limited to 'doc/HACKING/HelpfulTools.md')
| -rw-r--r-- | doc/HACKING/HelpfulTools.md | 130 |
1 files changed, 80 insertions, 50 deletions
diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md index 15bd153318..0ce59576f0 100644 --- a/doc/HACKING/HelpfulTools.md +++ b/doc/HACKING/HelpfulTools.md @@ -43,7 +43,9 @@ Builds should show up on the web at jenkins.torproject.org and on IRC at ## Valgrind - valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor +```console +$ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/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 @@ -77,10 +79,12 @@ we wish to permit are also documented in the blacklist file. 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 +```console +$ ./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 @@ -93,36 +97,48 @@ investigated (as of July 2014). To quickly run all the tests distributed with Tor: - make check +```console +$ make check +``` To run the fast unit tests only: - make test +```console +$ make test +``` To selectively run just some tests (the following can be combined arbitrarily): - ./src/test/test <name_of_test> [<name of test 2>] ... - ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ... - ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]... +```console +$ ./src/test/test <name_of_test> [<name of test 2>] ... +$ ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ... +$ ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]... +``` To run all tests, including those based on Stem or Chutney: - make test-full +```console +$ make test-full +``` To run all tests, including those based on Stem or Chutney that require a working connection to the internet: - make test-full-online +```console +$ make test-full-online +``` ## Running gcov for unit test coverage - ./configure --enable-coverage - make - make check - # or--- make test-full ? make test-full-online? - mkdir coverage-output - ./scripts/test/coverage coverage-output +```console +$ ./configure --enable-coverage +$ make +$ make check +$ # or--- make test-full ? make test-full-online? +$ mkdir coverage-output +$ ./scripts/test/coverage coverage-output +``` (On OSX, you'll need to start with `--enable-coverage CC=clang`.) @@ -145,7 +161,9 @@ you can run `make reset-gcov` to clear the intermediary gcov output. If you have two different `coverage-output` directories, and you want to see a meaningful diff between them, you can run: - ./scripts/test/cov-diff coverage-output1 coverage-output2 | less +```console +$ ./scripts/test/cov-diff coverage-output1 coverage-output2 | less +``` In this diff, any lines that were visited at least once will have coverage "1", and line numbers are deleted. This lets you inspect what you (probably) really @@ -313,12 +331,16 @@ that you're using the emacs-specific version of `etags` (bundled under the If you're using vim or emacs, you can also use Universal Ctags to build a tag file using the syntax: - ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' . +```console +$ ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' . +``` If you're using an older version of Universal Ctags, you can use the following instead: - ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' . +```console +ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' . +``` A vim-compatible tag file will be generated by default. If you use emacs, add the `-e` flag to generate an emacs-compatible tag file. @@ -330,50 +352,58 @@ source code. Here's how to use it: 1. Begin every file that should be documented with - /** - * \file filename.c - * \brief Short description of the file. - */ +``` + /** + * \file filename.c + * \brief Short description of the file. + */ +``` - (Doxygen will recognize any comment beginning with /** as special.) + (Doxygen will recognize any comment beginning with /** as special.) 2. Before any function, structure, #define, or variable you want to document, add a comment of the form: - /** Describe the function's actions in imperative sentences. - * - * Use blank lines for paragraph breaks - * - and - * - hyphens - * - for - * - lists. - * - * Write <b>argument_names</b> in boldface. - * - * \code - * place_example_code(); - * between_code_and_endcode_commands(); - * \endcode - */ +``` +/** Describe the function's actions in imperative sentences. + * + * Use blank lines for paragraph breaks + * - and + * - hyphens + * - for + * - lists. + * + * Write <b>argument_names</b> 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. */ - }; +```c +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 +```console +$ doxygen -g +``` - to generate a file called `Doxyfile`. Edit that file and run - `doxygen` to generate the API documentation. + 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. |