|
@@ -1,27 +1,111 @@
|
|
|
Hacking Tor: An Incomplete Guide
|
|
|
================================
|
|
|
|
|
|
+Getting started
|
|
|
+---------------
|
|
|
+
|
|
|
+For full information on how Tor is supposed to work, look at the files in
|
|
|
+doc/spec/ .
|
|
|
+
|
|
|
+For an explanation of how to change Tor's design to work differently, look at
|
|
|
+doc/spec/proposals/001-process.txt .
|
|
|
+
|
|
|
+For the latest version of the code, get a copy of git, and
|
|
|
+
|
|
|
+ git clone git://git.torproject.org/git/tor .
|
|
|
+
|
|
|
+We talk about Tor on the or-talk mailing list. Design proposals and
|
|
|
+discussion belong on the or-dev mailing list. We hang around on
|
|
|
+irc.oftc.net, with general discussion happening on #tor and development
|
|
|
+happening on #tor-dev.
|
|
|
+
|
|
|
+How we use Git branches
|
|
|
+-----------------------
|
|
|
+
|
|
|
+Each main development series (like 0.2.1, 0.2.2, etc) has its main work
|
|
|
+applied to a single branch. At most one series can be the development series
|
|
|
+at a time; all other series are maintenance series that get bug-fixes only.
|
|
|
+The development series is built in a git branch called "master"; the
|
|
|
+maintenance series are built in branches called "maint-0.2.0", "maint-0.2.1",
|
|
|
+and so on. We regularly merge the active maint branches forward.
|
|
|
+
|
|
|
+For all series except the development series, we also have a "release" branch
|
|
|
+(as in "release-0.2.1"). The release series is based on the corresponding
|
|
|
+maintenance series, except that it deliberately lags the maint series for
|
|
|
+most of its patches, so that bugfix patches are not typically included in a
|
|
|
+maintenance release until they've been tested for a while in a development
|
|
|
+release. Occasionally, we'll merge an urgent bugfix into the release branch
|
|
|
+before it gets merged into maint, but that's rare.
|
|
|
+
|
|
|
+If you're working on a bugfix for a bug that occurs in a particular version,
|
|
|
+base your bugfix branch on the "maint" branch for the first _actively
|
|
|
+developed_ series that has that bug. (Right now, that's 0.2.1.) If you're
|
|
|
+working on a new feature, base it on the master branch.
|
|
|
+
|
|
|
+
|
|
|
+How we log changes
|
|
|
+------------------
|
|
|
+
|
|
|
+When you do a commit that needs a ChangeLog entry, add a new file to
|
|
|
+the "changes" toplevel subdirectory. It should have the format of a
|
|
|
+one-entry changelog section from the current ChangeLog file, as in
|
|
|
+
|
|
|
+ o Major bugfixes:
|
|
|
+ - Fix a potential buffer overflow. Fixes bug 9999. Bugfix on
|
|
|
+ Tor 0.3.1.4-beta.
|
|
|
+
|
|
|
+To write a changes file, first categorize the change. Some common categories
|
|
|
+are: Minor bugfixes, Major bugfixes, Minor features, Major features, Code
|
|
|
+simplifications and refactoring. Then say what the change does. Then, if
|
|
|
+it's a bugfix, then mention what bug it fixes and when the bug was
|
|
|
+introduced.
|
|
|
+
|
|
|
+If at all possible, try to create this file in the same commit where
|
|
|
+you are making the change. Please give it a distinctive name that no
|
|
|
+other branch will use for the lifetime of your change.
|
|
|
+
|
|
|
+When Roger goes to make a release, he will concatenate all the entries
|
|
|
+in changes to make a draft changelog, and clear the directory. He'll
|
|
|
+then edit the draft changelog into a nice readable format.
|
|
|
+
|
|
|
+What needs a changes file?::
|
|
|
+ A not-exhaustive list: Anything that might change user-visible
|
|
|
+ behavior. Anything that changes internals, documentation, or the build
|
|
|
+ system enough that somebody could notice. Big or interesting code
|
|
|
+ rewrites. Anything about which somebody might plausibly wonder "when
|
|
|
+ did that happen, and/or why did we do that" 6 months down the line.
|
|
|
+
|
|
|
+Why use changes files instead of Git commit messages?::
|
|
|
+ Git commit messages are written for developers, not users, and they
|
|
|
+ are nigh-impossible to revise after the fact.
|
|
|
+
|
|
|
+Why use changes files instead of entries in the ChangeLog?::
|
|
|
+ Having every single commit touch the ChangeLog file tended to create
|
|
|
+ zillions of merge conflicts.
|
|
|
|
|
|
Useful tools
|
|
|
------------
|
|
|
|
|
|
+These aren't strictly necessary for hacking on Tor, but they can help track
|
|
|
+down bugs.
|
|
|
+
|
|
|
The buildbot
|
|
|
~~~~~~~~~~~~
|
|
|
|
|
|
https://buildbot.vidalia-project.net/one_line_per_build
|
|
|
|
|
|
-Useful command-lines
|
|
|
-~~~~~~~~~~~~~~~~~~~~
|
|
|
-
|
|
|
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
|
|
|
+ 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
|
|
|
|
|
@@ -30,7 +114,7 @@ pass --undef-value-errors=no to valgrind, or rebuild your openssl
|
|
|
with -DPURIFY.)
|
|
|
|
|
|
Running gcov for unit test coverage
|
|
|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
-----
|
|
|
make clean
|
|
@@ -48,6 +132,24 @@ of times.
|
|
|
Coding conventions
|
|
|
------------------
|
|
|
|
|
|
+Patch checklist
|
|
|
+~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+If possible, send your patch as one of these (in descending order of
|
|
|
+preference)
|
|
|
+
|
|
|
+ - A git branch we can pull from
|
|
|
+ - Patches generated by git format-patch
|
|
|
+ - A unified diff
|
|
|
+
|
|
|
+Did you remember...
|
|
|
+
|
|
|
+ - To build your code while configured with --enable-gcc-warnings?
|
|
|
+ - To run "make check-speces" on your code?
|
|
|
+ - To write unit tests, as possible?
|
|
|
+ - To base your code on the appropriate branch?
|
|
|
+ - To include a file in the "changes" directory as appropriate?
|
|
|
+
|
|
|
Whitespace and C conformance
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
@@ -78,8 +180,7 @@ the compiler, and help us find divergences from our preferred C style.
|
|
|
Getting emacs to edit Tor source properly
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
-Hi, folks! Nick here. I like to put the following snippet in my .emacs
|
|
|
-file:
|
|
|
+Nick likes to put the following snippet in his .emacs file:
|
|
|
|
|
|
-----
|
|
|
(add-hook 'c-mode-hook
|
|
@@ -111,7 +212,7 @@ what they want.
|
|
|
If you want to try this out, you'll need to change the filename regex
|
|
|
patterns to match where you keep your Tor files.
|
|
|
|
|
|
-If you *only* use emacs to edit Tor, you could always just say:
|
|
|
+If you use emacs for editing Tor and nothing else, you could always just say:
|
|
|
|
|
|
-----
|
|
|
(add-hook 'c-mode-hook
|
|
@@ -125,11 +226,13 @@ If you *only* use emacs to edit Tor, 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.
|
|
|
|
|
|
-Details
|
|
|
-~~~~~~~
|
|
|
|
|
|
-Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their
|
|
|
-generic equivalents. (They always succeed or exit.)
|
|
|
+Functions to use
|
|
|
+~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+We have some wrapper functions like tor_malloc, tor_free, tor_strdup, and
|
|
|
+tor_gettimeofday; use them instead of their generic equivalents. (They
|
|
|
+always succeed or exit.)
|
|
|
|
|
|
You can get a full list of the compatibility functions that Tor provides by
|
|
|
looking through src/common/util.h and src/common/compat.h. You can see the
|