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`.
10 All other content is in the following top-level directories:
13 Contains various scripts for developer use, as well as configuration files
14 and scripts for some of the tools used.
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.
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.
28 Contains the templates for :file:`GMXRC` script, some other installed scripts,
29 as well as installation rules for all these scripts.
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
35 Contains all source code. See :ref:`dev-source-layout`.
37 Contains build system logic for some high-level tests. Currently, only the
38 regression test build system logic and cppcheck rules are in this directory,
39 while other tests are under :file:`src/`.
41 .. _dev-source-layout:
43 Source code organization
44 ------------------------
46 The following figure shows a high-level view of components of what gets built
47 from the source code under :file:`src/` and how the code is organized.
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. If ``GMX_BUILD_MDRUN_ONLY`` is ``ON``, then the blue and white
51 components are built instead; :file:`libgromacs_mdrun` is built from a subset
52 of the code used for :file:`libgromacs`.
53 The gray parts are for testing, and are by default only built as part of the
54 ``tests`` target, but if ``GMX_DEVELOPER_BUILD`` is ``ON``, then these are
55 included in the default build target.
56 See :doc:`testutils` for details of the testing side.
58 .. digraph:: dev_high_level_components
61 node [ shape=box, style=filled, width=2 ]
66 label="externals\nsrc/external/", group=common, style=rounded
69 label="Google Test & Mock\nsrc/external/gmock-1.7.0/", group=test
70 style="rounded,filled", fillcolor="0 0 0.9"
76 label="libgromacs\nsrc/gromacs/", group=gmx, fillcolor="0.33 0.3 1"
79 label="libgromacs_mdrun\nsrc/gromacs/", group=mdrun, fillcolor="0.66 0.3 1"
83 label="testutils\nsrc/testutils/", group=test
84 style="rounded,filled", fillcolor="0 0 0.9"
87 label="mdrun object lib.\nsrc/programs/mdrun/", group=common, style=rouded
92 label="gmx\nsrc/programs/", group=gmx, fillcolor="0.33 0.3 1"
95 label="mdrun\nsrc/programs/", group=mdrun, fillcolor="0.66 0.3 1"
98 label="test binaries\nsrc/.../tests/", group=test
99 style="rounded,filled", fillcolor="0 0 0.9"
102 label="analysis template\nshare/template/", group=common
103 fillcolor="0.33 0.3 1"
106 gmx -> template [ style=invis, constraint=no ]
107 template -> mdrun [ style=invis, constraint=no ]
110 libgromacs -> externals
111 libgromacs_mdrun -> externals
112 mdrun_objlib -> libgromacs
115 mdrun -> libgromacs_mdrun
116 mdrun -> mdrun_objlib
117 testutils -> externals
119 testutils -> libgromacs
122 tests -> mdrun_objlib
124 template -> libgromacs
126 template -> mdrun_objlib [ style=invis ]
127 mdrun_objlib -> externals [ style=invis ]
129 All the source code (except for the analysis template) is under the
130 :file:`src/` directory. Only a few files related to the build system are
131 included at the root level. All actual code is in subdirectories:
134 The code under this directory is built into a single library,
135 :file:`libgromacs`. Installed headers are also located in this hierarchy.
136 This is the main part of the code, and is organized into further subdirectories
137 as *modules*. See below for details.
138 :file:`src/programs/`
139 |Gromacs| executables are built from code under this directory.
140 Although some build options can change this, there is typically only a single
141 binary, :file:`gmx`, built.
143 :file:`src/{...}/tests/`
144 Various subdirectories under :file:`src/` contain a subdirectory named
145 :file:`tests/`. The code from each such directory is built into a test
146 binary. Some such directories also provide shared test code as object
147 libraries that is linked into multiple test binaries from different folders.
148 See :doc:`testutils` for details.
149 :file:`src/testutils/`
150 Contains shared utility code for writing Google Test tests.
151 See :doc:`testutils` for details.
152 :file:`src/external/`
153 Contains bundled source code for various libraries and
154 components that |Gromacs| uses internally. All the code from these
155 directories are built using our custom build rules into :file:`libgromacs`,
156 or in some cases into the test binaries. Some CMake options change which
157 parts of this code are included in the build.
158 See :doc:`build-system` for some explanation about how the code in this
160 :file:`src/external/build-fftw/`
161 This folder contains the build system code for
162 downloading and building FFTW to be included into :file:`libgromacs`.
164 When compiling, the include search path is set to :file:`src/`.
165 Some directories from under :file:`src/external/` may also be included,
166 depending on the compilation options.
168 Organization under :file:`src/gromacs/`
169 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
171 The :file:`libgromacs` library is built from code under :file:`src/gromacs/`.
172 Again, the top-level directory contains build and installation rules for the
173 library, and :dfn:`public API convenience headers`. These convenience headers
174 provide the main installed headers that other code can use. They do not
175 contain any declarations, but only include a suitable set of headers from the
176 subdirectories. They typically also contain high-level Doxygen documentation
177 for the subdirectory with the same name: :file:`{module}.h` corresponds to
180 The code is organized into subdirectories. These subdirectories are denoted as
181 :dfn:`modules` throughout this documentation. Each module consists of a set
182 of routines that do some well-defined task or a collection of tasks.
184 Installed headers are a subset of the headers under :file:`src/gromacs/`.
185 They are installed into a corresponding hierarchy under
186 :file:`include/gromacs/` in the installation directory.
187 Comments at the top of the header files contain a note about their visibility:
188 public (installed), intra-library (can be used from inside the library), or
189 intra-module/intra-file. All headers should compile by themselves,
190 with installed headers doing so without reference to variables
191 defined in ``config.h`` or requiring other headers to be included before it.
192 Not installed headers are allowed to include ``config.h``. Cyclic include dependencies
193 prevent this, and must be avoided because of this. This is best guaranteed
194 by including every header in some source file as the first header,
195 even before ``config.h``. This is partly enforced by :doc:`gmxtree`,
196 which is run by Jenkins and votes accordingly in Gerrit.
198 Code inside the library should not unnecessarily include headers. In
199 particular, headers should not include other headers if a forward
200 declaration of a type is enough for the header. Within the library
201 source files, include only headers from other modules that are
202 necessary for that file. You can use the public API header if you
203 really require everything declared in it.
205 intra-module/intra-file.
207 See :doc:`naming` for some common naming patterns for files that can help
208 locating declarations.
210 Tests, and data required for them, are in a :file:`tests/` subdirectory under
211 the module directory.
212 See :doc:`testutils` for more details.
216 Documentation organization
217 --------------------------
219 All documentation (including this developer guide) is produced from source
220 files under :file:`docs/`, except for some command-line help that is generated
221 from the source code (by executing the compiled :file:`gmx` binary).
222 The build system provides various custom targets that build the documentation;
223 see :doc:`build-system` for details.
225 :file:`docs/fragments/`
226 Contains reStructuredText fragments used through ``.. include::`` mechanism
227 from various places in the documentation.
232 :file:`docs/install-guide/`
233 Contains reStructuredText source files for building the install guide section
234 of the user documentation, as well as the :file:`INSTALL` file for the source
236 The build rules are in :file:`docs/CMakeLists.txt`.
238 Contains LaTeX source files and build rules for the reference (PDF) manual.
239 :file:`docs/user-guide/`
240 Contains reStructuredText source files for building the user guide section
241 of the user documentation.
242 The build rules are in :file:`docs/CMakeLists.txt`.
247 Man pages for programs are generated by running the :file:`gmx` executable
248 after compiling it, and then using Sphinx on the reStructuredText files that
249 :file:`gmx` writes out.
251 The build rules for the man pages are in :file:`docs/CMakeLists.txt`.
256 :file:`docs/dev-manual/`
257 Contains reStructuredText source files used to build the developer guide.
258 The build rules are in :file:`docs/CMakeLists.txt`.
260 The organization of the developer guide is explained on the :ref:`front page of
261 the guide <dev guide>`.
263 Doxygen documentation
264 ^^^^^^^^^^^^^^^^^^^^^
266 :file:`docs/doxygen/`
267 Contains the build rules and some overview content for the Doxygen
269 See :doc:`doxygen` for details of how the Doxygen documentation is built and
272 .. TODO: Create a separate page (at the front of the developer guide, and/or at
273 the main index.rst) that describes the documentation from readers'
274 perspective, and move relevant content there. This should contain just an
275 overview of how the documentation is organized in the source tree.
277 The Doxygen documentation is made of a few different parts. Use the list
278 below as a guideline on where to look for a particular kind of content.
279 Since the documentation has been written over a long period of time and the
280 approach has evolved, not all the documentation yet follows these guidelines,
281 but this is where we are aiming at.
284 These contain mainly overview content, from general-level introduction down
285 into explanation of some particular areas of individual modules.
286 These are generally the place to start familiarizing with the code or a new
288 They can be reached by links from the main page, and also through cross-links
289 from places in the documentation where that information is relevant to
290 understand the context.
292 These contain mainly techical content, explaining the general implementation of
293 a particular module and listing the classes, functions etc. in the module.
294 They complement pages that describe the concepts.
295 They can be reached from the Modules tab, and also from all individual classes,
296 functions etc. that make up the module.
298 These document the usage of an individual class, and in some cases that of
299 closely related classes. Where necessary (and time allowing), a broader
300 overview is given on a separate page and/or in the module documentation.
302 These document the individual method. Typically, the class documentation or
303 other overview content is the place to look for how different methods interact.
304 file and namespace documentation
305 These are generally only placeholders for links, and do not contain much else.
306 The main content is the list of classes and other entities declared in that