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 Arrows indicate the direction of dependencies.
  48 The build system is described in detail in :doc:`build-system`.
  49 With default options, the green and white components are built as part of the
  50 default target.
  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/googletest/", 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    }
  77    testutils [
  78      label="testutils\nsrc/testutils/", group=test
  79      style="rounded,filled", fillcolor="0 0 0.9"
  80    ]
  81    subgraph {
  82      rank = same
  83      gmx [
  84        label="gmx\nsrc/programs/", group=gmx, fillcolor="0.33 0.3 1"
  85      ]
  86      tests [
  87        label="test binaries\nsrc/.../tests/", group=test
  88        style="rounded,filled", fillcolor="0 0 0.9"
  89      ]
  90      template [
  91        label="analysis template\nshare/template/", group=common
  92        fillcolor="0.33 0.3 1"
  93      ]
  94
  95      gmx -> template [ style=invis, constraint=no ]
  96    }
  97
  98    libgromacs -> externals
  99    gmx -> libgromacs
 100    testutils -> externals
 101    testutils -> gtest
 102    testutils -> libgromacs
 103    tests -> gtest
 104    tests -> libgromacs
 105    tests -> testutils
 106    template -> libgromacs
 107
 108 All the source code (except for the analysis template) is under the
 109 :file:`src/` directory.  Only a few files related to the build system are
 110 included at the root level.  All actual code is in subdirectories:
 111
 112 :file:`src/gromacs/`
 113   The code under this directory is built into a single library,
 114   :file:`libgromacs`.  Installed headers are also located in this hierarchy.
 115   This is the main part of the code, and is organized into further subdirectories
 116   as *modules*.  See below for details.
 117 :file:`src/programs/`
 118   The |Gromacs| executable ``gmx`` is built from code under this directory.
 119   Also found here is some of the driver code for the ``mdrun`` module called
 120   by ``gmx``, the whole of the ``gmx view`` visualization module, and numerous
 121   end-to-end tests of ``gmx mdrun``.
 122
 123 :file:`src/{...}/tests/`
 124   Various subdirectories under :file:`src/` contain a subdirectory named
 125   :file:`tests/`.  The code from each such directory is built into a test
 126   binary.  Some such directories also provide shared test code as object
 127   libraries that is linked into multiple test binaries from different folders.
 128   See :doc:`testutils` for details.
 129 :file:`src/testutils/`
 130   Contains shared utility code for writing Google Test tests.
 131   See :doc:`testutils` for details.
 132 :file:`src/external/`
 133   Contains bundled source code for various libraries and
 134   components that |Gromacs| uses internally.  All the code from these
 135   directories are built using our custom build rules into :file:`libgromacs`,
 136   or in some cases into the test binaries.  Some CMake options change which
 137   parts of this code are included in the build.
 138   See :doc:`build-system` for some explanation about how the code in this
 139   directory is used.
 140 :file:`src/external/build-fftw/`
 141   This folder contains the build system code for
 142   downloading and building FFTW to be included into :file:`libgromacs`.
 143
 144 When compiling, the include search path is set to :file:`src/`.
 145 Some directories from under :file:`src/external/` may also be included,
 146 depending on the compilation options.
 147
 148 Organization under :file:`src/gromacs/`
 149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 150
 151 The :file:`libgromacs` library is built from code under :file:`src/gromacs/`.
 152 Again, the top-level directory contains build and installation rules for the
 153 library, and :dfn:`public API convenience headers`.  These convenience headers
 154 provide the main installed headers that other code can use.  They do not
 155 contain any declarations, but only include a suitable set of headers from the
 156 subdirectories.  They typically also contain high-level Doxygen documentation
 157 for the subdirectory with the same name: :file:`{module}.h` corresponds to
 158 :file:`{module}/`.
 159
 160 The code is organized into subdirectories.  These subdirectories are denoted as
 161 :dfn:`modules` throughout this documentation.  Each module consists of a set
 162 of routines that do some well-defined task or a collection of tasks.
 163
 164 Installed headers are a subset of the headers under :file:`src/gromacs/`.
 165 They are installed into a corresponding hierarchy under
 166 :file:`include/gromacs/` in the installation directory.
 167 Comments at the top of the header files contain a note about their visibility:
 168 public (installed), intra-library (can be used from inside the library), or
 169 intra-module/intra-file. All headers should compile by themselves,
 170 with installed headers doing so without reference to variables
 171 defined in ``config.h`` or requiring other headers to be included before it.
 172 Not installed headers are allowed to include ``config.h``. Cyclic include dependencies
 173 prevent this, and must be avoided because of this. This is best guaranteed
 174 by including every header in some source file as the first header,
 175 even before ``config.h``.
 176
 177 Code inside the library should not unnecessarily include headers. In
 178 particular, headers should not include other headers if a forward
 179 declaration of a type is enough for the header. Within the library
 180 source files, include only headers from other modules that are
 181 necessary for that file. You can use the public API header if you
 182 really require everything declared in it.
 183
 184 See :doc:`naming` for some common naming patterns for files that can help
 185 locating declarations.
 186
 187 Tests, and data required for them, are in a :file:`tests/` subdirectory under
 188 the module directory.
 189 See :doc:`testutils` for more details.
 190
 191 .. _dev-doc-layout:
 192
 193 Documentation organization
 194 --------------------------
 195
 196 All documentation (including this developer guide) is produced from source
 197 files under :file:`docs/`, except for some command-line help that is generated
 198 from the source code (by executing the compiled :file:`gmx` binary).
 199 The build system provides various custom targets that build the documentation;
 200 see :doc:`build-system` for details.
 201
 202 :file:`docs/fragments/`
 203   Contains reStructuredText fragments used through ``.. include::`` mechanism
 204   from various places in the documentation.
 205
 206 User documentation
 207 ^^^^^^^^^^^^^^^^^^
 208
 209 :file:`docs/install-guide/`
 210   Contains reStructuredText source files for building the install guide section
 211   of the user documentation, as well as the :file:`INSTALL` file for the source
 212   package.
 213   The build rules are in :file:`docs/CMakeLists.txt`.
 214 :file:`docs/reference-manual/`
 215   Contains reStructuredText source files to generate the reference manual for
 216   html and LaTeX.
 217 :file:`docs/manual/`
 218   Contains LaTeX helper files to build the reference (PDF) manual.
 219 :file:`docs/user-guide/`
 220   Contains reStructuredText source files used to build the user guide section
 221   of the user documentation.
 222   The build rules are in :file:`docs/CMakeLists.txt`.
 223 :file:`docs/how-to/`
 224   Contains reStructuredText source files building the how-to section of
 225   the user focused documentation.
 226
 227 Unix man pages
 228 ^^^^^^^^^^^^^^
 229
 230 Man pages for programs are generated by running the :file:`gmx` executable
 231 after compiling it, and then using Sphinx on the reStructuredText files that
 232 :file:`gmx` writes out.
 233
 234 The build rules for the man pages are in :file:`docs/CMakeLists.txt`.
 235
 236 Developer guide
 237 ^^^^^^^^^^^^^^^
 238
 239 :file:`docs/dev-manual/`
 240   Contains reStructuredText source files used to build the developer guide.
 241   The build rules are in :file:`docs/CMakeLists.txt`.
 242
 243 The organization of the developer guide is explained on the :ref:`front page of
 244 the guide <dev guide>`.
 245
 246 Doxygen documentation
 247 ^^^^^^^^^^^^^^^^^^^^^
 248
 249 :file:`docs/doxygen/`
 250   Contains the build rules and some overview content for the Doxygen
 251   documentation.
 252   See :doc:`doxygen` for details of how the Doxygen documentation is built and
 253   organized.
 254
 255 .. todo:: Create a separate page (at the front of the developer guide, and/or at
 256    the main index.rst) that describes the documentation from readers'
 257    perspective, and move relevant content there.  This should contain just an
 258    overview of how the documentation is organized in the source tree.
 259
 260 The Doxygen documentation is made of a few different parts.  Use the list
 261 below as a guideline on where to look for a particular kind of content.
 262 Since the documentation has been written over a long period of time and the
 263 approach has evolved, not all the documentation yet follows these guidelines,
 264 but this is where we are aiming at.
 265
 266 documentation pages
 267   These contain mainly overview content, from general-level introduction down
 268   into explanation of some particular areas of individual modules.
 269   These are generally the place to start familiarizing with the code or a new
 270   area of the code.
 271   They can be reached by links from the main page, and also through cross-links
 272   from places in the documentation where that information is relevant to
 273   understand the context.
 274 module documentation
 275   These contain mainly techical content, explaining the general implementation of
 276   a particular module and listing the classes, functions etc. in the module.
 277   They complement pages that describe the concepts.
 278   They can be reached from the Modules tab, and also from all individual classes,
 279   functions etc. that make up the module.
 280 class documentation
 281   These document the usage of an individual class, and in some cases that of
 282   closely related classes.  Where necessary (and time allowing), a broader
 283   overview is given on a separate page and/or in the module documentation.
 284 method documentation
 285   These document the individual method.  Typically, the class documentation or
 286   other overview content is the place to look for how different methods interact.
 287 file and namespace documentation
 288   These are generally only placeholders for links, and do not contain much else.
 289   The main content is the list of classes and other entities declared in that
 290   file.