docs/doxygen/user/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 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 For historical reasons, there are directories `src/gromacs/gmxana/`,
  80 `src/gromacs/gmxlib/`, `src/gromacs/mdlib/`, and `src/gromacs/gmxpreprocess/`
  81 that do not follow the above rules.  The installed headers for these are in
  82 `src/gromacs/legacyheaders/`.  The aim is to gradually get rid of these
  83 directories and move code into proper modules.
  84
  85 Documentation organization
  86 ==========================
  87
  88 This Doxygen documentation is made of a few different parts.  Use the list
  89 below as a guideline on where to look for a particular kind of content.
  90 Since the documentation has been written over a long period of time and the
  91 approach has evolved, not all the documentation yet follows these guidelines,
  92 but this is where we are aiming at.
  93
  94 <dl>
  95 <dt>documentation pages</dt>
  96 <dd>
  97 These contain mainly overview content, from general-level introduction down
  98 into explanation of some particular areas of individual modules.
  99 These are generally the place to start familiarizing with the code or a new
 100 area of the code.
 101 They can be reached by links from the main page, and also through cross-links
 102 from places in the documentation where that information is relevant to
 103 understand the context.
 104 </dd>
 105 <dt>module documentation</dt>
 106 <dd>
 107 These contain mainly techical content, explaining the general implementation of
 108 a particular module and listing the classes, functions etc. in the module.
 109 They complement pages that describe the concepts.
 110 They can be reached from the Modules tab, and also from all individual classes,
 111 functions etc. that make up the module.
 112 </dd>
 113 <dt>class documentation</dt>
 114 <dd>
 115 These document the usage of an individual class, and in some cases that of
 116 closely related classes.  Where necessary (and time allowing), a broader
 117 overview is given on a separate page and/or in the module documentation.
 118 </dd>
 119 <dt>method documentation</dt>
 120 <dd>
 121 These document the individual method.  Typically, the class documentation or
 122 other overview content is the place to look for how different methods interact.
 123 </dd>
 124 <dt>file and namespace documentation</dt>
 125 <dd>
 126 These are generally only placeholders for links, and do not contain much else.
 127 The main content is the list of classes and other entities declared in that
 128 file.
 129 </dd>
 130 </dl>