1 Hacking Tor: An Incomplete Guide
2 ================================
7 For full information on how Tor is supposed to work, look at the files in
10 For an explanation of how to change Tor's design to work differently, look at
11 doc/spec/proposals/001-process.txt .
13 For the latest version of the code, get a copy of git, and
15 git clone git://git.torproject.org/git/tor .
17 We talk about Tor on the or-talk mailing list. Design proposals and
18 discussion belong on the or-dev mailing list. We hang around on
19 irc.oftc.net, with general discussion happening on #tor and development
20 happening on #tor-dev.
22 How we use Git branches
23 -----------------------
25 Each main development series (like 0.2.1, 0.2.2, etc) has its main work
26 applied to a single branch. At most one series can be the development series
27 at a time; all other series are maintenance series that get bug-fixes only.
28 The development series is built in a git branch called "master"; the
29 maintenance series are built in branches called "maint-0.2.0", "maint-0.2.1",
30 and so on. We regularly merge the active maint branches forward.
32 For all series except the development series, we also have a "release" branch
33 (as in "release-0.2.1"). The release series is based on the corresponding
34 maintenance series, except that it deliberately lags the maint series for
35 most of its patches, so that bugfix patches are not typically included in a
36 maintenance release until they've been tested for a while in a development
37 release. Occasionally, we'll merge an urgent bugfix into the release branch
38 before it gets merged into maint, but that's rare.
40 If you're working on a bugfix for a bug that occurs in a particular version,
41 base your bugfix branch on the "maint" branch for the first _actively
42 developed_ series that has that bug. (Right now, that's 0.2.1.) If you're
43 working on a new feature, base it on the master branch.
49 When you do a commit that needs a ChangeLog entry, add a new file to
50 the "changes" toplevel subdirectory. It should have the format of a
51 one-entry changelog section from the current ChangeLog file, as in
54 - Fix a potential buffer overflow. Fixes bug 9999. Bugfix on
57 To write a changes file, first categorize the change. Some common categories
58 are: Minor bugfixes, Major bugfixes, Minor features, Major features, Code
59 simplifications and refactoring. Then say what the change does. Then, if
60 it's a bugfix, then mention what bug it fixes and when the bug was
63 If at all possible, try to create this file in the same commit where
64 you are making the change. Please give it a distinctive name that no
65 other branch will use for the lifetime of your change.
67 When Roger goes to make a release, he will concatenate all the entries
68 in changes to make a draft changelog, and clear the directory. He'll
69 then edit the draft changelog into a nice readable format.
71 What needs a changes file?::
72 A not-exhaustive list: Anything that might change user-visible
73 behavior. Anything that changes internals, documentation, or the build
74 system enough that somebody could notice. Big or interesting code
75 rewrites. Anything about which somebody might plausibly wonder "when
76 did that happen, and/or why did we do that" 6 months down the line.
78 Why use changes files instead of Git commit messages?::
79 Git commit messages are written for developers, not users, and they
80 are nigh-impossible to revise after the fact.
82 Why use changes files instead of entries in the ChangeLog?::
83 Having every single commit touch the ChangeLog file tended to create
84 zillions of merge conflicts.
89 These aren't strictly necessary for hacking on Tor, but they can help track
95 https://buildbot.vidalia-project.net/one_line_per_build
100 The dmalloc library will keep track of memory allocation, so you can find out
101 if we're leaking memory, doing any double-frees, or so on.
103 dmalloc -l ~/dmalloc.log
104 (run the commands it tells you)
105 ./configure --with-dmalloc
110 valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor
112 (Note that if you get a zillion openssl warnings, you will also need to
113 pass --undef-value-errors=no to valgrind, or rebuild your openssl
116 Running gcov for unit test coverage
117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121 make CFLAGS='-g -fprofile-arcs -ftest-coverage'
123 cd src/common; gcov *.[ch]
124 cd ../or; gcov *.[ch]
127 Then, look at the .gcov files. '-' before a line means that the
128 compiler generated no code for that line. '######' means that the
129 line was never reached. Lines with numbers were called that number
138 If possible, send your patch as one of these (in descending order of
141 - A git branch we can pull from
142 - Patches generated by git format-patch
147 - To build your code while configured with --enable-gcc-warnings?
148 - To run "make check-spaces" on your code?
149 - To write unit tests, as possible?
150 - To base your code on the appropriate branch?
151 - To include a file in the "changes" directory as appropriate?
153 Whitespace and C conformance
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156 Invoke "make check-spaces" from time to time, so it can tell you about
157 deviations from our C whitespace style. Generally, we use:
159 - Unix-style line endings
160 - K&R-style indentation
161 - No space before newlines
162 - A blank line at the end of each file
163 - Never more than one blank line in a row
164 - Always spaces, never tabs
165 - No more than 79-columns per line.
166 - Two spaces per indent.
167 - A space between control keywords and their corresponding paren
168 "if (x)", "while (x)", and "switch (x)", never "if(x)", "while(x)", or
170 - A space between anything and an open brace.
171 - No space between a function name and an opening paren. "puts(x)", not
173 - Function declarations at the start of the line.
175 We try hard to build without warnings everywhere. In particular, if you're
176 using gcc, you should invoke the configure script with the option
177 "--enable-gcc-warnings". This will give a bunch of extra warning flags to
178 the compiler, and help us find divergences from our preferred C style.
180 Getting emacs to edit Tor source properly
181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183 Nick likes to put the following snippet in his .emacs file:
186 (add-hook 'c-mode-hook
189 (set-variable 'show-trailing-whitespace t)
191 (let ((fname (expand-file-name (buffer-file-name))))
193 ((string-match "^/home/nickm/src/libevent" fname)
194 (set-variable 'indent-tabs-mode t)
195 (set-variable 'c-basic-offset 4)
196 (set-variable 'tab-width 4))
197 ((string-match "^/home/nickm/src/tor" fname)
198 (set-variable 'indent-tabs-mode nil)
199 (set-variable 'c-basic-offset 2))
200 ((string-match "^/home/nickm/src/openssl" fname)
201 (set-variable 'indent-tabs-mode t)
202 (set-variable 'c-basic-offset 8)
203 (set-variable 'tab-width 8))
207 You'll note that it defaults to showing all trailing whitespace. The "cond"
208 test detects whether the file is one of a few C free software projects that I
209 often edit, and sets up the indentation level and tab preferences to match
212 If you want to try this out, you'll need to change the filename regex
213 patterns to match where you keep your Tor files.
215 If you use emacs for editing Tor and nothing else, you could always just say:
218 (add-hook 'c-mode-hook
221 (set-variable 'show-trailing-whitespace t)
222 (set-variable 'indent-tabs-mode nil)
223 (set-variable 'c-basic-offset 2)))
226 There is probably a better way to do this. No, we are probably not going
227 to clutter the files with emacs stuff.
233 We have some wrapper functions like tor_malloc, tor_free, tor_strdup, and
234 tor_gettimeofday; use them instead of their generic equivalents. (They
235 always succeed or exit.)
237 You can get a full list of the compatibility functions that Tor provides by
238 looking through src/common/util.h and src/common/compat.h. You can see the
239 available containers in src/common/containers.h. You should probably
240 familiarize yourself with these modules before you write too much code, or
241 else you'll wind up reinventing the wheel.
243 Use 'INLINE' instead of 'inline', so that we work properly on Windows.
245 Calling and naming conventions
246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248 Whenever possible, functions should return -1 on error and 0 on success.
250 For multi-word identifiers, use lowercase words combined with
251 underscores. (e.g., "multi_word_identifier"). Use ALL_CAPS for macros and
254 Typenames should end with "_t".
256 Function names should be prefixed with a module name or object name. (In
257 general, code to manipulate an object should be a module with the same name
258 as the object, so it's hard to tell which convention is used.)
260 Functions that do things should have imperative-verb names
261 (e.g. buffer_clear, buffer_resize); functions that return booleans should
262 have predicate names (e.g. buffer_is_empty, buffer_needs_resizing).
264 If you find that you have four or more possible return code values, it's
265 probably time to create an enum. If you find that you are passing three or
266 more flags to a function, it's probably time to create a flags argument that
272 Don't optimize anything if it's not in the critical path. Right now, the
273 critical path seems to be AES, logging, and the network itself. Feel free to
274 do your own profiling to determine otherwise.
279 https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#LogLevels
281 No error or warning messages should be expected during normal OR or OP
284 If a library function is currently called such that failure always means ERR,
285 then the library function should log WARN and let the caller log ERR.
287 [XXX Proposed convention: every message of severity INFO or higher should
288 either (A) be intelligible to end-users who don't know the Tor source; or (B)
289 somehow inform the end-users that they aren't expected to understand the
290 message (perhaps with a string like "internal error"). Option (A) is to be
291 preferred to option (B). -NM]
296 We use the 'doxygen' utility to generate documentation from our
297 source code. Here's how to use it:
299 1. Begin every file that should be documented with
302 * \brief Short description of the file.
305 (Doxygen will recognize any comment beginning with /** as special.)
307 2. Before any function, structure, #define, or variable you want to
308 document, add a comment of the form:
310 /** Describe the function's actions in imperative sentences.
312 * Use blank lines for paragraph breaks
318 * Write <b>argument_names</b> in boldface.
321 * place_example_code();
322 * between_code_and_endcode_commands();
326 3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
327 "\>", "\\", "\%", and "\#".
329 4. To document structure members, you can use two forms:
332 /** You can put the comment before an element; */
334 int b; /**< Or use the less-than symbol to put the comment
335 * after the element. */
338 5. To generate documentation from the Tor source code, type:
342 To generate a file called 'Doxyfile'. Edit that file and run
343 'doxygen' to generate the API documentation.
345 6. See the Doxygen manual for more information; this summary just
346 scratches the surface.
348 Doxygen comment conventions
349 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
351 Say what functions do as a series of one or more imperative sentences, as
352 though you were telling somebody how to be the function. In other words, DO
355 /** The strtol function parses a number.
357 * nptr -- the string to parse. It can include whitespace.
358 * endptr -- a string pointer to hold the first thing that is not part
359 * of the number, if present.
360 * base -- the numeric base.
361 * returns: the resulting number.
363 long strtol(const char *nptr, char **nptr, int base);
365 Instead, please DO say:
367 /** Parse a number in radix <b>base</b> from the string <b>nptr</b>,
368 * and return the result. Skip all leading whitespace. If
369 * <b>endptr</b> is not NULL, set *<b>endptr</b> to the first character
370 * after the number parsed.
372 long strtol(const char *nptr, char **nptr, int base);
374 Doxygen comments are the contract in our abstraction-by-contract world: if
375 the functions that call your function rely on it doing something, then your
376 function should mention that it does that something in the documentation. If
377 you rely on a function doing something beyond what is in its documentation,
378 then you should watch out, or it might do something else later.