Building Software With CMake

CMake is an open-source, cross-platform family of tools for building, testing, and packaging software.

Using CMake on CARC systems

Begin by logging in. You can find instructions for this in the Getting Started with Discovery or Getting Started with Endeavour user guides.

To use CMake, first load a corresponding module:

module purge
module load gcc/11.3.0 cmake/3.23.2

Other versions of CMake are available and may require different dependency modules. To see all available versions of CMake, enter:

module spider cmake

If you require a different version of CMake that is not currently installed on CARC systems, please submit a help ticket and we will install it for you.

Build process

The build process has three stages:

Configure stage
Make stage
Install stage

A CMake build sequence on CARC systems looks something like the following:

module purge
module load gcc/11.3.0 cmake/3.23.2

mkdir build
cd build

CC=gcc CXX=g++ FC=gfortran \
CFLAGS=-march=x86-64-v3 CXXFLAGS=-march=x86-64-v3 FFLAGS=-march=x86-64-v3 \
cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..

make

make install

Configure stage

CMake build behavior for a software project is described in plain-text files, traditionally named CMakeLists.txt. When invoked during the configure stage, CMake parses these text files and generates a native build chain for the desired platform and compiler. It provides options to customize the build process and specify paths to dependent software. On CARC systems, you may need to specify include file and library paths for dependent software used during the build or for linking libraries to executables.

It is best practice to create and use a build directory in order to keep the original source code clean (i.e., out-of-source builds). If something goes wrong, the build directory can be deleted and recreated without impacting the original source code. The build directory is typically created in the root directory of the software project. The compiler's output will be stored in the build directory, which includes both object files as well as final executables and libraries. It also stores several other files, including its cache.

mkdir build
cd build

Run the cmake command with appropriate options from within the build directory. On CARC systems, you will usually need to specify the compilers to use for the build and the final installation path. You can also specify compiler flags.

Note: If a compiler is not specified, CMake will default to using /usr/bin/{gcc,g++,gfortran} which will not be compatible with the rest of the loaded software stack.

You can use the following template command for your CMake builds:

CC=gcc CXX=g++ FC=gfortran \
CFLAGS=-march=x86-64-v3 CXXFLAGS=-march=x86-64-v3 FFLAGS=-march=x86-64-v3 \
cmake -DCMAKE_INSTALL_PREFIX=/home1/$USER/software ..

The \ character (as seen above) will continue a command on the next line. This means that everything before the \ character is actually a single command. Creating line breaks in this way improves readability.

To change the location of the install directory from the default /usr/local to your home directory, use an option like -DCMAKE_INSTALL_PREFIX=/home1/$USER/software

Running the cmake command produces a configure file CMakeCache.txt. To change the content of the CMake cache variables in this file, use the -D option after the cmake command. To see the full CMake variable list, enter cmake --help-variable-list.

The build output and error files are located within the build directory at ./CMakeFiles/CMakeOutput.log and ./CMakeFiles/CMakeError.log.

Make stage

After the configure stage completes successfully, a Makefile is created in the build directory. To build the software, enter:

make

This will likely be the most time consuming part of the build process. If something goes wrong here, soemthing may have gone wrong during the configure stage that was not reported properly. If needed, check the CMake output and error files for more details.

Install stage

This stage is optional and assumes there is an install target added to the Makefile. The CMakeLists.txt file may need to be modified for this. For example, there should be a line like the following:

install(TARGETS app DESTINATION)

where app is a build object, like an executable or library. Multiple objects can be specified.

After the make stage completes successfully, to install the executable binaries and libraries in the location prefixed during the configure stage, enter:

make install

This stage simply copies the specified build objects to the specified install prefix.

Additional resources

CMake website
CMake documentation