Building libvdwxc with CMake

This document describes how to build, test, and install libvdwxc with CMake. For the Autotools build system, see Building libvdwxc 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 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.

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.

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 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.