docs/dev-manual/codelayout.rst

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