commit 4bf73dfa261a1706659bce42a60f1af804a525f6 Author: Nick Mathewson <nickm@torproject.org> Date: Mon Nov 4 11:52:49 2019 -0500 Remove now-superseded part of doc/HACKING/design. --- doc/HACKING/design/01.00-lib-overview.md | 171 ------------------------------- 1 file changed, 171 deletions(-) diff --git a/doc/HACKING/design/01.00-lib-overview.md b/doc/HACKING/design/01.00-lib-overview.md deleted file mode 100644 index 58a92f406..000000000 --- a/doc/HACKING/design/01.00-lib-overview.md +++ /dev/null @@ -1,171 +0,0 @@ - -## Library code in Tor. - -Most of Tor's utility code is in modules in the `src/lib` subdirectory. In -general, this code is not necessarily Tor-specific, but is instead possibly -useful for other applications. - -This code includes: - - * Compatibility wrappers, to provide a uniform API across different - platforms. - - * Library wrappers, to provide a tor-like API over different libraries - that Tor uses for things like compression and cryptography. - - * Containers, to implement some general-purpose data container types. - -The modules in `src/lib` are currently well-factored: each one depends -only on lower-level modules. You can see an up-to-date list of the -modules sorted from lowest to highest level by running -`./scripts/maint/practracker/includes.py --toposort`. - -As of this writing, the library modules are (from lowest to highest -level): - - * `lib/cc` -- Macros for managing the C compiler and - language. Includes macros for improving compatibility and clarity - across different C compilers. - - * `lib/version` -- Holds the current version of Tor. - - * `lib/testsupport` -- Helpers for making test-only code and test - mocking support. - - * `lib/defs` -- Lowest-level constants used in many places across the - code. - - * `lib/subsys` -- Types used for declaring a "subsystem". A subsystem - is a module with support for initialization, shutdown, - configuration, and so on. - - * `lib/conf` -- Types and macros used for declaring configuration - options. - - * `lib/arch` -- Compatibility functions and macros for handling - differences in CPU architecture. - - * `lib/err` -- Lowest-level error handling code: responsible for - generating stack traces, handling raw assertion failures, and - otherwise reporting problems that might not be safe to report - via the regular logging module. - - * `lib/malloc` -- Wrappers and utilities for memory management. - - * `lib/intmath` -- Utilities for integer mathematics. - - * `lib/fdio` -- Utilities and compatibility code for reading and - writing data on file descriptors (and on sockets, for platforms - where a socket is not a kind of fd). - - * `lib/lock` -- Compatibility code for declaring and using locks. - Lower-level than the rest of the threading code. - - * `lib/ctime` -- Constant-time implementations for data comparison - and table lookup, used to avoid timing side-channels from standard - implementations of memcmp() and so on. - - * `lib/string` -- Low-level compatibility wrappers and utility - functions for string manipulation. - - * `lib/wallclock` -- Compatibility and utility functions for - inspecting and manipulating the current (UTC) time. - - * `lib/osinfo` -- Functions for inspecting the version and - capabilities of the operating system. - - * `lib/smartlist_core` -- The bare-bones pieces of our dynamic array - ("smartlist") implementation. There are higher-level pieces, but - these ones are used by (and therefore cannot use) the logging code. - - * `lib/log` -- Implements the logging system used by all higher-level - Tor code. You can think of this as the logical "midpoint" of the - library code: much of the higher-level code is higher-level - _because_ it uses the logging module, and much of the lower-level - code is specifically written to avoid having to log, because the - logging module depends on it. - - * `lib/container` -- General purpose containers, including dynamic arrays - ("smartlists"), hashtables, bit arrays, weak-reference-like "handles", - bloom filters, and a bit more. - - * `lib/trace` -- A general-purpose API for introducing - function-tracing functionality into Tor. Currently not much used. - - * `lib/thread` -- Threading compatibility and utility functionality, - other than low-level locks (which are in `lib/lock`) and - workqueue/threadpool code (which belongs in `lib/evloop`). - - * `lib/term` -- Code for terminal manipulation functions (like - reading a password from the user). - - * `lib/memarea` -- A data structure for a fast "arena" style allocator, - where the data is freed all at once. Used for parsing. - - * `lib/encoding` -- Implementations for encoding data in various - formats, datatypes, and transformations. - - * `lib/dispatch` -- A general-purpose in-process message delivery - system. Used by `lib/pubsub` to implement our inter-module - publish/subscribe system. - - * `lib/sandbox` -- Our Linux seccomp2 sandbox implementation. - - * `lib/pubsub` -- Code and macros to implement our publish/subscribe - message passing system. - - * `lib/fs` -- Utility and compatibility code for manipulating files, - filenames, directories, and so on. - - * `lib/confmgt` -- Code to parse, encode, and manipulate our - configuration files, state files, and so forth. - - * `lib/crypt_ops` -- Cryptographic operations. This module contains - wrappers around the cryptographic libraries that we support, - and implementations for some higher-level cryptographic - constructions that we use. - - * `lib/meminfo` -- Functions for inspecting our memory usage, if the - malloc implementation exposes that to us. - - * `lib/time` -- Higher level time functions, including fine-gained and - monotonic timers. - - * `lib/math` -- Floating-point mathematical utilities, including - compatibility code, and probability distributions. - - * `lib/buf` -- A general purpose queued buffer implementation, - similar to the BSD kernel's "mbuf" structure. - - * `lib/net` -- Networking code, including address manipulation, - compatibility wrappers, - - * `lib/compress` -- A compatibility wrapper around several - compression libraries, currently including zlib, zstd, and lzma. - - * `lib/geoip` -- Utilities to manage geoip (IP to country) lookups - and formats. - - * `lib/tls` -- Compatibility wrappers around the library (NSS or - OpenSSL, depending on configuration) that Tor uses to implement the - TLS link security protocol. - - * `lib/evloop` -- Tools to manage the event loop and related - functionality, in order to implement asynchronous networking, - timers, periodic events, and other scheduling tasks. - - * `lib/process` -- Utilities and compatibility code to launch and - manage subprocesses. - -### What belongs in lib? - -In general, if you can imagine some program wanting the functionality -you're writing, even if that program had nothing to do with Tor, your -functionality belongs in lib. - -If it falls into one of the existing "lib" categories, your -functionality belongs in lib. - -If you are using platform-specific `#ifdef`s to manage compatibility -issues among platforms, you should probably consider whether you can -put your code into lib.