[tor-commits] [tor/master] Move remaining CodeStructure.md contents into doxygen.

nickm at torproject.org nickm at torproject.org
Fri Jun 26 14:12:16 UTC 2020


commit 5336ac26693cdba47422771ea951d22a290f67df
Author: Nick Mathewson <nickm at torproject.org>
Date:   Fri Jun 26 10:11:42 2020 -0400

    Move remaining CodeStructure.md contents into doxygen.
---
 doc/HACKING/CodeStructure.md | 123 -------------------------------------------
 doc/include.am               |   1 -
 src/app/app.md               |   5 ++
 src/feature/feature.md       |  23 ++++++++
 4 files changed, 28 insertions(+), 124 deletions(-)

diff --git a/doc/HACKING/CodeStructure.md b/doc/HACKING/CodeStructure.md
deleted file mode 100644
index d387018f9..000000000
--- a/doc/HACKING/CodeStructure.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# Code Structure
-
-TODO: revise this to talk about how things are, rather than how things
-have changed.
-
-For quite a while now, the program *tor* has been built from source
-code in just two directories: **src/common** and **src/or**.
-
-This has become more-or-less untenable, for a few reasons -- most
-notably of which is that it has led our code to become more
-spaghetti-ish than I can endorse with a clean conscience.
-
-So to fix that, we've gone and done a huge code movement in our git
-master branch, which will land in a release once Tor `0.3.5.1-alpha` is
-out.
-
-Here's what we did:
-
-  * **src/common** has been turned into a set of static libraries.  These
-all live in the **src/lib/*** directories.  The dependencies between
-these libraries should have no cycles.  The libraries are:
-
-    - **arch** -- Headers to handle architectural differences
-    - **cc** -- headers to handle differences among compilers
-    - **compress** -- wraps zlib, zstd, lzma
-    - **container** -- high-level container types
-    - **crypt_ops** -- Cryptographic operations. Planning to split this into
-a higher and lower level library
-    - **ctime** -- Operations that need to run in constant-time. (Properly,
-data-invariant time)
-    - **defs** -- miscelaneous definitions needed throughout Tor.
-    - **encoding** -- transforming one data type into another, and various
-data types into strings.
-    - **err** -- lowest-level error handling, in cases where we can't use
-the logs because something that the logging system needs has broken.
-    - **evloop** -- Generic event-loop handling logic
-    - **fdio** -- Low-level IO wrapper functions for file descriptors.
-    - **fs** -- Operations on the filesystem
-    - **intmath** -- low-level integer math and misc bit-twiddling hacks
-    - **lock** -- low-level locking code
-    - **log** -- Tor's logging module.  This library sits roughly halfway up
-the library dependency diagram, since everything it depends on has to
-be carefully crafted to *not* log.
-    - **malloc** -- Low-level wrappers for the platform memory allocation functions.
-    - **math** -- Higher-level mathematical functions, and floating-point math
-    - **memarea** -- An arena allocator
-    - **meminfo** -- Functions for querying the current process's memory
-status and resources
-    - **net** -- Networking compatibility and convenience code
-    - **osinfo** -- Querying information about the operating system
-    - **process** -- Launching and querying the status of other processes
-    - **sandbox** -- Backend for the linux seccomp2 sandbox
-    - **smartlist_core** -- The lowest-level of the smartlist_t data type.
-Separated from the rest of the containers library because the logging
-subsystem depends on it.
-    - **string** -- Compatibility and convenience functions for manipulating
-C strings.
-    - **term** -- Terminal-related functions (currently limited to a getpass
-function).
-    - **testsupport** -- Macros for mocking, unit tests, etc.
-    - **thread** -- Higher-level thread compatibility code
-    - **time** -- Higher-level time management code, including format
-conversions and monotonic time
-    - **tls** -- Our wrapper around our TLS library
-    - **trace** -- Formerly src/trace -- a generic event tracing API
-    - **wallclock** -- Low-level time code, used by the log module.
-
-  * To ensure that the dependency graph in **src/common** remains under
-control, there is a tool that you can run called `make
-check-includes`.  It verifies that each module in Tor only includes
-the headers that it is permitted to include, using a per-directory
-*.may_include* file.
-
-  * The **src/or/or.h** header has been split into numerous smaller
-headers.  Notably, many important structures are now declared in a
-header called *foo_st.h*, where "foo" is the name of the structure.
-
-  * The **src/or** directory, which had most of Tor's code, had been split
-up into several directories.  This is still a work in progress:  This
-code has not itself been refactored, and its dependency graph is still
-a tangled web.  I hope we'll be working on that over the coming
-releases, but it will take a while to do.
-
-    - The new top-level source directories are:
-        - **src/core** -- Code necessary to actually perform or use onion routing.
-        - **src/feature** -- Code used only by some onion routing
-configurations, or only for a special purpose.
-        - **src/app** -- Top-level code to run, invoke, and configure the
-lower-level code
-
-    - The new second-level source directories are:
-        - **src/core/crypto** -- High-level cryptographic protocols used in Tor
-        - **src/core/mainloop** -- Tor's event loop, connection-handling, and
-traffic-routing code.
-        - **src/core/or** -- Parts related to handling onion routing itself
-        - **src/core/proto** -- support for encoding and decoding different
-wire protocols
-        - **src/feature/api** -- Support for making Tor embeddable
-        - **src/feature/client** -- Functionality which only Tor clients need
-        - **src/feature/control** -- Controller implementation
-        - **src/feature/dirauth** -- Directory authority
-        - **src/feature/dircache** -- Directory cache
-        - **src/feature/dirclient** -- Directory client
-        - **src/feature/dircommon** -- Shared code between the other directory modules
-        - **src/feature/hibernate** -- Hibernating when Tor is out of bandwidth
-or shutting down
-        - **src/feature/hs** -- v3 onion service implementation
-        - **src/feature/hs_common** -- shared code between both onion service
-implementations
-        - **src/feature/nodelist** -- storing and accessing the list of relays on
-the network.
-        - **src/feature/relay** -- code that only relay servers and exit servers need.
-        - **src/feature/rend** -- v2 onion service implementation
-        - **src/feature/stats** -- statistics and history
-        - **src/app/config** -- configuration and state for Tor
-        - **src/app/main** -- Top-level functions to invoke the rest or Tor.
-
-  * The `tor` executable is now built in **src/app/tor** rather than **src/or/tor**.
-
-  * There are more static libraries than before that you need to build
-into your application if you want to embed Tor.  Rather than
-maintaining this list yourself, I recommend that you run `make
-show-libs` to have Tor emit a list of what you need to link.
diff --git a/doc/include.am b/doc/include.am
index 8651f845e..5e0c90b0c 100644
--- a/doc/include.am
+++ b/doc/include.am
@@ -52,7 +52,6 @@ EXTRA_DIST+= doc/asciidoc-helper.sh			\
 	     doc/HACKING/README.1st.md				\
 	     doc/HACKING/CodingStandards.md 			\
 	     doc/HACKING/CodingStandardsRust.md			\
-	     doc/HACKING/CodeStructure.md			\
 	     doc/HACKING/Fuzzing.md				\
 	     doc/HACKING/GettingStarted.md 			\
 	     doc/HACKING/GettingStartedRust.md 			\
diff --git a/src/app/app.md b/src/app/app.md
index 138e75b12..298bde75f 100644
--- a/src/app/app.md
+++ b/src/app/app.md
@@ -4,3 +4,8 @@
 The "app" directory has Tor's main entry point and configuration logic,
 and is responsible for initializing and managing the other modules in
 Tor.
+
+The modules in "app" are:
+
+   - \refdir{app/config} -- configuration and state for Tor
+   - \refdir{app/main} -- Top-level functions to invoke the rest or Tor.
diff --git a/src/feature/feature.md b/src/feature/feature.md
index acc3487e5..d9f7bd5c0 100644
--- a/src/feature/feature.md
+++ b/src/feature/feature.md
@@ -5,3 +5,26 @@ The "feature" directory has modules that Tor uses only for a particular
 role or service, such as maintaining/using an onion service, operating as a
 relay or a client, or being a directory authority.
 
+Current subdirectories are:
+
+   - \refdir{feature/api} -- Support for making Tor embeddable
+   - \refdir{feature/client} -- Functionality which only Tor clients need
+   - \refdir{feature/control} -- Controller implementation
+   - \refdir{feature/dirauth} -- Directory authority
+   - \refdir{feature/dircache} -- Directory cache
+   - \refdir{feature/dirclient} -- Directory client
+   - \refdir{feature/dircommon} -- Shared code between the other directory modules
+   - \refdir{feature/dirparse} -- Directory parsing code.
+   - \refdir{feature/hibernate} -- Hibernating when Tor is out of bandwidth
+     or shutting down
+   - \refdir{feature/hs} -- v3 onion service implementation
+   - \refdir{feature/hs_common} -- shared code between both onion service
+     implementations
+   - \refdir{feature/keymgt} -- shared code for key management between
+     relays and onion services.
+   - \refdir{feature/nodelist} -- storing and accessing the list of relays on
+     the network.
+   - \refdir{feature/relay} -- code that only relay servers and exit servers
+     need.
+   - \refdir{feature/rend} -- v2 onion service implementation
+   - \refdir{feature/stats} -- statistics and history



More information about the tor-commits mailing list