HACKING 13 KB

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