1.3 Managing the build process with CMake

Building of FHI-aims is managed by CMake, which is a free and open-source build system generator. A build system generator is a tool that does not build anything by itself. Instead, it generates build scripts for a particular build system, e.g., Make, which are then used for the actual building. The build scripts, e.g., makefiles, are generated based on the user’s environment and it is the job of CMake to ensure that the generation stage is as straightforward and failsafe as possible. In principle, CMake is completely platform agnostic (the C stands for cross-platform). The focus of the present is on supporting FHI-aims in a Linux or Unix environment.

CMake was released in 2000 and is currently used in a large number of projects (including some big ones like HDF5, KDE, mySQL, and Netflix). One of the motivators for FHI-aims was a push from the ESL (Electronic Structure Library) project to adopt CMake as the build management standard. ESL is a collection of electronic structure codes with the aim of avoiding duplication of functionality by connecting different electronic structure codes with each other with minimal effort. That is one of the reasons to use CMake as it makes it relatively easy to include other CMake projects into a given project.

1.3.1 Example CMake usage

Here is a typical example to get started with CMake.

  1. 1.

    Go to the root directory of FHI-aims (the top-level directory of the FHI-aims git repository or the distributed version of FHI-aims - i.e., one level above src/) and create a build directory:

    mkdir build && cd build
  2. 2.

    Create a file called initial_cache.cmake in the build directory or make a copy of initial_cache.example.cmake which is in the root directory. The following is example contents for that file,

    ################
# Fortran Flags
################
set(CMAKE_Fortran_COMPILER "mpif90" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS "-O3 -ip -fp-model precise" CACHE STRING ""FORCE)
set(Fortran_MIN_FLAGS "-O0 -fp-model precise" CACHE STRING "" FORCE)

################
# C Flags
################
set(CMAKE_C_COMPILER "icc" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS "-O3 -ip -fp-model precise -std=gnu99" CACHE STRING "" FORCE)
set(CMAKE_CXX_COMPILER "icpc" CACHE STRING "" FORCE)

################
# Libraries
################
set(LIB_PATHS "/opt/intel/mkl/lib/intel64" CACHE STRING "" FORCE)
set(LIBS "mkl_intel_lp64 mkl_sequential mkl_core
mkl_blacs_intelmpi_lp64 mkl_scalapack_lp64" CACHE STRING "" FORCE)

################
# Optional Flags
################

# Switch on/off use of mpi; default: ON
set(USE_MPI ON CACHE BOOL "" FORCE)
# Switch on/off use of scalapack; default: ON
set(USE_SCALAPACK ON CACHE BOOL "" FORCE)
set(USE_HDF5 OFF CACHE BOOL "" FORCE)

    which you can edit to reflect your environment. The FORCE flag at the end of the set command tells CMake to overwrite existing entries. We recommend it as default. If you remove it, CMake will not change entries, once they have been initialized. When using the Intel C compiler, the -std=gnu99 flag (CMAKE_C_FLAGS flags) is currently needed for the C sources of ELPA and i-PI (this would not be the case with gcc, which also works fine together with Intel Fortran).

    As is evident, setting the correct values for these flags requires knowledge of several things: The Fortran and C compilers to be used, the Fortran and C compiler optimizations (or, correspondingly, flags for parts of the code that should not be optimized), the mathematical and MPI libraries to be used and their locations. Note that these are few items, but their choice is important for the performance of the code on a given computer. There are many different setups and automated tools do not always get these choices right. In the file above, we here identify those specific pieces where we feel that a user decision is necessary. Please ask for assistance (FHI-aims forums or Slack channel) if needed.

  3. 3.

    Issue

    cmake -C initial_cache.cmake ..

    from the build directory to configure. In this example, the “..” directory is used. In general, the directory given in this command should point to the directory where the ”CMakeLists.txt” file provided with FHI-aims is located.

    And yes – it has to be “-C” (capital C). “-c” (lowercase) will NOT work but will produce an error message that is not, unfortunately, helpful. So, if cmake refuses to get to work at all, double-check the exact spelling of the above line first (and make sure that the “initial_cache.cmake” file is in place and that “..” indeed points to the correct directory).

    If you encounter any other errors during this step, we recommend correcting your
    initial_cache.cmake file, saving it, then deleting the build directory and restarting from the first step.

  4. 4.

    Issue

    make -j [number]

    to build. An executable whose name starts with aims is created in the same directory.

    The value of [number] should be the same or less than the number of physical CPU cores available on your computer. Choosing sufficiently many cores speeds up the build process but on shared computers with multiple users (e.g., the login node of a cluster) it is typically nice to use only as many as you need, not necessarily the full node.

  5. 5.

    Move the newly generated FHI-aims binary to a directory where your binary files are typically collected. For example, if your FHI-aims top level directory contains a subdirectory bin/, use:

    mv aims.<version> ../bin

    In that command, replace the placeholder <version> with the actual completion of the name of the FHI-aims binary that you had just created.

For more details on how to use CMake, see Sec. H or our online tutorial at https://fhi-aims-club.gitlab.io/tutorials/cmake-tutorial.