mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-06 19:41:15 +01:00
doc: Replace "underline" with "## Section name".
This approach doesn't require variable-length underlines.
This commit is contained in:
Bartosz Duszel
+21
-40
@@ -1,11 +1,10 @@
|
||||
Useful tools
|
||||
============
|
||||
# Useful tools
|
||||
|
||||
These aren't strictly necessary for hacking on Tor, but they can help track
|
||||
down bugs.
|
||||
|
||||
Travis/Appveyor CI
|
||||
------------------
|
||||
## Travis/Appveyor CI
|
||||
|
||||
It's CI.
|
||||
|
||||
Looks like this:
|
||||
@@ -29,8 +28,7 @@ for your fork to build commits outside of PRs too:
|
||||
Builds should show up on the web at travis-ci.com and on IRC at #tor-ci on
|
||||
OFTC. If they don't, ask #tor-dev (also on OFTC).
|
||||
|
||||
Jenkins
|
||||
-------
|
||||
## Jenkins
|
||||
|
||||
It's CI/builders. Looks like this: https://jenkins.torproject.org
|
||||
|
||||
@@ -43,8 +41,7 @@ Builds Linux and Windows cross-compilation. Runs Linux tests.
|
||||
Builds should show up on the web at jenkins.torproject.org and on IRC at
|
||||
#tor-bots on OFTC. If they don't, ask #tor-dev (also on OFTC).
|
||||
|
||||
Valgrind
|
||||
--------
|
||||
## Valgrind
|
||||
|
||||
valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor
|
||||
|
||||
@@ -52,16 +49,14 @@ Valgrind
|
||||
pass `--undef-value-errors=no` to valgrind, or rebuild your openssl
|
||||
with `-DPURIFY`.)
|
||||
|
||||
Coverity
|
||||
--------
|
||||
## 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
|
||||
---------------------
|
||||
## clang Static Analyzer
|
||||
|
||||
The clang static analyzer can be run on the Tor codebase using Xcode (WIP)
|
||||
or a command-line build.
|
||||
@@ -69,8 +64,7 @@ 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
|
||||
------------------------
|
||||
## clang Runtime Sanitizers
|
||||
|
||||
To build the Tor codebase with the clang Address and Undefined Behavior
|
||||
sanitizers, see the file `contrib/clang/sanitize_blacklist.txt`.
|
||||
@@ -78,8 +72,7 @@ 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
|
||||
-----------------------------------
|
||||
## Running lcov for unit test coverage
|
||||
|
||||
Lcov is a utility that generates pretty HTML reports of test code coverage.
|
||||
To generate such a report:
|
||||
@@ -96,8 +89,7 @@ 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
|
||||
----------------------
|
||||
## Running the unit tests
|
||||
|
||||
To quickly run all the tests distributed with Tor:
|
||||
|
||||
@@ -123,8 +115,7 @@ working connection to the internet:
|
||||
|
||||
make test-full-online
|
||||
|
||||
Running gcov for unit test coverage
|
||||
-----------------------------------
|
||||
## Running gcov for unit test coverage
|
||||
|
||||
./configure --enable-coverage
|
||||
make
|
||||
@@ -164,8 +155,7 @@ lines?
|
||||
If you run ./scripts/test/cov-exclude, it marks excluded unreached
|
||||
lines with 'x', and excluded reached lines with '!!!'.
|
||||
|
||||
Running integration tests
|
||||
-------------------------
|
||||
## Running integration tests
|
||||
|
||||
We have the beginnings of a set of scripts to run integration tests using
|
||||
Chutney. To try them, set CHUTNEY_PATH to your chutney source directory, and
|
||||
@@ -174,14 +164,12 @@ run `make test-network`.
|
||||
We also have scripts to run integration tests using Stem. To try them, set
|
||||
`STEM_SOURCE_DIR` to your Stem source directory, and run `test-stem`.
|
||||
|
||||
Profiling Tor
|
||||
-------------
|
||||
## Profiling Tor
|
||||
|
||||
Ongoing notes about Tor profiling can be found at
|
||||
https://pad.riseup.net/p/profiling-tor
|
||||
|
||||
Profiling Tor with oprofile
|
||||
---------------------------
|
||||
## Profiling Tor with oprofile
|
||||
|
||||
The oprofile tool runs (on Linux only!) to tell you what functions Tor is
|
||||
spending its CPU time in, so we can identify performance bottlenecks.
|
||||
@@ -206,8 +194,7 @@ Here are some basic instructions
|
||||
* `opreport -l that_dir/*`
|
||||
- Profit
|
||||
|
||||
Profiling Tor with perf
|
||||
-----------------------
|
||||
## Profiling Tor with perf
|
||||
|
||||
This works with a running Tor, and requires root.
|
||||
|
||||
@@ -236,8 +223,7 @@ This works with a running Tor, and requires root.
|
||||
report -g > <FILENAME>.out`. Then you can compress that and put it somewhere
|
||||
public.
|
||||
|
||||
Profiling Tor with gperftools aka Google-performance-tools
|
||||
----------------------------------------------------------
|
||||
## Profiling Tor with gperftools aka Google-performance-tools
|
||||
|
||||
This should work on nearly any unixy system. It doesn't seem to be compatible
|
||||
with RunAsDaemon though.
|
||||
@@ -255,8 +241,7 @@ performance! See the gperftools manual for more info, but basically:
|
||||
|
||||
3. Run `pprof src/app/tor /tmp/profile` to start the REPL.
|
||||
|
||||
Generating and analyzing a callgraph
|
||||
------------------------------------
|
||||
## Generating and analyzing a callgraph
|
||||
|
||||
0. Build Tor on linux or mac, ideally with -O0 or -fno-inline.
|
||||
|
||||
@@ -266,8 +251,7 @@ Generating and analyzing a callgraph
|
||||
Note that currently the callgraph generator can't detect calls that pass
|
||||
through function pointers.
|
||||
|
||||
Getting emacs to edit Tor source properly
|
||||
-----------------------------------------
|
||||
## Getting emacs to edit Tor source properly
|
||||
|
||||
Nick likes to put the following snippet in his .emacs file:
|
||||
|
||||
@@ -315,8 +299,7 @@ If you use emacs for editing Tor and nothing else, you could always just say:
|
||||
There is probably a better way to do this. No, we are probably not going
|
||||
to clutter the files with emacs stuff.
|
||||
|
||||
Building a tag file (code index)
|
||||
--------------------------------
|
||||
## Building a tag file (code index)
|
||||
|
||||
Many functions in tor use `MOCK_IMPL` wrappers for unit tests. Your
|
||||
tag-building program must be told how to handle this syntax.
|
||||
@@ -340,8 +323,7 @@ instead:
|
||||
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.
|
||||
|
||||
Doxygen
|
||||
-------
|
||||
## Doxygen
|
||||
|
||||
We use the 'doxygen' utility to generate documentation from our
|
||||
source code. Here's how to use it:
|
||||
@@ -396,8 +378,7 @@ source code. Here's how to use it:
|
||||
6. See the Doxygen manual for more information; this summary just
|
||||
scratches the surface.
|
||||
|
||||
Style and best-practices checking
|
||||
--------------------------------
|
||||
## Style and best-practices checking
|
||||
|
||||
We use scripts to check for various problems in the formatting and style
|
||||
of our source code. The "check-spaces" test detects a bunch of violations
|
||||
|
||||
Reference in New Issue
Block a user