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 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 .
Generate a Ninja project with
cmake -G Ninja /path/to/source/dir. Building ROOT with Ninja is faster.
Generate the Xcode project with
cmake -G Xcode /path/to/source/dir. Open the generated file with the Xcode application.
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`