doc/HACKING/Module.md

   1 # Modules in Tor
   2
   3 This document describes the build system and coding standards when writing a
   4 module in Tor.
   5
   6 ## What is a module?
   7
   8 In the context of the tor code base, a module is a subsystem that we can
   9 selectively enable or disable, at `configure` time.
  10
  11 Currently, tor has these modules:
  12
  13   - Relay subsystem (relay)
  14   - Directory cache system (dircache).
  15   - Directory Authority subsystem (dirauth)
  16
  17 The dirauth code is located in its own directory in `src/feature/dirauth/`.
  18
  19 The relay code is located in a directory named `src/*/*relay`, which is
  20 being progressively refactored and disabled.
  21
  22 The dircache code is located in `src/*/*dircache`.  Right now, it is
  23 disabled if and only if the relay module is disabled.  (We are treating
  24 them as separate modules because they are logically independent, not
  25 because you would actually want to run one without the other.)
  26
  27 To disable a module, pass `--disable-module-{dirauth,relay}` at configure
  28 time. All modules are currently enabled by default.
  29
  30 ## Build System
  31
  32 The changes to the build system are pretty straightforward.
  33
  34 1. Locate in the `configure.ac` file this define: `m4_define(MODULES`. It
  35    contains a list (white-space separated) of the module in tor. Add yours to
  36    the list.
  37
  38 2. Use the `AC_ARG_ENABLE([module-relay]` template for your new module. We
  39    use the "disable module" approach instead of enabling them one by one. So,
  40    by default, tor will build all the modules.
  41
  42    This will define the `HAVE_MODULE_<name>` statement which can be used in
  43    the C code to conditionally compile things for your module. And the
  44    `BUILD_MODULE_<name>` is also defined for automake files (e.g: include.am).
  45
  46 3. In the `src/core/include.am` file, locate the `MODULE_RELAY_SOURCES`
  47    value.  You need to create your own `_SOURCES` variable for your module
  48    and then conditionally add the it to `LIBTOR_A_SOURCES` if you should
  49    build the module.
  50
  51    It is then **very** important to add your SOURCES variable to
  52    `src_or_libtor_testing_a_SOURCES` so the tests can build it.
  53
  54 Finally, your module will automatically be included in the
  55 `TOR_MODULES_ALL_ENABLED` variable which is used to build the unit tests.
  56 They always build everything in order to test everything.
  57
  58 ## Coding
  59
  60 As mentioned above, a module should be isolated in its own directories,
  61 suffixed with the name of the module, in `src/*/`.
  62
  63 There are couples of "rules" you want to follow:
  64
  65 * Minimize as much as you can the number of entry points into your module.
  66   Less is always better but of course that doesn't work out for every use
  67   case. However, it is a good thing to always keep that in mind.
  68
  69 * Do **not** use the `HAVE_MODULE_<name>` define outside of the module code
  70   base. Every entry point should have a second definition if the module is
  71   disabled. For instance:
  72
  73   ```c
  74   #ifdef HAVE_MODULE_DIRAUTH
  75
  76   int sr_init(int save_to_disk);
  77
  78   #else /* HAVE_MODULE_DIRAUTH */
  79
  80   static inline int
  81   sr_init(int save_to_disk)
  82   {
  83     (void) save_to_disk;
  84     return 0;
  85   }
  86
  87   #endif /* HAVE_MODULE_DIRAUTH */
  88
  89   ```
  90
  91   The main reason for this approach is to avoid having conditional code
  92   everywhere in the code base. It should be centralized as much as possible
  93   which helps maintainability but also avoids conditional spaghetti code
  94   making the code much more difficult to follow/understand.
  95
  96 * It is possible that you end up with code that needs to be used by the rest
  97   of the code base but is still part of your module. As a good example, if
  98   you look at `src/feature/shared_random_client.c`: it contains code needed
  99   by the hidden service subsystem but mainly related to the shared random
 100   subsystem very specific to the dirauth module.
 101
 102   This is fine but try to keep it as lean as possible and never use the same
 103   filename as the one in the module. For example, this is a bad idea and
 104   should never be done:
 105
 106     - `src/feature/dirclient/shared_random.c`
 107     - `src/feature/dirauth/shared_random.c`
 108
 109 * When you include headers from the module, **always** use the full module
 110   path in your statement. Example:
 111
 112 ```c
 113 #include "feature/dirauth/dirvote.h"`
 114 ```
 115
 116   The main reason is that we do **not** add the module include path by default
 117   so it needs to be specified. But also, it helps our human brain understand
 118   which part comes from a module or not.
 119
 120   Even **in** the module itself, use the full include path like above.