HACKING

   1 Naming conventions:
   2
   3 include files:
   4 - _lib: library without need for a process
   5 - _service: library that needs a service process
   6 - _plugin: plugin definition
   7 - _protocol: structs used in network protocol
   8 - exceptions:
   9   * gnunet_config.h      --- generated
  10   * platform.h           --- first included
  11   * plibc.h              --- external library
  12   * gnunet_common.h      --- fundamental routines
  13   * gnunet_directories.h --- generated
  14   * gettext.h            --- external library
  15
  16
  17 binaries:
  18 - gnunet-service-xxx: service process (has listen socket)
  19 - gnunet-daemon-xxx: daemon process (no listen socket)
  20 - gnunet-helper-xxx[-yyy]: SUID helper for module xxx
  21 - gnunet-yyy: command-line tool for end-users
  22 - libgnunet_plugin_xxx_yyy.so: plugin for API xxx
  23 - libgnunetxxx.so: library for API xxx
  24
  25
  26 logging:
  27 - services and daemons use their directory name in GNUNET_log_setup (i.e. 'core')
  28   and log using plain 'GNUNET_log'.
  29 - command-line tools use their full name in GNUNET_log_setup (i.e. 'gnunet-publish')
  30   and log using plain 'GNUNET_log'.
  31 - service access libraries log using 'GNUNET_log_from' and use
  32   'DIRNAME-api' for the component (i.e. 'core-api')
  33 - pure libraries (without associated service) use 'GNUNET_log_from' with
  34   the component set to their library name (without lib
  35   or '.so'), which should also be their directory name (i.e. 'nat')
  36 - plugins should use 'GNUNET_log_from' with the directory name
  37   and the plugin name combined to produce the component name (i.e. 'transport-tcp').
  38 - logging should be unified per-file by defining a LOG macro with the
  39   appropriate arguments, along these lines:
  40   #define LOG(kind,...) GNUNET_log_from (kind, "example-api",__VA_ARGS__)
  41
  42
  43 configuration:
  44 - paths (that are substituted in all filenames) are in PATHS (have as few as possible)
  45 - globals for the daemon are in [gnunetd] (for now, have as few as possible!)
  46 - all options for a particular module (src/MODULE) are under [MODULE]
  47 - options for a plugin of a module are under [MODULE-PLUGINNAME]
  48 - options only for debugging / testing / profiling are under [TESTING],
  49   together with the options for the testing module itself
  50
  51
  52 exported symbols:
  53 - must start with "GNUNET_modulename_" and be defined in "modulename.c"
  54 - exceptions: those defined in gnunet_common.h
  55
  56
  57 private (library-internal) symbols (including structs & macros):
  58 - must NOT start with any prefix
  59 - must not be exported in a way that linkers could use them or
  60   other libraries might see them via headers; they must be either
  61   declared/defined in C source files or in headers that are in
  62   the respective directory under src/modulename/ and NEVER be
  63   declared in src/include/.
  64
  65 testcases:
  66 - must be called "test_module-under-test_case-description.c"
  67 - "case-description" maybe omitted if there is only one test
  68
  69
  70 performance tests:
  71 - must be called "perf_module-under-test_case-description.c"
  72 - "case-description" maybe omitted if there is only one performance test
  73 - Must only be run if HAVE_BENCHMARKS is satisfied
  74
  75
  76 src/ directories:
  77 - gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm)
  78 - gnunet-service-NAME: service processes with accessor library (i.e., gnunet-service-arm)
  79 - libgnunetNAME: accessor library (_service.h-header) or standalone library (_lib.h-header)
  80 - gnunet-daemon-NAME: daemon process without accessor library (i.e., gnunet-daemon-hostlist) and no GNUnet management port
  81 - libgnunet_plugin_DIR_NAME: loadable plugins (i.e., libgnunet_plugin_transport_tcp)
  82
  83
  84 Coding style:
  85 - GNU guidelines generally apply
  86 - declare only one variable per line, so
  87
  88   int i;
  89   int j;
  90
  91   instead of
  92
  93   int i,j;
  94 - Indentation should be done using the 'pre-commit' script in the top-level
  95   directory using the patched (!) GNU indent.  See also the posting at
  96   https://gnunet.org/gnunetindentation
  97
  98
  99 Build-system:
 100
 101 If you have code that is likely not to compile or build rules you might want to not
 102 trigger for most developers, use "if HAVE_EXPERIMENTAL" in your Makefile.am.  Then
 103 it is OK to (temporarily) add non-compiling (or known-to-not-port) code.
 104
 105 If you want to compile all testcases but NOT run them, run configure with the
 106 --enable-test-suppression option.
 107
 108 If you want to run all testcases, including those that take a while, run configure with the
 109 --enable-expensive-testcases option.
 110
 111 If you want to compile and run benchmarks, run configure with the
 112 --enable-benchmarks option.
 113
 114 If you want to obtain code coverage results, run configure with the
 115 --enable-coverage option and run the coverage.sh script in contrib/.
 116
 117
 118 Minimum file-sharing system (in order of dependency):
 119 gnunet-service-arm
 120 gnunet-service-transport
 121 gnunet-service-core
 122 gnunet-daemon-hostlist
 123 gnunet-daemon-topology
 124 gnunet-service-statistics
 125 gnunet-service-datastore
 126 gnunet-service-datacache
 127 gnunet-service-dht
 128 gnunet-service-fs