[tor-commits] [tor/master] Mention trunnel in CodingStandards; describe how in trunnel/README

nickm at torproject.org nickm at torproject.org
Wed Oct 14 14:40:30 UTC 2015

commit 49ccb7e7b88d38a572277824a344ad423494a293
Author: Nick Mathewson <nickm at 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
 and https://gitweb.torproject.org/trunnel.git/tree/doc/trunnel.md

More information about the tor-commits mailing list