.. _building_with_cmake: .. index:: CMake, Configuration, Installation Building :program:`libvdwxc` with CMake ******************************************* This document describes how to build, test, and install :program:`libvdwxc` with CMake. For the Autotools build system, see :ref:`building_with_autotools`. Requirements =========================== The CMake build requires CMake 3.20 or newer, a C99 compiler, and a supported FFT library. FFTW3 in double precision and Intel oneMKL are supported for serial builds. MPI builds require an MPI C compiler and FFTW3 with its MPI library. PFFT is an optional dependency for MPI builds. A Fortran compiler is needed only to build the Fortran interface test. The Fortran interface library itself is built with the C compiler. Recommended procedure =========================== We recommend using a separate build directory. From the top source directory of :program:`libvdwxc`, run:: cmake -S . -B build \ -DCMAKE_INSTALL_PREFIX="$HOME/dft-libs/libvdwxc" \ -DBUILD_TESTING=ON cmake --build build -j 4 ctest --test-dir build --output-on-failure cmake --install build These commands configure the build, compile the libraries and tests, run the test suite, and install the result. CMake can build directly from a Git checkout without running ``autogen.sh`` or ``autoreconf``. Build directories starting with "tmp-" are ignored by Git. By default, CMake builds static libraries without MPI support. For single-configuration generators, the build type defaults to ``Release``. Use ``-DBUILD_SHARED_LIBS=ON`` to build shared libraries, or ``-DCMAKE_BUILD_TYPE=Debug`` for a debug build. Compilers can be selected when first configuring a build directory, for example:: cmake -S . -B build-gcc -DCMAKE_C_COMPILER=gcc Configuration options =========================== The following options control the main features of the CMake build: * ``BUILD_SHARED_LIBS`` builds shared libraries instead of static libraries. It is ``OFF`` by default. * ``BUILD_TESTING`` builds and registers the test suite with CTest. It is ``OFF`` by default. * ``VDWXC_ENABLE_MPI`` enables distributed FFTs with FFTW-MPI. It is ``OFF`` by default. * ``VDWXC_ENABLE_PFFT`` enables the PFFT backend when MPI is enabled. It is ``OFF`` by default. * ``VDWXC_ENABLE_TIMING`` enables timing information at run-time. It is ``OFF`` by default. * ``VDWXC_FFT_PROVIDER`` selects ``AUTO``, ``FFTW3``, or ``MKL``. It defaults to ``AUTO``. * ``VDWXC_FORTRAN_TESTS`` builds the Fortran interface test when testing is enabled. By default, it is enabled if a Fortran compiler is found. Set it to ``OFF`` to skip this test, or to ``ON`` to require it. MPI builds of this test also require MPI Fortran support. .. index:: FFT parameters; CMake FFT libraries =========================== Default behaviour ---------------------------- With ``VDWXC_FFT_PROVIDER=AUTO``, serial builds select oneMKL if the ``MKLROOT`` environment variable is set and non-empty, and FFTW3 otherwise. MPI builds always select FFTW3 in this mode. If the selected provider cannot be found, configuration stops with an error. Set ``VDWXC_FFT_PROVIDER`` explicitly to choose a provider. Using FFTW3 ---------------------------- To select FFTW3 explicitly, run:: cmake -S . -B build-fftw -DVDWXC_FFT_PROVIDER=FFTW3 CMake first looks for the FFTW3 CMake package. If it is unavailable, the build uses ``pkg-config`` to find ``fftw3``. For an installation outside the standard search paths, set ``CMAKE_PREFIX_PATH`` to its installation prefix:: cmake -S . -B build-fftw \ -DVDWXC_FFT_PROVIDER=FFTW3 \ -DCMAKE_PREFIX_PATH=/usr/local/my_fftw3 When using ``pkg-config``, ``PKG_CONFIG_PATH`` can also be used to specify the directory containing ``fftw3.pc``. Using Intel oneMKL ---------------------------- The oneMKL provider requires its CMake package and FFTW3 interface headers. For example:: MKLROOT=/path/to/mkl cmake -S . -B build-mkl \ -DVDWXC_FFT_PROVIDER=MKL The default oneMKL settings are ``MKL_INTERFACE=lp64``, ``MKL_THREADING=sequential``, and ``MKL_LINK=dynamic``. These can be changed through CMake cache options, for example ``-DMKL_LINK=static``. The oneMKL provider supports serial FFTs only. Distributed FFTs require the FFTW3 provider and FFTW-MPI. .. index:: MPI parameters; CMake MPI and PFFT =========================== To enable MPI support, run:: cmake -S . -B build-mpi \ -DVDWXC_ENABLE_MPI=ON \ -DVDWXC_FFT_PROVIDER=FFTW3 \ -DBUILD_TESTING=ON cmake --build build-mpi -j 4 ctest --test-dir build-mpi --output-on-failure CMake detects the MPI C compiler and launcher. If necessary, specify the MPI wrapper with ``-DMPI_C_COMPILER=/path/to/mpicc``. FFTW3 must provide ``fftw3-mpi.h`` and ``libfftw3_mpi`` as well as its serial library. Use FFTW3 and PFFT installations built for the selected MPI implementation. To enable PFFT, add ``-DVDWXC_ENABLE_PFFT=ON`` to an MPI-enabled configuration. PFFT is located through ``pkg-config``; set ``PKG_CONFIG_PATH`` to the directory containing ``pfft.pc`` if necessary. Configuration fails if PFFT is requested but cannot be found. Using the installed library =========================== The installation includes the libraries, headers, Fortran interface source, ``libvdwxc_info`` program, and metadata for CMake and ``pkg-config``. A CMake project can use the installed library as follows:: find_package(libvdwxc CONFIG REQUIRED) target_link_libraries(my_program PRIVATE libvdwxc::vdwxc) For the Fortran interface, link to ``libvdwxc::vdwxcfort`` and compile the installed ``vdwxcfort.f90`` module source with your Fortran compiler. Set ``CMAKE_PREFIX_PATH`` to the installation prefix of :program:`libvdwxc` when configuring the calling project if the installation is outside the standard search paths. Projects using ``pkg-config`` can query ``libvdwxc`` with:: pkg-config --cflags --libs libvdwxc Use ``pkg-config --static --cflags --libs libvdwxc`` when linking statically, so that dependency libraries are included.