mirrors/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2025-02-24 06:48:05 +01:00
Code Issues Projects Releases Wiki Activity

doc(hacking): enhance markdown style

Browse source
This commit is contained in:
Antoine Veuiller 2019-08-21 16:22:08 +02:00
parent a5911c4551
commit 0d6c8eed49
1 changed files with 72 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
doc/HACKING/CodeStructure.md
View file

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