12 .. TODO: Add details for most of the tools, either in the form of links to wiki,
13 or to a separate page that explains more details.
19 |Gromacs| uses git as the version control system.
20 Instructions for setting up git for |Gromacs|, as well as tips and tricks for
21 its use, can be found on the wiki: `Git Tips & Tricks`_
23 Other basic tutorial material for ``git`` can be found on the web.
26 All code changes go through a code review system at
27 http://gerrit.gromacs.org.
30 All changes pushed to Gerrit are automatically compiled and otherwise
31 checked on various platforms using a continuous integration system at
32 http://jenkins.gromacs.org.
35 Bugs and issues, as well as some random features and discussions,
36 are tracked at http://redmine.gromacs.org.
38 .. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
43 .. TODO: details, ASAN, others?
46 Main tool used in the build system.
48 packaging for distribution (CPack)
51 |Gromacs| uses a unit testing framework based on Google C++ Testing
52 Framework (gtest) and CTest. All unit tests are automatically run on Jenkins
54 Details can be found on a separate page on :doc:`testutils`.
59 `cppcheck <http://cppcheck.sourceforge.net>`_ is used for static code
60 analysis, and is run automatically on Jenkins for each commit. Different rules
61 are used for C and C++ code (with stricter checking for C++ code, as that is
62 newer). The build system provides a ``cppcheck`` target (produced from
63 ``tests/CppCheck.cmake``) to run the tool. This target is used also by Jenkins.
67 .. _dev-formatting-tools:
69 Code formatting and style
70 -------------------------
72 The tools and scripts listed below are used to automatically check/apply
73 formatting that follows |Gromacs| style guidelines described on a separate page:
77 `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
78 indentation and other formatting of the source code to follow
79 :doc:`formatting`. All code must remain invariant under uncrustify
80 with the config at ``admin/uncrustify.cfg``. A patched version of uncrustify is
81 used. See :doc:`uncrustify` for details.
83 ``admin/copyright.py``
84 This Python script adds and formats copyright headers in source files.
85 ``uncrustify.sh`` (see below) uses the script to check/update copyright years on
86 changed files automatically.
88 ``admin/uncrustify.sh``
89 This ``bash`` script runs uncrustify and ``copyright.py`` for all
90 files that have local changes and checks that they conform to the prescribed
91 style. Optionally, the script can also apply changes to make the files
93 This script is automatically run by Jenkins to ensure that all commits adhere
94 to :doc:`formatting`. If the uncrustify job does not succeed, it
95 means that this script has something to complain.
96 See :doc:`uncrustify` for details.
98 ``admin/git-pre-commit``
99 This sample git pre-commit hook can be used if one wants to apply
100 ``uncrustify.sh`` automatically before every commit to check for formatting
101 issues. See :doc:`uncrustify` for details.
103 ``docs/doxygen/includesorter.py``
104 This Python script sorts and reformats #include directives according to
105 the guidelines at :doc:`includestyle`. Details are documented on a
106 separate page (with the whole suite of Python scripts used for source code
107 checks): :ref:`dev-include-sorter`.
109 include directive checker
110 In its present form, the above include sorter script cannot be conveniently
111 applied in ``uncrustify.sh``. To check for issues, it is instead integrated into
112 a ``check-source`` build target. When this target is built, it also checks for
113 include formatting issues. Internally, it uses the sorter script. This check
114 is run in Jenkins as part of the Documentation job.
115 Details for the checking mechanism are on a separate page (common for several
116 checkers): :doc:`gmxtree`.
118 ``admin/reformat_all.sh``
119 This ``bash`` script runs uncrustify/``copyright.py``/include sorter
120 on all relevant files in the source tree (or in a particular directory).
121 The script can also produce the list of files where these scripts are applied,
122 for use with other scripts. See :doc:`uncrustify` for details.
125 git attributes (specified in ``.gitattributes`` files) are used to annotate
126 which files are subject to automatic formatting checks (and for automatic
127 reformatting by the above scripts). See ``man gitattributes`` for an overview of
128 the mechanism. We use the ``filter`` attribute to specify the type of automatic
129 checking/formatting to apply. Custom attributes are used for specifying some
130 build system dependencies for easier processing in CMake.
134 Documentation generation
135 ------------------------
137 Building the |Gromacs| documentation
138 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
140 .. TODO: Move this onto a separate page
142 For now, there are multiple components, formats and tools for the
143 |Gromacs| documentation, which is aimed primarily at version-specific
144 deployment of the complete documentation on the website.
146 This is quite complex, because the dependencies for building the
147 documentation must not get in the way of building the code
148 (particularly when cross-compiling), and yet the code must build and
149 run in order for some documentation to be generated. Also, man page
150 documentation (and command-line completions) must be built from the
151 wrapper binary, in order to be bundled into the tarball.
153 The outputs of interest to most developers are generally produced in the
154 ``docs/html/`` subdirectory of the build tree.
156 You need to enable at least some of the following CMake options:
159 Option needed for trying to build the PDF reference manual
160 (requires LaTeX and ImageMagick)
162 Option that controls 1) whether shell completions are built automatically,
163 and 2) whether built man pages are installed if available (the user still needs
164 to build the ``man`` target manually before installing)
165 ``GMX_BUILD_WEBPAGE``
166 Option needed for compiling all the documentation into the webpage
168 Some documentation cannot be built if the CMake option
169 ``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it
170 requires executing the ``gmx`` binary.
172 The following make targets are the most useful:
175 Builds the PDF reference manual
177 Makes man pages from the wrapper binary with Sphinx
179 Makes the code documentation with Doxygen
181 Makes the INSTALL file for the tarball with Sphinx
183 Makes all the components of the GROMACS webpage that require Sphinx,
184 including install guide and user guide.
186 Makes the complete GROMACS webpage, requires everything. When complete,
187 you can browse ``docs/html/index.html`` to find everything.
189 If built from a release tarball, the ``SOURCE_MD5SUM``,
190 ``SOURCE_TARBALL``, ``REGRESSIONTESTS_MD5SUM``, and
191 ``REGRESSIONTESTS_TARBALL`` CMake variables can be set to pass in
192 the md5sum values and names of those tarballs, for embedding into the
193 final deployment to the |Gromacs| website.
195 The following tools are used in building parts of the documentation.
198 `Doxygen <http://www.doxygen.org>`_ is used to extract documentation from
199 source code comments. Also some other overview
200 content is laid out by Doxygen from Markdown source files. Currently, version
201 |EXPECTED_DOXYGEN_VERSION| is required for a warning-free build. Thorough
202 explanation of the Doxygen setup and instructions for documenting the source
203 code can be found on a separate page: :doc:`doxygen`.
206 The Doxygen documentation uses ``dot`` from `graphviz
207 <http://www.graphviz.org>`_ for building some graphs. The tool is not
208 mandatory, but the Doxygen build will produce warnings if it is not
209 available, and the graphs are omitted from the documentation.
212 The Doxygen documentation uses `mscgen
213 <http://www.mcternan.me.uk/mscgen/>`_ for building some graphs. As with ``dot``,
214 the tool is not mandatory, but not having it available will result in warnings
217 Doxygen issue checker
218 Doxygen produces warnings about some incorrect uses and wrong
219 documentation, but there are many common mistakes that it does not detect.
220 |Gromacs| uses an additional, custom Python script to check for such issues.
221 This is most easily invoked through a ``check-source`` target in the build system.
222 The script also checks that documentation for a header matches its use in the
223 source code (e.g., that a header documented as internal to a module is not
224 actually used from outside the module). These checks are run in Jenkins as
225 part of the Documentation job. Details for the custom checker are on a
226 separate page (common for several checkers): :doc:`gmxtree`.
228 module dependency graphs
229 |Gromacs| uses a custom Python script to generate an annotated dependency
230 graph for the code, showing #include dependencies between modules.
231 The generated graph is embedded into the Doxygen documentation:
232 `Module dependency graph`__
233 This script shares most of its implementation with the custom checkers, and is
234 documented on the same page: :doc:`gmxtree`.
236 __ doxygen-page-modulegraph_
239 `Sphinx <http://sphinx-doc.org/>`_; at least version 1.2.3) is used
240 for building some parts of the documentation from reStructuredText
244 Also requires ImageMagick for converting graphics file formats.
248 documentation exported from source files
249 For man pages, HTML documentation of command-line options for executables,
250 and for shell completions, the ``gmx`` binary has explicit C++ code to export
251 the information required. The build system provides targets that then invoke
252 the built ``gmx`` binary to produce these documentation items. The generated
253 items are packaged into source tarballs so that this is not necessary when
254 building from a source distribution (since in general, it will not work in
255 cross-compilation scenarios). To build and install these from a git
256 distribution, explicit action is required.
257 See `Doxygen documentation on the wrapper binary`__
258 for some additional details.
260 __ doxygen-page-wrapperbinary_
262 .. include:: doxygen-links.rst