Development-time tools

Several tools have their own individual pages and are listed below.

• Using Doxygen
  • Documentation flavors
  • Building the documentation
  • General guidelines for Doxygen markup
  • GROMACS specifics
  • Documenting specific code constructs
  • Examples
• GROMACS change management
  • Getting started
  • Code Review
  • FAQs
  • More git tips
• Understanding Jenkins builds
  • Pre-submit verification
  • On-demand builds
• releng repository
  • Jenkins scripts (releng Python module)
  • Workflow build overview
  • releng Python API
  • Jenkins configuration
  • Interacting with builds in Jenkins
  • How to do common things with Jenkins builds
• Source tree checker scripts
  • Checker details
  • Include order sorting
  • Include dependency graphs
• Automatic source code formatting
  • Setting up uncrustify
  • What is automatically formatted?
  • Scripts
  • Using git filters
• Unit testing
  • Finding, building and running
  • Unit testing framework
  • Getting started with new tests
• Physical validation
  • Test description
  • Building and testing using the build system
  • Direct usage of the python script
  • Adding new tests

Change management

GROMACS change management is supported by the following tools. (For change submission guidelines, refer to Contribute to GROMACS.)

git

GROMACS uses git as the version control system. Instructions for setting up git for GROMACS, as well as tips and tricks for its use, can be found in GROMACS change management.

Other basic tutorial material for git can be found on the web.

Gerrit

All code changes go through a code review system at http://gerrit.gromacs.org.

Jenkins

All changes pushed to Gerrit are automatically compiled and otherwise checked on various platforms using a continuous integration system at http://jenkins.gromacs.org. Understanding Jenkins builds documents how Jenkins interacts with the build system, providing information on how to replicate the builds Jenkins does (e.g., to diagnose issues). releng repository provides more information on the technical implementation of the builds.

Redmine

Bugs and issues, as well as some random features and discussions, are tracked at http://redmine.gromacs.org.

Build system

CMake

Main tool used in the build system.

ccache

When the ccache caching compiler wrapper is found on the PATH, we attempt to set up a caching compiler wrapper for CMake builds. Not all compilers are supported. Refer to the ENABLE_CCACHE option in CMakeLists.txt and to cmake/gmxCcache.cmake for details. Please submit updates if you find that the current configuration is too conservative.

packaging for distribution (CPack)

unit testing (CTest)

GROMACS uses a unit testing framework based on Google C++ Testing Framework (gtest) and CTest. All unit tests are automatically run on Jenkins for each commit. Details can be found on a separate page on Unit testing.

regression tests

clang-tidy

clang-tidy is used for static code analysis. clang-tidy is easy to install. It is contained in the llvm binary package. Only version 7.0.* with libstdc++<7 or libc++ is supported. Others might miss tests or give false positives. It is run automatically on Jenkins for each commit. Many checks have fixes which can automatically be applied. To run it, the build has to be configured with cmake -DGMX_CLANG_TIDY=ON -DGMX_OPENMP=no -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=on. Any CMAKE_BUILD_TYPE which enables asserts (e.g. ASAN) works. Such a configured build will run both the compiler as well as clang-tidy when building. The name of the clang-tidy executable is set with

-DCLANG_TIDY=..., and the full path to it can be set with -DCLANG_TIDY_EXE=....

To apply the automatic fixes to the issue identified clang-tidy should be run sepereately (running clang-tidy with -fix as part of the build can corrupt header files). To fix a specific file run clang-tidy -fix -header-filter '.*' {file}, to fix all files in parallel run-clang-tidy.py -fix -header-filter '.*' '(?<!/selection/parser\.cpp|selection/scanner\.cpp)$', and to fix all modified files run-clang-tidy.py -fix -header-filter '.*' $(git diff HEAD --name-only). The run-clang-tidy.py script is in the share/clang/ subfolder of the llvm distribution. clang-tidy has to be able to find the compile_commands.json file. Eithe run from the build folder or add a symlink to the source folder.

clang static analyzer

coverage

Code formatting and style

The tools and scripts listed below are used to automatically check/apply formatting that follows GROMACS style guidelines described on a separate page: Style guidelines.

uncrustify

uncrustify is used for automatic indentation and other formatting of the source code to follow Guidelines for code formatting. All code must remain invariant under uncrustify with the config at admin/uncrustify.cfg. A patched version of uncrustify is used. See Automatic source code formatting for details.

admin/copyright.py

This Python script adds and formats copyright headers in source files. uncrustify.sh (see below) uses the script to check/update copyright years on changed files automatically.

admin/uncrustify.sh

This bash script runs uncrustify and copyright.py for all files that have local changes and checks that they conform to the prescribed style. Optionally, the script can also apply changes to make the files conform. This script is automatically run by Jenkins to ensure that all commits adhere to Guidelines for code formatting. If the uncrustify job does not succeed, it means that this script has something to complain. See Automatic source code formatting for details.

admin/git-pre-commit

This sample git pre-commit hook can be used if one wants to apply uncrustify.sh automatically before every commit to check for formatting issues. See Automatic source code formatting for details.

docs/doxygen/includesorter.py

This Python script sorts and reformats #include directives according to the guidelines at Guidelines for #include directives. Details are documented on a separate page (with the whole suite of Python scripts used for source code checks): Include order sorting.

include directive checker

In its present form, the above include sorter script cannot be conveniently applied in uncrustify.sh. To check for issues, it is instead integrated into a check-source build target. When this target is built, it also checks for include formatting issues. Internally, it uses the sorter script. This check is run in Jenkins as part of the Documentation job. Details for the checking mechanism are on a separate page (common for several checkers): Source tree checker scripts.

admin/reformat_all.sh

This bash script runs uncrustify/copyright.py/include sorter on all relevant files in the source tree (or in a particular directory). The script can also produce the list of files where these scripts are applied, for use with other scripts. See Automatic source code formatting for details.

git attributes

git attributes (specified in .gitattributes files) are used to annotate which files are subject to automatic formatting checks (and for automatic reformatting by the above scripts). See man gitattributes for an overview of the mechanism. We use the filter attribute to specify the type of automatic checking/formatting to apply. Custom attributes are used for specifying some build system dependencies for easier processing in CMake.

include-what-you-use