doxygen/codelayout.md

   1 General organization of the code and documentation {#page_codelayout}
   2 ==================================================
   3
   4 Source code organization
   5 ========================
   6
   7 The source code for \Gromacs is under the `src/` subdirectory
   8 (except for an analysis tool template, which is under `share/template/`).
   9 The subfolders under this directory are:
  10 <dl>
  11 <dt>`src/gromacs/`</dt>
  12 <dd>
  13 The code under this directory is built into a single library,
  14 `libgromacs`.  Installed headers are also located in this hierarchy.
  15 This is the main part of the code, and is organized into further subdirectories
  16 as _modules_ (see below)
  17 </dd>
  18 <dt>`src/programs/`</dt>
  19 <dd>
  20 \Gromacs executables are built from code under this directory.
  21 Although some build options can change this, there is typically only a single
  22 binary, `gmx`, built.
  23 </dd>
  24 \if libapi
  25 <dt>`src/testutils/`</dt>
  26 <dd>
  27 Shared utility code for writing unit tests is found under this directory.
  28 </dd>
  29 <dt>`src/external/`</dt>
  30 <dd>
  31 This directory contains bundled source code for various libraries and
  32 components that \Gromacs uses internally.
  33 </dd>
  34 <dt>`src/contrib/`</dt>
  35 <dd>
  36 This directory contains collection of less well maintained code that may or may
  37 not compile.  It is not included in the build.
  38 </dd>
  39 \endif
  40 </dl>
  41
  42 Organization under `src/gromacs/`
  43 ---------------------------------
  44
  45 There is no code directly under `src/gromacs/`, except for some public API
  46 convenience headers.  The code is organized into subdirectories, denoted
  47 _modules_.  Each module consists of a set of routines that do some well-defined
  48 task or a collection of tasks.  Installed headers are a subset of the headers
  49 in `src/gromacs/` and in the module subdirectories.  They are installed into a
  50 corresponding hierarchy under `include/gromacs/` in the installation directory.
  51 Comments at the top of the header files contain a note about their visibility:
  52 public (installed), intra-library (can be used from inside the library), or
  53 intra-module/intra-file.
  54
  55 Each module directory contains one or more `<file>.c/.cpp` files, each of which
  56 has a corresponding `<file>.h` file that declares the external API in that file
  57 (there are some exceptions, but this gives a general picture).
  58 Typically, a C++ file declares a class of the same or similar name, but may
  59 also declare some related classes.
  60 There can also be a `<file>-impl.h` file that declares classes or functions that
  61 are not accessible outside the module.  In most cases, declarations that
  62 are not used outside a single source file are in the source file.
  63
  64 Unit tests, and data required for them, are in a `tests/` subdirectory under
  65 the module directory.
  66 \if libapi
  67 See \ref page_unittesting for more details.
  68 \endif
  69
  70 When compiling, the include search path is set to `src/`.  This means that
  71 source files include headers as
  72
  73     #include "gromacs/<module>/<file>.h"
  74
  75 The following is also possible for intra-module headers:
  76
  77     #include "<file>.h"
  78
  79 Header files include other headers using
  80
  81     #include "../<othermodule>/<file>.h"
  82
  83 because relative paths work best for installed headers.  For non-installed
  84 headers, the path relative to `src/` is sometimes also used.
  85
  86 For historical reasons, there are directories `src/gromacs/gmxana/`,
  87 `src/gromacs/gmxlib/`, `src/gromacs/mdlib/`, and `src/gromacs/gmxpreprocess/`
  88 that do not follow the above rules.  The installed headers for these are in
  89 `src/gromacs/legacyheaders/`.  The aim is to gradually get rid of these
  90 directories and move code into proper modules.
  91
  92 Documentation organization
  93 ==========================
  94
  95 This Doxygen documentation is made of a few different parts.  Use the list
  96 below as a guideline on where to look for a particular kind of content.
  97 Since the documentation has been written over a long period of time and the
  98 approach has evolved, not all the documentation yet follows these guidelines,
  99 but this is where we are aiming at.
 100
 101 <dl>
 102 <dt>documentation pages</dt>
 103 <dd>
 104 These contain mainly overview content, from general-level introduction down
 105 into explanation of some particular areas of individual modules.
 106 These are generally the place to start familiarizing with the code or a new
 107 area of the code.
 108 They can be reached by links from the main page, and also through cross-links
 109 from places in the documentation where that information is relevant to
 110 understand the context.
 111 </dd>
 112 <dt>module documentation</dt>
 113 <dd>
 114 These contain mainly techical content, explaining the general implementation of
 115 a particular module and listing the classes, functions etc. in the module.
 116 They complement pages that describe the concepts.
 117 They can be reached from the Modules tab, and also from all individual classes,
 118 functions etc. that make up the module.
 119 </dd>
 120 <dt>class documentation</dt>
 121 <dd>
 122 These document the usage of an individual class, and in some cases that of
 123 closely related classes.  Where necessary (and time allowing), a broader
 124 overview is given on a separate page and/or in the module documentation.
 125 </dd>
 126 <dt>method documentation</dt>
 127 <dd>
 128 These document the individual method.  Typically, the class documentation or
 129 other overview content is the place to look for how different methods interact.
 130 </dd>
 131 <dt>file and namespace documentation</dt>
 132 <dd>
 133 These are generally only placeholders for links, and do not contain much else.
 134 The main content is the list of classes and other entities declared in that
 135 file.
 136 </dd>
 137 </dl>