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 .. TODO: Document our usage of build types in general, and list the existing
  30    build types, describing their purpose.
  31
  32 CMake cache variables
  33 ---------------------
  34
  35 This section provides a (currently incomplete) list of cache variables that
  36 developers or advanced users can set to affect what CMake generates and/or what
  37 will get built.
  38
  39 .. TODO: Figure out where to document basic variables intended for user
  40    consumption, and how does it relate to documentation here.
  41
  42 .. TODO: Document the remaining variables below, and identify any variables
  43    missing from the list.
  44
  45 Compiler flags
  46 ^^^^^^^^^^^^^^
  47
  48 Standard CMake mechanism for specifying the compiler flags is to use
  49 ``CMAKE_C_FLAGS``/``CMAKE_CXX_FLAGS`` for flags that affect all build types,
  50 and :samp:`CMAKE_C_FLAGS_{buildtype}`/:samp:`CMAKE_CXX_FLAGS_{buildtype}` for
  51 flags that only affect a specific build type.  CMake provides some default flags.
  52
  53 |Gromacs| determines its own set of default flags, grouped into two categories:
  54
  55 * Generic flags that are appended to the above default CMake flag variables
  56   (possibly for multiple build types), generally specifying optimization flags
  57   to use and controlling compiler warnings.
  58 * Specific flags for certain features that the build system determines to be
  59   necessary for successful compilation.  One example is flags that determine
  60   what SIMD instruction set the compiler is allowed to use/needs to support.
  61
  62 All of the above flags are only added after testing that they work with the
  63 provided compiler.
  64
  65 There is one cache variable to control the behavior of automatic compiler flags:
  66
  67 .. cmake:: GMX_SKIP_DEFAULT_CFLAGS
  68
  69    If set ``ON``, the build system will not add any compiler flags
  70    automatically (neither generic nor specific as defined above), and will skip
  71    most linker flags as well.
  72    The default flags that would have been added are instead printed out when
  73    :command:`cmake` is run, and the user can set the flags themselves using the
  74    CMake variables.
  75    If ``OFF`` (the default), the flags are added as described above.
  76
  77 The code the determine the default generic flags is in
  78 :file:`cmake/gmxCFlags.cmake`.
  79 Code that sets the specific flags (e.g., SIMD flags) is in the main
  80 :file:`CMakeLists.txt`; search for :cmake:`GMX_SKIP_DEFAULT_CFLAGS`.
  81 The variables used there can be traced back to the locations where the actual
  82 flags to use are determined.
  83
  84 Variables affecting compilation/linking
  85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  86
  87 .. cmake:: GMX_BROKEN_CALLOC
  88
  89 .. cmake:: GMX_BUILD_FOR_COVERAGE
  90
  91    Special variable set ``ON`` by Jenkins when doing a build for the coverage
  92    job.  Allows the build system to set options to produce as useful coverage
  93    metrics as possible.  Currently, it disables all asserts to avoid them
  94    showing up as poor conditional coverage.
  95    Defaults to ``OFF``, and there should not be any need to change this in a
  96    manual build.
  97
  98    .. TODO: This could likely be replaced by a (yet another) build type.
  99
 100 .. cmake:: GMX_BUILD_MDRUN_ONLY
 101
 102    If set ``ON``, the build system is configured to only build and install a
 103    single :file:`mdrun` executable.  To be fully functional, the installed
 104    :file:`mdrun` requires a standard |Gromacs| installation (with
 105    ``GMX_BUILD_MDRUN_ONLY=OFF``) in the same installation prefix, as the
 106    mdrun-only build does not install any data files or scripts, only the
 107    binary.  This is intended for cases where one wants to/needs to compile one
 108    or more instances of :file:`mdrun` with different build options (e.g., MPI
 109    or SIMD) than the full installation with the other utilities.
 110    Defaults to ``OFF``, in which case a single :file:`gmx` executable is built
 111    and installed, together with all the supporting files.  :command:`mdrun` can
 112    be executed as :command:`gmx mdrun`.
 113
 114 .. cmake:: GMX_BUILD_OWN_FFTW
 115
 116 .. cmake:: GMX_BUILD_SHARED_EXE
 117
 118 .. cmake:: GMX_CXX11
 119
 120    If ``ON``, some C++11 features are used internally (mainly
 121    ``std::unique_ptr``).
 122    If ``OFF``, no C++11 features are used in the code (``boost::shared_ptr`` is
 123    used as a replacement).
 124    The default is ``ON`` if the compilation environment is determined to
 125    support enough C++11 (GPU builds cannot for now use C++11).
 126    Installed headers are not affected.
 127
 128 .. cmake:: GMX_CYCLE_SUBCOUNTERS
 129
 130 .. cmake:: GMX_DATA_INSTALL_DIR
 131
 132    Sets the directory under :file:`share/` where data files are installed.
 133    The default is ``gromacs``, which puts the files under
 134    file:`share/gromacs/`.
 135    See :doc:`relocatable-binaries` for how this influences the build.
 136
 137 .. cmake:: GMX_DOUBLE
 138
 139 .. cmake:: GMX_EXTRAE
 140
 141 .. cmake:: GMX_EXTERNAL_BLAS
 142
 143 .. cmake:: GMX_EXTERNAL_LAPACK
 144
 145 .. cmake:: GMX_EXTERNAL_BOOST
 146
 147    If ``ON``, |GROMACS| is compiled against Boost headers found in the system.
 148    If ``OFF``, a subset of Boost headers found in :file:`src/external/boost/`
 149    is used instead.
 150
 151    Default is ``ON`` if external Boost library can be found, ``OFF`` otherwise.
 152
 153    The Boost headers are also used in installed headers and affect the API/ABI,
 154    so using the internal Boost can cause compatibility issues if compiling
 155    other software that uses both |GROMACS| and Boost.
 156
 157 .. cmake:: GMX_EXTERNAL_TNG
 158
 159 .. cmake:: GMX_FFT_LIBRARY
 160
 161 .. cmake:: GMX_GIT_VERSION_INFO
 162
 163    Whether to generate version information dynamically from git for each build
 164    (e.g., HEAD commit hash).
 165    Defaults to ``ON`` if the build is from a git repository and :command:`git`
 166    is found, otherwise ``OFF``.
 167    If ``OFF``, static version information from
 168    :file:`cmake/gmxVersionInfo.cmake` is used.
 169
 170 .. cmake:: GMX_GPU
 171
 172 .. cmake:: GMX_LIB_INSTALL_DIR
 173
 174    Sets the installation directory for libraries (default is determined by
 175    standard CMake package ``GNUInstallDirs``).
 176    See :doc:`relocatable-binaries` for how this influences the build.
 177
 178 .. cmake:: GMX_LOAD_PLUGINS
 179
 180 .. cmake:: GMX_MPI
 181
 182 .. cmake:: GMX_OPENMP
 183
 184 .. cmake:: GMX_PREFER_STATIC_LIBS
 185
 186 .. cmake:: GMX_SIMD
 187
 188 .. cmake:: GMX_SOFTWARE_INVSQRT
 189
 190 .. cmake:: GMX_THREAD_MPI
 191
 192 .. cmake:: GMX_USE_RDTSCP
 193
 194 .. cmake:: GMX_USE_TNG
 195
 196 .. cmake:: GMX_VMD_PLUGIN_PATH
 197
 198 .. cmake:: GMX_X11
 199
 200 .. cmake:: GMX_XML
 201
 202    Currently, this option has no effect on the compilation or linking, since
 203    there is no code outside the tests that would use :file:`libxml2`.
 204
 205 Variables affecting the ``all`` target
 206 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 207
 208 .. cmake:: BUILD_TESTING
 209
 210    Standard variable created by CTest that enables/disables all tests.
 211    Defaults to ``ON``.
 212
 213 .. cmake:: GMX_BUILD_HELP
 214
 215    Controls handling of man pages and shell completions.  Possible values:
 216
 217    ``OFF`` (default for builds from release source distribution)
 218      Man pages and shell completions are not generated as part of the ``all``
 219      target, and only installed if compiling from a source package.
 220    ``AUTO`` (default for builds from development version)
 221      Shell completions are generated by executing the :file:`gmx` binary as
 222      part of the ``all`` target.  If it fails, a message is printed, but the
 223      build succeeds.
 224      Man pages need to be generated manually by invoking the ``man`` target.
 225      Man pages and shell completions are installed if they have been
 226      successfully generated.
 227    ``ON``
 228      Works the same as ``AUTO``, except that if invoking the :file:`gmx` binary
 229      fails, the build fails as well.
 230
 231 .. cmake:: GMX_DEVELOPER_BUILD
 232
 233    If set ``ON``, the ``all`` target will include also the test binaries using
 234    Google Test (if :cmake:`GMX_BUILD_UNITTESTS` is ``ON``).
 235    In the future, other developer convenience features (as well as features
 236    inconvenient for a general user) can be added to the set controlled by this
 237    variable.
 238
 239 Variables affecting special targets
 240 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 241
 242 .. cmake:: CPPCHECK_XML_OUTPUT
 243
 244    If set ``ON``, the ``cppcheck`` target generates reports for all found
 245    issues in XML format.  This is used by Jenkins, which parses the XML files
 246    to show the issues on the web page.
 247    If ``OFF`` (the default), issues are reported as plain text to standard
 248    output and to a text file.
 249
 250 .. cmake:: GMX_BUILD_MANUAL
 251
 252    If set ``ON``, CMake detection for LaTeX and other prerequisites for the
 253    reference PDF manual is done, and the ``manual`` target for building the
 254    manual is generated.
 255    If ``OFF`` (the default), all detection is skipped and the manual cannot be
 256    built.
 257
 258    .. TODO: Consider if this is really necessary, or if we could just use
 259       GMX_DEVELOPER_BUILD.
 260
 261 .. cmake:: GMX_BUILD_TARBALL
 262
 263    If set ``ON``, ``-dev`` suffix is stripped off from version strings and some
 264    other version info logic is adjusted such that the man pages and other
 265    documentation generated from this build is suitable for releasing (on the
 266    web page and/or in the source distribution package).
 267    Defaults to ``OFF``.
 268
 269 .. cmake:: GMX_BUILD_UNITTESTS
 270
 271    If ``ON``, test binaries using Google Test are built (either as the separate
 272    ``tests`` targer, or also as part of the ``all`` target, depending on
 273    :cmake:`GMX_DEVELOPER_BUILD`).  :file:`libxml2` is required for building the
 274    tests, but other prerequisites (Google Test and Google Mock frameworks) are
 275    included in :file:`src/external/`.
 276    Defaults to ``ON`` if :file:`libxml2` is found and :cmake:`BUILD_TESTING` is
 277    ``ON``.
 278
 279 .. cmake:: GMX_COMPACT_DOXYGEN
 280
 281    If set ``ON``, Doxygen configuration is changed to avoid generating large
 282    dependency graphs, which makes it significantly faster to run Doxygen and
 283    reduces disk usage.  This is typically useful when developing the
 284    documentation to reduce the build times.
 285    Defaults to ``OFF``.
 286
 287 .. cmake:: REGRESSIONTEST_DOWNLOAD
 288
 289    If set ``ON``, CMake will download the regression tests and extract them to
 290    a local directory.  :cmake:`REGRESSIONTEST_PATH` is set to the extracted
 291    tests.  Note that this happens during the configure phase, not during the
 292    build.
 293    After the download is done, the variable is automatically reset to ``OFF``
 294    again to avoid repeated downloads.  Can be set to ``ON`` to download again.
 295    Defaults to ``OFF``.
 296
 297 .. cmake:: REGRESSIONTEST_PATH
 298
 299    Path to extracted regression test suite matching the source tree (the
 300    directory containing :file:`gmxtest.pl`)
 301    If set, CTest tests are generated to run the regression tests.
 302    Defaults to empty.
 303
 304 .. cmake:: SOURCE_MD5SUM
 305
 306    Sets the MD5 sum of the release tarball when generating the HTML
 307    documentation.  It gets inserted into the download section of the HTML
 308    pages.
 309
 310 External libraries
 311 ------------------
 312
 313 .. TODO: List external libraries used (either from src/external/, or from the
 314    system), whether they are required or optional, what functionality they
 315    provide for Gromacs, and how to control their use.
 316
 317 Special targets
 318 ---------------
 319
 320 In addition to the default ``all`` target, the generated build system has
 321 several custom targets that are intended to be explicitly built to perform
 322 various tasks (some of these may also run automatically).  There are various
 323 other targets as well used internally by these, but those are typically not
 324 intended to be invoked directly.
 325
 326 check
 327    Builds all the binaries needed by the tests and runs the tests.  If some
 328    types of tests are not available, shows a note to the user.
 329    This is the main target intended for normal users to run the tests.
 330    See :doc:`testutils`.
 331 check-source
 332    Runs a custom Python checker script to check for various source-level
 333    issues.  Uses Doxygen XML documentation as well as rudimentary parsing of
 334    some parts of the source files.
 335    This target is used as part of the Jenkins documentation job.
 336    All CMake code is currently in :file:`docs/doxygen/`.
 337    See :doc:`gmxtree`.
 338 completion
 339    Runs the compiled :file:`gmx` executable to generate shell command-line
 340    completion definitions.  This target is only added if
 341    :cmake:`GMX_BUILD_HELP` is not ``OFF``, and it is run automatically as part
 342    of the default ``all`` target.  See :cmake:`GMX_BUILD_HELP`.
 343    All CMake code is in :file:`src/programs/`.
 344 cppcheck
 345    Runs :command:`cppcheck` with the flags used in Jenkins for all the source
 346    files.  This target is directly used by the Jenkins cppcheck job.
 347    All CMake code is in :file:`tests/CppCheck.cmake`.
 348 dep-graphs*
 349    Builds include dependency graphs for the source files using :command:`dot`
 350    from graphviz.
 351    All CMake code is in :file:`docs/doxygen/`.
 352    See :doc:`gmxtree`.
 353 doxygen-*
 354    Targets that run Doxygen to generate the documentation.
 355    The ``doxygen-all`` target runs as part of the ``webpage`` target, which in
 356    turn runs as part of the Jenkins documentation job.
 357    All CMake code is in :file:`docs/doxygen/`.
 358    See :doc:`doxygen`.
 359 install-guide
 360    Runs Sphinx to generate a plain-text INSTALL file for the source package.
 361    The files is generated at :file:`docs/install-guide/text/`, from where it
 362    gets put at the root of the source package by CPack.
 363    All CMake code is in :file:`docs/`.
 364 man
 365    Runs Sphinx to generate man pages for the programs.
 366    Internally, also runs the compiled :file:`gmx` executable to generate the
 367    input files for Sphinx.
 368    All CMake code is in :file:`docs/`.
 369    See :cmake:`GMX_BUILD_HELP` for information on when the man pages are
 370    installed.
 371 manual
 372    Runs LaTeX to generate the reference PDF manual.
 373    All CMake code is in :file:`docs/manual/`.
 374    See :cmake:`GMX_BUILD_MANUAL`.
 375 package_source
 376    Standard target created by CPack that builds a source package.
 377    This target is used to generate the released source packages.
 378 test
 379    Standard target created by CTest that runs all the registered tests.
 380    Note that this does not build the test binaries, only runs them, so you need
 381    to first ensure that they are up-to-date.
 382    See :doc:`testutils`.
 383 tests
 384    Builds all the binaries needed by the tests (but not ``gmx``).
 385    See :doc:`testutils`.
 386 webpage
 387    Collection target that runs the other documentation targets to generate the
 388    full set of HTML (and linked) documentaion.
 389    This target is used as part of the Jenkins documentation job.
 390    All CMake code is in :file:`docs/`.
 391 webpage-sphinx
 392    Runs Sphinx to generate most content for the HTML documentation (the set of
 393    web pages this developer guide is also part of).
 394    Internally, also runs the compiled :file:`gmx` executable to generate some
 395    input files for Sphinx.
 396    All CMake code is in :file:`docs/`.
 397
 398 Passing information to source code
 399 ----------------------------------
 400
 401 The build system uses a few different mechanisms to influence the compilation:
 402
 403 * On the highest level, some CMake options select what files will be compiled.
 404 * Some options are passed on the compiler command line using ``-D`` or
 405   equivalent, such that they are available in every compilation unit.  This
 406   should be used with care to keep the compiler command lines manageable.
 407   You can find the current set of such defines with ::
 408
 409     git grep add_definitions
 410
 411 * A few header files are generated using CMake ``configure_file()`` and
 412   included in the desired source files.  These files must exist for the
 413   compilation to pass.  Only a few files use an ``#ifdef HAVE_CONFIG_H`` to
 414   protect against inclusion in case the define is not set; this is used in
 415   files that may get compiled outside the main build system.
 416
 417   :file:`buildinfo.h`
 418     Contains various strings about the build environment, used mainly for
 419     outputting version information to log files and when requested.
 420   :file:`config.h`
 421     Contains defines for conditional compilation within source files.
 422   :file:`gmxpre-config.h`
 423     Included by :file:`gmxpre.h` as the first thing in every source file.
 424     Should only contain defines that are required before any other header for
 425     correct operation.  For example, defines that affect the behavior of system
 426     headers fall in this category.  See Doxygen documentation for
 427     :file:`gmxpre.h`.
 428
 429   All the above files get generated in :file:`src/`.
 430
 431   Additionally, the following file is generated by the build system:
 432
 433   :file:`baseversion-gen.c`
 434     Provides definitions for declarations in :file:`baseversion-gen.h` for
 435     version info output.  The contents are generated either from Git version
 436     info, or from static version info if not building from a git repository.