The GROMACS build system uses CMake (version 2.8.8 or newer is required) to generate the actual build system for the build tool choosen by the user. See CMake documentation for general introduction to CMake and how to use it. This documentation focuses on how the GROMACS build system is organized and implemented, and what features it provides to developers (some of which may be of interest to advanced users).
Most developers use make or ninja as the underlying build system, so there can be parts of the build system that are specifically designed for command-line consumption with these tools, and may not work ideally with other environments, but basic building should be possible with all the environments supported by CMake.
Also, the build system and version control is designed for out-of-source builds. In-source builds mostly work (there are a few custom targets that do not), but no particular effort has been put to, e.g., having .gitignore files that exclude all the build outputs, or to have the clean target remove all possible build outputs.
Build types is a CMake concept that provides overall control of how the build tools are used on the given platform to produce executable code. These can be set in CMake in various ways, including on a command line such as cmake -DCMAKE_BUILD_TYPE=Debug. GROMACS supports the following standard CMake build types:
Additionally, GROMACS provides the following build types for development and testing. Their implementations can be found in cmake/gmxBuildTypeXXX.cmake.
For all of the sanitizer builds, to get readable stack traces, you may need to ensure that the ASAN_SYMBOLIZER_PATH environment variable (or your PATH) include that of the llvm-symbolizer binary.
With some generators, CMake generates the build system for more than a single CMAKE_BUILD_TYPE from one pass over the CMakeLists.txt files, so any code that uses CMAKE_BUILD_TYPE in CMakeLists.txt directly will break. GROMACS does use such CMake code, so we do not fully support all these build types in such generators (which includes Visual Studio).
This section provides a (currently incomplete) list of cache variables that developers or advanced users can set to affect what CMake generates and/or what will get built.
Standard CMake mechanism for specifying the compiler flags is to use CMAKE_C_FLAGS/CMAKE_CXX_FLAGS for flags that affect all build types, and CMAKE_C_FLAGS_buildtype/CMAKE_CXX_FLAGS_buildtype for flags that only affect a specific build type. CMake provides some default flags.
GROMACS determines its own set of default flags, grouped into two categories:
All of the above flags are only added after testing that they work with the provided compiler.
There is one cache variable to control the behavior of automatic compiler flags:
If set ON, the build system will not add any compiler flags automatically (neither generic nor specific as defined above), and will skip most linker flags as well. The default flags that would have been added are instead printed out when cmake is run, and the user can set the flags themselves using the CMake variables. If OFF (the default), the flags are added as described above.
The code the determine the default generic flags is in cmake/gmxCFlags.cmake. Code that sets the specific flags (e.g., SIMD flags) is in the main CMakeLists.txt; search for GMX_SKIP_DEFAULT_CFLAGS. The variables used there can be traced back to the locations where the actual flags to use are determined.
Special variable set ON by Jenkins when doing a build for the coverage job. Allows the build system to set options to produce as useful coverage metrics as possible. Currently, it disables all asserts to avoid them showing up as poor conditional coverage. Defaults to OFF, and there should not be any need to change this in a manual build.
If set ON, the build system is configured to only build and install a single mdrun executable. To be fully functional, the installed mdrun requires a standard GROMACS installation (with GMX_BUILD_MDRUN_ONLY=OFF) in the same installation prefix, as the mdrun-only build does not install any data files or scripts, only the binary. This is intended for cases where one wants to/needs to compile one or more instances of mdrun with different build options (e.g., MPI or SIMD) than the full installation with the other utilities. Defaults to OFF, in which case a single gmx executable is built and installed, together with all the supporting files. mdrun can be executed as gmx mdrun.
If ON, some C++11 features are used internally (mainly std::unique_ptr). If OFF, no C++11 features are used in the code (boost::shared_ptr is used as a replacement). The default is ON if the compilation environment is determined to support enough C++11 (GPU builds cannot for now use C++11). Installed headers are not affected.
Sets the directory under share/ where data files are installed. The default is gromacs, which puts the files under file:share/gromacs/. See Relocatable binaries for how this influences the build.
If ON, GROMACS is compiled against Boost headers found in the system. If OFF, a subset of Boost headers found in src/external/boost/ is used instead.
Default is ON if external Boost library can be found, OFF otherwise.
The Boost headers are also used in installed headers and affect the API/ABI, so using the internal Boost can cause compatibility issues if compiling other software that uses both GROMACS and Boost.
Whether to generate version information dynamically from git for each build (e.g., HEAD commit hash). Defaults to ON if the build is from a git repository and git is found, otherwise OFF. If OFF, static version information from cmake/gmxVersionInfo.cmake is used.
Sets the installation directory for libraries (default is determined by standard CMake package GNUInstallDirs). See Relocatable binaries for how this influences the build.
Currently, this option has no effect on the compilation or linking, since there is no code outside the tests that would use libxml2.
Standard variable created by CTest that enables/disables all tests. Defaults to ON.
Controls handling of man pages and shell completions. Possible values:
If set ON, the all target will include also the test binaries using Google Test (if GMX_BUILD_UNITTESTS is ON). In the future, other developer convenience features (as well as features inconvenient for a general user) can be added to the set controlled by this variable.
If set ON, the cppcheck target generates reports for all found issues in XML format. This is used by Jenkins, which parses the XML files to show the issues on the web page. If OFF (the default), issues are reported as plain text to standard output and to a text file.
If set ON, CMake detection for LaTeX and other prerequisites for the reference PDF manual is done, and the manual target for building the manual is generated. If OFF (the default), all detection is skipped and the manual cannot be built.
If set ON, -dev suffix is stripped off from version strings and some other version info logic is adjusted such that the man pages and other documentation generated from this build is suitable for releasing (on the web page and/or in the source distribution package). Defaults to OFF.
If ON, test binaries using Google Test are built (either as the separate tests targer, or also as part of the all target, depending on GMX_DEVELOPER_BUILD). libxml2 is required for building the tests, but other prerequisites (Google Test and Google Mock frameworks) are included in src/external/. Defaults to ON if libxml2 is found and BUILD_TESTING is ON.
If set ON, Doxygen configuration is changed to avoid generating large dependency graphs, which makes it significantly faster to run Doxygen and reduces disk usage. This is typically useful when developing the documentation to reduce the build times. Defaults to OFF.
If set ON, CMake will download the regression tests and extract them to a local directory. REGRESSIONTEST_PATH is set to the extracted tests. Note that this happens during the configure phase, not during the build. After the download is done, the variable is automatically reset to OFF again to avoid repeated downloads. Can be set to ON to download again. Defaults to OFF.
Path to extracted regression test suite matching the source tree (the directory containing gmxtest.pl) If set, CTest tests are generated to run the regression tests. Defaults to empty.
Sets the MD5 sum of the release tarball when generating the HTML documentation. It gets inserted into the download section of the HTML pages.
In addition to the default all target, the generated build system has several custom targets that are intended to be explicitly built to perform various tasks (some of these may also run automatically). There are various other targets as well used internally by these, but those are typically not intended to be invoked directly.
The build system uses a few different mechanisms to influence the compilation:
On the highest level, some CMake options select what files will be compiled.
Some options are passed on the compiler command line using -D or equivalent, such that they are available in every compilation unit. This should be used with care to keep the compiler command lines manageable. You can find the current set of such defines with
git grep add_definitions
A few header files are generated using CMake configure_file() and included in the desired source files. These files must exist for the compilation to pass. Only a few files use an #ifdef HAVE_CONFIG_H to protect against inclusion in case the define is not set; this is used in files that may get compiled outside the main build system.
Contains various strings about the build environment, used mainly for outputting version information to log files and when requested.
Contains defines for conditional compilation within source files.
Included by gmxpre.h as the first thing in every source file. Should only contain defines that are required before any other header for correct operation. For example, defines that affect the behavior of system headers fall in this category. See Doxygen documentation for gmxpre.h.
All the above files get generated in src/.
Additionally, the following file is generated by the build system:
Provides definitions for declarations in baseversion-gen.h for version info output. The contents are generated either from Git version info, or from static version info if not building from a git repository.