docs/dev-manual/overview.rst

   1 Codebase overview
   2 =================
   3
   4 The root directory of the |Gromacs| repository only contains :file:`CMakeLists.txt`
   5 (the root file for the CMake build system), a few files supporting the build
   6 system, and a few standard informative files (:file:`README` etc.).  The
   7 :file:`INSTALL` is generated for source packages from
   8 :file:`docs/install-guide/index.rst`.
   9
  10 All other content is in the following top-level directories:
  11
  12 :file:`admin/`
  13   Contains various scripts for developer use, as well as configuration files
  14   and scripts for some of the tools used.
  15 :file:`cmake/`
  16   Contains code fragments and find modules for CMake.
  17   Some content here is copied and/or adapted from newer versions of CMake than
  18   the minimum currently supported.
  19   Default suppression file for valgrind is also included here.
  20 :file:`docs/`
  21   Contains the build system logic and source code for all documentation, both
  22   user-facing and developer-facing.  Some of the documentation is generated
  23   from the source code under :file:`src/`; see :ref:`dev-doc-layout`.
  24   This directory also contains some developer scripts that use the Doxygen
  25   documentation for their operation.
  26 :file:`scripts/`
  27   Contains the templates for :file:`GMXRC` script, some other installed scripts,
  28   as well as installation rules for all these scripts.
  29 :file:`share/`
  30   Contains data files that will be installed under :file:`share/`.  These
  31   include a template for writing C++ analysis tools, and data files used by
  32   |Gromacs|.
  33 :file:`src/`
  34   Contains all source code.  See :ref:`dev-source-layout`.
  35 :file:`tests/`
  36   Contains build system logic for some high-level tests.  Currently, only the
  37   regression test build system logic and cppcheck rules are in this directory,
  38   while other tests are under :file:`src/`.
  39
  40 .. _dev-source-layout:
  41
  42 Source code organization
  43 ------------------------
  44
  45 The following figure shows a high-level view of components of what gets built
  46 from the source code under :file:`src/` and how the code is organized.
  47 With default options, the green and white components are built as part of the
  48 default target.  If ``GMX_BUILD_MDRUN_ONLY`` is ``ON``, then the blue and white
  49 components are built instead; :file:`libgromacs_mdrun` is built from a subset
  50 of the code used for :file:`libgromacs`.
  51 The gray parts are for testing, and are by default only built as part of the
  52 ``tests`` target, but if ``GMX_DEVELOPER_BUILD`` is ``ON``, then these are
  53 included in the default build target.
  54 See :doc:`testutils` for details of the testing side.
  55
  56 .. digraph:: dev_high_level_components
  57
  58    concentrate = yes
  59    node [ shape=box, style=filled, width=2 ]
  60
  61    subgraph {
  62      rank = same
  63      externals [
  64        label="externals\nsrc/external/", group=common, style=rounded
  65      ]
  66      gtest [
  67        label="Google Test & Mock\nsrc/external/gmock-1.7.0/", group=test
  68        style="rounded,filled", fillcolor="0 0 0.9"
  69      ]
  70    }
  71    subgraph {
  72      rank = same
  73      libgromacs [
  74        label="libgromacs\nsrc/gromacs/", group=gmx, fillcolor="0.33 0.3 1"
  75      ]
  76      libgromacs_mdrun [
  77        label="libgromacs_mdrun\nsrc/gromacs/", group=mdrun, fillcolor="0.66 0.3 1"
  78      ]
  79    }
  80    testutils [
  81      label="testutils\nsrc/testutils/", group=test
  82      style="rounded,filled", fillcolor="0 0 0.9"
  83    ]
  84    mdrun_objlib [
  85      label="mdrun object lib.\nsrc/programs/mdrun/", group=common, style=rouded
  86    ]
  87    subgraph {
  88      rank = same
  89      gmx [
  90        label="gmx\nsrc/programs/", group=gmx, fillcolor="0.33 0.3 1"
  91      ]
  92      mdrun [
  93        label="mdrun\nsrc/programs/", group=mdrun, fillcolor="0.66 0.3 1"
  94      ]
  95      tests [
  96        label="test binaries\nsrc/.../tests/", group=test
  97        style="rounded,filled", fillcolor="0 0 0.9"
  98      ]
  99      template [
 100        label="analysis template\nshare/template/", group=common
 101        fillcolor="0.33 0.3 1"
 102      ]
 103
 104      gmx -> template [ style=invis, constraint=no ]
 105      template -> mdrun [ style=invis, constraint=no ]
 106    }
 107
 108    libgromacs -> externals
 109    libgromacs_mdrun -> externals
 110    mdrun_objlib -> libgromacs
 111    gmx -> libgromacs
 112    gmx -> mdrun_objlib
 113    mdrun -> libgromacs_mdrun
 114    mdrun -> mdrun_objlib
 115    testutils -> externals
 116    testutils -> gtest
 117    testutils -> libgromacs
 118    tests -> gtest
 119    tests -> libgromacs
 120    tests -> mdrun_objlib
 121    tests -> testutils
 122    template -> libgromacs
 123
 124    template -> mdrun_objlib [ style=invis ]
 125    mdrun_objlib -> externals [ style=invis ]
 126
 127 All the source code (except for the analysis template) is under the
 128 :file:`src/` directory.  Only a few files related to the build system are
 129 included at the root level.  All actual code is in subdirectories:
 130
 131 :file:`src/gromacs/`
 132   The code under this directory is built into a single library,
 133   :file:`libgromacs`.  Installed headers are also located in this hierarchy.
 134   This is the main part of the code, and is organized into further subdirectories
 135   as *modules*.  See below for details.
 136 :file:`src/programs/`
 137   |Gromacs| executables are built from code under this directory.
 138   Although some build options can change this, there is typically only a single
 139   binary, :file:`gmx`, built.
 140
 141 :file:`src/{...}/tests/`
 142   Various subdirectories under :file:`src/` contain a subdirectory named
 143   :file:`tests/`.  The code from each such directory is built into a test
 144   binary.  Some such directories also provide shared test code as object
 145   libraries that is linked into multiple test binaries from different folders.
 146   See :doc:`testutils` for details.
 147 :file:`src/testutils/`
 148   Contains shared utility code for writing Google Test tests.
 149   See :doc:`testutils` for details.
 150 :file:`src/external/`
 151   Contains bundled source code for various libraries and
 152   components that |Gromacs| uses internally.  All the code from these
 153   directories are built using our custom build rules into :file:`libgromacs`,
 154   or in some cases into the test binaries.  Some CMake options change which
 155   parts of this code are included in the build.
 156 :file:`src/contrib/`
 157   Contains collection of less well maintained code that may or may
 158   not compile.  It is not included in the build.
 159 :file:`src/contrib/fftw/`
 160   As an exception to the above, this folder contains the build system code for
 161   downloading and building FFTW to be included into :file:`libgromacs`.
 162
 163 When compiling, the include search path is set to :file:`src/`.
 164 Some directories from under :file:`src/external/` may also be included,
 165 depending on the compilation options.
 166
 167 Organization under :file:`src/gromacs/`
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 The :file:`libgromacs` library is built from code under :file:`src/gromacs/`.
 171 Again, the top-level directory contains build and installation rules for the
 172 library, and :dfn:`public API convenience headers`.  These convenience headers
 173 provide the main installed headers that other code can use.  They do not
 174 contain any declarations, but only include a suitable set of headers from the
 175 subdirectories.  They typically also contain high-level Doxygen documentation
 176 for the subdirectory with the same name: :file:`{module}.h` corresponds to
 177 :file:`{module}/`.
 178
 179 The code is organized into subdirectories.  These subdirectories are denoted as
 180 :dfn:`modules` throughout this documentation.  Each module consists of a set
 181 of routines that do some well-defined task or a collection of tasks.
 182
 183 Installed headers are a subset of the headers under :file:`src/gromacs/`.
 184 They are installed into a corresponding hierarchy under
 185 :file:`include/gromacs/` in the installation directory.
 186 Comments at the top of the header files contain a note about their visibility:
 187 public (installed), intra-library (can be used from inside the library), or
 188 intra-module/intra-file.
 189
 190 See :doc:`naming` for some common naming patterns for files that can help
 191 locating declarations.
 192
 193 Tests, and data required for them, are in a ``tests/`` subdirectory under
 194 the module directory.
 195 See :doc:`testutils` for more details.
 196
 197 For historical reasons, there are directories :file:`src/gromacs/gmxana/`,
 198 :file:`src/gromacs/gmxlib/`, :file:`src/gromacs/mdlib/`, and
 199 :file:`src/gromacs/gmxpreprocess/` that do not follow the above rules.
 200 The installed headers for these are in :file:`src/gromacs/legacyheaders/`.
 201 The aim is to gradually get rid of these directories and move code into proper
 202 modules.
 203
 204 .. _dev-doc-layout:
 205
 206 Documentation organization
 207 --------------------------
 208
 209 All documentation (including this developer guide) is produced from source
 210 files under :file:`docs/`, except for some command-line help that is generated
 211 from the source code (by executing the compiled :file:`gmx` binary).
 212 The build system provides various custom targets that build the documentation.
 213
 214 :file:`docs/fragments/`
 215   Contains reStructuredText fragments used through ``.. include::`` mechanism
 216   from various places in the documentation.
 217
 218 User documentation
 219 ^^^^^^^^^^^^^^^^^^
 220
 221 :file:`docs/install-guide/`
 222   Contains reStructuredText source files for building the install guide section
 223   of the user documentation, as well as the :file:`INSTALL` file for the source
 224   package.
 225   The build rules are in :file:`docs/CMakeLists.txt`.
 226 :file:`docs/manual/`
 227   Contains LaTeX source files and build rules for the reference (PDF) manual.
 228 :file:`docs/user-guide/`
 229   Contains reStructuredText source files for building the user guide section
 230   of the user documentation.
 231   The build rules are in :file:`docs/CMakeLists.txt`.
 232
 233 Unix man pages
 234 ^^^^^^^^^^^^^^
 235
 236 Man pages for programs are generated by running the :file:`gmx` executable
 237 after compiling it, and then using Sphinx on the reStructuredText files that
 238 :file:`gmx` writes out.
 239
 240 The build rules for the man pages are in :file:`docs/CMakeLists.txt`.
 241
 242 Developer guide
 243 ^^^^^^^^^^^^^^^
 244
 245 :file:`docs/dev-manual/`
 246   Contains reStructuredText source files used to build the developer guide.
 247   The build rules are in :file:`docs/CMakeLists.txt`.
 248
 249 The organization of the developer guide is explained on the :doc:`front page of
 250 the guide <index>`.
 251
 252 Doxygen documentation
 253 ^^^^^^^^^^^^^^^^^^^^^
 254
 255 :file:`docs/doxygen/`
 256   Contains the build rules and some overview content for the Doxygen
 257   documentation.
 258   See :doc:`doxygen` for details of how the Doxygen documentation is built and
 259   organized.
 260
 261 .. TODO: Create a separate page (at the front of the developer guide, and/or at
 262    the main index.rst) that describes the documentation from readers'
 263    perspective, and move relevant content there.  This should contain just an
 264    overview of how the documentation is organized in the source tree.
 265
 266 The Doxygen documentation is made of a few different parts.  Use the list
 267 below as a guideline on where to look for a particular kind of content.
 268 Since the documentation has been written over a long period of time and the
 269 approach has evolved, not all the documentation yet follows these guidelines,
 270 but this is where we are aiming at.
 271
 272 documentation pages
 273   These contain mainly overview content, from general-level introduction down
 274   into explanation of some particular areas of individual modules.
 275   These are generally the place to start familiarizing with the code or a new
 276   area of the code.
 277   They can be reached by links from the main page, and also through cross-links
 278   from places in the documentation where that information is relevant to
 279   understand the context.
 280 module documentation
 281   These contain mainly techical content, explaining the general implementation of
 282   a particular module and listing the classes, functions etc. in the module.
 283   They complement pages that describe the concepts.
 284   They can be reached from the Modules tab, and also from all individual classes,
 285   functions etc. that make up the module.
 286 class documentation
 287   These document the usage of an individual class, and in some cases that of
 288   closely related classes.  Where necessary (and time allowing), a broader
 289   overview is given on a separate page and/or in the module documentation.
 290 method documentation
 291   These document the individual method.  Typically, the class documentation or
 292   other overview content is the place to look for how different methods interact.
 293 file and namespace documentation
 294   These are generally only placeholders for links, and do not contain much else.
 295   The main content is the list of classes and other entities declared in that
 296   file.