Basic CMake

Basic CMake usage

This section explains basic aspects of CMake which you may need in your day-to-day usage.

CMake comes with extensive documentation, in the form of html files, and as online help accessible via the cmake executable itself. Execute cmake –help for further help options.

CMake allows you to specify a build tool (e.g., GNU make, Visual Studio, or Xcode). If not specified on the command line, CMake tries to guess which build tool to use, based on your environment. Once it has identified your build tool, CMake uses the corresponding Generator to create files for your build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can explicitly specify the generator with the command line option -G “Name of the generator”. To see a list of the available generators on your system, execute

$ cmake --help

This will list the generator names at the end of the help text.

The generator names are case-sensitive, and may contain spaces. For this reason, you should enter them exactly as they are listed in the cmake –help output, in quotes. For example, to generate project files specifically for Visual Studio 12, you can execute:

$ cmake -G "Visual Studio 12" path/to/source

For a given development platform there can be more than one adequate generator. If you use Visual Studio, “NMake Makefiles” is a generator you can use for building with NMake. By default, CMake chooses the most specific generator supported by your development environment. If you want an alternative generator, you must tell this to CMake with the -G option.

Options and variables

Variables customize how the build will be generated. Options are boolean variables, with possible values ON/OFF. Options and variables are defined on the CMake command line like this:

$ cmake -DVARIABLE=value path/to/source You can set a variable after the initial `CMake` invocation to change its value. You can also undefine a variable:

$ cmake -UVARIABLE path/to/source Variables are stored in the `CMake` cache. This is a file named `CMakeCache.txt` stored at the root of your build directory that is generated by `cmake`. Editing it yourself is not recommended.

Variables are listed in the CMake cache with the variable name and type separated by a colon. You can also specify the variable and type on the CMake command line:

$ cmake -DVARIABLE:TYPE=value path/to/source

Variables in the CMake cache are ‘remembered’, so you do not need to type them if you execute cmake command again. It is recommended to delete the file CMakeCache.txt to start from a clean configuration.

CMake generators

CMake can generate, in addition to standard makefiles, specific projects for various integrated development environments (IDEs) such as Xcode, Eclipse, Visual Studio, etc.. The available generators depend on the platform for which cmake have been build. To see the list of available generators do cmake --help .

Ninja

Generate a Ninja project with cmake -G Ninja /path/to/source/dir. Building ROOT with Ninja is faster.

Xcode

Generate the Xcode project with cmake -G Xcode /path/to/source/dir. Open the generated file with the Xcode application.

Visual Studio

Generate the Microsoft Visual Studio solution with cmake -G "Visual Studio 10" /path/to/source/dir. Open the generated solution with C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\devenv.exe ROOT.sln`