CMake Useful Variables

CMake uses and defines many variables, which can be used in CMakeLists.txt files.

Locations

CMAKE_BINARY_DIR

if you are building in-source, this is the same as CMAKE_SOURCE_DIR, otherwise this is the top level directory of your build tree

CMAKE_CURRENT_BINARY_DIR

if you are building in-source, this is the same as CMAKE_CURRENT_SOURCE_DIR, otherwise this is the directory where the compiled or generated files from the current CMakeLists.txt will go to

CMAKE_SOURCE_DIR

this is the directory, from which cmake was started, i.e. the top level source directory

CMAKE_CURRENT_SOURCE_DIR

this is the directory where the currently processed CMakeLists.txt is located in

PROJECT_NAME

the name of the project set by PROJECT() command.

PROJECT_BINARY_DIR

contains the full path to the top level directory of your build tree

PROJECT_SOURCE_DIR

contains the full path to the root of your project source directory, i.e. to the nearest directory where CMakeLists.txt contains the PROJECT() command

EXECUTABLE_OUTPUT_PATH

set this variable to specify a common place where CMake should put all executable files (instead of CMAKE_CURRENT_BINARY_DIR)
SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)

LIBRARY_OUTPUT_PATH

set this variable to specify a common place where CMake should put all libraries (instead of CMAKE_CURRENT_BINARY_DIR)
SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)

CMAKE_MODULE_PATH

tell CMake to search first in directories listed in CMAKE_MODULE_PATH when you use FIND_PACKAGE() or INCLUDE()
SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts)

FIND_PACKAGE(HelloWorld)

CMAKE_COMMAND

this is the complete path of the cmake which runs currently (e.g. /usr/local/bin/cmake)

CMAKE_ROOT

this is the CMake installation directory

CMAKE_CURRENT_LIST_FILE

this is the filename including the complete path of the file where this variable is used.

CMAKE_CURRENT_LIST_LINE

this is linenumber where the variable is used.

Environment Variables

These are environment variables which effect cmake behaviour.

CMAKE_INCLUDE_PATH

This is used when searching for include files e.g. using the FIND_PATH() command. If you have headers in non-standard locations, it may be useful to set this variable to this directory (e.g. /sw/include on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)

CMAKE_LIBRARY_PATH

This is used when searching for libraries e.g. using the FIND_LIBRARY() command. If you have libraries in non-standard locations, it may be useful to set this variable to this directory (e.g. /sw/lib on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)

CMAKE_INSTALL_ALWAYS

If set during installation CMake will install all files whether they have changed or not. The default when this is not set is to install only files that have changed since the previous installation. In both cases all files are reported to indicate CMake knows they are up to date in the installed location.

$ENV{name}

This is not an environment variable , but this is how you can access environment variables from cmake files. It returns the content of the environment variable with the given name (e.g. $ENV{PROGRAMFILES})

System Information

CMAKE_MAJOR_VERSION

major version number for CMake, e.g. the "2" in CMake 2.4.3

CMAKE_MINOR_VERSION

minor version number for CMake, e.g. the "4" in CMake 2.4.3

CMAKE_PATCH_VERSION

patch version number for CMake, e.g. the "3" in CMake 2.4.3

CMAKE_SYSTEM

the complete system name, e.g. "Linux-2.4.22", "FreeBSD-5.4-RELEASE" or "Windows 5.1"

CMAKE_SYSTEM_NAME

the short system name, e.g. "Linux", "FreeBSD" or "Windows"

CMAKE_SYSTEM_VERSION

only the version part of CMAKE_SYSTEM

CMAKE_SYSTEM_PROCESSOR

the processor name (e.g. "Intel(R) Pentium(R) M processor 2.00GHz")

UNIX

is TRUE on all UNIX-like OS's, including Apple OS X and CygWin

WIN32

is TRUE on Windows, including CygWin

APPLE

is TRUE on Apple OS X

MINGW

is TRUE when using the MinGW compiler in Windows

CYGWIN

is TRUE on Windows when using the CygWin version of cmake

BORLAND

is TRUE on Windows when using a Borland compiler

MSVC, MSVC_IDE, MSVC60, MSVC70, MSVC71, MSVC80, CMAKE_COMPILER_2005

Microsoft compiler

Various Options

CMAKE_SKIP_RULE_DEPENDENCY

set this to true if you don't want to rebuild the object files if the rules have changed, but not the actual source files or headers (e.g. if you changed the some compiler switches)

CMAKE_SKIP_INSTALL_ALL_DEPENDENCY

since CMake 2.1 the install rule depends on all, i.e. everything will be built before installing. If you don't like this, set this one to true.

CMAKE_SKIP_RPATH

If set, runtime paths are not added when using shared libraries. Default it is set to OFF.

CMAKE_VERBOSE_MAKEFILE

set this to true if you are using makefiles and want to see the full compile and link commands instead of only the shortened ones

CMAKE_SUPPRESS_REGENERATION

this will cause CMake to not put in the rules that re-run CMake. This might be useful if you want to use the generated build files on another machine.

Compilers and Tools

A simple way to get switches to the compiler is to use ADD_DEFINITIONS(). But there are also two variables exactly for this purpose:

CMAKE_C_FLAGS

the compiler flags for compiling C sources

CMAKE_CXX_FLAGS

the compiler flags for compiling C++ sources

CMAKE_BUILD_TYPE

Choose the type of build. CMake has default flags for these:

• None (CMAKE_C_FLAGS or CMAKE_CXX_FLAGS used)
• Debug (CMAKE_C_FLAGS_DEBUG or CMAKE_CXX_FLAGS_DEBUG)
• Release (CMAKE_C_FLAGS_RELEASE or CMAKE_CXX_FLAGS_RELEASE)
• RelWithDebInfo (CMAKE_C_FLAGS_RELWITHDEBINFO or CMAKE_CXX_FLAGS_RELWITHDEBINFO
• MinSizeRel (CMAKE_C_FLAGS_MINSIZEREL or CMAKE_CXX_FLAGS_MINSIZEREL)

Example: SET(CMAKE_BUILD_TYPE Debug)

You can create your own build type like this:
SET(CMAKE_BUILD_TYPE distribution)
SET(CMAKE_CXX_FLAGS_DISTRIBUTION "-O3")
SET(CMAKE_C_FLAGS_DISTRIBUTION "-O3")

BUILD_SHARED_LIBS

if this is set to ON, then all libraries are built as shared libraries by default.
SET(BUILD_SHARED_LIBS ON)

The following variables are detected during the cmake run and set accordingly (e.g. to gcc). If you want to force the use of other tools, you can set these variables manually to the desired tools. E.g. if you want to use the gcc cross compiling toolchain for arm processors, you could do the following: SET(CMAKE_C_COMPILER arm-elf-gcc)

CMAKE_C_COMPILER

the compiler used for C files

CMAKE_CXX_COMPILER

the compiler used for C++ files

CMAKE_COMPILER_IS_GNUCC

if the compiler is a variant of gcc, this should be set to 1

CMAKE_COMPILER_IS_GNUCXX

if the compiler is a variant of g++, this should be set to 1

CMAKE_AR, CMAKE_RANLIB

the tools for creating libraries

Build rules

Build rules are defined in CMakeCInformation.cmake and CMakeCXXInformation.cmake.

Rules for C++ sources:

CMAKE_CXX_CREATE_SHARED_LIBRARY

CMAKE_CXX_CREATE_SHARED_MODULE

CMAKE_CXX_CREATE_STATIC_LIBRARY

CMAKE_CXX_COMPILE_OBJECT

CMAKE_CXX_LINK_EXECUTABLE

and the equivalents for C sources:

CMAKE_C_CREATE_SHARED_LIBRARY

CMAKE_C_CREATE_SHARED_MODULE

CMAKE_C_CREATE_STATIC_LIBRARY

CMAKE_C_COMPILE_OBJECT

CMAKE_C_LINK_EXECUTABLE

You can override the variables manually, e.g. replacing some flags in the linker command, but you can't change the value of the variables in sharp braces. Usually you don't have to change these rules, only in rare cases. You should only do this if you know what you are doing and there is no other way.

Variables not listed here

CMake has many more variables than are listed above. Documenting all of them is an ongoing project. We need everyone's help with this. If you know of a CMake variable that is not listed here, please edit the wiki and add it. Don't worry about whether you have a precise description for it. This is a wiki, and other people can provide a better description as time goes on.

How does one find out about additional variables? The CMake mailing list is probably the best resource. Some things can be learned from inspecting the CMake source code. Many - but not all of them - are also listed by this Dashboard script for extracting variables. The output of this script is rather raw, but it is a good starting point for finding more variables.

When a CMake dashboard is run, a "SystemInformation test" is usually run as well. Among other things, it lists the names and values of all of the CMake variables that are in use when the test is run. The script looks at the SystemInformation test output, and uses regular expressions to find the start and end of the "AllVariables.txt" section. It prints the results out in the form of XML.

Logging code

This code may be placed in a CMakelists.txt file to create status messages that log a number of the variables documented above. It is not a complete list, however. The variables are not auto-generated from the wiki, it is just sample code. Add whatever variables you are interested in.

1. Sample code for logging useful variables.

---

CMake: [Welcome | Site Map]