4 Several tools have their own individual pages and are listed below.
17 .. TODO: Consider what is the most reasonable structure; currently, this list
18 here does not make much sense in the overall organization and creates a
19 confusing TOC for the developer guide.
21 .. TODO: Add details for most of the tools, either in the form of links to wiki,
22 or to a separate page that explains more details.
27 |Gromacs| change management is supported by the following tools.
28 (For change submission guidelines, refer to :doc:`contribute`.)
31 |Gromacs| uses `git <https://git-scm.com/>`__ as the version control system.
32 Instructions for setting up git for |Gromacs|, as well as tips and tricks for
33 its use, can be found in :doc:`change-management`.
35 Other basic tutorial material for ``git`` can be found on the `web <https://git-scm.com/doc/ext>`__.
38 All code changes go through a code review system at
39 http://gerrit.gromacs.org.
42 All changes pushed to Gerrit are automatically compiled and otherwise
43 checked on various platforms using a continuous integration system at
44 http://jenkins.gromacs.org.
45 :doc:`jenkins` documents how Jenkins interacts with the build system,
46 providing information on how to replicate the builds Jenkins does (e.g., to
48 :doc:`releng/index` provides more information on the technical implementation
52 Bugs and issues, as well as some random features and discussions,
53 are tracked at http://redmine.gromacs.org.
55 .. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
60 .. TODO: details, ASAN, others?
63 Main tool used in the build system.
66 When the `ccache <https://ccache.samba.org>`_ caching compiler wrapper is
67 found on the PATH, we attempt to set up a caching compiler wrapper for CMake
68 builds. Not all compilers are supported. Refer to the ``ENABLE_CCACHE``
69 option in ``CMakeLists.txt`` and to ``cmake/gmxCcache.cmake``
70 for details. Please submit updates if you find that the current
71 configuration is too conservative.
73 packaging for distribution (CPack)
76 |Gromacs| uses a unit testing framework based on Google C++ Testing
77 Framework (gtest) and CTest. All unit tests are automatically run on Jenkins
79 Details can be found on a separate page on :doc:`testutils`.
84 `clang-tidy <http://releases.llvm.org/6.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html>`
85 is used for static code analysis. clang-tidy is easy to install. It is contained in
86 the llvm binary `package <http://releases.llvm.org/download.html#6.0.0>`. Only
87 version 6.0 is supported. Others might miss tests or give false positives.
88 It is run automatically on Jenkins for each commit. To run it manually, configure
89 with ``cmake -DGMX_CLANG_TIDY=ON -DGMX_OPENMP=no -DCMAKE_BUILD_TYPE=Debug`` and then run make
90 normally (for ``CMAKE_BUILD_TYPE`` any type which enables asserts (e.g. ASAN) works).
91 The name of the clang-tidy executable that CMake should search for be set with
92 ``-DCLANG_TIDY=...`, and the full path to it can be set with ``-DCLANG_TIDY_EXE=...``.
93 Many checks have fixes which automatically get applied when building with clang-tidy
94 enabled, so you may want to run this tool locally to apply the fixes before
98 `cppcheck <http://cppcheck.sourceforge.net>`_ is used for static code
99 analysis, and is run automatically on Jenkins for each commit. Different rules
100 are used for C and C++ code (with stricter checking for C++ code, as that is
101 newer). The build system provides a ``cppcheck`` target (produced from
102 ``tests/CppCheck.cmake``) to run the tool. This target is used also by Jenkins.
104 clang static analyzer
108 .. _dev-formatting-tools:
110 Code formatting and style
111 -------------------------
113 The tools and scripts listed below are used to automatically check/apply
114 formatting that follows |Gromacs| style guidelines described on a separate page:
118 `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
119 indentation and other formatting of the source code to follow
120 :doc:`formatting`. All code must remain invariant under uncrustify
121 with the config at ``admin/uncrustify.cfg``. A patched version of uncrustify is
122 used. See :doc:`uncrustify` for details.
124 ``admin/copyright.py``
125 This Python script adds and formats copyright headers in source files.
126 ``uncrustify.sh`` (see below) uses the script to check/update copyright years on
127 changed files automatically.
129 ``admin/uncrustify.sh``
130 This ``bash`` script runs uncrustify and ``copyright.py`` for all
131 files that have local changes and checks that they conform to the prescribed
132 style. Optionally, the script can also apply changes to make the files
134 This script is automatically run by Jenkins to ensure that all commits adhere
135 to :doc:`formatting`. If the uncrustify job does not succeed, it
136 means that this script has something to complain.
137 See :doc:`uncrustify` for details.
139 ``admin/git-pre-commit``
140 This sample git pre-commit hook can be used if one wants to apply
141 ``uncrustify.sh`` automatically before every commit to check for formatting
142 issues. See :doc:`uncrustify` for details.
144 ``docs/doxygen/includesorter.py``
145 This Python script sorts and reformats #include directives according to
146 the guidelines at :doc:`includestyle`. Details are documented on a
147 separate page (with the whole suite of Python scripts used for source code
148 checks): :ref:`dev-include-sorter`.
150 include directive checker
151 In its present form, the above include sorter script cannot be conveniently
152 applied in ``uncrustify.sh``. To check for issues, it is instead integrated into
153 a ``check-source`` build target. When this target is built, it also checks for
154 include formatting issues. Internally, it uses the sorter script. This check
155 is run in Jenkins as part of the Documentation job.
156 Details for the checking mechanism are on a separate page (common for several
157 checkers): :doc:`gmxtree`.
159 ``admin/reformat_all.sh``
160 This ``bash`` script runs uncrustify/``copyright.py``/include sorter
161 on all relevant files in the source tree (or in a particular directory).
162 The script can also produce the list of files where these scripts are applied,
163 for use with other scripts. See :doc:`uncrustify` for details.
166 git attributes (specified in ``.gitattributes`` files) are used to annotate
167 which files are subject to automatic formatting checks (and for automatic
168 reformatting by the above scripts). See ``man gitattributes`` for an overview of
169 the mechanism. We use the ``filter`` attribute to specify the type of automatic
170 checking/formatting to apply. Custom attributes are used for specifying some
171 build system dependencies for easier processing in CMake.