.. highlight:: bash Build system overview ===================== The |Gromacs| build system uses CMake (version |CMAKE_MINIMUM_REQUIRED_VERSION| 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 :file:`.gitignore` files that exclude all the build outputs, or to have the ``clean`` target remove all possible build outputs. Build types ----------- 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: **Release** Fully optimized code intended for use in production simulation. This is the default. **Debug** Compiled code intended for use with debugging tools, with low optimization levels and debug information for symbols. **RelWithDebInfo** As Release, but with debug information for symbol names, which can help debugging issues that only emerge in optimized code. **MinSizeRel** As Release, but optimized to minimize the size of the resulting executable. This is never a concern for |Gromacs| installations, so should not be used, but probably works. Additionally, |Gromacs| provides the following build types for development and testing. Their implementations can be found in ``cmake/gmxBuildTypeXXX.cmake``. **Reference** This build type compiles a version of |Gromacs| aimed solely at correctness. All parallelization and optimization possibilities are disabled. This build type is compiled with gcc 5 to generate the regression test reference values, against which all other |Gromacs| builds are tested. **RelWithAssert** As Release, but removes ``-DNDEBUG`` from compiler command lines, which makes all assertion statements active (and can have other safety-related side effects in |Gromacs| and code upon which it depends) **Profile** As Release, but adds ``-pg`` for use with profiling tools. This is not likely to be effective for profiling the performance of :ref:`gmx mdrun`, but can be useful for the tools. **TSAN** Builds |Gromacs| for use with ThreadSanitzer in gcc and clang (http://clang.llvm.org/docs/ThreadSanitizer.html) to detect data races. This disables the use of atomics in ThreadMPI, preferring the mutex-based implementation. **ASAN** Builds |Gromacs| for use with AddressSanitzer in gcc and clang (http://clang.llvm.org/docs/AddressSanitizer.html) to detect many kinds of memory mis-use. By default, AddressSanitizer includes LeakSanitizer. **MSAN** Builds |Gromacs| for use with AddressSanitzer in clang (http://clang.llvm.org/docs/MemorySanitizer.html) to detect reads of unitialized memory. This functionality requires that dependencies of the |Gromacs| build have been built in a compatible way (roughly, static libraries with ``-g -fsanitize=memory -fno-omit-frame-pointer``), which generally requires at least the C++ standard library to have been built specially. The path where the includes and libraries for dependencies should be found for this build type is set in the CMake cache variable ``GMX_MSAN_PATH``. Only internal XDR and internal fftpack are supported at this time. 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). CMake cache variables --------------------- 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. .. TODO: Figure out where to document basic variables intended for user consumption, and how does it relate to documentation here. .. TODO: Document the remaining variables below, and identify any variables missing from the list. Compiler flags ^^^^^^^^^^^^^^ 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 :samp:`CMAKE_C_FLAGS_{buildtype}`/:samp:`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: * Generic flags that are appended to the above default CMake flag variables (possibly for multiple build types), generally specifying optimization flags to use and controlling compiler warnings. * Specific flags for certain features that the build system determines to be necessary for successful compilation. One example is flags that determine what SIMD instruction set the compiler is allowed to use/needs to support. 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: .. cmake:: GMX_SKIP_DEFAULT_CFLAGS 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 :command:`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 :file:`cmake/gmxCFlags.cmake`. Code that sets the specific flags (e.g., SIMD flags) is in the main :file:`CMakeLists.txt`; search for :cmake:`GMX_SKIP_DEFAULT_CFLAGS`. The variables used there can be traced back to the locations where the actual flags to use are determined. Variables affecting compilation/linking ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. cmake:: GMX_BROKEN_CALLOC .. cmake:: GMX_BUILD_FOR_COVERAGE 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. .. TODO: This could likely be replaced by a (yet another) build type. .. cmake:: GMX_BUILD_MDRUN_ONLY If set ``ON``, the build system is configured to only build and install a single :file:`mdrun` executable. To be fully functional, the installed :file:`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 :file:`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 :file:`gmx` executable is built and installed, together with all the supporting files. :command:`mdrun` can be executed as :command:`gmx mdrun`. .. cmake:: GMX_BUILD_OWN_FFTW .. cmake:: GMX_BUILD_SHARED_EXE .. cmake:: GMX_COMPILER_WARNINGS If set ``ON``, various compiler warnings are enabled for compilers that Jenkins uses for verification. Defaults to ``OFF`` when building from a source tarball so that users compiling with versions not tested on Jenkins are not exposed to our rather aggressive warning flags that can trigger a lot of warnings with, e.g., new versions of the compilers we use. When building from a git repository, defaults to ``ON``. .. cmake:: GMX_CYCLE_SUBCOUNTERS If set to ``ON``, enables performance subcounters that offer more fine-grained mdrun performance measurement and evaluation than the default counters. See :doc:`/user-guide/mdrun-performance` for the description of subcounters which are available. Defaults to ``OFF``. .. cmake:: GMX_ENABLE_CCACHE If set to ``ON``, attempts to set up the `ccache `_ caching compiler wrapper to speed up repeated builds. The ``ccache`` executable is searched for with ``find_package()`` if CMake is being run with a compatible build type. If the executable is found and a compatible compiler is configured, CMake launch wrapper scripts are set. If enabled, the ``ccache`` executable location discovered by CMake must be accessible during build, as well. Defaults to ``OFF`` to minimize build system complexity. .. cmake:: GMX_INSTALL_DATASUBDIR Sets the subdirectory under CMAKE_INSTALL_DATADIR where GROMACS-specific read-only architecture-independent data files are installed. The default is ``gromacs``, which means the files will go under ``share/gromacs``. To alter the ``share`` part, change CMAKE_INSTALL_DATADIR. See :doc:`relocatable-binaries` for how this influences the build. .. cmake:: GMX_DOUBLE Many part of |Gromacs| are implemented in terms of "real" precision, which is actually either a single- or double-precision type, according to the value of this flag. Some parts of the code deliberately use single- or double-precision types, and these are unaffected by this setting. See reference manual for further information. .. cmake:: GMX_RELAXED_DOUBLE_PRECISION Permit a double-precision configuration to compute some quantities to single-precision accuracy. Particularly on architectures where only double-precision SIMD is available (e.g. Sparc machines such as the K computer), it is faster to default to ``GMX_DOUBLE=ON`` and use SIMD than to use ``GMX_DOUBLE=OFF`` and use no SIMD. However, if the user does not need full double precision, then some optimizations can achieve the equivalent of single-precision results (e.g. fewer Newton-Raphson iterations for a reciprocal square root computation). .. cmake:: GMX_EXTRAE .. cmake:: GMX_EXTERNAL_BLAS .. cmake:: GMX_EXTERNAL_LAPACK .. cmake:: GMX_EXTERNAL_TNG .. cmake:: GMX_FFT_LIBRARY .. cmake:: GMX_GIT_VERSION_INFO 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 :command:`git` is found, otherwise ``OFF``. If ``OFF``, static version information from :file:`cmake/gmxVersionInfo.cmake` is used. .. cmake:: GMX_GPU .. cmake:: GMX_CLANG_CUDA Use clang for compiling CUDA GPU code, both host and device. .. cmake:: GMX_CUDA_CLANG_FLAGS Pass additional CUDA-only compiler flags to clang using this variable. .. cmake:: CMAKE_INSTALL_LIBDIR Sets the installation directory for libraries (default is determined by standard CMake package ``GNUInstallDirs``). See :doc:`relocatable-binaries` for how this influences the build. .. cmake:: GMX_LOAD_PLUGINS .. cmake:: GMX_MPI .. cmake:: GMX_OPENMP .. cmake:: GMX_PREFER_STATIC_LIBS .. cmake:: GMX_SIMD .. cmake:: GMX_SOFTWARE_INVSQRT .. cmake:: GMX_THREAD_MPI .. cmake:: GMX_USE_RDTSCP .. cmake:: GMX_USE_TNG .. cmake:: GMX_VMD_PLUGIN_PATH .. cmake:: GMX_X11 .. cmake:: GMX_XML Currently, this option has no effect on the compilation or linking, since there is no code outside the tests that would use :file:`libxml2`. Variables affecting the ``all`` target ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. cmake:: BUILD_TESTING Standard variable created by CTest that enables/disables all tests. Defaults to ``ON``. .. cmake:: GMX_BUILD_HELP Controls handling of man pages and shell completions. Possible values: ``OFF`` (default for builds from release source distribution) Man pages and shell completions are not generated as part of the ``all`` target, and only installed if compiling from a source package. ``AUTO`` (default for builds from development version) Shell completions are generated by executing the :file:`gmx` binary as part of the ``all`` target. If it fails, a message is printed, but the build succeeds. Man pages need to be generated manually by invoking the ``man`` target. Man pages and shell completions are installed if they have been successfully generated. ``ON`` Works the same as ``AUTO``, except that if invoking the :file:`gmx` binary fails, the build fails as well. .. cmake:: GMX_DEVELOPER_BUILD If set ``ON``, the ``all`` target will include also the test binaries using Google Test (if :cmake:`GMX_BUILD_UNITTESTS` is ``ON``). Also, :cmake:`GMX_COMPILER_WARNINGS` is always enabled. 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. .. cmake:: GMX_CLANG_TIDY `clang-tidy `_ is used for static code analysis and (some) automated fixing of issues detected. clang-tidy is easy to install. It is contained in the llvm binary `package `_. Only version 8.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 seperately (running clang-tidy with ``-fix-errors`` as part of the build can corrupt header files). To fix a specific file run ``clang-tidy -fix-errors -header-filter '.*' {file}``, to fix all files in parallel ``run-clang-tidy.py -fix -header-filter '.*' '(?