6 https://buildbot.vidalia-project.net/one_line_per_build
8 0.1. Useful command-lines that are non-trivial to reproduce but can
9 help with tracking bugs or leaks.
13 dmalloc -l ~/dmalloc.log
14 (run the commands it tells you)
15 ./configure --with-dmalloc
19 valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor
21 (Note that if you get a zillion openssl warnings, you will also need to
22 pass --undef-value-errors=no to valgrind, or rebuild your openssl
25 0.2. Running gcov for unit test coverage
28 make CFLAGS='-g -fprofile-arcs -ftest-coverage'
30 cd src/common; gcov *.[ch]
33 Then, look at the .gcov files. '-' before a line means that the
34 compiler generated no code for that line. '######' means that the
35 line was never reached. Lines with numbers were called that number
40 1.0. Whitespace and C conformance
42 Invoke "make check-spaces" from time to time, so it can tell you about
43 deviations from our C whitespace style. Generally, we use:
44 - Unix-style line endings
45 - K&R-style indentation
46 - No space before newlines
47 - A blank line at the end of each file
48 - Never more than one blank line in a row
49 - Always spaces, never tabs
50 - No more than 79-columns per line.
51 - Two spaces per indent.
52 - A space between control keywords and their corresponding paren
53 "if (x)", "while (x)", and "switch (x)", never "if(x)", "while(x)", or
55 - A space between anything and an open brace.
56 - No space between a function name and an opening paren. "puts(x)", not
58 - Function declarations at the start of the line.
60 We try hard to build without warnings everywhere. In particular, if you're
61 using gcc, you should invoke the configure script with the option
62 "--enable-gcc-warnings". This will give a bunch of extra warning flags to
63 the compiler, and help us find divergences from our preferred C style.
65 1.0.1. Getting emacs to edit Tor source properly.
67 Hi, folks! Nick here. I like to put the following snippet in my .emacs
69 (add-hook 'c-mode-hook
72 (set-variable 'show-trailing-whitespace t)
74 (let ((fname (expand-file-name (buffer-file-name))))
76 ((string-match "^/home/nickm/src/libevent" fname)
77 (set-variable 'indent-tabs-mode t)
78 (set-variable 'c-basic-offset 4)
79 (set-variable 'tab-width 4))
80 ((string-match "^/home/nickm/src/tor" fname)
81 (set-variable 'indent-tabs-mode nil)
82 (set-variable 'c-basic-offset 2))
83 ((string-match "^/home/nickm/src/openssl" fname)
84 (set-variable 'indent-tabs-mode t)
85 (set-variable 'c-basic-offset 8)
86 (set-variable 'tab-width 8))
89 You'll note that it defaults to showing all trailing whitespace. The
90 "cond" test detects whether the file is one of a few C free software
91 projects that I often edit, and sets up the indentation level and tab
92 preferences to match what they want.
94 If you want to try this out, you'll need to change the filename regex
95 patterns to match where you keep your Tor files.
97 If you *only* use emacs to edit Tor, you could always just say:
99 (add-hook 'c-mode-hook
102 (set-variable 'show-trailing-whitespace t)
103 (set-variable 'indent-tabs-mode nil)
104 (set-variable 'c-basic-offset 2)))
106 There is probably a better way to do this. No, we are probably not going
107 to clutter the files with emacs stuff.
111 Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their
112 generic equivalents. (They always succeed or exit.)
114 You can get a full list of the compatibility functions that Tor provides by
115 looking through src/common/util.h and src/common/compat.h. You can see the
116 available containers in src/common/containers.h. You should probably
117 familiarize yourself with these modules before you write too much code,
118 or else you'll wind up reinventing the wheel.
120 Use 'INLINE' instead of 'inline', so that we work properly on Windows.
122 1.2. Calling and naming conventions
124 Whenever possible, functions should return -1 on error and 0 on success.
126 For multi-word identifiers, use lowercase words combined with
127 underscores. (e.g., "multi_word_identifier"). Use ALL_CAPS for macros and
130 Typenames should end with "_t".
132 Function names should be prefixed with a module name or object name. (In
133 general, code to manipulate an object should be a module with the same
134 name as the object, so it's hard to tell which convention is used.)
136 Functions that do things should have imperative-verb names
137 (e.g. buffer_clear, buffer_resize); functions that return booleans should
138 have predicate names (e.g. buffer_is_empty, buffer_needs_resizing).
140 If you find that you have four or more possible return code values, it's
141 probably time to create an enum. If you find that you are passing three or
142 more flags to a function, it's probably time to create a flags argument
143 that takes a bitfield.
145 1.3. What To Optimize
147 Don't optimize anything if it's not in the critical path. Right now,
148 the critical path seems to be AES, logging, and the network itself.
149 Feel free to do your own profiling to determine otherwise.
153 https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#LogLevels
155 No error or warning messages should be expected during normal OR or OP
158 If a library function is currently called such that failure always
159 means ERR, then the library function should log WARN and let the caller
162 [XXX Proposed convention: every message of severity INFO or higher should
163 either (A) be intelligible to end-users who don't know the Tor source; or
164 (B) somehow inform the end-users that they aren't expected to understand
165 the message (perhaps with a string like "internal error"). Option (A) is
166 to be preferred to option (B). -NM]
170 We use the 'doxygen' utility to generate documentation from our
171 source code. Here's how to use it:
173 1. Begin every file that should be documented with
176 * \brief Short description of the file.
179 (Doxygen will recognize any comment beginning with /** as special.)
181 2. Before any function, structure, #define, or variable you want to
182 document, add a comment of the form:
184 /** Describe the function's actions in imperative sentences.
186 * Use blank lines for paragraph breaks
192 * Write <b>argument_names</b> in boldface.
195 * place_example_code();
196 * between_code_and_endcode_commands();
200 3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
201 "\>", "\\", "\%", and "\#".
203 4. To document structure members, you can use two forms:
206 /** You can put the comment before an element; */
208 int b; /**< Or use the less-than symbol to put the comment
209 * after the element. */
212 5. To generate documentation from the Tor source code, type:
216 To generate a file called 'Doxyfile'. Edit that file and run
217 'doxygen' to generate the API documentation.
219 6. See the Doxygen manual for more information; this summary just
220 scratches the surface.
222 1.5.1. Doxygen comment conventions
224 Say what functions do as a series of one or more imperative sentences, as
225 though you were telling somebody how to be the function. In other words,
228 /** The strtol function parses a number.
230 * nptr -- the string to parse. It can include whitespace.
231 * endptr -- a string pointer to hold the first thing that is not part
232 * of the number, if present.
233 * base -- the numeric base.
234 * returns: the resulting number.
236 long strtol(const char *nptr, char **nptr, int base);
238 Instead, please DO say:
240 /** Parse a number in radix <b>base</b> from the string <b>nptr</b>,
241 * and return the result. Skip all leading whitespace. If
242 * <b>endptr</b> is not NULL, set *<b>endptr</b> to the first character
243 * after the number parsed.
245 long strtol(const char *nptr, char **nptr, int base);
247 Doxygen comments are the contract in our abstraction-by-contract world: if
248 the functions that call your function rely on it doing something, then your
249 function should mention that it does that something in the documentation.
250 If you rely on a function doing something beyond what is in its
251 documentation, then you should watch out, or it might do something else
258 2.1.1. How Incoming data is handled
260 There are two paths for data arriving at Tor over the network: regular
265 When Tor takes information over the network, it uses the functions
266 read_to_buf() and read_to_buf_tls() in buffers.c. These read from a
267 socket or an SSL* into a buffer_t, which is an mbuf-style linkedlist
270 read_to_buf() and read_to_buf_tls() are called only from
271 connection_read_to_buf() in connection.c. It takes a connection_t
272 pointer, and reads data into it over the network, up to the
273 connection's current bandwidth limits. It places that data into the
274 "inbuf" field of the connection, and then:
275 - Adjusts the connection's want-to-read/want-to-write status as
277 - Increments the read and written counts for the connection as
279 - Adjusts bandwidth buckets as appropriate.
281 connection_read_to_buf() is called only from connection_handle_read().
282 The connection_handle_read() function is called whenever libevent
283 decides (based on select, poll, epoll, kqueue, etc) that there is data
284 to read from a connection. If any data is read,
285 connection_handle_read() calls connection_process_inbuf() to see if
286 any of the data can be processed. If the connection was closed,
287 connection_handle_read() calls connection_reached_eof().
289 Connection_process_inbuf() and connection_reached_eof() both dispatch
290 based on the connection type to determine what to do with the data
291 that's just arrived on the connection's inbuf field. Each type of
292 connection has its own version of these functions. For example,
293 directory connections process incoming data in
294 connection_dir_process_inbuf(), while OR connections process incoming
295 data in connection_or_process_inbuf(). These
296 connection_*_process_inbuf() functions extract data from the
297 connection's inbuf field (a buffer_t), using functions from buffers.c.
298 Some of these accessor functions are straightforward data extractors
299 (like fetch_from_buf()); others do protocol-specific parsing.
304 Tor launches (and optionally accepts) DNS requests using the code in
305 eventdns.c, which is a copy of libevent's evdns.c. (We don't use
306 libevent's version because it is not yet in the versions of libevent
307 all our users have.) DNS replies are read in nameserver_read();
308 DNS queries are read in server_port_read().