commit 49ccb7e7b88d38a572277824a344ad423494a293 Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 14 10:40:27 2015 -0400
Mention trunnel in CodingStandards; describe how in trunnel/README --- doc/HACKING/CodingStandards.txt | 25 ++++++++++++++++++++----- src/trunnel/README | 13 ++++++++++++- 2 files changed, 32 insertions(+), 6 deletions(-)
diff --git a/doc/HACKING/CodingStandards.txt b/doc/HACKING/CodingStandards.txt index fa4990d..2d03b8e 100644 --- a/doc/HACKING/CodingStandards.txt +++ b/doc/HACKING/CodingStandards.txt @@ -122,20 +122,35 @@ using gcc, you should invoke the configure script with the option "--enable-gcc-warnings". This will give a bunch of extra warning flags to the compiler, and help us find divergences from our preferred C style.
-Functions to use -~~~~~~~~~~~~~~~~ +Functions to use; functions not 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 -available containers in src/common/containers.h. You should probably +looking through src/common/util*.h and src/common/compat*.h. You can see the +available containers in src/common/containers*.h. You should probably familiarize yourself with these modules before you write too much code, or else you'll wind up reinventing the wheel.
-Use 'INLINE' instead of 'inline', so that we work properly on Windows. +Use 'INLINE' instead of 'inline' -- it's a vestige of an old hack to make +sure that we worked on MSVC6. + +We don't use strcat or strcpy or sprintf of any of those notoriously broken +old C functions. Use strlcat, strlcpy, or tor_snprintf/tor_asprintf instead. + +Functions not to write +~~~~~~~~~~~~~~~~~~~~~~ + +Try to never hand-write new code to parse or generate binary +formats. Instead, use trunnel if at all possible. See + https://gitweb.torproject.org/trunnel.git/tree +for more information about trunnel. + +For information on adding new trunnel code to Tor, see src/trunnel/README +
Calling and naming conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/trunnel/README b/src/trunnel/README index 383272c..e24aea0 100644 --- a/src/trunnel/README +++ b/src/trunnel/README @@ -1,10 +1,21 @@ This directory contains code for use with, and code made by, the automatic code generation tool "Trunnel".
+Trunnel generates binary parsers and formatters for simple data +structures. It aims for human-readable, obviously-correct outputs over +maximum efficiency or flexibility. + The .trunnel files are the inputs here; the .c and .h files are the outputs. -To regenerate the .c and .h files, run "scripts/codegen/run_trunnel.sh". + +To add a new structure: + - Add a new .trunnel file or expand an existing one to describe the format + of the structure. + - Regenerate the .c and .h files. To do this, you run + "scripts/codegen/run_trunnel.sh". You'll need trunnel installed. + - Add the .trunnel, .c, and .h files to include.am
For the Trunnel source code, and more documentation about using Trunnel, see https://gitweb.torproject.org/trunnel.git , especially https://gitweb.torproject.org/trunnel.git/tree/README and https://gitweb.torproject.org/trunnel.git/tree/doc/trunnel.md +