mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-23 20:03:31 +01:00
Remove now-superseded part of doc/HACKING/design.
This commit is contained in:
Nick Mathewson
parent
76e8effc7b
commit
4bf73dfa26
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user