View source for 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 [https://en.wikipedia.org/wiki/Make_%28software%29 Make]. However, it can also generate files for other systems, including [https://www.visualstudio.com/ Visual Studio] and [https://developer.apple.com/xcode/ 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 (<tt>cmake</tt>), run a terminal-based GUI version (<tt>ccmake</tt>), or run a Qt-based GUI version (<tt>cmake-gui</tt>). In any case, there are some pieces of information you can pass to CMake.

===Build and source directories===

This is mandatory information. For both <tt>cmake</tt> and <tt>ccmake</tt>, 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

<tt>cmake-gui</tt> 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 <tt>cmake</tt> and <tt>ccmake</tt> using the -G argument (use <tt>cmake --help</tt> to get a list of possible ''generators'', and see the [http://www.cmake.org/cmake/help/v3.3/manual/cmake-generators.7.html CMake generators documentation] for more information about them).

For example, you could run

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

to generate files that can be used with the <tt>make</tt> command, or

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

to generate [http://kate-editor.org/ Kate] project files in combination with files for [https://martine.github.io/ninja/ Ninja].

<tt>cmake-gui</tt> 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 [http://www.cmake.org/cmake/help/v3.3/manual/cmake-generators.7.html#visual-studio-generators Visual Studio generators] in CMake 3.0 or later, you probably want to set the platform name 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 [http://www.cmake.org/cmake/help/v3.3/manual/cmake-language.7.html#variables 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 <tt>CMAKE_INSTALL_PREFIX</tt>. You might want to set this to <tt>/usr</tt> on a Linux system, or to <tt>C:\Program Files\Project Name</tt> on a Windows system. <tt>cmake</tt> 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 <tt>ccmake</tt> and <tt>cmake-gui</tt>, you will need to first configure the project. Then you will be presented with a list of available variables you can change. Some of these ("advanced" variables) will be hidden initially - these should be variables you don't normally need to change because CMake should detect the correct values automatically (such as the location of a particular library). If you do need to change them, there is an option to show the advanced variables.

You may notice that the above command included <tt>:PATH</tt> just after the name of the variable we wanted to set. This is optional extra information about the variable type that helps <tt>cmake-gui</tt> 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 <tt>cmake-gui</tt>.

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 [http://api.kde.org/ecm/kde-module/KDEInstallDirs.html 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.