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

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

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.