docs/dev-manual/build-system.rst

   1 .. highlight:: bash
   2
   3 Build system overview
   4 =====================
   5
   6 The |Gromacs| build system uses CMake (version
   7 |GMX_CMAKE_MINIMUM_REQUIRED_VERSION| or newer is required) to generate the
   8 actual build system for the build tool choosen by the user.  See CMake
   9 documentation for general introduction to CMake and how to use it.  This
  10 documentation focuses on how the |Gromacs| build system is organized and
  11 implemented, and what features it provides to developers (some of which may be
  12 of interest to advanced users).
  13
  14 Most developers use ``make`` or ``ninja`` as the underlying build system, so
  15 there can be parts of the build system that are specifically designed for
  16 command-line consumption with these tools, and may not work ideally with other
  17 environments, but basic building should be possible with all the environments
  18 supported by CMake.
  19
  20 Also, the build system and version control is designed for out-of-source
  21 builds.  In-source builds mostly work (there are a few custom targets that do
  22 not), but no particular effort has been put to, e.g., having :file:`.gitignore`
  23 files that exclude all the build outputs, or to have the ``clean`` target
  24 remove all possible build outputs.
  25
  26 Build types
  27 -----------
  28
  29 Build types is a CMake concept that provides overall control of how
  30 the build tools are used on the given platform to produce executable
  31 code. These can be set in CMake in various ways, including on a
  32 command line such as ``cmake -DCMAKE_BUILD_TYPE=Debug``. |Gromacs|
  33 supports the following standard CMake build types:
  34
  35 **Release**
  36   Fully optimized code intended for use in production simulation. This is the
  37   default.
  38
  39 **Debug**
  40   Compiled code intended for use with debugging tools, with low optimization levels
  41   and debug information for symbols.
  42
  43 **RelWithDebInfo**
  44   As Release, but with debug information for symbol names, which can help debugging
  45   issues that only emerge in optimized code.
  46
  47 **MinSizeRel**
  48   As Release, but optimized to minimize the size of the resulting executable. This
  49   is never a concern for |Gromacs| installations, so should not be used, but
  50   probably works.
  51
  52 Additionally, |Gromacs| provides the following build types for development and
  53 testing. Their implementations can be found in ``cmake/gmxBuildTypeXXX.cmake``.
  54
  55 **Reference**
  56   This build type compiles a version of |Gromacs| aimed solely at correctness. All
  57   parallelization and optimization possibilities are disabled. This build type is
  58   compiled with gcc 4.7 to generate the regression test reference values, against
  59   which all other |Gromacs| builds are tested.
  60
  61 **RelWithAssert**
  62   As Release, but removes ``-DNDEBUG`` from compiler command lines, which makes
  63   all assertion statements active (and can have other safety-related side effects
  64   in |Gromacs| and code upon which it depends)
  65
  66 **Profile**
  67   As Release, but adds ``-pg`` for use with profiling tools. This is not
  68   likely to be effective for profiling the performance of :ref:`gmx mdrun`, but can
  69   be useful for the tools.
  70
  71 **TSAN**
  72   Builds |Gromacs| for use with ThreadSanitzer in gcc >= 4.8 and clang
  73   >= 3.4 (http://clang.llvm.org/docs/ThreadSanitizer.html) to detect
  74   data races. This disables the use of atomics in ThreadMPI,
  75   preferring the mutex-based implementation.
  76
  77 **ASAN**
  78   Builds |Gromacs| for use with AddressSanitzer in gcc >= 4.8 and
  79   clang >= 3.4 (http://clang.llvm.org/docs/AddressSanitizer.html) to
  80   detect many kinds of memory mis-use. By default, AddressSanitizer
  81   includes LeakSanitizer.
  82
  83 **MSAN**
  84   Builds |Gromacs| for use with AddressSanitzer in clang >= 3.4
  85   (http://clang.llvm.org/docs/MemorySanitizer.html) to detect
  86   reads of unitialized memory. This functionality requires that
  87   dependencies of the |Gromacs| build have been built in a compatible
  88   way (roughly, static libraries with ``-g -fsanitize=memory
  89   -fno-omit-frame-pointer``), which generally requires at least the C++
  90   standard library to have been built specially. The path where the
  91   includes and libraries for dependencies should be found for this
  92   build type is set in the CMake cache variable
  93   ``GMX_MSAN_PATH``. Only internal XDR and internal fftpack are
  94   supported at this time.
  95
  96 For all of the sanitizer builds, to get readable stack traces, you may
  97 need to ensure that the ``ASAN_SYMBOLIZER_PATH`` environment variable
  98 (or your ``PATH``) include that of the ``llvm-symbolizer`` binary.
  99
 100 With some generators, CMake generates the build system for more than a
 101 single ``CMAKE_BUILD_TYPE`` from one pass over the ``CMakeLists.txt``
 102 files, so any code that uses ``CMAKE_BUILD_TYPE`` in
 103 ``CMakeLists.txt`` directly will break. |Gromacs| does use such CMake
 104 code, so we do not fully support all these build types in such
 105 generators (which includes Visual Studio).
 106
 107 CMake cache variables
 108 ---------------------
 109
 110 This section provides a (currently incomplete) list of cache variables that
 111 developers or advanced users can set to affect what CMake generates and/or what
 112 will get built.
 113
 114 .. TODO: Figure out where to document basic variables intended for user
 115    consumption, and how does it relate to documentation here.
 116
 117 .. TODO: Document the remaining variables below, and identify any variables
 118    missing from the list.
 119
 120 Compiler flags
 121 ^^^^^^^^^^^^^^
 122
 123 Standard CMake mechanism for specifying the compiler flags is to use
 124 ``CMAKE_C_FLAGS``/``CMAKE_CXX_FLAGS`` for flags that affect all build types,
 125 and :samp:`CMAKE_C_FLAGS_{buildtype}`/:samp:`CMAKE_CXX_FLAGS_{buildtype}` for
 126 flags that only affect a specific build type.  CMake provides some default flags.
 127
 128 |Gromacs| determines its own set of default flags, grouped into two categories:
 129
 130 * Generic flags that are appended to the above default CMake flag variables
 131   (possibly for multiple build types), generally specifying optimization flags
 132   to use and controlling compiler warnings.
 133 * Specific flags for certain features that the build system determines to be
 134   necessary for successful compilation.  One example is flags that determine
 135   what SIMD instruction set the compiler is allowed to use/needs to support.
 136
 137 All of the above flags are only added after testing that they work with the
 138 provided compiler.
 139
 140 There is one cache variable to control the behavior of automatic compiler flags:
 141
 142 .. cmake:: GMX_SKIP_DEFAULT_CFLAGS
 143
 144    If set ``ON``, the build system will not add any compiler flags
 145    automatically (neither generic nor specific as defined above), and will skip
 146    most linker flags as well.
 147    The default flags that would have been added are instead printed out when
 148    :command:`cmake` is run, and the user can set the flags themselves using the
 149    CMake variables.
 150    If ``OFF`` (the default), the flags are added as described above.
 151
 152 The code the determine the default generic flags is in
 153 :file:`cmake/gmxCFlags.cmake`.
 154 Code that sets the specific flags (e.g., SIMD flags) is in the main
 155 :file:`CMakeLists.txt`; search for :cmake:`GMX_SKIP_DEFAULT_CFLAGS`.
 156 The variables used there can be traced back to the locations where the actual
 157 flags to use are determined.
 158
 159 Variables affecting compilation/linking
 160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 161
 162 .. cmake:: GMX_BROKEN_CALLOC
 163
 164 .. cmake:: GMX_BUILD_FOR_COVERAGE
 165
 166    Special variable set ``ON`` by Jenkins when doing a build for the coverage
 167    job.  Allows the build system to set options to produce as useful coverage
 168    metrics as possible.  Currently, it disables all asserts to avoid them
 169    showing up as poor conditional coverage.
 170    Defaults to ``OFF``, and there should not be any need to change this in a
 171    manual build.
 172
 173    .. TODO: This could likely be replaced by a (yet another) build type.
 174
 175 .. cmake:: GMX_BUILD_MDRUN_ONLY
 176
 177    If set ``ON``, the build system is configured to only build and install a
 178    single :file:`mdrun` executable.  To be fully functional, the installed
 179    :file:`mdrun` requires a standard |Gromacs| installation (with
 180    ``GMX_BUILD_MDRUN_ONLY=OFF``) in the same installation prefix, as the
 181    mdrun-only build does not install any data files or scripts, only the
 182    binary.  This is intended for cases where one wants to/needs to compile one
 183    or more instances of :file:`mdrun` with different build options (e.g., MPI
 184    or SIMD) than the full installation with the other utilities.
 185    Defaults to ``OFF``, in which case a single :file:`gmx` executable is built
 186    and installed, together with all the supporting files.  :command:`mdrun` can
 187    be executed as :command:`gmx mdrun`.
 188
 189 .. cmake:: GMX_BUILD_OWN_FFTW
 190
 191 .. cmake:: GMX_BUILD_SHARED_EXE
 192
 193 .. cmake:: GMX_CXX11
 194
 195    If ``ON``, some C++11 features are used internally (mainly
 196    ``std::unique_ptr``).
 197    If ``OFF``, no C++11 features are used in the code (``boost::shared_ptr`` is
 198    used as a replacement).
 199    The default is ``ON`` if the compilation environment is determined to
 200    support enough C++11 (GPU builds cannot for now use C++11).
 201    Installed headers are not affected.
 202
 203 .. cmake:: GMX_CYCLE_SUBCOUNTERS
 204
 205 .. cmake:: GMX_DATA_INSTALL_DIR
 206
 207    Sets the directory under :file:`share/` where data files are installed.
 208    The default is ``gromacs``, which puts the files under
 209    file:`share/gromacs/`.
 210    See :doc:`relocatable-binaries` for how this influences the build.
 211
 212 .. cmake:: GMX_DOUBLE
 213
 214 .. cmake:: GMX_EXTRAE
 215
 216 .. cmake:: GMX_EXTERNAL_BLAS
 217
 218 .. cmake:: GMX_EXTERNAL_LAPACK
 219
 220 .. cmake:: GMX_EXTERNAL_BOOST
 221
 222    If ``ON``, |GROMACS| is compiled against Boost headers found in the system.
 223    If ``OFF``, a subset of Boost headers found in :file:`src/external/boost/`
 224    is used instead.
 225
 226    Default is ``ON`` if external Boost library can be found, ``OFF`` otherwise.
 227
 228    The Boost headers are also used in installed headers and affect the API/ABI,
 229    so using the internal Boost can cause compatibility issues if compiling
 230    other software that uses both |GROMACS| and Boost.
 231
 232 .. cmake:: GMX_EXTERNAL_TNG
 233
 234 .. cmake:: GMX_FFT_LIBRARY
 235
 236 .. cmake:: GMX_GIT_VERSION_INFO
 237
 238    Whether to generate version information dynamically from git for each build
 239    (e.g., HEAD commit hash).
 240    Defaults to ``ON`` if the build is from a git repository and :command:`git`
 241    is found, otherwise ``OFF``.
 242    If ``OFF``, static version information from
 243    :file:`cmake/gmxVersionInfo.cmake` is used.
 244
 245 .. cmake:: GMX_GPU
 246
 247 .. cmake:: GMX_LIB_INSTALL_DIR
 248
 249    Sets the installation directory for libraries (default is determined by
 250    standard CMake package ``GNUInstallDirs``).
 251    See :doc:`relocatable-binaries` for how this influences the build.
 252
 253 .. cmake:: GMX_LOAD_PLUGINS
 254
 255 .. cmake:: GMX_MPI
 256
 257 .. cmake:: GMX_OPENMP
 258
 259 .. cmake:: GMX_PREFER_STATIC_LIBS
 260
 261 .. cmake:: GMX_SIMD
 262
 263 .. cmake:: GMX_SOFTWARE_INVSQRT
 264
 265 .. cmake:: GMX_THREAD_MPI
 266
 267 .. cmake:: GMX_USE_RDTSCP
 268
 269 .. cmake:: GMX_USE_TNG
 270
 271 .. cmake:: GMX_VMD_PLUGIN_PATH
 272
 273 .. cmake:: GMX_X11
 274
 275 .. cmake:: GMX_XML
 276
 277    Currently, this option has no effect on the compilation or linking, since
 278    there is no code outside the tests that would use :file:`libxml2`.
 279
 280 Variables affecting the ``all`` target
 281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 282
 283 .. cmake:: BUILD_TESTING
 284
 285    Standard variable created by CTest that enables/disables all tests.
 286    Defaults to ``ON``.
 287
 288 .. cmake:: GMX_BUILD_HELP
 289
 290    Controls handling of man pages and shell completions.  Possible values:
 291
 292    ``OFF`` (default for builds from release source distribution)
 293      Man pages and shell completions are not generated as part of the ``all``
 294      target, and only installed if compiling from a source package.
 295    ``AUTO`` (default for builds from development version)
 296      Shell completions are generated by executing the :file:`gmx` binary as
 297      part of the ``all`` target.  If it fails, a message is printed, but the
 298      build succeeds.
 299      Man pages need to be generated manually by invoking the ``man`` target.
 300      Man pages and shell completions are installed if they have been
 301      successfully generated.
 302    ``ON``
 303      Works the same as ``AUTO``, except that if invoking the :file:`gmx` binary
 304      fails, the build fails as well.
 305
 306 .. cmake:: GMX_DEVELOPER_BUILD
 307
 308    If set ``ON``, the ``all`` target will include also the test binaries using
 309    Google Test (if :cmake:`GMX_BUILD_UNITTESTS` is ``ON``).
 310    In the future, other developer convenience features (as well as features
 311    inconvenient for a general user) can be added to the set controlled by this
 312    variable.
 313
 314 Variables affecting special targets
 315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 316
 317 .. cmake:: CPPCHECK_XML_OUTPUT
 318
 319    If set ``ON``, the ``cppcheck`` target generates reports for all found
 320    issues in XML format.  This is used by Jenkins, which parses the XML files
 321    to show the issues on the web page.
 322    If ``OFF`` (the default), issues are reported as plain text to standard
 323    output and to a text file.
 324
 325 .. cmake:: GMX_BUILD_MANUAL
 326
 327    If set ``ON``, CMake detection for LaTeX and other prerequisites for the
 328    reference PDF manual is done, and the ``manual`` target for building the
 329    manual is generated.
 330    If ``OFF`` (the default), all detection is skipped and the manual cannot be
 331    built.
 332
 333    .. TODO: Consider if this is really necessary, or if we could just use
 334       GMX_DEVELOPER_BUILD.
 335
 336 .. cmake:: GMX_BUILD_TARBALL
 337
 338    If set ``ON``, ``-dev`` suffix is stripped off from version strings and some
 339    other version info logic is adjusted such that the man pages and other
 340    documentation generated from this build is suitable for releasing (on the
 341    web page and/or in the source distribution package).
 342    Defaults to ``OFF``.
 343
 344 .. cmake:: GMX_BUILD_UNITTESTS
 345
 346    If ``ON``, test binaries using Google Test are built (either as the separate
 347    ``tests`` targer, or also as part of the ``all`` target, depending on
 348    :cmake:`GMX_DEVELOPER_BUILD`).  :file:`libxml2` is required for building the
 349    tests, but other prerequisites (Google Test and Google Mock frameworks) are
 350    included in :file:`src/external/`.
 351    Defaults to ``ON`` if :file:`libxml2` is found and :cmake:`BUILD_TESTING` is
 352    ``ON``.
 353
 354 .. cmake:: GMX_COMPACT_DOXYGEN
 355
 356    If set ``ON``, Doxygen configuration is changed to avoid generating large
 357    dependency graphs, which makes it significantly faster to run Doxygen and
 358    reduces disk usage.  This is typically useful when developing the
 359    documentation to reduce the build times.
 360    Defaults to ``OFF``.
 361
 362 .. cmake:: REGRESSIONTEST_DOWNLOAD
 363
 364    If set ``ON``, CMake will download the regression tests and extract them to
 365    a local directory.  :cmake:`REGRESSIONTEST_PATH` is set to the extracted
 366    tests.  Note that this happens during the configure phase, not during the
 367    build.
 368    After the download is done, the variable is automatically reset to ``OFF``
 369    again to avoid repeated downloads.  Can be set to ``ON`` to download again.
 370    Defaults to ``OFF``.
 371
 372 .. cmake:: REGRESSIONTEST_PATH
 373
 374    Path to extracted regression test suite matching the source tree (the
 375    directory containing :file:`gmxtest.pl`)
 376    If set, CTest tests are generated to run the regression tests.
 377    Defaults to empty.
 378
 379 .. cmake:: SOURCE_MD5SUM
 380
 381    Sets the MD5 sum of the release tarball when generating the HTML
 382    documentation.  It gets inserted into the download section of the HTML
 383    pages.
 384
 385 External libraries
 386 ------------------
 387
 388 .. TODO: List external libraries used (either from src/external/, or from the
 389    system), whether they are required or optional, what functionality they
 390    provide for Gromacs, and how to control their use.
 391
 392 Special targets
 393 ---------------
 394
 395 In addition to the default ``all`` target, the generated build system has
 396 several custom targets that are intended to be explicitly built to perform
 397 various tasks (some of these may also run automatically).  There are various
 398 other targets as well used internally by these, but those are typically not
 399 intended to be invoked directly.
 400
 401 check
 402    Builds all the binaries needed by the tests and runs the tests.  If some
 403    types of tests are not available, shows a note to the user.
 404    This is the main target intended for normal users to run the tests.
 405    See :doc:`testutils`.
 406 check-source
 407    Runs a custom Python checker script to check for various source-level
 408    issues.  Uses Doxygen XML documentation as well as rudimentary parsing of
 409    some parts of the source files.
 410    This target is used as part of the Jenkins documentation job.
 411    All CMake code is currently in :file:`docs/doxygen/`.
 412    See :doc:`gmxtree`.
 413 completion
 414    Runs the compiled :file:`gmx` executable to generate shell command-line
 415    completion definitions.  This target is only added if
 416    :cmake:`GMX_BUILD_HELP` is not ``OFF``, and it is run automatically as part
 417    of the default ``all`` target.  See :cmake:`GMX_BUILD_HELP`.
 418    All CMake code is in :file:`src/programs/`.
 419 cppcheck
 420    Runs :command:`cppcheck` with the flags used in Jenkins for all the source
 421    files.  This target is directly used by the Jenkins cppcheck job.
 422    All CMake code is in :file:`tests/CppCheck.cmake`.
 423 dep-graphs*
 424    Builds include dependency graphs for the source files using :command:`dot`
 425    from graphviz.
 426    All CMake code is in :file:`docs/doxygen/`.
 427    See :doc:`gmxtree`.
 428 doxygen-*
 429    Targets that run Doxygen to generate the documentation.
 430    The ``doxygen-all`` target runs as part of the ``webpage`` target, which in
 431    turn runs as part of the Jenkins documentation job.
 432    All CMake code is in :file:`docs/doxygen/`.
 433    See :doc:`doxygen`.
 434 install-guide
 435    Runs Sphinx to generate a plain-text INSTALL file for the source package.
 436    The files is generated at :file:`docs/install-guide/text/`, from where it
 437    gets put at the root of the source package by CPack.
 438    All CMake code is in :file:`docs/`.
 439 man
 440    Runs Sphinx to generate man pages for the programs.
 441    Internally, also runs the compiled :file:`gmx` executable to generate the
 442    input files for Sphinx.
 443    All CMake code is in :file:`docs/`.
 444    See :cmake:`GMX_BUILD_HELP` for information on when the man pages are
 445    installed.
 446 manual
 447    Runs LaTeX to generate the reference PDF manual.
 448    All CMake code is in :file:`docs/manual/`.
 449    See :cmake:`GMX_BUILD_MANUAL`.
 450 package_source
 451    Standard target created by CPack that builds a source package.
 452    This target is used to generate the released source packages.
 453 test
 454    Standard target created by CTest that runs all the registered tests.
 455    Note that this does not build the test binaries, only runs them, so you need
 456    to first ensure that they are up-to-date.
 457    See :doc:`testutils`.
 458 tests
 459    Builds all the binaries needed by the tests (but not ``gmx``).
 460    See :doc:`testutils`.
 461 webpage
 462    Collection target that runs the other documentation targets to generate the
 463    full set of HTML (and linked) documentaion.
 464    This target is used as part of the Jenkins documentation job.
 465    All CMake code is in :file:`docs/`.
 466 webpage-sphinx
 467    Runs Sphinx to generate most content for the HTML documentation (the set of
 468    web pages this developer guide is also part of).
 469    Internally, also runs the compiled :file:`gmx` executable to generate some
 470    input files for Sphinx.
 471    All CMake code is in :file:`docs/`.
 472
 473 Passing information to source code
 474 ----------------------------------
 475
 476 The build system uses a few different mechanisms to influence the compilation:
 477
 478 * On the highest level, some CMake options select what files will be compiled.
 479 * Some options are passed on the compiler command line using ``-D`` or
 480   equivalent, such that they are available in every compilation unit.  This
 481   should be used with care to keep the compiler command lines manageable.
 482   You can find the current set of such defines with ::
 483
 484     git grep add_definitions
 485
 486 * A few header files are generated using CMake ``configure_file()`` and
 487   included in the desired source files.  These files must exist for the
 488   compilation to pass.  Only a few files use an ``#ifdef HAVE_CONFIG_H`` to
 489   protect against inclusion in case the define is not set; this is used in
 490   files that may get compiled outside the main build system.
 491
 492   :file:`buildinfo.h`
 493     Contains various strings about the build environment, used mainly for
 494     outputting version information to log files and when requested.
 495   :file:`config.h`
 496     Contains defines for conditional compilation within source files.
 497   :file:`gmxpre-config.h`
 498     Included by :file:`gmxpre.h` as the first thing in every source file.
 499     Should only contain defines that are required before any other header for
 500     correct operation.  For example, defines that affect the behavior of system
 501     headers fall in this category.  See Doxygen documentation for
 502     :file:`gmxpre.h`.
 503
 504   All the above files get generated in :file:`src/`.
 505
 506   Additionally, the following file is generated by the build system:
 507
 508   :file:`baseversion-gen.c`
 509     Provides definitions for declarations in :file:`baseversion-gen.h` for
 510     version info output.  The contents are generated either from Git version
 511     info, or from static version info if not building from a git repository.