Build system improvements (#4608)

Description of changes:
- use modern CMake and enable ccache for CUDA files
- document all CMake options of the ESPResSo project
- fix regressions in the python documentation that will become errors in future Sphinx and autopep versions
- rewrite and unit test the config file generator
   - bugfix: compiler errors are no longer ignored when parsing `myconfig-final.hpp` and `cmake_config.hpp`
   - bugfix: external features mismatch between `features.def` and `cmake_config.cmakein` now throws errors

CMakeLists.txt

@@ -123,14 +123,13 @@ set(TEST_TIMEOUT "300" CACHE STRING
                              "Timeout in seconds for each testsuite test")
 
 if(WITH_CCACHE)
-  find_program(CCACHE ccache)
-  if(CCACHE)
-    message(STATUS "Found ccache ${CCACHE}")
-    set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE} CACHE STRING "ccache executable")
-  else()
-    message(FATAL_ERROR "ccache not found.")
-  endif(CCACHE)
-endif(WITH_CCACHE)
+  find_program(CCACHE_PROGRAM ccache REQUIRED)
+  if(CCACHE_PROGRAM)
+    message(STATUS "Found ccache: ${CCACHE_PROGRAM}")
+    set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE_PROGRAM})
+    set(CMAKE_CUDA_COMPILER_LAUNCHER ${CCACHE_PROGRAM})
+  endif()
+endif()
 
 # Write compile commands to file, for various tools...
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
@@ -321,20 +320,25 @@ endif(WITH_VALGRIND_INSTRUMENTATION)
 #
 
 find_package(MPI 3.0 REQUIRED)
-find_package(MpiexecBackend)
+include(espresso_get_mpiexec_vendor)
+espresso_get_mpiexec_vendor()
+message(
+  STATUS
+    "Found ${ESPRESSO_MPIEXEC_VENDOR}: ${MPIEXEC} (version \"${ESPRESSO_MPIEXEC_VERSION}\")"
+)
 
 # OpenMPI checks the number of processes against the number of CPUs
 set(MPIEXEC_OVERSUBSCRIBE "")
 # Open MPI 4.x has a bug on NUMA archs that prevents running in singleton mode
 set(ESPRESSO_MPIEXEC_GUARD_SINGLETON_NUMA OFF)
 set(ESPRESSO_CPU_MODEL_NAME_OMPI_SINGLETON_NUMA_PATTERN "AMD (EPYC|Ryzen)")
 
-if("${MPIEXEC_BACKEND_NAME}" STREQUAL "OpenMPI")
-  if("${MPIEXEC_BACKEND_VERSION}" VERSION_GREATER_EQUAL 2.0.0)
+if("${ESPRESSO_MPIEXEC_VENDOR}" STREQUAL "OpenMPI")
+  if(${ESPRESSO_MPIEXEC_VERSION} VERSION_GREATER_EQUAL 2.0.0)
     set(MPIEXEC_OVERSUBSCRIBE "-oversubscribe")
   endif()
-  if("${MPIEXEC_BACKEND_VERSION}" VERSION_GREATER_EQUAL 4.0
-     AND "${MPIEXEC_BACKEND_VERSION}" VERSION_LESS 5.0)
+  if(${ESPRESSO_MPIEXEC_VERSION} VERSION_GREATER_EQUAL 4.0
+     AND ${ESPRESSO_MPIEXEC_VERSION} VERSION_LESS 5.0)
     if(NOT DEFINED ESPRESSO_CPU_MODEL_NAME)
       if(CMAKE_SYSTEM_NAME STREQUAL Linux)
         if(EXISTS /proc/cpuinfo)
@@ -363,7 +367,7 @@ endif()
 # base folder is deleted upon completion of a job, other jobs will fail when
 # attempting to create subdirectories in the base folder.
 # https://github.com/open-mpi/ompi/issues/8510
-if("${MPIEXEC_BACKEND_NAME}" STREQUAL "OpenMPI" AND INSIDE_DOCKER)
+if("${ESPRESSO_MPIEXEC_VENDOR}" STREQUAL "OpenMPI" AND INSIDE_DOCKER)
   cmake_host_system_information(RESULT hostname QUERY HOSTNAME)
   function(set_mpiexec_tmpdir)
     set(MPIEXEC_TMPDIR --mca orte_tmpdir_base

cmake/FindCUDACompilerClang.cmake

@@ -87,12 +87,12 @@ set(CUDA 1)
 target_compile_options(
   espresso_cuda_flags
   INTERFACE
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Debug>:-g>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Release>:-O3 -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},MinSizeRel>:-O2 -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},RelWithDebInfo>:-O2 -g -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Coverage>:-O3 -g>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},RelWithAssert>:-O3 -g>
+  $<$<CONFIG:Debug>:-g>
+  $<$<CONFIG:Release>:-O3 -DNDEBUG>
+  $<$<CONFIG:MinSizeRel>:-O2 -DNDEBUG>
+  $<$<CONFIG:RelWithDebInfo>:-O2 -g -DNDEBUG>
+  $<$<CONFIG:Coverage>:-O3 -g>
+  $<$<CONFIG:RelWithAssert>:-O3 -g>
   # GTX-900 series (Maxwell)
   $<$<VERSION_LESS:${CMAKE_CUDA_COMPILER_VERSION},12>:--cuda-gpu-arch=sm_52>
   # GTX-1000 series (Pascal)

cmake/FindCUDACompilerNVCC.cmake

@@ -53,12 +53,12 @@ add_library(espresso::cuda_flags ALIAS espresso_cuda_flags)
 target_compile_options(
   espresso_cuda_flags
   INTERFACE
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Debug>:>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Release>:-Xptxas=-O3 -Xcompiler=-O3 -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},MinSizeRel>:-Xptxas=-O2 -Xcompiler=-Os -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},RelWithDebInfo>:-Xptxas=-O2 -Xcompiler=-O2,-g -DNDEBUG>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},Coverage>:-Xptxas=-O3 -Xcompiler=-Og,-g>
-  $<$<STREQUAL:${CMAKE_BUILD_TYPE},RelWithAssert>:-Xptxas=-O3 -Xcompiler=-O3,-g>
+  $<$<CONFIG:Debug>:>
+  $<$<CONFIG:Release>:-Xptxas=-O3 -Xcompiler=-O3 -DNDEBUG>
+  $<$<CONFIG:MinSizeRel>:-Xptxas=-O2 -Xcompiler=-Os -DNDEBUG>
+  $<$<CONFIG:RelWithDebInfo>:-Xptxas=-O2 -Xcompiler=-O2,-g -DNDEBUG>
+  $<$<CONFIG:Coverage>:-Xptxas=-O3 -Xcompiler=-Og,-g>
+  $<$<CONFIG:RelWithAssert>:-Xptxas=-O3 -Xcompiler=-O3,-g>
   "--compiler-bindir=${CMAKE_CXX_COMPILER}"
   $<$<BOOL:${WARNINGS_ARE_ERRORS}>:-Xcompiler=-Werror;-Xptxas=-Werror>
   $<$<BOOL:${CMAKE_OSX_SYSROOT}>:-Xcompiler=-isysroot;-Xcompiler=${CMAKE_OSX_SYSROOT}>
@@ -67,7 +67,7 @@ target_compile_options(
 function(add_gpu_library)
   add_library(${ARGV})
   set(GPU_TARGET_NAME ${ARGV0})
-  set_property(TARGET ${GPU_TARGET_NAME} PROPERTY CUDA_SEPARABLE_COMPILATION ON)
+  set_target_properties(${GPU_TARGET_NAME} PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
   target_link_libraries(${GPU_TARGET_NAME} PRIVATE espresso::cuda_flags)
   list(APPEND cuda_archs 75) # RTX-2000 series (Turing)
   list(APPEND cuda_archs 61) # GTX-1000 series (Pascal)

cmake/cmake_config.cmakein

@@ -3,8 +3,6 @@
 
 #cmakedefine CUDA
 
-#cmakedefine HIP
-
 #cmakedefine FFTW
 
 #cmakedefine H5MD
@@ -13,10 +11,6 @@
 
 #cmakedefine GSL
 
-#cmakedefine BLAS
-
-#cmakedefine LAPACK
-
 #cmakedefine STOKESIAN_DYNAMICS
 
 #cmakedefine VALGRIND_INSTRUMENTATION

cmake/espresso_get_mpiexec_vendor.cmake

@@ -0,0 +1,51 @@
+#
+# Copyright (C) 2022 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+# Find the MPI backend.
+#
+# This code sets the following variables:
+#
+#  ESPRESSO_MPIEXEC_VENDOR ESPRESSO_MPIEXEC_VERSION
+
+function(espresso_get_mpiexec_vendor)
+  set(MPIEXEC_BACKEND_NAME "unknown")
+  set(MPIEXEC_BACKEND_VERSION 0.0.0)
+  execute_process(
+    COMMAND ${MPIEXEC} --version RESULT_VARIABLE MPI_VERSION_RESULT
+    OUTPUT_VARIABLE MPI_VERSION_OUTPUT ERROR_VARIABLE MPI_VERSION_OUTPUT)
+  if(MPI_VERSION_RESULT EQUAL 0)
+    if(MPI_VERSION_OUTPUT MATCHES "Intel\\(R\\) MPI Library")
+      set(MPIEXEC_BACKEND_NAME "Intel")
+      string(REGEX REPLACE ".*Build ([0-9]+).*" "\\1" MPIEXEC_BACKEND_VERSION
+                           ${MPI_VERSION_OUTPUT})
+    endif()
+    if(MPI_VERSION_OUTPUT MATCHES "HYDRA")
+      set(MPIEXEC_BACKEND_NAME "MPICH")
+      string(REGEX REPLACE ".*Version: +([0-9\\.]+).*" "\\1"
+                           MPIEXEC_BACKEND_VERSION ${MPI_VERSION_OUTPUT})
+    endif()
+    if(MPI_VERSION_OUTPUT MATCHES "\\(Open(RTE| MPI)\\)")
+      set(MPIEXEC_BACKEND_NAME "OpenMPI")
+      string(REGEX REPLACE ".*\\(Open(RTE| MPI)\\) ([0-9\\.]+).*" "\\2"
+                           MPIEXEC_BACKEND_VERSION ${MPI_VERSION_OUTPUT})
+    endif()
+  endif()
+  set(ESPRESSO_MPIEXEC_VENDOR ${MPIEXEC_BACKEND_NAME} PARENT_SCOPE)
+  set(ESPRESSO_MPIEXEC_VERSION ${MPIEXEC_BACKEND_VERSION} PARENT_SCOPE)
+endfunction()

cmake/version.cmake

@@ -1,3 +1,22 @@
+#
+# Copyright (C) 2017-2022 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
 if(GIT_EXECUTABLE)
   # Get the name of the working branch
   execute_process(

doc/CMakeLists.txt

@@ -1,3 +1,22 @@
+#
+# Copyright (C) 2015-2022 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
 add_subdirectory(doxygen)
 add_subdirectory(sphinx)
 add_subdirectory(logo)

doc/logo/CMakeLists.txt

@@ -1,3 +1,22 @@
+#
+# Copyright (C) 2015-2022 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
 set(logo_FILES
     logo.svg logo.pdf logo_500x500.png logo-small.svg logo-small.pdf
     logo_32x32.png logo_48x48.png logo_100x100.png logo-animated-100.gif

doc/sphinx/installation.rst

@@ -736,37 +736,56 @@ Options and Variables
 ~~~~~~~~~~~~~~~~~~~~~
 
 The behavior of |es| can be controlled by means of options and variables
-in the :file:`CMakeLists.txt` file. Also options are defined there.
-The following options are available:
-
-* ``WITH_CUDA``: Build with GPU support
-
-* ``WITH_HDF5``: Build with HDF5
-
-* ``WITH_TESTS``: Enable tests
-
-* ``WITH_SCAFACOS``: Build with ScaFaCoS support
-
-* ``WITH_STOKESIAN_DYNAMICS`` Build with Stokesian Dynamics support
-
-* ``WITH_VALGRIND_INSTRUMENTATION``: Build with valgrind instrumentation
-  markers
-
+in the :file:`CMakeLists.txt` file. Most options are boolean values
+(``ON`` or ``OFF``). A few options are strings or semicolon-delimited lists.
+
+The following options control features from external libraries:
+
+* ``WITH_CUDA``: Build with GPU support.
+* ``WITH_HDF5``: Build with HDF5 support.
+* ``WITH_SCAFACOS``: Build with ScaFaCoS support.
+* ``WITH_GSL``: Build with GSL support.
+* ``WITH_STOKESIAN_DYNAMICS`` Build with Stokesian Dynamics support.
+
+The following options control code instrumentation:
+
+* ``WITH_VALGRIND_INSTRUMENTATION``: Build with valgrind instrumentation markers
+* ``WITH_PROFILER``: Build with Caliper profiler annotations
+* ``WITH_MSAN``: Compile C++ code with memory sanitizer
+* ``WITH_ASAN``: Compile C++ code with address sanitizer
+* ``WITH_UBSAN``: Compile C++ code with undefined behavior sanitizer
+* ``WITH_COVERAGE``: Generate C++ code coverage reports when running |es|
+* ``WITH_COVERAGE_PYTHON``: Generate Python code coverage reports when running |es|
+
+The following options control how the project is built and tested:
+
+* ``WITH_CLANG_TIDY``: Run Clang-Tidy during compilation.
+* ``WITH_CPPCHECK``: Run Cppcheck during compilation.
+* ``WITH_CCACHE``: Enable compiler cache for faster rebuilds.
+* ``WITH_TESTS``: Enable C++ and Python tests.
+* ``WITH_CUDA_COMPILER`` (string): Select the CUDA compiler.
+* ``CTEST_ARGS`` (string): Arguments passed to the ``ctest`` command.
+* ``TEST_TIMEOUT``: Test timeout.
 * ``ESPRESSO_ADD_OMPI_SINGLETON_WARNING``: Add a runtime warning in the
   pypresso and ipypresso scripts that is triggered in singleton mode
   with Open MPI version 4.x on unsupported NUMA environments
   (see :term:`MPI installation requirements <MPI>` for details).
-
-When the value in the :file:`CMakeLists.txt` file is set to ON, the
-corresponding option is created; if the value of the option is set to OFF,
-the corresponding option is not created. These options can also be modified
+* ``MYCONFIG_NAME`` (string): Filename of the user-provided config file
+* ``MPIEXEC_PREFLAGS``, ``MPIEXEC_POSTFLAGS`` (strings): Flags passed to the
+  ``mpiexec`` command in MPI-parallel tests and benchmarks.
+* ``CMAKE_CXX_FLAGS`` (string): Flags passed to the compilers.
+* ``CMAKE_BUILD_TYPE`` (string): Build type. Default is ``Release``.
+* ``CUDA_TOOLKIT_ROOT_DIR`` (string): Path to the CUDA toolkit directory.
+
+Most of these options are opt-in, meaning their default value is set to
+``OFF`` in the :file:`CMakeLists.txt` file. These options can be modified
 by calling ``cmake`` with the command line argument ``-D``:
 
 .. code-block:: bash
 
     cmake -D WITH_HDF5=OFF ..
 
-When an option is activated, additional options may become available.
+When an option is enabled, additional options may become available.
 For example with ``-D WITH_CUDA=ON``, one can choose the CUDA compiler with
 ``-D WITH_CUDA_COMPILER=<compiler_id>``, where ``<compiler_id>`` can be
 ``nvcc`` (default) or ``clang``.