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   See :doc:`build-system` for details of the build system.
  21 :file:`docs/`
  22   Contains the build system logic and source code for all documentation, both
  23   user-facing and developer-facing.  Some of the documentation is generated
  24   from the source code under :file:`src/`; see :ref:`dev-doc-layout`.
  25   This directory also contains some developer scripts that use the Doxygen
  26   documentation for their operation.
  27 :file:`scripts/`
  28   Contains the templates for :file:`GMXRC` script, some other installed scripts,
  29   as well as installation rules for all these scripts.
  30 :file:`share/`
  31   Contains data files that will be installed under :file:`share/`.  These
  32   include a template for writing C++ analysis tools, and data files used by
  33   |Gromacs|.
  34 :file:`src/`
  35   Contains all source code.  See :ref:`dev-source-layout`.
  36 :file:`tests/`
  37   Contains build system logic for some high-level tests.  Currently, only the
  38   regression test build system logic, 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 The build system is described in detail in :doc:`build-system`.
  48 With default options, the green and white components are built as part of the
  49 default target.  If ``GMX_BUILD_MDRUN_ONLY`` is ``ON``, then the blue and white
  50 components are built instead; :file:`libgromacs_mdrun` is built from a subset
  51 of the code used for :file:`libgromacs`.
  52 The gray parts are for testing, and are by default only built as part of the
  53 ``tests`` target, but if ``GMX_DEVELOPER_BUILD`` is ``ON``, then these are
  54 included in the default build target.
  55 See :doc:`testutils` for details of the testing side.
  56
  57 .. digraph:: dev_high_level_components
  58
  59    concentrate = yes
  60    node [ shape=box, style=filled, width=2 ]
  61
  62    subgraph {
  63      rank = same
  64      externals [
  65        label="externals\nsrc/external/", group=common, style=rounded
  66      ]
  67      gtest [
  68        label="Google Test & Mock\nsrc/external/gmock-1.7.0/", group=test
  69        style="rounded,filled", fillcolor="0 0 0.9"
  70      ]
  71    }
  72    subgraph {
  73      rank = same
  74      libgromacs [
  75        label="libgromacs\nsrc/gromacs/", group=gmx, fillcolor="0.33 0.3 1"
  76      ]
  77      libgromacs_mdrun [
  78        label="libgromacs_mdrun\nsrc/gromacs/", group=mdrun, fillcolor="0.66 0.3 1"
  79      ]
  80    }
  81    testutils [
  82      label="testutils\nsrc/testutils/", group=test
  83      style="rounded,filled", fillcolor="0 0 0.9"
  84    ]
  85    mdrun_objlib [
  86      label="mdrun object lib.\nsrc/programs/mdrun/", group=common, style=rouded
  87    ]
  88    subgraph {
  89      rank = same
  90      gmx [
  91        label="gmx\nsrc/programs/", group=gmx, fillcolor="0.33 0.3 1"
  92      ]
  93      mdrun [
  94        label="mdrun\nsrc/programs/", group=mdrun, fillcolor="0.66 0.3 1"
  95      ]
  96      tests [
  97        label="test binaries\nsrc/.../tests/", group=test
  98        style="rounded,filled", fillcolor="0 0 0.9"
  99      ]
 100      template [
 101        label="analysis template\nshare/template/", group=common
 102        fillcolor="0.33 0.3 1"
 103      ]
 104
 105      gmx -> template [ style=invis, constraint=no ]
 106      template -> mdrun [ style=invis, constraint=no ]
 107    }
 108
 109    libgromacs -> externals
 110    libgromacs_mdrun -> externals
 111    mdrun_objlib -> libgromacs
 112    gmx -> libgromacs
 113    gmx -> mdrun_objlib
 114    mdrun -> libgromacs_mdrun
 115    mdrun -> mdrun_objlib
 116    testutils -> externals
 117    testutils -> gtest
 118    testutils -> libgromacs
 119    tests -> gtest
 120    tests -> libgromacs
 121    tests -> mdrun_objlib
 122    tests -> testutils
 123    template -> libgromacs
 124
 125    template -> mdrun_objlib [ style=invis ]
 126    mdrun_objlib -> externals [ style=invis ]
 127
 128 All the source code (except for the analysis template) is under the
 129 :file:`src/` directory.  Only a few files related to the build system are
 130 included at the root level.  All actual code is in subdirectories:
 131
 132 :file:`src/gromacs/`
 133   The code under this directory is built into a single library,
 134   :file:`libgromacs`.  Installed headers are also located in this hierarchy.
 135   This is the main part of the code, and is organized into further subdirectories
 136   as *modules*.  See below for details.
 137 :file:`src/programs/`
 138   |Gromacs| executables are built from code under this directory.
 139   Although some build options can change this, there is typically only a single
 140   binary, :file:`gmx`, built.
 141
 142 :file:`src/{...}/tests/`
 143   Various subdirectories under :file:`src/` contain a subdirectory named
 144   :file:`tests/`.  The code from each such directory is built into a test
 145   binary.  Some such directories also provide shared test code as object
 146   libraries that is linked into multiple test binaries from different folders.
 147   See :doc:`testutils` for details.
 148 :file:`src/testutils/`
 149   Contains shared utility code for writing Google Test tests.
 150   See :doc:`testutils` for details.
 151 :file:`src/external/`
 152   Contains bundled source code for various libraries and
 153   components that |Gromacs| uses internally.  All the code from these
 154   directories are built using our custom build rules into :file:`libgromacs`,
 155   or in some cases into the test binaries.  Some CMake options change which
 156   parts of this code are included in the build.
 157   See :doc:`build-system` for some explanation about how the code in this
 158   directory is used.
 159 :file:`src/external/build-fftw/`
 160   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. All headers should compile by themselves,
 189 with installed headers doing so without reference to variables
 190 defined in ``config.h`` or requiring other headers to be included before it.
 191 Not installed headers are allowed to include ``config.h``. Cyclic include dependencies
 192 prevent this, and must be avoided because of this. This is best guaranteed
 193 by including every header in some source file as the first header,
 194 even before ``config.h``. This is partly enforced by :doc:`gmxtree`,
 195 which is run by Jenkins and votes accordingly in Gerrit.
 196
 197 Code inside the library should not unnecessarily include headers. In
 198 particular, headers should not include other headers if a forward
 199 declaration of a type is enough for the header. Within the library
 200 source files, include only headers from other modules that are
 201 necessary for that file. You can use the public API header if you
 202 really require everything declared in it.
 203
 204 intra-module/intra-file.
 205
 206 See :doc:`naming` for some common naming patterns for files that can help
 207 locating declarations.
 208
 209 Tests, and data required for them, are in a :file:`tests/` subdirectory under
 210 the module directory.
 211 See :doc:`testutils` for more details.
 212
 213 .. _dev-doc-layout:
 214
 215 Documentation organization
 216 --------------------------
 217
 218 All documentation (including this developer guide) is produced from source
 219 files under :file:`docs/`, except for some command-line help that is generated
 220 from the source code (by executing the compiled :file:`gmx` binary).
 221 The build system provides various custom targets that build the documentation;
 222 see :doc:`build-system` for details.
 223
 224 :file:`docs/fragments/`
 225   Contains reStructuredText fragments used through ``.. include::`` mechanism
 226   from various places in the documentation.
 227
 228 User documentation
 229 ^^^^^^^^^^^^^^^^^^
 230
 231 :file:`docs/install-guide/`
 232   Contains reStructuredText source files for building the install guide section
 233   of the user documentation, as well as the :file:`INSTALL` file for the source
 234   package.
 235   The build rules are in :file:`docs/CMakeLists.txt`.
 236 :file:`docs/reference-manual/`
 237   Contains reStructuredText source files to generate the reference manual for
 238   html and LaTeX.
 239 :file:`docs/manual/`
 240   Contains LaTeX helper files to build the reference (PDF) manual.
 241 :file:`docs/user-guide/`
 242   Contains reStructuredText source files used to build the user guide section
 243   of the user documentation.
 244   The build rules are in :file:`docs/CMakeLists.txt`.
 245 :file:`docs/how-to/`
 246   Contains reStructuredText source files building the how-to section of
 247   the user focused documentation.
 248
 249 Unix man pages
 250 ^^^^^^^^^^^^^^
 251
 252 Man pages for programs are generated by running the :file:`gmx` executable
 253 after compiling it, and then using Sphinx on the reStructuredText files that
 254 :file:`gmx` writes out.
 255
 256 The build rules for the man pages are in :file:`docs/CMakeLists.txt`.
 257
 258 Developer guide
 259 ^^^^^^^^^^^^^^^
 260
 261 :file:`docs/dev-manual/`
 262   Contains reStructuredText source files used to build the developer guide.
 263   The build rules are in :file:`docs/CMakeLists.txt`.
 264
 265 The organization of the developer guide is explained on the :ref:`front page of
 266 the guide <dev guide>`.
 267
 268 Doxygen documentation
 269 ^^^^^^^^^^^^^^^^^^^^^
 270
 271 :file:`docs/doxygen/`
 272   Contains the build rules and some overview content for the Doxygen
 273   documentation.
 274   See :doc:`doxygen` for details of how the Doxygen documentation is built and
 275   organized.
 276
 277 .. todo:: Create a separate page (at the front of the developer guide, and/or at
 278    the main index.rst) that describes the documentation from readers'
 279    perspective, and move relevant content there.  This should contain just an
 280    overview of how the documentation is organized in the source tree.
 281
 282 The Doxygen documentation is made of a few different parts.  Use the list
 283 below as a guideline on where to look for a particular kind of content.
 284 Since the documentation has been written over a long period of time and the
 285 approach has evolved, not all the documentation yet follows these guidelines,
 286 but this is where we are aiming at.
 287
 288 documentation pages
 289   These contain mainly overview content, from general-level introduction down
 290   into explanation of some particular areas of individual modules.
 291   These are generally the place to start familiarizing with the code or a new
 292   area of the code.
 293   They can be reached by links from the main page, and also through cross-links
 294   from places in the documentation where that information is relevant to
 295   understand the context.
 296 module documentation
 297   These contain mainly techical content, explaining the general implementation of
 298   a particular module and listing the classes, functions etc. in the module.
 299   They complement pages that describe the concepts.
 300   They can be reached from the Modules tab, and also from all individual classes,
 301   functions etc. that make up the module.
 302 class documentation
 303   These document the usage of an individual class, and in some cases that of
 304   closely related classes.  Where necessary (and time allowing), a broader
 305   overview is given on a separate page and/or in the module documentation.
 306 method documentation
 307   These document the individual method.  Typically, the class documentation or
 308   other overview content is the place to look for how different methods interact.
 309 file and namespace documentation
 310   These are generally only placeholders for links, and do not contain much else.
 311   The main content is the list of classes and other entities declared in that
 312   file.