H.1 The build process

CMake itself is usually obtained from an official repository of a Linux distribution or built from source. When building from source, the only prerequisite is a C++ compiler.

The build process with CMake consists of two steps: the configuration stage, which generates the platform’s native build files, and the compilation stage. (This is vaguely similar to the standard configure and make steps associated with Autotools.)

The configuration stage creates a set of persistent variables, which are contained in a file called CMakeCache.txt in the build directory. These are referred to as cache variables and they are the user-configurable settings for the project. All the important decisions such as which compiler to use, which libraries to link against, etc., are stored as cache variables. There are three main ways to perform the configuration stage (or set the contents of the CMake cache):

•
Running cmake and specifying all the configuration variables on the command line. For example, running
```
cmake -D CMAKE_Fortran_COMPILER=mpif90 ~aims
```
from within the build directory, where $\sim$ aims is the root source directory, sets mpif90 as the Fortran compiler. This approach is good for debugging and quick testing purposes but if a large number of variables is to be specified, it might not be very convenient. Also, no logic can be included this way.
•
A better way is to keep the configuration variables in a separate file, an example of which is initial_cache.example.cmake in the root source directory of FHI-aims. It contains example initial values for some configuration variables, which you can edit to reflect your environment. Make a copy of it first, for example initial_cache.cmake. When done editing, run
```
cmake -C ~aims/initial_cache.cmake ~aims
```
from the build directory. The -C option tells CMake to load a script, in this case initial_cache.cmake, which populates the initial cache. The loaded entries take priority over the project’s default values. A change of the content of the initial cache file has no effect after the first configuring. Instead, it would be necessary to empty the build directory before using the cache file again. Alternatively, one could use a cache editor like ccmake to modify the configuration variables without emptying the whole build directory, as explained next.
•
Run cmake first and then configure using a CMake GUI. In the case of FHI-aims, a bare cmake run is disallowed, since specifying at the least the Fortran compiler is required. In general, this is not a requirement for CMake projects. Two commonly used graphical front ends (or cache editors) are the curses based ccmake and the Qt-based cmake-gui. When using ccmake, issue
```
cmake -D CMAKE_Fortran_COMPILER=mpif90 ~aims
ccmake .
```
from the build directory. Some CMake variables and options appear with a short help text to each variable displayed at the bottom in a status bar. Pressing ’t’ reveals all options. When done editing, press ’c’ to reconfigure and ’g’ to generate the native build scripts (e.g., makefiles). Pay attention when ccmake warns you that the cache variables have been reset. This will happen, for example, when changing the compiler, and will necessitate the reconfiguring of some variables. After configuring, it is a good idea to go through all the variables once more to check that everything is correct. Using cmake-gui is similar to ccmake:
```
cmake -D CMAKE_Fortran_COMPILER=mpif90 ~aims
cmake-gui .
```
Besides a graphical window that opens, the usage of cmake-gui is analogous to ccmake.

When done configuring, FHI-aims can be compiled by issuing a compile command depending on the CMake generator used. A CMake generator is the function that writes the build files. The default behavior is to generate makefiles for Make, in which case the compile command is make. When using another generator such as Ninja (which coincides with the name of the actual build system, Ninja), the compile command is ninja. See cmake --help for which generators are available. It is actually unnecessary to think about generators at all when you run

cmake --build .

which is a generic command that always uses the correct compile command. When done compiling, an executable called aims<...> is produced in the root build directory. The default base name of the final target is aims and the <...> part depends on details such as the FHI-aims version number. An executable is not the only supported target. For instance, when building a shared library in a Linux environment, a library called libaims<...>.so is produced instead.

Note that in general, CMake can also run from the source directory, but this is not allowed in FHI-aims due to certain conflicts. It is a good practice anyway to compile in a separate build directory in order to support multiple build configurations simultaneously and to keep the source directory clean.