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 \if libapi
  42 \subpage page_modulegraph
  43 \endif
  44
  45 Organization under `src/gromacs/`
  46 ---------------------------------
  47
  48 There is no code directly under `src/gromacs/`, except for some public API
  49 convenience headers.  The code is organized into subdirectories, denoted
  50 _modules_.  Each module consists of a set of routines that do some well-defined
  51 task or a collection of tasks.  Installed headers are a subset of the headers
  52 in `src/gromacs/` and in the module subdirectories.  They are installed into a
  53 corresponding hierarchy under `include/gromacs/` in the installation directory.
  54 Comments at the top of the header files contain a note about their visibility:
  55 public (installed), intra-library (can be used from inside the library), or
  56 intra-module/intra-file.
  57
  58 Each module directory contains one or more `<file>.c/.cpp` files, each of which
  59 has a corresponding `<file>.h` file that declares the external API in that file
  60 (there are some exceptions, but this gives a general picture).
  61 Typically, a C++ file declares a class of the same or similar name, but may
  62 also declare some related classes.
  63 There can also be a `<file>-impl.h` file that declares classes or functions that
  64 are not accessible outside the module.  In most cases, declarations that
  65 are not used outside a single source file are in the source file.
  66
  67 Unit tests, and data required for them, are in a `tests/` subdirectory under
  68 the module directory.
  69 \if libapi
  70 See \ref page_unittesting for more details.
  71 \endif
  72
  73 When compiling, the include search path is set to `src/`.  This means that
  74 files include headers as
  75
  76     #include "gromacs/<module>/<file>.h"
  77
  78 The following is also possible for intra-module headers:
  79
  80     #include "<file>.h"
  81
  82 For historical reasons, there are directories `src/gromacs/gmxana/`,
  83 `src/gromacs/gmxlib/`, `src/gromacs/mdlib/`, and `src/gromacs/gmxpreprocess/`
  84 that do not follow the above rules.  The installed headers for these are in
  85 `src/gromacs/legacyheaders/`.  The aim is to gradually get rid of these
  86 directories and move code into proper modules.
  87
  88 Documentation organization
  89 ==========================
  90
  91 This Doxygen documentation is made of a few different parts.  Use the list
  92 below as a guideline on where to look for a particular kind of content.
  93 Since the documentation has been written over a long period of time and the
  94 approach has evolved, not all the documentation yet follows these guidelines,
  95 but this is where we are aiming at.
  96
  97 <dl>
  98 <dt>documentation pages</dt>
  99 <dd>
 100 These contain mainly overview content, from general-level introduction down
 101 into explanation of some particular areas of individual modules.
 102 These are generally the place to start familiarizing with the code or a new
 103 area of the code.
 104 They can be reached by links from the main page, and also through cross-links
 105 from places in the documentation where that information is relevant to
 106 understand the context.
 107 </dd>
 108 <dt>module documentation</dt>
 109 <dd>
 110 These contain mainly techical content, explaining the general implementation of
 111 a particular module and listing the classes, functions etc. in the module.
 112 They complement pages that describe the concepts.
 113 They can be reached from the Modules tab, and also from all individual classes,
 114 functions etc. that make up the module.
 115 </dd>
 116 <dt>class documentation</dt>
 117 <dd>
 118 These document the usage of an individual class, and in some cases that of
 119 closely related classes.  Where necessary (and time allowing), a broader
 120 overview is given on a separate page and/or in the module documentation.
 121 </dd>
 122 <dt>method documentation</dt>
 123 <dd>
 124 These document the individual method.  Typically, the class documentation or
 125 other overview content is the place to look for how different methods interact.
 126 </dd>
 127 <dt>file and namespace documentation</dt>
 128 <dd>
 129 These are generally only placeholders for links, and do not contain much else.
 130 The main content is the list of classes and other entities declared in that
 131 file.
 132 </dd>
 133 </dl>