dwww: tpablo.net

dwww Home | Manual pages | Find package

CMAKE-VARIABLES(7) CMake CMAKE-VARIABLES(7)

NAME
cmake-variables - CMake Variables Reference

This page documents variables that are provided by CMake or have mean-
ing to CMake when set by project code.

For general information on variables, see the Variables section in the
cmake-language manual.

NOTE:
CMake reserves identifiers that:

• begin with CMAKE_ (upper-, lower-, or mixed-case), or

• begin with _CMAKE_ (upper-, lower-, or mixed-case), or

• begin with _ followed by the name of any CMake Command.

VARIABLES THAT PROVIDE INFORMATION
CMAKE_AR
Name of archiving tool for static libraries.

This specifies the name of the program that creates archive or static
libraries.

CMAKE_ARGC
Number of command line arguments passed to CMake in script mode.

When run in -P script mode, CMake sets this variable to the number of
command line arguments. See also CMAKE_ARGV0, 1, 2 ...

CMAKE_ARGV0
Command line argument passed to CMake in script mode.

When run in -P script mode, CMake sets this variable to the first com-
mand line argument. It then also sets CMAKE_ARGV1, CMAKE_ARGV2, ...
and so on, up to the number of command line arguments given. See also
CMAKE_ARGC.

CMAKE_BINARY_DIR
The path to the top level of the build tree.

This is the full path to the top level of the current CMake build tree.
For an in-source build, this would be the same as CMAKE_SOURCE_DIR.

When run in -P script mode, CMake sets the variables CMAKE_BINARY_DIR,
CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR
to the current working directory.

CMAKE_BUILD_TOOL
This variable exists only for backwards compatibility. It contains the
same value as CMAKE_MAKE_PROGRAM. Use that variable instead.

CMAKE_CACHE_MAJOR_VERSION
Major version of CMake used to create the CMakeCache.txt file

This stores the major version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run on
a previously created cache file.

CMAKE_CACHE_MINOR_VERSION
Minor version of CMake used to create the CMakeCache.txt file

This stores the minor version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run on
a previously created cache file.

CMAKE_CACHE_PATCH_VERSION
Patch version of CMake used to create the CMakeCache.txt file

This stores the patch version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run on
a previously created cache file.

CMAKE_CACHEFILE_DIR
The directory with the CMakeCache.txt file.

This is the full path to the directory that has the CMakeCache.txt file
in it. This is the same as CMAKE_BINARY_DIR.

CMAKE_CFG_INTDIR
Deprecated since version 3.21: This variable has poor support on Ninja
Multi-Config, and predates the existence of the $<CONFIG> generator ex-
pression. Use $<CONFIG> instead.

Build-time reference to per-configuration output subdirectory.

For native build systems supporting multiple configurations in the
build tree (such as Visual Studio Generators and Xcode), the value is a
reference to a build-time variable specifying the name of the per-con-
figuration output subdirectory. On Makefile Generators this evaluates
to . because there is only one configuration in a build tree. Example
values:

$(ConfigurationName) = Visual Studio 9
$(Configuration) = Visual Studio 10
$(CONFIGURATION) = Xcode
. = Make-based tools
. = Ninja
${CONFIGURATION} = Ninja Multi-Config

Since these values are evaluated by the native build system, this vari-
able is suitable only for use in command lines that will be evaluated
at build time. Example of intended usage:

add_executable(mytool mytool.c)
add_custom_command(
OUTPUT out.txt
COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
DEPENDS mytool in.txt
)
add_custom_target(drive ALL DEPENDS out.txt)

Note that CMAKE_CFG_INTDIR is no longer necessary for this purpose but
has been left for compatibility with existing projects. Instead
add_custom_command() recognizes executable target names in its COMMAND
option, so ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool can
be replaced by just mytool.

This variable is read-only. Setting it is undefined behavior. In
multi-configuration build systems the value of this variable is passed
as the value of preprocessor symbol CMAKE_INTDIR to the compilation of
all source files.

CMAKE_COMMAND
The full path to the cmake(1) executable.

This is the full path to the CMake executable cmake(1) which is useful
from custom commands that want to use the cmake -E option for portable
system commands. (e.g. /usr/local/bin/cmake)

CMAKE_CPACK_COMMAND
New in version 3.13.

Full path to cpack(1) command installed with CMake.

This is the full path to the CPack executable cpack(1) which is useful
from custom commands that want to use the cmake(1) -E option for porta-
ble system commands.

CMAKE_CROSSCOMPILING
Intended to indicate whether CMake is cross compiling, but note limita-
tions discussed below.

This variable will be set to true by CMake if the CMAKE_SYSTEM_NAME
variable has been set manually (i.e. in a toolchain file or as a cache
entry from the cmake command line). In most cases, manually setting
CMAKE_SYSTEM_NAME will only be done when cross compiling, since it will
otherwise be given the same value as CMAKE_HOST_SYSTEM_NAME if not man-
ually set, which is correct for the non-cross-compiling case. In the
event that CMAKE_SYSTEM_NAME is manually set to the same value as
CMAKE_HOST_SYSTEM_NAME, then CMAKE_CROSSCOMPILING will still be set to
true.

Another case to be aware of is that builds targeting Apple platforms
other than macOS are handled differently to other cross compiling sce-
narios. Rather than relying on CMAKE_SYSTEM_NAME to select the target
platform, Apple device builds use CMAKE_OSX_SYSROOT to select the ap-
propriate SDK, which indirectly determines the target platform. Fur-
thermore, when using the Xcode generator, developers can switch between
device and simulator builds at build time rather than having a single
choice at configure time, so the concept of whether the build is cross
compiling or not is more complex. Therefore, the use of CMAKE_CROSSCOM-
PILING is not recommended for projects targeting Apple devices.

CMAKE_CROSSCOMPILING_EMULATOR
New in version 3.3.

This variable is only used when CMAKE_CROSSCOMPILING is on. It should
point to a command on the host system that can run executable built for
the target system.

If this variable contains a semicolon-separated list, then the first
value is the command and remaining values are its arguments.

The command will be used to run try_run() generated executables, which
avoids manual population of the TryRunResults.cmake file.

It is also used as the default value for the CROSSCOMPILING_EMULATOR
target property of executables.

CMAKE_CTEST_COMMAND
Full path to ctest(1) command installed with CMake.

This is the full path to the CTest executable ctest(1) which is useful
from custom commands that want to use the cmake(1) -E option for porta-
ble system commands.

CMAKE_CURRENT_BINARY_DIR
The path to the binary directory currently being processed.

This the full path to the build directory that is currently being pro-
cessed by cmake. Each directory added by add_subdirectory() will cre-
ate a binary directory in the build tree, and as it is being processed
this variable will be set. For in-source builds this is the current
source directory being processed.

When run in -P script mode, CMake sets the variables CMAKE_BINARY_DIR,
CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR
to the current working directory.

CMAKE_CURRENT_FUNCTION
New in version 3.17.

When executing code inside a function(), this variable contains the
name of the current function. It can be useful for diagnostic or debug
messages.

See also CMAKE_CURRENT_FUNCTION_LIST_DIR, CMAKE_CURRENT_FUNC-
TION_LIST_FILE and CMAKE_CURRENT_FUNCTION_LIST_LINE.

CMAKE_CURRENT_FUNCTION_LIST_DIR
New in version 3.17.

When executing code inside a function(), this variable contains the
full directory of the listfile that defined the current function.

It is quite common practice in CMake for modules to use some additional
files, such as templates to be copied in after substituting CMake vari-
ables. In such cases, a function needs to know where to locate those
files in a way that doesn't depend on where the function is called.
Without CMAKE_CURRENT_FUNCTION_LIST_DIR, the code to do that would typ-
ically use the following pattern:

set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")

function(foo)
configure_file(
"${_THIS_MODULE_BASE_DIR}/some.template.in"
some.output
)
endfunction()

Using CMAKE_CURRENT_FUNCTION_LIST_DIR inside the function instead elim-
inates the need for the extra variable which would otherwise be visible
outside the function's scope. The above example can be written in the
more concise and more robust form:

function(foo)
configure_file(
"${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
some.output
)
endfunction()

See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_FILE and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

CMAKE_CURRENT_FUNCTION_LIST_FILE
New in version 3.17.

When executing code inside a function(), this variable contains the
full path to the listfile that defined the current function.

See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

CMAKE_CURRENT_FUNCTION_LIST_LINE
New in version 3.17.

When executing code inside a function(), this variable contains the
line number in the listfile where the current function was defined.

See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
CMAKE_CURRENT_FUNCTION_LIST_FILE.

CMAKE_CURRENT_LIST_DIR
Full directory of the listfile currently being processed.

As CMake processes the listfiles in your project this variable will al-
ways be set to the directory where the listfile which is currently be-
ing processed (CMAKE_CURRENT_LIST_FILE) is located. The value has dy-
namic scope. When CMake starts processing commands in a source file it
sets this variable to the directory where this file is located. When
CMake finishes processing commands from the file it restores the previ-
ous value. Therefore the value of the variable inside a macro or func-
tion is the directory of the file invoking the bottom-most entry on the
call stack, not the directory of the file containing the macro or func-
tion definition.

See also CMAKE_LINK_SEARCH_END_STATIC.

CMAKE_MAJOR_VERSION
First version number component of the CMAKE_VERSION variable.

CMAKE_MAKE_PROGRAM
Tool that can launch the native build system. The value may be the
full path to an executable or just the tool name if it is expected to
be in the PATH.

The tool selected depends on the CMAKE_GENERATOR used to configure the
project:

• The Makefile Generators set this to make, gmake, or a generator-spe-
cific tool (e.g. nmake for NMake Makefiles).

These generators store CMAKE_MAKE_PROGRAM in the CMake cache so that
it may be edited by the user.

• The Ninja generator sets this to ninja.

This generator stores CMAKE_MAKE_PROGRAM in the CMake cache so that
it may be edited by the user.

• The Xcode generator sets this to xcodebuild.

This generator prefers to lookup the build tool at build time rather
than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
This is because xcodebuild is easy to find.

For compatibility with versions of CMake prior to 3.2, if a user or
project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
CMake will use the specified value.

• The Visual Studio Generators set this to the full path to MSBuild.exe
(VS >= 10), devenv.com (VS 7,8,9), or VCExpress.exe (VS Express 8,9).
(See also variables CMAKE_VS_MSBUILD_COMMAND and CMAKE_VS_DEVENV_COM-
MAND.

These generators prefer to lookup the build tool at build time rather
than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
This is because the tools are version-specific and can be located us-
ing the Windows Registry. It is also necessary because the proper
build tool may depend on the project content (e.g. the Intel Fortran
plugin to VS 10 and 11 requires devenv.com to build its .vfproj
project files even though MSBuild.exe is normally preferred to sup-
port the CMAKE_GENERATOR_TOOLSET).

For compatibility with versions of CMake prior to 3.0, if a user or
project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
CMake will use the specified value if possible.

• The Green Hills MULTI generator sets this to the full path to
gbuild.exe(Windows) or gbuild(Linux) based upon the toolset being
used.

Once the generator has initialized a particular value for this vari-
able, changing the value has undefined behavior.

The CMAKE_MAKE_PROGRAM variable is set for use by project code. The
value is also used by the cmake(1) --build and ctest(1)
--build-and-test tools to launch the native build process.

CMAKE_MATCH_COUNT
New in version 3.2.

The number of matches with the last regular expression.

When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
variables with the match contents. The CMAKE_MATCH_COUNT variable
holds the number of match expressions when these are filled.

CMAKE_MATCH_<n>
New in version 3.9.

Capture group <n> matched by the last regular expression, for groups 0
through 9. Group 0 is the entire match. Groups 1 through 9 are the
subexpressions captured by () syntax.

When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
variables with the match contents. The CMAKE_MATCH_COUNT variable
holds the number of match expressions when these are filled.

CMAKE_MINIMUM_REQUIRED_VERSION
The <min> version of CMake given to the most recent call to the
cmake_minimum_required(VERSION) command in the current variable scope
or any parent variable scope.

CMAKE_MINOR_VERSION
Second version number component of the CMAKE_VERSION variable.

CMAKE_NETRC
New in version 3.11.

This variable is used to initialize the NETRC option for the file(DOWN-
LOAD) and file(UPLOAD) commands. See those commands for additional in-
formation.

This variable is also used by the ExternalProject and FetchContent mod-
ules for internal calls to file(DOWNLOAD).

The local option takes precedence over this variable.

CMAKE_NETRC_FILE
New in version 3.11.

This variable is used to initialize the NETRC_FILE option for the
file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi-
tional information.

This variable is also used by the ExternalProject and FetchContent mod-
ules for internal calls to file(DOWNLOAD).

The local option takes precedence over this variable.

CMAKE_PARENT_LIST_FILE
Full path to the CMake file that included the current one.

While processing a CMake file loaded by include() or find_package()
this variable contains the full path to the file including it. The top
of the include stack is always the CMakeLists.txt for the current di-
rectory. See also CMAKE_CURRENT_LIST_FILE.

CMAKE_PATCH_VERSION
Third version number component of the CMAKE_VERSION variable.

CMAKE_PROJECT_DESCRIPTION
New in version 3.9.

The description of the top level project.

This variable holds the description of the project as specified in the
top level CMakeLists.txt file by a project() command. In the event
that the top level CMakeLists.txt contains multiple project() calls,
the most recently called one from that top level CMakeLists.txt will
determine the value that CMAKE_PROJECT_DESCRIPTION contains. For exam-
ple, consider the following top level CMakeLists.txt:

cmake_minimum_required(VERSION 3.0)
project(First DESCRIPTION "I am First")
project(Second DESCRIPTION "I am Second")
add_subdirectory(sub)
project(Third DESCRIPTION "I am Third")

And sub/CMakeLists.txt with the following contents:

project(SubProj DESCRIPTION "I am SubProj")
message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")

The most recently seen project() command from the top level CMake-
Lists.txt would be project(Second ...), so this will print:

CMAKE_PROJECT_DESCRIPTION = I am Second

To obtain the description from the most recent call to project() in the
current directory scope or above, see the PROJECT_DESCRIPTION variable.

CMAKE_PROJECT_HOMEPAGE_URL
New in version 3.12.

The homepage URL of the top level project.

This variable holds the homepage URL of the project as specified in the
top level CMakeLists.txt file by a project() command. In the event
that the top level CMakeLists.txt contains multiple project() calls,
the most recently called one from that top level CMakeLists.txt will
determine the value that CMAKE_PROJECT_HOMEPAGE_URL contains. For ex-
ample, consider the following top level CMakeLists.txt:

cmake_minimum_required(VERSION 3.0)
project(First HOMEPAGE_URL "http://first.example.com")
project(Second HOMEPAGE_URL "http://second.example.com")
add_subdirectory(sub)
project(Third HOMEPAGE_URL "http://third.example.com")

And sub/CMakeLists.txt with the following contents:

project(SubProj HOMEPAGE_URL "http://subproj.example.com")
message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}")

The most recently seen project() command from the top level CMake-
Lists.txt would be project(Second ...), so this will print:

CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com

To obtain the homepage URL from the most recent call to project() in
the current directory scope or above, see the PROJECT_HOMEPAGE_URL
variable.

CMAKE_PROJECT_NAME
The name of the top level project.

This variable holds the name of the project as specified in the top
level CMakeLists.txt file by a project() command. In the event that
the top level CMakeLists.txt contains multiple project() calls, the
most recently called one from that top level CMakeLists.txt will deter-
mine the name that CMAKE_PROJECT_NAME contains. For example, consider
the following top level CMakeLists.txt:

cmake_minimum_required(VERSION 3.0)
project(First)
project(Second)
add_subdirectory(sub)
project(Third)

And sub/CMakeLists.txt with the following contents:

project(SubProj)
message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")

The most recently seen project() command from the top level CMake-
Lists.txt would be project(Second), so this will print:

CMAKE_PROJECT_NAME = Second

To obtain the name from the most recent call to project() in the cur-
rent directory scope or above, see the PROJECT_NAME variable.

CMAKE_PROJECT_VERSION
New in version 3.12.

The version of the top level project.

This variable holds the version of the project as specified in the top
level CMakeLists.txt file by a project() command. In the event that
the top level CMakeLists.txt contains multiple project() calls, the
most recently called one from that top level CMakeLists.txt will deter-
mine the value that CMAKE_PROJECT_VERSION contains. For example, con-
sider the following top level CMakeLists.txt:

cmake_minimum_required(VERSION 3.0)
project(First VERSION 1.2.3)
project(Second VERSION 3.4.5)
add_subdirectory(sub)
project(Third VERSION 6.7.8)

And sub/CMakeLists.txt with the following contents:

project(SubProj VERSION 1)
message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")

The most recently seen project() command from the top level CMake-
Lists.txt would be project(Second ...), so this will print:

CMAKE_PROJECT_VERSION = 3.4.5

To obtain the version from the most recent call to project() in the
current directory scope or above, see the PROJECT_VERSION variable.

CMAKE_PROJECT_VERSION_MAJOR
New in version 3.12.

The major version of the top level project.

This variable holds the major version of the project as specified in
the top level CMakeLists.txt file by a project() command. Please see
CMAKE_PROJECT_VERSION documentation for the behavior when multiple
project() commands are used in the sources.

CMAKE_PROJECT_VERSION_MINOR
New in version 3.12.

The minor version of the top level project.

This variable holds the minor version of the project as specified in
the top level CMakeLists.txt file by a project() command. Please see
CMAKE_PROJECT_VERSION documentation for the behavior when multiple
project() commands are used in the sources.

CMAKE_PROJECT_VERSION_PATCH
New in version 3.12.

The patch version of the top level project.

This variable holds the patch version of the project as specified in
the top level CMakeLists.txt file by a project() command. Please see
CMAKE_PROJECT_VERSION documentation for the behavior when multiple
project() commands are used in the sources.

CMAKE_PROJECT_VERSION_TWEAK
New in version 3.12.

The tweak version of the top level project.

This variable holds the tweak version of the project as specified in
the top level CMakeLists.txt file by a project() command. Please see
CMAKE_PROJECT_VERSION documentation for the behavior when multiple
project() commands are used in the sources.

CMAKE_RANLIB
Name of randomizing tool for static libraries.

This specifies name of the program that randomizes libraries on UNIX,
not used on Windows, but may be present.

CMAKE_ROOT
Install directory for running cmake.

This is the install root for the running CMake and the Modules direc-
tory can be found here. This is commonly used in this format:
${CMAKE_ROOT}/Modules

CMAKE_RULE_MESSAGES
New in version 3.13.

Specify whether to report a message for each make rule.

If set in the cache it is used to initialize the value of the RULE_MES-
SAGES property. Users may disable the option in their local build tree
to disable granular messages and report only as each target completes
in Makefile builds.

CMAKE_SCRIPT_MODE_FILE
Full path to the cmake(1) -P script file currently being processed.

When run in cmake(1) -P script mode, CMake sets this variable to the
full path of the script file. When run to configure a CMakeLists.txt
file, this variable is not set.

CMAKE_SHARED_LIBRARY_PREFIX
The prefix for shared libraries that you link to.

The prefix to use for the name of a shared library, lib on UNIX.

CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.

CMAKE_SHARED_LIBRARY_SUFFIX
The suffix for shared libraries that you link to.

The suffix to use for the end of a shared library filename, .dll on
Windows.

CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.

CMAKE_SHARED_MODULE_PREFIX
The prefix for loadable modules that you link to.

The prefix to use for the name of a loadable module on this platform.

CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides this for language <LANG>.

CMAKE_SHARED_MODULE_SUFFIX
The suffix for shared libraries that you link to.

The suffix to use for the end of a loadable module filename on this
platform

CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides this for language <LANG>.

CMAKE_SIZEOF_VOID_P
Size of a void pointer.

This is set to the size of a pointer on the target machine, and is de-
termined by a try compile. If a 64-bit size is found, then the library
search path is modified to look for 64-bit libraries first.

CMAKE_SKIP_INSTALL_RULES
Whether to disable generation of installation rules.

If TRUE, CMake will neither generate installation rules nor will it
generate cmake_install.cmake files. This variable is FALSE by default.

CMAKE_SKIP_RPATH
If true, do not add run time path information.

If this is set to TRUE, then the rpath information is not added to com-
piled executables. The default is to add rpath information if the
platform supports it. This allows for easy running from the build
tree. To omit RPATH in the install step, but not the build step, use
CMAKE_SKIP_INSTALL_RPATH instead.

CMAKE_SOURCE_DIR
The path to the top level of the source tree.

This is the full path to the top level of the current CMake source
tree. For an in-source build, this would be the same as CMAKE_BI-
NARY_DIR.

When run in -P script mode, CMake sets the variables CMAKE_BINARY_DIR,
CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and CMAKE_CURRENT_SOURCE_DIR
to the current working directory.

CMAKE_STATIC_LIBRARY_PREFIX
The prefix for static libraries that you link to.

The prefix to use for the name of a static library, lib on UNIX.

CMAKE_STATIC_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.

CMAKE_STATIC_LIBRARY_SUFFIX
The suffix for static libraries that you link to.

The suffix to use for the end of a static library filename, .lib on
Windows.

CMAKE_STATIC_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.

CMAKE_Swift_MODULE_DIRECTORY
New in version 3.15.

Swift module output directory.

This variable is used to initialize the Swift_MODULE_DIRECTORY property
on all the targets. See the target property for additional informa-
tion.

CMAKE_Swift_NUM_THREADS
New in version 3.15.1.

Number of threads for parallel compilation for Swift targets.

This variable controls the number of parallel jobs that the swift
driver creates for building targets. If not specified, it will default
to the number of logical CPUs on the host.

CMAKE_TOOLCHAIN_FILE
Path to toolchain file supplied to cmake(1).

This variable is specified on the command line when cross-compiling
with CMake. It is the path to a file which is read early in the CMake
run and which specifies locations for compilers and toolchain utili-
ties, and other target platform and compiler related information.

Relative paths are allowed and are interpreted first as relative to the
build directory, and if not found, relative to the source directory.

This is initialized by the CMAKE_TOOLCHAIN_FILE environment variable if
it is set when a new build tree is first created.

CMAKE_TWEAK_VERSION
Defined to 0 for compatibility with code written for older CMake ver-
sions that may have defined higher values.

NOTE:
In CMake versions 2.8.2 through 2.8.12, this variable holds the
fourth version number component of the CMAKE_VERSION variable.

CMAKE_VERBOSE_MAKEFILE
Enable verbose output from Makefile builds.

This variable is a cache entry initialized (to FALSE) by the project()
command. Users may enable the option in their local build tree to get
more verbose output from Makefile builds and show each command line as
it is launched.

CMAKE_VERSION
The CMake version string as three non-negative integer components sepa-
rated by . and possibly followed by - and other information. The first
two components represent the feature level and the third component rep-
resents either a bug-fix level or development date.

Release versions and release candidate versions of CMake use the for-
mat:

<major>.<minor>.<patch>[-rc<n>]

where the <patch> component is less than 20000000. Development ver-
sions of CMake use the format:

<major>.<minor>.<date>[-<id>]

where the <date> component is of format CCYYMMDD and <id> may contain
arbitrary text. This represents development as of a particular date
following the <major>.<minor> feature release.

Individual component values are also available in variables:

• CMAKE_MAJOR_VERSION

• CMAKE_MINOR_VERSION

• CMAKE_PATCH_VERSION

• CMAKE_TWEAK_VERSION

Use the if() command VERSION_LESS, VERSION_GREATER, VERSION_EQUAL, VER-
SION_LESS_EQUAL, or VERSION_GREATER_EQUAL operators to compare version
string values against CMAKE_VERSION using a component-wise test. Ver-
sion component values may be 10 or larger so do not attempt to compare
version strings as floating-point numbers.

NOTE:
CMake versions 2.8.2 through 2.8.12 used three components for the
feature level. Release versions represented the bug-fix level in a
fourth component, i.e. <major>.<minor>.<patch>[.<tweak>][-rc<n>].
Development versions represented the development date in the fourth
component, i.e. <major>.<minor>.<patch>.<date>[-<id>].

CMake versions prior to 2.8.2 used three components for the feature
level and had no bug-fix component. Release versions used an
even-valued second component, i.e. <major>.<even-mi-
nor>.<patch>[-rc<n>]. Development versions used an odd-valued sec-
ond component with the development date as the third component, i.e.
<major>.<odd-minor>.<date>.

The CMAKE_VERSION variable is defined by CMake 2.6.3 and higher.
Earlier versions defined only the individual component variables.

CMAKE_VS_DEVENV_COMMAND
The generators for Visual Studio 9 2008 and above set this variable to
the devenv.com command installed with the corresponding Visual Studio
version. Note that this variable may be empty on Visual Studio Express
editions because they do not provide this tool.

This variable is not defined by other generators even if devenv.com is
installed on the computer.

The CMAKE_VS_MSBUILD_COMMAND is also provided for Visual Studio 10 2010
and above. See also the CMAKE_MAKE_PROGRAM variable.

CMAKE_VS_MSBUILD_COMMAND
The generators for Visual Studio 10 2010 and above set this variable to
the MSBuild.exe command installed with the corresponding Visual Studio
version.

This variable is not defined by other generators even if MSBuild.exe is
installed on the computer.

The CMAKE_VS_DEVENV_COMMAND is also provided for the non-Express edi-
tions of Visual Studio. See also the CMAKE_MAKE_PROGRAM variable.

CMAKE_VS_NsightTegra_VERSION
New in version 3.1.

When using a Visual Studio generator with the CMAKE_SYSTEM_NAME vari-
able set to Android, this variable contains the version number of the
installed NVIDIA Nsight Tegra Visual Studio Edition.

CMAKE_VS_PLATFORM_NAME
New in version 3.1.

Visual Studio target platform name used by the current generator.

VS 8 and above allow project files to specify a target platform. CMake
provides the name of the chosen platform in this variable. See the
CMAKE_GENERATOR_PLATFORM variable for details.

See also the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.

CMAKE_VS_PLATFORM_NAME_DEFAULT
New in version 3.14.3.

Default for the Visual Studio target platform name for the current gen-
erator without considering the value of the CMAKE_GENERATOR_PLATFORM
variable. For Visual Studio Generators for VS 2017 and below this is
always Win32. For VS 2019 and above this is based on the host plat-
form.

See also the CMAKE_VS_PLATFORM_NAME variable.

CMAKE_VS_PLATFORM_TOOLSET
Visual Studio Platform Toolset name.

VS 10 and above use MSBuild under the hood and support multiple com-
piler toolchains. CMake may specify a toolset explicitly, such as v110
for VS 11 or Windows7.1SDK for 64-bit support in VS 10 Express. CMake
provides the name of the chosen toolset in this variable.

See the CMAKE_GENERATOR_TOOLSET variable for details.

CMAKE_VS_PLATFORM_TOOLSET_CUDA
New in version 3.9.

NVIDIA CUDA Toolkit version whose Visual Studio toolset to use.

The Visual Studio Generators for VS 2010 and above support using a CUDA
toolset provided by a CUDA Toolkit. The toolset version number may be
specified by a field in CMAKE_GENERATOR_TOOLSET of the form cuda=8.0.
Or it is automatically detected if a path to a standalone CUDA direc-
tory is specified in the form cuda=C:\path\to\cuda. If none is speci-
fied CMake will choose a default version. CMake provides the selected
CUDA toolset version in this variable. The value may be empty if no
CUDA Toolkit with Visual Studio integration is installed.

CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
New in version 3.16.

Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer).

The Visual Studio Generators for VS 2010 and above support using a
standalone (non-installed) NVIDIA CUDA toolkit. The path may be speci-
fied by a field in CMAKE_GENERATOR_TOOLSET of the form
cuda=C:\path\to\cuda. The given directory must at least contain the
nvcc compiler in path .\bin and must provide Visual Studio integration
files in path .\extras\visual_studio_integration\ MSBuildExtensions\.
One can create a standalone CUDA toolkit directory by either opening a
installer with 7zip or copying the files that are extracted by the run-
ning installer. The value may be empty if no path to a standalone CUDA
Toolkit was specified.

CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
New in version 3.8.

Visual Studio preferred tool architecture.

The Visual Studio Generators for VS 2013 and above support using either
the 32-bit or 64-bit host toolchains by specifying a host=x86 or
host=x64 value in the CMAKE_GENERATOR_TOOLSET option. CMake provides
the selected toolchain architecture preference in this variable (x86,
x64, or empty).

CMAKE_VS_PLATFORM_TOOLSET_VERSION
New in version 3.12.

Visual Studio Platform Toolset version.

The Visual Studio Generators for VS 2017 and above allow to select mi-
nor versions of the same toolset. The toolset version number may be
specified by a field in CMAKE_GENERATOR_TOOLSET of the form ver-
sion=14.11. If none is specified CMake will choose a default toolset.
The value may be empty if no minor version was selected and the default
is used.

If the value is not empty, it is the version number that MSBuild uses
in its Microsoft.VCToolsVersion.*.props file names.

New in version 3.19.7: VS 16.9's toolset may also be specified as
14.28.16.9 because VS 16.10 uses the file name Microsoft.VCToolsVer-
sion.14.28.16.9.props.

Three-Component MSVC Toolset Versions
New in version 3.19.7.

The version= field may be given a three-component toolset version such
as 14.28.29910, and CMake will convert it to the name used by MSBuild
Microsoft.VCToolsVersion.*.props files. This is useful to distinguish
between VS 16.8's 14.28.29333 toolset and VS 16.9's 14.28.29910
toolset. It also matches vcvarsall's -vcvars_ver= behavior.

CMAKE_VS_TARGET_FRAMEWORK_VERSION
New in version 3.22.

Visual Studio target framework version.

In some cases, the Visual Studio Generators may use an explicit value
for the MSBuild TargetFrameworkVersion setting in .csproj files. CMake
provides the chosen value in this variable.

See the CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION variable and DOTNET_TAR-
GET_FRAMEWORK_VERSION target property to specify custom TargetFrame-
workVersion values for project targets.

See also CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER and CMAKE_VS_TAR-
GET_FRAMEWORK_TARGETS_VERSION.

CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
New in version 3.22.

Visual Studio target framework identifier.

In some cases, the Visual Studio Generators may use an explicit value
for the MSBuild TargetFrameworkIdentifier setting in .csproj files.
CMake provides the chosen value in this variable.

See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and CMAKE_VS_TARGET_FRAME-
WORK_TARGETS_VERSION.

CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
New in version 3.22.

Visual Studio target framework targets version.

In some cases, the Visual Studio Generators may use an explicit value
for the MSBuild TargetFrameworkTargetsVersion setting in .csproj files.
CMake provides the chosen value in this variable.

See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and CMAKE_VS_TARGET_FRAME-
WORK_IDENTIFIER.

CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
New in version 3.4.

Visual Studio Windows Target Platform Version.

When targeting Windows 10 and above Visual Studio 2015 and above sup-
port specification of a target Windows version to select a correspond-
ing SDK. The CMAKE_SYSTEM_VERSION variable may be set to specify a
version. Otherwise CMake computes a default version based on the Win-
dows SDK versions available. The chosen Windows target version number
is provided in CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION. If no Windows
10 SDK is available this value will be empty.

One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to an ab-
solute path to tell CMake to look for Windows 10 SDKs in a custom loca-
tion. The specified directory is expected to contain Include/10.0.*
directories.

See also CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.

CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
New in version 3.19.

Override the Windows 10 SDK Maximum Version for VS 2015 and beyond.

The CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM variable may be
set to a false value (e.g. OFF, FALSE, or 0) or the SDK version to use
as the maximum (e.g. 10.0.14393.0). If unset, the default depends on
which version of Visual Studio is targeted by the current generator.

This can be used in conjunction with CMAKE_SYSTEM_VERSION, which CMake
uses to select CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.

CMAKE_XCODE_BUILD_SYSTEM
New in version 3.19.

Xcode build system selection.

The Xcode generator defines this variable to indicate which variant of
the Xcode build system will be used. The value is the version of Xcode
in which the corresponding build system first became mature enough for
use by CMake. The possible values are:

1 The original Xcode build system. This is the default when using
Xcode 11.x or below.

12 The Xcode "new build system" introduced by Xcode 10. It became
mature enough for use by CMake in Xcode 12. This is the default
when using Xcode 12.x or above.

The CMAKE_XCODE_BUILD_SYSTEM variable is informational and should not
be modified by project code. See the Xcode Build System Selection doc-
umentation section to select the Xcode build system.

CMAKE_XCODE_PLATFORM_TOOLSET
Xcode compiler selection.

Xcode supports selection of a compiler from one of the installed
toolsets. CMake provides the name of the chosen toolset in this vari-
able, if any is explicitly selected (e.g. via the cmake(1) -T option).

<PROJECT-NAME>_BINARY_DIR
Top level binary directory for the named project.

A variable is created with the name used in the project() command, and
is the binary directory for the project. This can be useful when
add_subdirectory() is used to connect several projects.

<PROJECT-NAME>_DESCRIPTION
New in version 3.12.

Value given to the DESCRIPTION option of the most recent call to the
project() command with project name <PROJECT-NAME>, if any.

<PROJECT-NAME>_HOMEPAGE_URL
New in version 3.12.

Value given to the HOMEPAGE_URL option of the most recent call to the
project() command with project name <PROJECT-NAME>, if any.

<PROJECT-NAME>_IS_TOP_LEVEL
New in version 3.21.

A boolean variable indicating whether the named project was called in a
top level CMakeLists.txt file.

To obtain the value from the most recent call to project() in the cur-
rent directory scope or above, see the PROJECT_IS_TOP_LEVEL variable.

The variable value will be true in:

• the top-level directory of the project

• the top-level directory of an external project added by ExternalPro-
ject

The variable value will be false in:

• a directory added by add_subdirectory()

• a directory added by FetchContent

<PROJECT-NAME>_SOURCE_DIR
Top level source directory for the named project.

A variable is created with the name used in the project() command, and
is the source directory for the project. This can be useful when
add_subdirectory() is used to connect several projects.

<PROJECT-NAME>_VERSION
Value given to the VERSION option of the most recent call to the
project() command with project name <PROJECT-NAME>, if any.

See also the component-wise version variables <PROJECT-NAME>_VER-
SION_MAJOR, <PROJECT-NAME>_VERSION_MINOR, <PROJECT-NAME>_VERSION_PATCH,
and <PROJECT-NAME>_VERSION_TWEAK.

<PROJECT-NAME>_VERSION_MAJOR
First version number component of the <PROJECT-NAME>_VERSION variable
as set by the project() command.

<PROJECT-NAME>_VERSION_MINOR
Second version number component of the <PROJECT-NAME>_VERSION variable
as set by the project() command.

<PROJECT-NAME>_VERSION_PATCH
Third version number component of the <PROJECT-NAME>_VERSION variable
as set by the project() command.

<PROJECT-NAME>_VERSION_TWEAK
Fourth version number component of the <PROJECT-NAME>_VERSION variable
as set by the project() command.

PROJECT_BINARY_DIR
Full path to build directory for project.

This is the binary directory of the most recent project() command.

PROJECT_DESCRIPTION
New in version 3.9.

Short project description given to the project command.

This is the description given to the most recently called project()
command in the current directory scope or above. To obtain the de-
scription of the top level project, see the CMAKE_PROJECT_DESCRIPTION
variable.

PROJECT_HOMEPAGE_URL
New in version 3.12.

The homepage URL of the project.

This is the homepage URL given to the most recently called project()
command in the current directory scope or above. To obtain the home-
page URL of the top level project, see the CMAKE_PROJECT_HOMEPAGE_URL
variable.

PROJECT_IS_TOP_LEVEL
New in version 3.21.

A boolean variable indicating whether the most recently called
project() command in the current scope or above was in the top level
CMakeLists.txt file.

Some modules should only be included as part of the top level CMake-
Lists.txt file to not cause unintended side effects in the build tree,
and this variable can be used to conditionally execute such code. For
example, consider the CTest module, which creates targets and options:

project(MyProject)
...
if(PROJECT_IS_TOP_LEVEL)
include(CTest)
endif()

The variable value will be true in:

• the top-level directory of the project

• the top-level directory of an external project added by ExternalPro-
ject

The variable value will be false in:

• a directory added by add_subdirectory()

• a directory added by FetchContent

PROJECT_NAME
Name of the project given to the project command.

This is the name given to the most recently called project() command in
the current directory scope or above. To obtain the name of the top
level project, see the CMAKE_PROJECT_NAME variable.

PROJECT_SOURCE_DIR
This is the source directory of the last call to the project() command
made in the current directory scope or one of its parents. Note, it is
not affected by calls to project() made within a child directory scope
(i.e. from within a call to add_subdirectory() from the current scope).

PROJECT_VERSION
Value given to the VERSION option of the most recent call to the
project() command, if any.

See also the component-wise version variables PROJECT_VERSION_MAJOR,
PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH, and PROJECT_VER-
SION_TWEAK.

PROJECT_VERSION_MAJOR
First version number component of the PROJECT_VERSION variable as set
by the project() command.

PROJECT_VERSION_MINOR
Second version number component of the PROJECT_VERSION variable as set
by the project() command.

PROJECT_VERSION_PATCH
Third version number component of the PROJECT_VERSION variable as set
by the project() command.

PROJECT_VERSION_TWEAK
Fourth version number component of the PROJECT_VERSION variable as set
by the project() command.

VARIABLES THAT CHANGE BEHAVIOR
BUILD_SHARED_LIBS
Global flag to cause add_library() to create shared libraries if on.

If present and true, this will cause all libraries to be built shared
unless the library was explicitly added as a static library. This
variable is often added to projects as an option() so that each user of
a project can decide if they want to build the project using shared or
static libraries.

CMAKE_ABSOLUTE_DESTINATION_FILES
List of files which have been installed using an ABSOLUTE DESTINATION
path.

This variable is defined by CMake-generated cmake_install.cmake
scripts. It can be used (read-only) by programs or scripts that source
those install scripts. This is used by some CPack generators (e.g.
RPM).

CMAKE_APPBUNDLE_PATH
Semicolon-separated list of directories specifying a search path for
macOS application bundles used by the find_program(), and find_pack-
age() commands.

CMAKE_AUTOMOC_RELAXED_MODE
Deprecated since version 3.15.

Switch between strict and relaxed automoc mode.

By default, AUTOMOC behaves exactly as described in the documentation
of the AUTOMOC target property. When set to TRUE, it accepts more in-
put and tries to find the correct input file for moc even if it differs
from the documented behavior. In this mode it e.g. also checks
whether a header file is intended to be processed by moc when a
"foo.moc" file has been included.

Relaxed mode has to be enabled for KDE4 compatibility.

CMAKE_BACKWARDS_COMPATIBILITY
Deprecated. See CMake Policy CMP0001 documentation.

CMAKE_BUILD_TYPE
Specifies the build type on single-configuration generators (e.g.
Makefile Generators or Ninja). Typical values include Debug, Release,
RelWithDebInfo and MinSizeRel, but custom build types can also be de-
fined.

This variable is initialized by the first project() or enable_lan-
guage() command called in a project when a new build tree is first cre-
ated. If the CMAKE_BUILD_TYPE environment variable is set, its value
is used. Otherwise, a toolchain-specific default is chosen when a lan-
guage is enabled. The default value is often an empty string, but this
is usually not desirable and one of the other standard build types is
usually more appropriate.

Depending on the situation, the value of this variable may be treated
case-sensitively or case-insensitively. See Build Configurations for
discussion of this and other related topics.

For multi-config generators, see CMAKE_CONFIGURATION_TYPES.

CMAKE_CLANG_VFS_OVERLAY
New in version 3.19.

When cross compiling for windows with clang-cl, this variable can be an
absolute path pointing to a clang virtual file system yaml file, which
will enable clang-cl to resolve windows header names on a case sensi-
tive file system.

CMAKE_CODEBLOCKS_COMPILER_ID
New in version 3.11.

Change the compiler id in the generated CodeBlocks project files.

CodeBlocks uses its own compiler id string which differs from
CMAKE_<LANG>_COMPILER_ID. If this variable is left empty, CMake tries
to recognize the CodeBlocks compiler id automatically. Otherwise the
specified string is used in the CodeBlocks project file. See the Code-
Blocks documentation for valid compiler id strings.

Other IDEs like QtCreator that also use the CodeBlocks generator may
ignore this setting.

CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
New in version 3.10.

Change the way the CodeBlocks generator creates project files.

If this variable evaluates to ON the generator excludes from the
project file any files that are located outside the project root.

CMAKE_CODELITE_USE_TARGETS
New in version 3.7.

Change the way the CodeLite generator creates projectfiles.

If this variable evaluates to ON at the end of the top-level CMake-
Lists.txt file, the generator creates projectfiles based on targets
rather than projects.

CMAKE_COLOR_MAKEFILE
Enables color output when using the Makefile Generators.

When enabled, the generated Makefiles will produce colored output. De-
fault is ON.

CMAKE_CONFIGURATION_TYPES
Specifies the available build types (configurations) on multi-config
generators (e.g. Visual Studio, Xcode, or Ninja Multi-Config). Typical
values include Debug, Release, RelWithDebInfo and MinSizeRel, but cus-
tom build types can also be defined.

This variable is initialized by the first project() or enable_lan-
guage() command called in a project when a new build tree is first cre-
ated. If the CMAKE_CONFIGURATION_TYPES environment variable is set,
its value is used. Otherwise, the default value is generator-specific.

Depending on the situation, the values in this variable may be treated
case-sensitively or case-insensitively. See Build Configurations for
discussion of this and other related topics.

For single-config generators, see CMAKE_BUILD_TYPE.

CMAKE_DEPENDS_IN_PROJECT_ONLY
New in version 3.6.

When set to TRUE in a directory, the build system produced by the Make-
file Generators is set up to only consider dependencies on source files
that appear either in the source or in the binary directories. Changes
to source files outside of these directories will not cause rebuilds.

This should be used carefully in cases where some source files are
picked up through external headers during the build.

CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
Variable for disabling find_package() calls.

Every non-REQUIRED find_package() call in a project can be disabled by
setting the variable CMAKE_DISABLE_FIND_PACKAGE_<PackageName> to TRUE.
This can be used to build a project without an optional package, al-
though that package is installed.

This switch should be used during the initial CMake run. Otherwise if
the package has already been found in a previous CMake run, the vari-
ables which have been stored in the cache will still be there. In that
case it is recommended to remove the cache variables for this package
from the cache using the cache editor or cmake(1) -U

See also the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable.

CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
New in version 3.6.

This cache variable is used by the Eclipse project generator. See
cmake-generators(7).

The Eclipse project generator generates so-called linked resources e.g.
to the subproject root dirs in the source tree or to the source files
of targets. This can be disabled by setting this variable to FALSE.

CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
New in version 3.6.

This cache variable is used by the Eclipse project generator. See
cmake-generators(7).

If this variable is set to TRUE, the Eclipse project generator will
generate an Eclipse project in CMAKE_SOURCE_DIR . This project can then
be used in Eclipse e.g. for the version control functionality.
CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT defaults to FALSE; so nothing is
written into the source directory.

CMAKE_ECLIPSE_MAKE_ARGUMENTS
New in version 3.6.

This cache variable is used by the Eclipse project generator. See
cmake-generators(7).

This variable holds arguments which are used when Eclipse invokes the
make tool. By default it is initialized to hold flags to enable paral-
lel builds (using -j typically).

CMAKE_ECLIPSE_RESOURCE_ENCODING
New in version 3.16.

This cache variable tells the Eclipse CDT4 project generator to set the
resource encoding to the given value in generated project files. If no
value is given, no encoding will be set.

CMAKE_ECLIPSE_VERSION
New in version 3.6.

This cache variable is used by the Eclipse project generator. See
cmake-generators(7).

When using the Eclipse project generator, CMake tries to find the
Eclipse executable and detect the version of it. Depending on the ver-
sion it finds, some features are enabled or disabled. If CMake doesn't
find Eclipse, it assumes the oldest supported version, Eclipse Callisto
(3.2).

CMAKE_ERROR_DEPRECATED
Whether to issue errors for deprecated functionality.

If TRUE, use of deprecated functionality will issue fatal errors. If
this variable is not set, CMake behaves as if it were set to FALSE.

CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
Ask cmake_install.cmake script to error out as soon as a file with ab-
solute INSTALL DESTINATION is encountered.

The fatal error is emitted before the installation of the offending
file takes place. This variable is used by CMake-generated cmake_in-
stall.cmake scripts. If one sets this variable to ON while running the
script, it may get fatal error messages from the script.

CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
New in version 3.15.

If this variable is set to STDERR, STDOUT or NONE then commands in exe-
cute_process() calls will be printed to either stderr or stdout or not
at all.

CMAKE_EXPORT_COMPILE_COMMANDS
New in version 3.5.

Enable/Disable output of compile commands during generation.

If enabled, generates a compile_commands.json file containing the exact
compiler calls for all translation units of the project in ma-
chine-readable form. The format of the JSON file looks like:

[
{
"directory": "/home/user/development/project",
"command": "/usr/bin/c++ ... -c ../foo/foo.cc",
"file": "../foo/foo.cc"
},

...

{
"directory": "/home/user/development/project",
"command": "/usr/bin/c++ ... -c ../foo/bar.cc",
"file": "../foo/bar.cc"
}
]

This is initialized by the CMAKE_EXPORT_COMPILE_COMMANDS environment
variable, and initializes the EXPORT_COMPILE_COMMANDS target property
for all targets.

NOTE:
This option is implemented only by Makefile Generators and the
Ninja. It is ignored on other generators.

This option currently does not work well in combination with the
UNITY_BUILD target property or the CMAKE_UNITY_BUILD variable.

CMAKE_EXPORT_PACKAGE_REGISTRY
New in version 3.15.

Enables the export(PACKAGE) command when CMP0090 is set to NEW.

The export(PACKAGE) command does nothing by default. In some cases it
is desirable to write to the user package registry, so the CMAKE_EX-
PORT_PACKAGE_REGISTRY variable may be set to enable it.

If CMP0090 is not set to NEW this variable does nothing, and the
CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable controls the behavior in-
stead.

See also Disabling the Package Registry.

CMAKE_EXPORT_NO_PACKAGE_REGISTRY
New in version 3.1.

Disable the export(PACKAGE) command when CMP0090 is not set to NEW.

In some cases, for example for packaging and for system wide installa-
tions, it is not desirable to write the user package registry. If the
CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the export(PACK-
AGE) command will do nothing.

If CMP0090 is set to NEW this variable does nothing, and the CMAKE_EX-
PORT_PACKAGE_REGISTRY variable controls the behavior instead.

See also Disabling the Package Registry.

CMAKE_FIND_APPBUNDLE
New in version 3.4.

This variable affects how find_* commands choose between macOS Applica-
tion Bundles and unix-style package components.

On Darwin or systems supporting macOS Application Bundles, the
CMAKE_FIND_APPBUNDLE variable can be set to empty or one of the follow-
ing:

FIRST Try to find application bundles before standard programs. This
is the default on Darwin.

LAST Try to find application bundles after standard programs.

ONLY Only try to find application bundles.

NEVER Never try to find application bundles.

CMAKE_FIND_FRAMEWORK
New in version 3.4.

This variable affects how find_* commands choose between macOS Frame-
works and unix-style package components.

On Darwin or systems supporting macOS Frameworks, the CMAKE_FIND_FRAME-
WORK variable can be set to empty or one of the following:

FIRST Try to find frameworks before standard libraries or headers.
This is the default on Darwin.

LAST Try to find frameworks after standard libraries or headers.

ONLY Only try to find frameworks.

NEVER Never try to find frameworks.

CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
New in version 3.9.

Specify a <suffix> to tell the find_library() command to search in a
lib<suffix> directory before each lib directory that would normally be
searched.

This overrides the behavior of related global properties:

• FIND_LIBRARY_USE_LIB32_PATHS

• FIND_LIBRARY_USE_LIB64_PATHS

• FIND_LIBRARY_USE_LIBX32_PATHS

CMAKE_FIND_LIBRARY_PREFIXES
Prefixes to prepend when looking for libraries.

This specifies what prefixes to add to library names when the find_li-
brary() command looks for libraries. On UNIX systems this is typically
lib, meaning that when trying to find the foo library it will look for
libfoo.

CMAKE_FIND_LIBRARY_SUFFIXES
Suffixes to append when looking for libraries.

This specifies what suffixes to add to library names when the find_li-
brary() command looks for libraries. On Windows systems this is typi-
cally .lib and, depending on the compiler, .dll.a, .a (e.g. GCC and
Clang), so when it tries to find the foo library, it will look for
[<prefix>]foo.lib and/or [<prefix>]foo[.dll].a, depending on the com-
piler used and the <prefix> specified in the CMAKE_FIND_LIBRARY_PRE-
FIXES.

CMAKE_FIND_NO_INSTALL_PREFIX
Exclude the values of the CMAKE_INSTALL_PREFIX and CMAKE_STAGING_PREFIX
variables from CMAKE_SYSTEM_PREFIX_PATH. CMake adds these project-des-
tination prefixes to CMAKE_SYSTEM_PREFIX_PATH by default in order to
support building a series of dependent packages and installing them
into a common prefix. Set CMAKE_FIND_NO_INSTALL_PREFIX to TRUE to sup-
press this behavior.

The CMAKE_SYSTEM_PREFIX_PATH is initialized on the first call to a
project() or enable_language() command. Therefore one must set
CMAKE_FIND_NO_INSTALL_PREFIX before this in order to take effect. A
user may set the variable as a cache entry on the command line to
achieve this.

Note that the prefix(es) may still be searched for other reasons, such
as being the same prefix as the CMake installation, or for being a
built-in system prefix.

CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
New in version 3.1.

Deprecated since version 3.16: Use the CMAKE_FIND_USE_PACKAGE_REGISTRY
variable instead.

By default this variable is not set. If neither CMAKE_FIND_USE_PACK-
AGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY is set, then
find_package() will use the User Package Registry unless the
NO_CMAKE_PACKAGE_REGISTRY option is provided.

CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY is ignored if
CMAKE_FIND_USE_PACKAGE_REGISTRY is set.

In some cases, for example to locate only system wide installations, it
is not desirable to use the User Package Registry when searching for
packages. If the CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable is
TRUE, all the find_package() commands will skip the User Package Reg-
istry as if they were called with the NO_CMAKE_PACKAGE_REGISTRY argu-
ment.

See also Disabling the Package Registry.

CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
New in version 3.1.

Deprecated since version 3.16: Use the CMAKE_FIND_USE_SYSTEM_PACK-
AGE_REGISTRY variable instead.

By default this variable is not set. If neither CMAKE_FIND_USE_SYS-
TEM_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
is set, then find_package() will use the System Package Registry unless
the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is provided.

CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY is ignored if
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY is set.

In some cases, it is not desirable to use the System Package Registry
when searching for packages. If the
CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable is TRUE, all the
find_package() commands will skip the System Package Registry as if
they were called with the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY argument.

See also Disabling the Package Registry.

CMAKE_FIND_PACKAGE_PREFER_CONFIG
New in version 3.15.

Tell find_package() to try "Config" mode before "Module" mode if no
mode was specified.

The command find_package() operates without an explicit mode when the
reduced signature is used without the MODULE option. In this case, by
default, CMake first tries Module mode by searching for a
Find<pkg>.cmake module. If it fails, CMake then searches for the pack-
age using Config mode.

Set CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to tell find_package() to
first search using Config mode before falling back to Module mode.

This variable may be useful when a developer has compiled a custom ver-
sion of a common library and wishes to link it to a dependent project.
If this variable is set to TRUE, it would prevent a dependent project's
call to find_package() from selecting the default library located by
the system's Find<pkg>.cmake module before finding the developer's cus-
tom built library.

Once this variable is set, it is the responsibility of the exported
<pkg>Config.cmake files to provide the same result variables as the
Find<pkg>.cmake modules so that dependent projects can use them inter-
changeably.

CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
New in version 3.14.

Set to TRUE to tell find_package() calls to resolve symbolic links in
the value of <PackageName>_DIR.

This is helpful in use cases where the package search path points at a
proxy directory in which symlinks to the real package locations appear.
This is not enabled by default because there are also common use cases
in which the symlinks should be preserved.

CMAKE_FIND_PACKAGE_WARN_NO_MODULE
Tell find_package() to warn if called without an explicit mode.

If find_package() is called without an explicit mode option (MODULE,
CONFIG, or NO_MODULE) and no Find<pkg>.cmake module is in CMAKE_MOD-
ULE_PATH then CMake implicitly assumes that the caller intends to
search for a package configuration file. If no package configuration
file is found then the wording of the failure message must account for
both the case that the package is really missing and the case that the
project has a bug and failed to provide the intended Find module. If
instead the caller specifies an explicit mode option then the failure
message can be more specific.

Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_package() to
warn when it implicitly assumes Config mode. This helps developers en-
force use of an explicit mode in all calls to find_package() within a
project.

This variable has no effect if CMAKE_FIND_PACKAGE_PREFER_CONFIG is set
to TRUE.

CMAKE_FIND_ROOT_PATH
Semicolon-separated list of root paths to search on the filesystem.

This variable is most useful when cross-compiling. CMake uses the paths
in this list as alternative roots to find filesystem items with
find_package(), find_library() etc.

CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYS-
ROOT are used by find_file() and find_path().

If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
be ignored and only the host system root will be used. If set to BOTH,
then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
be searched.

CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYS-
ROOT are used by find_library().

CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYS-
ROOT are used by find_package().

CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYS-
ROOT are used by find_program().

CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by cmake-specific environment variables:

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of TRUE. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_SYS-
TEM_PATH, CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH, CMAKE_FIND_USE_SYS-
TEM_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FIND_USE_CMAKE_PATH
New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by cmake-specific cache variables:

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of TRUE. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_SYSTEM_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACK-
AGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by platform-specific cmake variables:

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of TRUE. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH, CMAKE_FIND_USE_SYS-
TEM_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FIND_USE_PACKAGE_REGISTRY
New in version 3.16.

Controls the default behavior of the find_package() command for whether
or not to search paths provided by the User Package Registry.

By default this variable is not set and the behavior will fall back to
that determined by the deprecated CMAKE_FIND_PACKAGE_NO_PACKAGE_REG-
ISTRY variable. If that is also not set, then find_package() will use
the User Package Registry unless the NO_CMAKE_PACKAGE_REGISTRY option
is provided.

This variable takes precedence over CMAKE_FIND_PACKAGE_NO_PACKAGE_REG-
ISTRY when both are set.

In some cases, for example to locate only system wide installations, it
is not desirable to use the User Package Registry when searching for
packages. If the CMAKE_FIND_USE_PACKAGE_REGISTRY variable is FALSE,
all the find_package() commands will skip the User Package Registry as
if they were called with the NO_CMAKE_PACKAGE_REGISTRY argument.

See also Disabling the Package Registry and the
CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_SYSTEM_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FIND_USE_PACKAGE_ROOT_PATH
New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by <PackageName>_ROOT variables:

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

By default this variable is not set, which is equivalent to it having a
value of TRUE. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_SYSTEM_EN-
VIRONMENT_PATH, CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_REGISTRY variables.

CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
New in version 3.16.

Controls the default behavior of the following commands for whether or
not to search paths provided by standard system environment variables:

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

This is useful in cross-compiling environments.

By default this variable is not set, which is equivalent to it having a
value of TRUE. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_PACK-
AGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and CMAKE_FIND_USE_SYS-
TEM_PACKAGE_REGISTRY variables.

CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
New in version 3.16.

Controls searching the System Package Registry by the find_package()
command.

By default this variable is not set and the behavior will fall back to
that determined by the deprecated CMAKE_FIND_PACKAGE_NO_SYSTEM_PACK-
AGE_REGISTRY variable. If that is also not set, then find_package()
will use the System Package Registry unless the NO_CMAKE_SYSTEM_PACK-
AGE_REGISTRY option is provided.

This variable takes precedence over CMAKE_FIND_PACKAGE_NO_SYSTEM_PACK-
AGE_REGISTRY when both are set.

In some cases, for example to locate only user specific installations,
it is not desirable to use the System Package Registry when searching
for packages. If the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable is
FALSE, all the find_package() commands will skip the System Package
Registry as if they were called with the NO_CMAKE_SYSTEM_PACKAGE_REG-
ISTRY argument.

See also Disabling the Package Registry.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRON-
MENT_PATH, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_SYSTEM_EN-
VIRONMENT_PATH, CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FRAMEWORK_PATH
Semicolon-separated list of directories specifying a search path for
macOS frameworks used by the find_library(), find_package(),
find_path(), and find_file() commands.

CMAKE_IGNORE_PATH
Semicolon-separated list of directories to be ignored by the find_pro-
gram(), find_library(), find_file(), and find_path() commands. This is
useful in cross-compiling environments where some system directories
contain incompatible but possibly linkable libraries. For example, on
cross-compiled cluster environments, this allows a user to ignore di-
rectories containing libraries meant for the front-end machine.

By default this is empty; it is intended to be set by the project.
Note that CMAKE_IGNORE_PATH takes a list of directory names, not a list
of prefixes. To ignore paths under prefixes (bin, include, lib, etc.),
specify them explicitly.

See also the CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH, CMAKE_INCLUDE_PATH,
and CMAKE_PROGRAM_PATH variables.

CMAKE_INCLUDE_DIRECTORIES_BEFORE
Whether to append or prepend directories by default in include_directo-
ries().

This variable affects the default behavior of the include_directories()
command. Setting this variable to ON is equivalent to using the BEFORE
option in all uses of that command.

CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
Whether to force prepending of project include directories.

This variable affects the order of include directories generated in
compiler command lines. If set to ON, it causes the CMAKE_SOURCE_DIR
and the CMAKE_BINARY_DIR to appear first.

CMAKE_INCLUDE_PATH
Semicolon-separated list of directories specifying a search path for
the find_file() and find_path() commands. By default it is empty, it
is intended to be set by the project. See also CMAKE_SYSTEM_IN-
CLUDE_PATH and CMAKE_PREFIX_PATH.

CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
Default component used in install() commands.

If an install() command is used without the COMPONENT argument, these
files will be grouped into a default component. The name of this de-
fault install component will be taken from this variable. It defaults
to Unspecified.

CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
New in version 3.11.

Default permissions for directories created implicitly during installa-
tion of files by install() and file(INSTALL).

If make install is invoked and directories are implicitly created they
get permissions set by CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
variable or platform specific default permissions if the variable is
not set.

Implicitly created directories are created if they are not explicitly
installed by install() command but are needed to install a file on a
certain path. Example of such locations are directories created due to
the setting of CMAKE_INSTALL_PREFIX.

Expected content of the CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
variable is a list of permissions that can be used by install() command
PERMISSIONS section.

Example usage:

set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
OWNER_READ
OWNER_WRITE
OWNER_EXECUTE
GROUP_READ
)

CMAKE_INSTALL_MESSAGE
New in version 3.1.

Specify verbosity of installation script code generated by the in-
stall() command (using the file(INSTALL) command). For paths that are
newly installed or updated, installation may print lines like:

-- Installing: /some/destination/path

For paths that are already up to date, installation may print lines
like:

-- Up-to-date: /some/destination/path

The CMAKE_INSTALL_MESSAGE variable may be set to control which messages
are printed:

ALWAYS Print both Installing and Up-to-date messages.

LAZY Print Installing but not Up-to-date messages.

NEVER Print neither Installing nor Up-to-date messages.

Other values have undefined behavior and may not be diagnosed.

If this variable is not set, the default behavior is ALWAYS.

CMAKE_INSTALL_PREFIX
Install directory used by install().

If make install is invoked or INSTALL is built, this directory is
prepended onto all install directories. This variable defaults to
/usr/local on UNIX and c:/Program Files/${PROJECT_NAME} on Windows.
See CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT for how a project might
choose its own default.

On UNIX one can use the DESTDIR mechanism in order to relocate the
whole installation. See DESTDIR for more information.

The installation prefix is also added to CMAKE_SYSTEM_PREFIX_PATH so
that find_package(), find_program(), find_library(), find_path(), and
find_file() will search the prefix for other software.

NOTE:
Use the GNUInstallDirs module to provide GNU-style options for the
layout of directories within the installation.

CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
New in version 3.7.1.

CMake sets this variable to a TRUE value when the CMAKE_INSTALL_PREFIX
has just been initialized to its default value, typically on the first
run of CMake within a new build tree. This can be used by project code
to change the default without overriding a user-provided value:

if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
endif()

CMAKE_LIBRARY_PATH
Semicolon-separated list of directories specifying a search path for
the find_library() command. By default it is empty, it is intended to
be set by the project. See also CMAKE_SYSTEM_LIBRARY_PATH and
CMAKE_PREFIX_PATH.

CMAKE_LINK_DIRECTORIES_BEFORE
New in version 3.13.

Whether to append or prepend directories by default in link_directo-
ries().

This variable affects the default behavior of the link_directories()
command. Setting this variable to ON is equivalent to using the BEFORE
option in all uses of that command.

CMAKE_MFC_FLAG
Use the MFC library for an executable or dll.

Enables the use of the Microsoft Foundation Classes (MFC). It should
be set to 1 for the static MFC library, and 2 for the shared MFC li-
brary. This is used in Visual Studio project files.

Usage example:

add_definitions(-D_AFXDLL)
set(CMAKE_MFC_FLAG 2)
add_executable(CMakeSetup WIN32 ${SRCS})

Contents of CMAKE_MFC_FLAG may use generator expressions.

CMAKE_MAXIMUM_RECURSION_DEPTH
New in version 3.14.

Maximum recursion depth for CMake scripts. It is intended to be set on
the command line with -DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>, or within
CMakeLists.txt by projects that require a large recursion depth.
Projects that set this variable should provide the user with a way to
override it. For example:

# About to perform deeply recursive actions
if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
endif()

If it is not set, or is set to a non-integer value, a sensible default
limit is used. If the recursion limit is reached, the script terminates
immediately with a fatal error.

Calling any of the following commands increases the recursion depth:

• include()

• find_package()

• add_subdirectory()

• try_compile()

• ctest_read_custom_files()

• ctest_run_script() (unless NEW_PROCESS is specified)

• User-defined function()'s and macro()'s (note that function() and
macro() themselves don't increase recursion depth)

• Reading or writing variables that are being watched by a vari-
able_watch()

CMAKE_MESSAGE_CONTEXT
New in version 3.17.

When enabled by the cmake --log-context command line option or the
CMAKE_MESSAGE_CONTEXT_SHOW variable, the message() command converts the
CMAKE_MESSAGE_CONTEXT list into a dot-separated string surrounded by
square brackets and prepends it to each line for messages of log levels
NOTICE and below.

For logging contexts to work effectively, projects should generally AP-
PEND and POP_BACK an item to the current value of CMAKE_MESSAGE_CONTEXT
rather than replace it. Projects should not assume the message context
at the top of the source tree is empty, as there are scenarios where
the context might have already been set (e.g. hierarchical projects).

WARNING:
Valid context names are restricted to anything that could be used as
a CMake variable name. All names that begin with an underscore or
the string cmake_ are also reserved for use by CMake and should not
be used by projects.

Example:

function(bar)
list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
message(VERBOSE "bar VERBOSE message")
endfunction()

function(baz)
list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
message(DEBUG "baz DEBUG message")
endfunction()

function(foo)
list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
bar()
message(TRACE "foo TRACE message")
baz()
endfunction()

list(APPEND CMAKE_MESSAGE_CONTEXT "top")

message(VERBOSE "Before `foo`")
foo()
message(VERBOSE "After `foo`")

list(POP_BACK CMAKE_MESSAGE_CONTEXT)

Which results in the following output:

-- [top] Before `foo`
-- [top.foo.bar] bar VERBOSE message
-- [top.foo] foo TRACE message
-- [top.foo.baz] baz DEBUG message
-- [top] After `foo`

CMAKE_MESSAGE_CONTEXT_SHOW
New in version 3.17.

Setting this variable to true enables showing a context with each line
logged by the message() command (see CMAKE_MESSAGE_CONTEXT for how the
context itself is specified).

This variable is an alternative to providing the --log-context option
on the cmake command line. Whereas the command line option will apply
only to that one CMake run, setting CMAKE_MESSAGE_CONTEXT_SHOW to true
as a cache variable will ensure that subsequent CMake runs will con-
tinue to show the message context.

Projects should not set CMAKE_MESSAGE_CONTEXT_SHOW. It is intended for
users so that they may control whether or not to include context with
messages.

CMAKE_MESSAGE_INDENT
New in version 3.16.

The message() command joins the strings from this list and for log lev-
els of NOTICE and below, it prepends the resultant string to each line
of the message.

Example:

list(APPEND listVar one two three)

message(VERBOSE [[Collected items in the "listVar":]])
list(APPEND CMAKE_MESSAGE_INDENT " ")

foreach(item IN LISTS listVar)
message(VERBOSE ${item})
endforeach()

list(POP_BACK CMAKE_MESSAGE_INDENT)
message(VERBOSE "No more indent")

Which results in the following output:

-- Collected items in the "listVar":
-- one
-- two
-- three
-- No more indent

CMAKE_MESSAGE_LOG_LEVEL
New in version 3.17.

When set, this variable specifies the logging level used by the mes-
sage() command. Valid values are the same as those for the --log-level
command line option of the cmake(1) program. If this variable is set
and the --log-level command line option is given, the command line op-
tion takes precedence.

The main advantage to using this variable is to make a log level per-
sist between CMake runs. Setting it as a cache variable will ensure
that subsequent CMake runs will continue to use the chosen log level.

Projects should not set this variable, it is intended for users so that
they may control the log level according to their own needs.

CMAKE_MODULE_PATH
Semicolon-separated list of directories specifying a search path for
CMake modules to be loaded by the include() or find_package() commands
before checking the default modules that come with CMake. By default
it is empty, it is intended to be set by the project.

CMAKE_POLICY_DEFAULT_CMP<NNNN>
Default for CMake Policy CMP<NNNN> when it is otherwise left unset.

Commands cmake_minimum_required(VERSION) and cmake_policy(VERSION) by
default leave policies introduced after the given version unset. Set
CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to specify the default for
policy CMP<NNNN>, where <NNNN> is the policy number.

This variable should not be set by a project in CMake code as a way to
set its own policies; use cmake_policy(SET) instead. This variable is
meant to externally set policies for which a project has not itself
been updated:

• Users running CMake may set this variable in the cache (e.g. -DC-
MAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>). Set it to OLD to quiet a
policy warning while using old behavior or to NEW to try building the
project with new behavior.

• Projects may set this variable before a call to add_subdirectory()
that adds a third-party project in order to set its policies without
modifying third-party code.

CMAKE_POLICY_WARNING_CMP<NNNN>
Explicitly enable or disable the warning when CMake Policy CMP<NNNN>
has not been set explicitly by cmake_policy() or implicitly by
cmake_minimum_required(). This is meaningful only for the policies that
do not warn by default:

• CMAKE_POLICY_WARNING_CMP0025 controls the warning for policy CMP0025.

• CMAKE_POLICY_WARNING_CMP0047 controls the warning for policy CMP0047.

• CMAKE_POLICY_WARNING_CMP0056 controls the warning for policy CMP0056.

• CMAKE_POLICY_WARNING_CMP0060 controls the warning for policy CMP0060.

• CMAKE_POLICY_WARNING_CMP0065 controls the warning for policy CMP0065.

• CMAKE_POLICY_WARNING_CMP0066 controls the warning for policy CMP0066.

• CMAKE_POLICY_WARNING_CMP0067 controls the warning for policy CMP0067.

• CMAKE_POLICY_WARNING_CMP0082 controls the warning for policy CMP0082.

• CMAKE_POLICY_WARNING_CMP0089 controls the warning for policy CMP0089.

• CMAKE_POLICY_WARNING_CMP0102 controls the warning for policy CMP0102.

• CMAKE_POLICY_WARNING_CMP0112 controls the warning for policy CMP0112.

• CMAKE_POLICY_WARNING_CMP0116 controls the warning for policy CMP0116.

• CMAKE_POLICY_WARNING_CMP0126 controls the warning for policy CMP0126.

• CMAKE_POLICY_WARNING_CMP0128 controls the warning for policy CMP0128.

This variable should not be set by a project in CMake code. Project
developers running CMake may set this variable in their cache to enable
the warning (e.g. -DCMAKE_POLICY_WARNING_CMP<NNNN>=ON). Alternatively,
running cmake(1) with the --debug-output, --trace, or --trace-expand
option will also enable the warning.

CMAKE_PREFIX_PATH
Semicolon-separated list of directories specifying installation pre-
fixes to be searched by the find_package(), find_program(), find_li-
brary(), find_file(), and find_path() commands. Each command will add
appropriate subdirectories (like bin, lib, or include) as specified in
its own documentation.

By default this is empty. It is intended to be set by the project.

See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH, CMAKE_LI-
BRARY_PATH, CMAKE_PROGRAM_PATH, and CMAKE_IGNORE_PATH.

CMAKE_PROGRAM_PATH
Semicolon-separated list of directories specifying a search path for
the find_program() command. By default it is empty, it is intended to
be set by the project. See also CMAKE_SYSTEM_PROGRAM_PATH and
CMAKE_PREFIX_PATH.

CMAKE_PROJECT_INCLUDE
New in version 3.15.

A CMake language file or module to be included as the last step of all
project() command calls. This is intended for injecting custom code
into project builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE and CMAKE_PROJECT_IN-
CLUDE_BEFORE variables.

CMAKE_PROJECT_INCLUDE_BEFORE
New in version 3.15.

A CMake language file or module to be included as the first step of all
project() command calls. This is intended for injecting custom code
into project builds without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE and CMAKE_PROJECT_INCLUDE
variables.

CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
A CMake language file or module to be included as the last step of any
project() command calls that specify <PROJECT-NAME> as the project
name. This is intended for injecting custom code into project builds
without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
CMAKE_PROJECT_INCLUDE and CMAKE_PROJECT_INCLUDE_BEFORE variables.

CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
New in version 3.17.

A CMake language file or module to be included as the first step of any
project() command calls that specify <PROJECT-NAME> as the project
name. This is intended for injecting custom code into project builds
without modifying their source.

See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, CMAKE_PROJECT_IN-
CLUDE and CMAKE_PROJECT_INCLUDE_BEFORE variables.

CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>
New in version 3.22.

Variable for making find_package() call REQUIRED.

Every non-REQUIRED find_package() call in a project can be turned into
REQUIRED by setting the variable CMAKE_REQUIRE_FIND_PACKAGE_<Package-
Name> to TRUE. This can be used to assert assumptions about build en-
vironment and to ensure the build will fail early if they do not hold.

See also the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable.

CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
Don't make the install target depend on the all target.

By default, the install target depends on the all target. This has the
effect, that when make install is invoked or INSTALL is built, first
the all target is built, then the installation starts. If
CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is set to TRUE, this dependency is
not created, so the installation process will start immediately, inde-
pendent from whether the project has been completely built or not.

CMAKE_STAGING_PREFIX
This variable may be set to a path to install to when cross-compiling.
This can be useful if the path in CMAKE_SYSROOT is read-only, or other-
wise should remain pristine.

The CMAKE_STAGING_PREFIX location is also used as a search prefix by
the find_* commands. This can be controlled by setting the
CMAKE_FIND_NO_INSTALL_PREFIX variable.

If any RPATH/RUNPATH entries passed to the linker contain the
CMAKE_STAGING_PREFIX, the matching path fragments are replaced with the
CMAKE_INSTALL_PREFIX.

CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
New in version 3.8.

This variable contains a list of env vars as a list of tokens with the
syntax var=value.

Example:

set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
"FOO=FOO1\;FOO2\;FOON"
"BAR=BAR1\;BAR2\;BARN"
"BAZ=BAZ1\;BAZ2\;BAZN"
"FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN"
"VALID="
)

In case of malformed variables CMake will fail:

set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
"THIS_IS_NOT_VALID"
)

CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
New in version 3.8.

If this variable evaluates to ON at the end of the top-level CMake-
Lists.txt file, the Sublime Text 2 extra generator excludes the build
tree from the .sublime-project if it is inside the source tree.

CMAKE_SUPPRESS_REGENERATION
New in version 3.12.

If CMAKE_SUPPRESS_REGENERATION is OFF, which is default, then CMake
adds a special target on which all other targets depend that checks the
build system and optionally re-runs CMake to regenerate the build sys-
tem when the target specification source changes.

If this variable evaluates to ON at the end of the top-level CMake-
Lists.txt file, CMake will not add the regeneration target to the build
system or perform any build system checks.

CMAKE_SYSROOT
Path to pass to the compiler in the --sysroot flag.

The CMAKE_SYSROOT content is passed to the compiler in the --sysroot
flag, if supported. The path is also stripped from the RPATH/RUNPATH
if necessary on installation. The CMAKE_SYSROOT is also used to prefix
paths searched by the find_* commands.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

See also the CMAKE_SYSROOT_COMPILE and CMAKE_SYSROOT_LINK variables.

CMAKE_SYSROOT_COMPILE
New in version 3.9.

Path to pass to the compiler in the --sysroot flag when compiling
source files. This is the same as CMAKE_SYSROOT but is used only for
compiling sources and not linking.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

CMAKE_SYSROOT_LINK
New in version 3.9.

Path to pass to the compiler in the --sysroot flag when linking. This
is the same as CMAKE_SYSROOT but is used only for linking and not com-
piling sources.

This variable may only be set in a toolchain file specified by the
CMAKE_TOOLCHAIN_FILE variable.

CMAKE_SYSTEM_APPBUNDLE_PATH
New in version 3.4.

Search path for macOS application bundles used by the find_program(),
and find_package() commands. By default it contains the standard di-
rectories for the current system. It is not intended to be modified by
the project, use CMAKE_APPBUNDLE_PATH for this.

CMAKE_SYSTEM_FRAMEWORK_PATH
New in version 3.4.

Search path for macOS frameworks used by the find_library(), find_pack-
age(), find_path(), and find_file() commands. By default it contains
the standard directories for the current system. It is not intended to
be modified by the project, use CMAKE_FRAMEWORK_PATH for this.

CMAKE_SYSTEM_IGNORE_PATH
Semicolon-separated list of directories to be ignored by the find_pro-
gram(), find_library(), find_file(), and find_path() commands. This is
useful in cross-compiling environments where some system directories
contain incompatible but possibly linkable libraries. For example, on
cross-compiled cluster environments, this allows a user to ignore di-
rectories containing libraries meant for the front-end machine.

By default this contains a list of directories containing incompatible
binaries for the host system. See the CMAKE_IGNORE_PATH variable that
is intended to be set by the project.

See also the CMAKE_SYSTEM_PREFIX_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
CMAKE_SYSTEM_INCLUDE_PATH, and CMAKE_SYSTEM_PROGRAM_PATH variables.

CMAKE_SYSTEM_INCLUDE_PATH
Semicolon-separated list of directories specifying a search path for
the find_file() and find_path() commands. By default this contains the
standard directories for the current system. It is not intended to be
modified by the project; use CMAKE_INCLUDE_PATH for this. See also
CMAKE_SYSTEM_PREFIX_PATH.

CMAKE_SYSTEM_LIBRARY_PATH
Semicolon-separated list of directories specifying a search path for
the find_library() command. By default this contains the standard di-
rectories for the current system. It is not intended to be modified by
the project; use CMAKE_LIBRARY_PATH for this. See also CMAKE_SYS-
TEM_PREFIX_PATH.

CMAKE_SYSTEM_PREFIX_PATH
Semicolon-separated list of directories specifying installation pre-
fixes to be searched by the find_package(), find_program(), find_li-
brary(), find_file(), and find_path() commands. Each command will add
appropriate subdirectories (like bin, lib, or include) as specified in
its own documentation.

By default this contains the system directories for the current system,
the CMAKE_INSTALL_PREFIX, and the CMAKE_STAGING_PREFIX. The installa-
tion and staging prefixes may be excluded by setting the
CMAKE_FIND_NO_INSTALL_PREFIX variable.

The system directories that are contained in CMAKE_SYSTEM_PREFIX_PATH
are locations that typically include installed software. An example be-
ing /usr/local for UNIX based platforms. In addition to standard plat-
form locations, CMake will also add values to CMAKE_SYSTEM_PREFIX_PATH
based on environment variables. The environment variables and search
locations that CMake uses may evolve over time, as platforms and their
conventions also evolve. The following provides an indicative list of
environment variables and locations that CMake searches, but they are
subject to change:

CrayLinuxEnvironment:

• ENV{SYSROOT_DIR}/

• ENV{SYSROOT_DIR}/usr

• ENV{SYSROOT_DIR}/usr/local

Darwin:

• ENV{SDKROOT}/usr When CMAKE_OSX_SYSROOT is not explicitly
specified.

OpenBSD:

• ENV{LOCALBASE}

Unix:

• ENV{CONDA_PREFIX} when using a conda compiler

Windows:

• ENV{ProgramW6432}

• ENV{ProgramFiles}

• ENV{ProgramFiles(x86)}

• ENV{SystemDrive}/Program Files

• ENV{SystemDrive}/Program Files (x86)

CMAKE_SYSTEM_PREFIX_PATH is not intended to be modified by the project;
use CMAKE_PREFIX_PATH for this.

See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
CMAKE_SYSTEM_PROGRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.

CMAKE_SYSTEM_PROGRAM_PATH
Semicolon-separated list of directories specifying a search path for
the find_program() command. By default this contains the standard di-
rectories for the current system. It is not intended to be modified by
the project; use CMAKE_PROGRAM_PATH for this. See also CMAKE_SYS-
TEM_PREFIX_PATH.

CMAKE_TLS_CAINFO
Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com-
mands' TLS_CAINFO options. It is unset by default.

This variable is also used by the ExternalProject and FetchContent mod-
ules for internal calls to file(DOWNLOAD).

CMAKE_TLS_VERIFY
Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com-
mands' TLS_VERIFY options. If not set, the default is off.

This variable is also used by the ExternalProject and FetchContent mod-
ules for internal calls to file(DOWNLOAD).

TLS verification can help provide confidence that one is connecting to
the desired server. When downloading known content, one should also
use file hashes to verify it.

set(CMAKE_TLS_VERIFY TRUE)

CMAKE_USER_MAKE_RULES_OVERRIDE
Specify a CMake file that overrides platform information.

CMake loads the specified file while enabling support for each language
from either the project() or enable_language() commands. It is loaded
after CMake's builtin compiler and platform information modules have
been loaded but before the information is used. The file may set plat-
form information variables to override CMake's defaults.

This feature is intended for use only in overriding information vari-
ables that must be set before CMake builds its first test project to
check that the compiler for a language works. It should not be used to
load a file in cases that a normal include() will work. Use it only as
a last resort for behavior that cannot be achieved any other way. For
example, one may set the CMAKE_C_FLAGS_INIT variable to change the de-
fault value used to initialize the CMAKE_C_FLAGS variable before it is
cached. The override file should NOT be used to set anything that
could be set after languages are enabled, such as variables like
CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries.
Information set in the file will be used for try_compile() and
try_run() builds too.

CMAKE_WARN_DEPRECATED
Whether to issue warnings for deprecated functionality.

If not FALSE, use of deprecated functionality will issue warnings. If
this variable is not set, CMake behaves as if it were set to TRUE.

When running cmake(1), this option can be enabled with the -Wdeprecated
option, or disabled with the -Wno-deprecated option.

CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
Ask cmake_install.cmake script to warn each time a file with absolute
INSTALL DESTINATION is encountered.

This variable is used by CMake-generated cmake_install.cmake scripts.
If one sets this variable to ON while running the script, it may get
warning messages from the script.

CMAKE_XCODE_GENERATE_SCHEME
New in version 3.9.

If enabled, the Xcode generator will generate schema files. These are
useful to invoke analyze, archive, build-for-testing and test actions
from the command line.

This variable initializes the XCODE_GENERATE_SCHEME target property on
all targets.

CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
New in version 3.11.

If enabled, the Xcode generator will generate only a single Xcode
project file for the topmost project() command instead of generating
one for every project() command.

This could be useful to speed up the CMake generation step for large
projects and to work-around a bug in the ZERO_CHECK logic.

CMAKE_XCODE_LINK_BUILD_PHASE_MODE
New in version 3.19.

This variable is used to initialize the XCODE_LINK_BUILD_PHASE_MODE
property on targets. It affects the methods that the Xcode generator
uses to link different kinds of libraries. Its default value is NONE.

CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
New in version 3.13.

Whether to enable Address Sanitizer in the Diagnostics section of the
generated Xcode scheme.

This variable initializes the XCODE_SCHEME_ADDRESS_SANITIZER property
on all targets.