--- /dev/null
+.. highlight:: bash
+
+Build system overview
+=====================
+
+The |Gromacs| build system uses CMake (version
+|GMX_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
+-----------
+
+.. TODO: Document our usage of build types in general, and list the existing
+ build types, describing their purpose.
+
+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_CXX11
+
+ 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.
+
+.. cmake:: GMX_CYCLE_SUBCOUNTERS
+
+.. cmake:: GMX_DATA_INSTALL_DIR
+
+ Sets the directory under :file:`share/` where data files are installed.
+ The default is ``gromacs``, which puts the files under
+ file:`share/gromacs/`.
+ See :doc:`relocatable-binaries` for how this influences the build.
+
+.. cmake:: GMX_DOUBLE
+
+.. cmake:: GMX_EXTRAE
+
+.. cmake:: GMX_EXTERNAL_BLAS
+
+.. cmake:: GMX_EXTERNAL_LAPACK
+
+.. cmake:: GMX_EXTERNAL_BOOST
+
+ If ``ON``, |GROMACS| is compiled against Boost headers found in the system.
+ If ``OFF``, a subset of Boost headers found in :file:`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.
+
+.. 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_LIB_INSTALL_DIR
+
+ 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``).
+ 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.
+
+Variables affecting special targets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cmake:: CPPCHECK_XML_OUTPUT
+
+ 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.
+
+.. cmake:: GMX_BUILD_MANUAL
+
+ 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.
+
+ .. TODO: Consider if this is really necessary, or if we could just use
+ GMX_DEVELOPER_BUILD.
+
+.. cmake:: GMX_BUILD_TARBALL
+
+ 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``.
+
+.. cmake:: GMX_BUILD_UNITTESTS
+
+ 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
+ :cmake:`GMX_DEVELOPER_BUILD`). :file:`libxml2` is required for building the
+ tests, but other prerequisites (Google Test and Google Mock frameworks) are
+ included in :file:`src/external/`.
+ Defaults to ``ON`` if :file:`libxml2` is found and :cmake:`BUILD_TESTING` is
+ ``ON``.
+
+.. cmake:: GMX_COMPACT_DOXYGEN
+
+ 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``.
+
+.. cmake:: REGRESSIONTEST_DOWNLOAD
+
+ If set ``ON``, CMake will download the regression tests and extract them to
+ a local directory. :cmake:`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``.
+
+.. cmake:: REGRESSIONTEST_PATH
+
+ Path to extracted regression test suite matching the source tree (the
+ directory containing :file:`gmxtest.pl`)
+ If set, CTest tests are generated to run the regression tests.
+ Defaults to empty.
+
+.. cmake:: SOURCE_MD5SUM
+
+ Sets the MD5 sum of the release tarball when generating the HTML
+ documentation. It gets inserted into the download section of the HTML
+ pages.
+
+External libraries
+------------------
+
+.. TODO: List external libraries used (either from src/external/, or from the
+ system), whether they are required or optional, what functionality they
+ provide for Gromacs, and how to control their use.
+
+Special targets
+---------------
+
+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.
+
+check
+ Builds all the binaries needed by the tests and runs the tests. If some
+ types of tests are not available, shows a note to the user.
+ This is the main target intended for normal users to run the tests.
+ See :doc:`testutils`.
+check-source
+ Runs a custom Python checker script to check for various source-level
+ issues. Uses Doxygen XML documentation as well as rudimentary parsing of
+ some parts of the source files.
+ This target is used as part of the Jenkins documentation job.
+ All CMake code is currently in :file:`docs/doxygen/`.
+ See :doc:`gmxtree`.
+completion
+ Runs the compiled :file:`gmx` executable to generate shell command-line
+ completion definitions. This target is only added if
+ :cmake:`GMX_BUILD_HELP` is not ``OFF``, and it is run automatically as part
+ of the default ``all`` target. See :cmake:`GMX_BUILD_HELP`.
+ All CMake code is in :file:`src/programs/`.
+cppcheck
+ Runs :command:`cppcheck` with the flags used in Jenkins for all the source
+ files. This target is directly used by the Jenkins cppcheck job.
+ All CMake code is in :file:`tests/CppCheck.cmake`.
+dep-graphs*
+ Builds include dependency graphs for the source files using :command:`dot`
+ from graphviz.
+ All CMake code is in :file:`docs/doxygen/`.
+ See :doc:`gmxtree`.
+doxygen-*
+ Targets that run Doxygen to generate the documentation.
+ The ``doxygen-all`` target runs as part of the ``webpage`` target, which in
+ turn runs as part of the Jenkins documentation job.
+ All CMake code is in :file:`docs/doxygen/`.
+ See :doc:`doxygen`.
+install-guide
+ Runs Sphinx to generate a plain-text INSTALL file for the source package.
+ The files is generated at :file:`docs/install-guide/text/`, from where it
+ gets put at the root of the source package by CPack.
+ All CMake code is in :file:`docs/`.
+man
+ Runs Sphinx to generate man pages for the programs.
+ Internally, also runs the compiled :file:`gmx` executable to generate the
+ input files for Sphinx.
+ All CMake code is in :file:`docs/`.
+ See :cmake:`GMX_BUILD_HELP` for information on when the man pages are
+ installed.
+manual
+ Runs LaTeX to generate the reference PDF manual.
+ All CMake code is in :file:`docs/manual/`.
+ See :cmake:`GMX_BUILD_MANUAL`.
+package_source
+ Standard target created by CPack that builds a source package.
+ This target is used to generate the released source packages.
+test
+ Standard target created by CTest that runs all the registered tests.
+ Note that this does not build the test binaries, only runs them, so you need
+ to first ensure that they are up-to-date.
+ See :doc:`testutils`.
+tests
+ Builds all the binaries needed by the tests (but not ``gmx``).
+ See :doc:`testutils`.
+webpage
+ Collection target that runs the other documentation targets to generate the
+ full set of HTML (and linked) documentaion.
+ This target is used as part of the Jenkins documentation job.
+ All CMake code is in :file:`docs/`.
+webpage-sphinx
+ Runs Sphinx to generate most content for the HTML documentation (the set of
+ web pages this developer guide is also part of).
+ Internally, also runs the compiled :file:`gmx` executable to generate some
+ input files for Sphinx.
+ All CMake code is in :file:`docs/`.
+
+Passing information to source code
+----------------------------------
+
+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.
+
+ :file:`buildinfo.h`
+ Contains various strings about the build environment, used mainly for
+ outputting version information to log files and when requested.
+ :file:`config.h`
+ Contains defines for conditional compilation within source files.
+ :file:`gmxpre-config.h`
+ Included by :file:`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
+ :file:`gmxpre.h`.
+
+ All the above files get generated in :file:`src/`.
+
+ Additionally, the following file is generated by the build system:
+
+ :file:`baseversion-gen.c`
+ Provides definitions for declarations in :file:`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.
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff