Difference between revisions of "CMake Useful Variables"

From KitwarePublic
Jump to navigationJump to search
(some variables appear to be read-only)
Line 171: Line 171:
 
; TARGET_VERSION_MAJOR
 
; TARGET_VERSION_MAJOR
 
; TARGET_VERSION_MINOR
 
; 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 ==
 
== Variables not listed here ==

Revision as of 07:03, 14 November 2007

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_COMMAND 
this is the complete path of the cmake which runs currently (e.g. /usr/local/bin/cmake)
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 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.

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()
SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts)
FIND_PACKAGE(HelloWorld)
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)
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)
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. /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 & 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_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 
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 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 
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.
SET(BUILD_SHARED_LIBS ON)
CMAKE_AR 
tool for creating libraries. See also CMAKE_RANLIB, as "ar" and "ranlib" are typically used together.
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")

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_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:
CC=gcc-3.3 CXX=g++-3.3 cmake
to set the compiler. Any other way (like writing make CC=gcc-3.3 CXX=g++-3.3) will not work. When using distcc or similar tools, you need to write:
CC="distcc gcc-3.3" CXX="distcc g++-3.3" cmake
CMAKE_C_FLAGS 
the compiler flags for compiling C sources. Note you can also specify switches with ADD_DEFINITIONS().
CMAKE_C_OUTPUT_EXTENSION 
what C object files end in. Typically .o or .obj.
CMAKE_CFG_INTDIR 
the configuration directory for the project. For MSVC generators it is typically one of "/Debug", "/Release", "/RelWithDebInfo", or "/MinSizeRel". For other compiler generators 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_RANLIB 
tool for creating libraries. See also CMAKE_AR, as "ar" and "ranlib" are typically used together.

prefixes, suffixes, 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.

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 <SOURCE> 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 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]