View source for CMake Useful Variables

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

'''NOTE:''' As of CMake 2.6.0 many of these variables have been officially documented in TXT and [http://www.cmake.org/cmake/help/documentation.html HTML] files released with CMake.  You may still see some ''useful'' variables here that haven't yet been documented in the official documentation, although the number of these diminishes with every release.  This page, in either case, is more of a distilled list of some of the more important variables.  The [http://www.cmake.org/cmake/help/documentation.html official documentation] is home of the authoritative guide to all CMake variables, commands, and properties.

== 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_COMMAND : this is the complete path of the cmake which runs currently (e.g. <tt>/usr/local/bin/cmake</tt>)
; 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_CURRENT_LIST_FILE : this is the full path to the listfile currently being processed.
; CMAKE_CURRENT_LIST_DIR : (since '''2.8.3''') this is the directory of the listfile currently being processed.
; CMAKE_CURRENT_LIST_LINE : this is linenumber where the variable is used.
CMakeLists.txt contains the PROJECT() command
; CMAKE_CURRENT_SOURCE_DIR : this is the directory where the currently processed  CMakeLists.txt is located in
; CMAKE_FILES_DIRECTORY : the directory within the current binary directory that contains all the CMake generated files.  Typically evaluates to "/CMakeFiles".  Note the leading slash for the directory.  Typically used with the current binary directory, i.e. ${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}
; CMAKE_MODULE_PATH : tell CMake to search first in directories listed in CMAKE_MODULE_PATH when you use FIND_PACKAGE() or INCLUDE()<br> <tt> SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts)</tt><br> <tt>FIND_PACKAGE(HelloWorld)</tt>
; CMAKE_ROOT : this is the CMake installation directory
; CMAKE_SOURCE_DIR : this is the directory, from which cmake was started, i.e. the top level source directory
; EXECUTABLE_OUTPUT_PATH : set this variable to specify a common place where CMake should put all executable files  (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)</tt>
; LIBRARY_OUTPUT_PATH : set this variable to specify a common place where CMake should put all libraries (instead of CMAKE_CURRENT_BINARY_DIR)<br> <tt>SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)</tt>
; PROJECT_NAME : the name of the project set by PROJECT() command.
; CMAKE_PROJECT_NAME : the name of the first project set by the PROJECT() command, i.e. the top level project.
; 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

== 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. <tt>/sw/include</tt> 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. <tt>/sw/lib</tt> on Mac OS X). If you need several directories, separate them by the platform specific separators (e.g. ":" on UNIX)

; CMAKE_PREFIX_PATH : (since CMake '''2.6.0''') This is used when searching for include files, binaries, or libraries using either the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() commands.  For each path in the CMAKE_PREFIX_PATH list, CMake will check "PATH/include" and "PATH" when FIND_PATH() is called, "PATH/bin" and "PATH" when FIND_PROGRAM() is called, and "PATH/lib" and "PATH" when FIND_LIBRARY() is called.  See the documentation for FIND_PACKAGE(), FIND_LIBRARY(), FIND_PATH(), and FIND_PROGRAM() for more details.

; 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. <tt>$ENV{PROGRAMFILES}</tt>)

; DESTDIR : If this environment variable is set it will be prefixed to CMAKE_INSTALL_PREFIX in places where it is used to access files during installation.  This allows the files to be installed in an intermediate directory tree without changing the final installation path name.  Since the value of CMAKE_INSTALL_PREFIX may be included in installed files it is important to use DESTDIR rather than changing CMAKE_INSTALL_PREFIX when it is necessary to install to a intermediate staging directory.

== System & Compiler 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_TWEAK_VERSION : tweak version number for CMake, e.g. the "1" in CMake X.X.X.1.  Releases use tweak < 20000000 and development versions use the date format CCYYMMDD for the tweak level.
; CMAKE_VERSION : The version number combined, eg.  2.8.4.20110222-ged5ba for a Nightly build. or  2.8.4 for a Release build.
; 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")
; CMAKE_GENERATOR : the generator specified on the commandline.
; 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 systems.  Note this does ''not'' imply the system is Mac OS X, only that __APPLE__ is #defined in C/C++ header files.  Obtain more specific system information via CMAKE_SYSTEM_VERSION, i.e. IF(${CMAKE_SYSTEM_NAME} MATCHES "Darwin"), then it's Mac OS X.
; MINGW : is TRUE when using the MinGW compiler in Windows
; MSYS : is TRUE when using the MSYS developer environment in Windows
; CYGWIN : is TRUE on Windows when using the ''CygWin'' version of cmake
; BORLAND : is TRUE on Windows when using a Borland compiler
; WATCOM : is TRUE on Windows when using the Open Watcom compiler
; MSVC, MSVC_IDE, MSVC60, MSVC70, MSVC71, MSVC80, CMAKE_COMPILER_2005, MSVC90, MSVC10 (Visual Studio 2010) : Microsoft compiler
; CMAKE_COMPILER_IS_GNUCC : is TRUE if the compiler is a variant of gcc
; CMAKE_COMPILER_IS_GNUCXX : is TRUE if the compiler is a variant of g++

== 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_INCLUDE_CURRENT_DIR : automatically add CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include directories in every processed CMakeLists.txt. It behaves as if you had used INCLUDE_DIRECTORIES in every CMakeLists.txt file or your project. The added directory paths are relative to the being-processed CMakeLists.txt, which is different in each directory. (See [http://www.cmake.org/pipermail/cmake/2007-March/013193.html this thread] for more details).
; CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE : order the include directories so that directories which are in the source or build tree always come before directories outside the project.
; 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.
; CMAKE_COLOR_MAKEFILE : create Makefiles with colored output (defaults to on)
; CMAKE_SKIP_PREPROCESSED_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating preprocessed files (foo.i)
; CMAKE_SKIP_ASSEMBLY_SOURCE_RULES : (since 2.4.4) if set to TRUE, the generated Makefiles will not contain rules for creating compiled, but not yet assembled files (foo.s)
; CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS : (redundant since '''2.6.0''') set this to true if you don't want to have to bother having your IF() ELSE() and ENDIF() conditions match.  In other words so you can do this:

 IF(FOO)
    SET(BAR bar.cc)
 ELSE()
    SET(BAR bar2.cc)
 ENDIF()

== Compilers and Tools ==

; BUILD_SHARED_LIBS : if this is set to ON, then all libraries are built as shared libraries by default.<br> <tt>SET(BUILD_SHARED_LIBS ON)</tt>

; CMAKE_AR : tool for creating libraries.  See also CMAKE_RANLIB, as "ar" and "ranlib" are typically used together.
; CMAKE_BUILD_TYPE : A variable which controls the type of build when using a ''single-configuration generator'' like the Makefile generator. CMake will create by default the following variables when using a single-configuration generator:

*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)

You can use these default compilation flags (or modify them) by setting the CMAKE_BUILD_TYPE variable at configuration time from within the "ccmake" GUI. '''Note!'''  The default values for these flags change with different compilers. If CMake does not know your compiler, the contents will be empty.

If you are using the Makefile generator, you can create your own build type like this:<br>
<tt>SET(CMAKE_BUILD_TYPE distribution)<br>
SET(CMAKE_CXX_FLAGS_DISTRIBUTION "-O3")<br>
SET(CMAKE_C_FLAGS_DISTRIBUTION "-O3")</tt>

Note that CMAKE_BUILD_TYPE is not initialized with a readable value at configuration time.  This is because the user is free to select a build type at build time.  Use CMAKE_CFG_INTDIR if you need a variable that evaluates to the correct build time directory.

; CMAKE_CONFIGURATION_TYPES : When using a ''multi-configuration generator'', such as the one for '''Visual Studio''', this variable contains a list of the available configurations.
; CMAKE_C_COMPILER : the compiler used for C files.  Normally it is detected and set during the CMake run, but you can override it at configuration time.  '''Note!'''  It can not be changed after the first cmake or ccmake run. Although the gui allows to enter an alternative, it will be ignored in the next 'configure' run. Use for example: <br><tt>CC=gcc-3.3 CXX=g++-3.3 cmake</tt><br> to set the compiler. (You can also set CMAKE_C_COMPILER_INIT, before any PROJECT() or ENABLE_LANGUAGE() command.)  Any other way (like writing <tt>make CC=gcc-3.3 CXX=g++-3.3</tt>) will not work. When using distcc or similar tools, you need to write: <br><tt>CC="distcc gcc-3.3" CXX="distcc g++-3.3" cmake</tt><br> However, this will empty all your CMAKE_..._FLAGS_... above.<br>

; CMAKE_C_FLAGS : the compiler flags for compiling C sources.  Note you can also specify switches with ADD_DEFINITIONS().
; CMAKE_C_FLAGS_DEBUG : compiler flags for compiling a debug build from C sources.
; CMAKE_C_FLAGS_RELEASE : compiler flags for compiling a release build from C sources.
; CMAKE_C_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C sources.
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in.  Typically .o or .obj.
; CMAKE_CFG_INTDIR : meta-variable! Please note that this is an '''important''' variable, since on multi-configuration generators it will be generated into '''dynamically switched''' content based on the configuration that the user currently selected within the generated build environment. Indicates the name of the current configuration (~ directory) for the project. May be used for any purpose which needs per-configuration-dynamic switching of strings, not just OutputDir configuration. For multi-configuration generators (e.g. MSVC) the resulting strings are typically some of "Debug", "Release", "RelWithDebInfo", or "MinSizeRel".  For other compiler generators (single-configuration ones) it is typically ".", as they don't use MSVC-style configuration directories.
; CMAKE_CXX_COMPILER : the compiler used for C++ files.  Normally it is detected and set during the CMake run, but you can override it at configuration time.  '''Note!'''  It can not be changed after the first cmake or ccmake run.  See CMAKE_C_COMPILER above.

; CMAKE_CXX_FLAGS : the compiler flags for compiling C++ sources.  Note you can also specify switches with ADD_DEFINITIONS().
; CMAKE_CXX_FLAGS_DEBUG : compiler flags for compiling a debug build from C++ sources.
; CMAKE_CXX_FLAGS_RELEASE : compiler flags for compiling a release build from C++ sources.
; CMAKE_CXX_FLAGS_RELWITHDEBINFO : compiler flags for compiling a release build with debug flags from C++ sources.
; CMAKE_RANLIB : tool for creating libraries.  See also CMAKE_AR, as "ar" and "ranlib" are typically used together.

; CMAKE_SHARED_LINKER_FLAGS : additional compiler flags for building shared libraries, e.g.: <br>
<tt>set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--no-undefined")</tt><br>
On Unix systems, this will make linker report any unresolved symbols from object files (which is quite typical when you compile many targets in CMake projects, but do not bother with linking target dependencies in proper order).

== Prefixes, Suffixes (Postfixes), and Extensions ==
; CMAKE_C_IGNORE_EXTENSIONS :
; CMAKE_C_OUTPUT_EXTENSION : what C object files end in.  Typically .o or .obj.
; CMAKE_C_SOURCE_FILE_EXTENSIONS :
; CMAKE_CXX_IGNORE_EXTENSIONS :
; CMAKE_CXX_OUTPUT_EXTENSION : what C++ object files end in.  Typically .o or .obj.
; CMAKE_CXX_SOURCE_FILE_EXTENSIONS :
; CMAKE_EXECUTABLE_SUFFIX :
; CMAKE_FIND_LIBRARY_PREFIXES :
; CMAKE_FIND_LIBRARY_SUFFIXES :
; CMAKE_IMPORT_LIBRARY_PREFIX : Windows-specific.  Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_IMPORT_LIBRARY_SUFFIX : Windows-specific.  Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_LINK_LIBRARY_SUFFIX : Windows-specific.
; CMAKE_RC_OUTPUT_EXTENSION : Windows-specific.
; CMAKE_RC_SOURCE_FILE_EXTENSIONS : Windows-specific.
; CMAKE_SHARED_LIBRARY_PREFIX : Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_SHARED_LIBRARY_SUFFIX : Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_SHARED_MODULE_PREFIX :
; CMAKE_SHARED_MODULE_SUFFIX :
; CMAKE_STATIC_LIBRARY_PREFIX : Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_STATIC_LIBRARY_SUFFIX : Appears to be read-only.  Use SET_TARGET_PROPERTIES.
; CMAKE_DEBUG_POSTFIX : Add a custom "postfix" to static and shared libraries when in Debug build. Example: mylib_d.lib.
; CMAKE_RELEASE_POSTFIX :
; CMAKE_<config>_POSTFIX :

== 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.

== Expansion Rules ==
From examining the source code the following style names exist:

; ASSEMBLY_SOURCE
; FLAGS
; LANGUAGE_COMPILE_FLAGS
; LINK_FLAGS
; LINK_LIBRARIES
; OBJECT
; OBJECTS
; OBJECTS_QUOTED
; OBJECT_DIR
; PREPROCESSED_SOURCE
; SOURCE
; TARGET
; TARGET_BASE
; TARGET_IMPLIB
; TARGET_INSTALLNAME_DIR
; TARGET_PDB
; TARGET_QUOTED
; TARGET_SONAME
; TARGET_VERSION_MAJOR
; TARGET_VERSION_MINOR

Please note you can set these properties globally using SET or LIST, or for a single target using SET_TARGET_PROPERTIES.

== 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 [[CMake_Useful_Variables/Get_Variables_From_CMake_Dashboards|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.
#[[CMake_Useful_Variables/Logging_Useful_Variables | Sample code for logging useful variables.]]


{{CMake/Template/Footer}}