Developer Guide

This set of pages contains guidelines, instructions, and explanations related to GROMACS development. The actual code is documented in Doxygen documentation linked below.

The focus is (at least for now) on things that are tightly tied to the code itself, such as helper scripts that reside in the source repository and organization of the code itself, and may require the documentation to be updated in sync.

The guide is currently split into a few main parts:

• Overview of the GROMACS codebase.

• Collection of overview pages that describe some important implementation aspects.

• Generic guidelines to follow when developing GROMACS. For some of the guidelines, scripts exist (see below) to automatically reformat the code and/or enforce the guidelines for each commit.

• Instructions on what tools are used, and how to use them.

In addition to this, Doxygen documentation extracted from the comments in the C/C++ code is available to document the actual existing code.

Some overview documentation that is closely related to the actual C/C++ code appears in the Doxygen documentation, while some other overview content is in the developer guide. The reasons are partially technical, but crosslinks between the developer guide and the Doxygen documentation are provided whenever related content appears split between the two sources.

The documentation does not yet cover all areas, but more content is being (slowly) added.

• Contribute to GROMACS
  • Checklist
  • Preparing code for submission
  • Alternatives
  • Do you have more questions?
  • Removing functionality
• Codebase overview
  • Source code organization
  • Documentation organization
• Build system overview
  • Build types
  • CMake cache variables
  • External libraries
  • Special targets
  • Passing information to source code
• Change Management
  • Getting started
  • Labels
  • Code Review
  • More git tips
• Relocatable binaries
  • Finding shared libraries
  • Finding data files
  • Known issues
• Documentation generation
  • Building the GROMACS documentation
  • Needed build tools
• Style guidelines
  • Guidelines for code formatting
  • Guidelines for #include directives
  • Naming conventions
  • Allowed language features
  • Guidelines for creating meaningful issue reports
  • Guidelines for formatting of git commits
  • Error handling
• Development-time tools
  • Using Doxygen
  • Change Management
  • Automation and Infrastructure
  • Release engineering with GitLab
  • Source tree checker scripts
  • Automatic source code formatting
  • Unit testing
  • Physical validation
  • Change management
  • Build system
  • Code formatting and style
• Known issues relevant for developers
  • Issues with GPU timer with OpenCL
  • GPU emulation does not work
  • OpenCL on NVIDIA Volta and later broken
  • PME decomposition automated task assignment broken

Doxygen documentation

• Public API documentation

  This contains documentation for code that appears in installed headers, as well as some overview documentation to understand those parts of the code. Please note that the definition of the public API is very preliminary and subject to change, in particular for parts that have not been documented.

• Code documentation

  This contains the public API documentation as a subset, but also has more details on the internal implementation of GROMACS. This is a good place to start to understand some specific area of the code in general to, e.g., contribute.

• Full documentation

  This contains every single documented function from the codebase, including internal There can be an overwhelming amount of detail, but this can be useful if trying to find some specific function within the codebase.