Guidelines and HOWTOs/CMake/Building

CMake works by generating a build system for another tool to use. By default, it will generate makefiles for use with GNU Make. However, it can also generate files for other systems, including Visual Studio and XCode. As such, building a project is a two-step process: configuring, then building.

Configuring

First, you need to configure the project. This involves running CMake, which will determine the necessary information about your system and, if it finds everything it needs, generate the build system.

We recommend you build into a separate directory. This has two main advantages: when building, you can revert to the state you started with simply by deleting this directory, and when developing your changes are not mixed up with the files generated by the build system.

CMake has three different interfaces. You can run the command-line tool directly (cmake), run a terminal-based GUI version (ccmake), or run a Qt-based GUI version (cmake-gui). In any case, there are some pieces of information you can pass to CMake.

Build and source directories

This is mandatory information. For both cmake and ccmake, you run it from the build directory and pass the source directory as an argument. For example,

 cd /path/to/build/directory
 cmake /path/to/source/directory

cmake-gui can be run from anywhere; both the source and build directories need to be provided in the widgets at the top of the interface.

Build system (generators)

As noted above, CMake just generates configuration files the tell another tool how to build the project. You can specify this to cmake and ccmake using the -G argument (use cmake --help to get a list of possible generators, and see the CMake generators documentation for more information about the individual generators).

For example, you could run

 cmake -G "Unix Makefiles" /path/to/source/directory

to generate files that can be used with the make command, or

 cmake -G "Kate - Ninja" /path/to/source/directory

to generate Kate project files in combination with files for Ninja.

cmake-gui will ask you to choose a generator when you first press the Configure button.

Depending on the generator (and the version of CMake you are using), you can also specify a toolset to use or a platform name, to further control how the build is performed. We won't cover this in detail, except to note that with the Visual Studio generators, you probably want to set the platform name with CMake 3.0 or later in order to choose between 32-bit and 64-bit builds. For example:

 cmake -G "Visual Studio 10 2010" -A x64 c:\path\to\source\directory

Cache Variables

CMake stores settings mostly in the form of variables. These range from the location of a library the project depends on to whether unit tests should be built. When you run CMake, you can provide default values for some of these by setting cache variables. There is more detailed information in the CMake documentation, but this is mostly only important if you are writing a CMake-based project.

The variable you are mostly likely to want to change is the installation location, which is named CMAKE_INSTALL_PREFIX. You might want to set this to /usr on a Linux system, or to C:\Program Files\Project Name/tt> on a Windows system. cmake can be passed a value for this using the -D argument:

 cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr /path/to/source/directory

In the case of ccmake and cmake-gui, you will need to first configure the project. Then you will be presented with a list of available variables you can change. You may notice that the above command included ":PATH" just after the name of the variable we wanted to set. This is optional extra information about the variable type that helps cmake-gui decide how to let the user edit the variable (in this case, it will show a dialog that allows the user to choose a directory). Other options are BOOL (which can be set to ON or OFF), FILEPATH (like PATH but for files instead of directories) and STRING (any other value). Omitting this information is safe, though:

 cmake -DCMAKE_INSTALL_PREFIX=/usr /path/to/source/directory

will work just as well if you do not intend to use cmake-gui.

For other variables you can set, you will need to consult the documentation of the project you are building. A common setting is whether to build tests:

 cmake -DBUILD_TESTING:BOOL=OFF /path/to/source/directory

If you are building a KDE Frameworks-based project, you will almost certainly be able to control the installation location of particular files using the variables from the KDEInstallDirs module; for example:

 cmake -DCMAKE_INSTALL_PREFIX=/usr -DKDE_INSTALL_SYSCONFDIR=/etc -DKDE_INSTALL_QTPLUGINDIR=lib/qt5/plugins /path/to/source/directory

Building

Building is done using whatever build system you asked CMake to generate configuration files for. For example, with the "Unix Makefiles" generator, you would run

 make
 make install

from the build directory. With one of the Visual Studio generators, you would either run msbuild from the build directory or open the generated solution file in Visual Studio and build as normal.