Ubuntu Manpage: cmake-variables - CMake Variables Reference

name
variables that provide information
variables that change behavior
variables that describe the system
variables that control the build
variables for languages
variables for ctest
variables for cpack
variable expansion operators
internal variables
deprecated variables that provide information
deprecated variables that change behavior
deprecated variables that describe the system
deprecated variables that control the build
deprecated variables for languages
deprecated variables for ctest
copyright

Provided by: cmake-data_3.31.5-2ubuntu3_all

NAME

       cmake-variables - CMake Variables Reference

       This  page  documents  variables  that are provided by CMake or have meaning 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 command 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 cmake -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
This variable is used internally by CMake, and may not be set during the first configuration of a build
tree. When it is set, it has the same value as CMAKE_BINARY_DIR. Use that variable instead.

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 expression. 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-configuration output subdirectory. On Makefile Generators this evaluates to . because there is only
one configuration in a build tree. Example values:

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

Since these values are evaluated by the native build system, this variable 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
Added in version 3.13.

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

This is the full path to the CPack executable cpack(1) that can be used for custom commands or tests to
invoke CPack commands.

CMAKE_CROSSCOMPILING
This variable is set by CMake to indicate whether it is cross compiling, but note limitations 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, if not manually set, it will be given the
same value as CMAKE_HOST_SYSTEM_NAME, 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 scenarios. Rather than relying on CMAKE_SYSTEM_NAME to select the
target platform, Apple device builds use CMAKE_OSX_SYSROOT to select the appropriate SDK, which
indirectly determines the target platform. Furthermore, 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_CROSSCOMPILING is not recommended for projects targeting Apple devices.

CMAKE_CROSSCOMPILING_EMULATOR
Added 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.

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

Added in version 3.28: This variable can be initialized via an CMAKE_CROSSCOMPILING_EMULATOR environment
variable.

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

This variable is also used as the default value for the CROSSCOMPILING_EMULATOR target property of
executables. However, while generator expressions are supported by the target property (since CMake
3.29), they are not supported by this variable's try_run() functionality.

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

This is the full path to the CTest executable ctest(1) that can be used for custom commands or tests to
invoke CTest commands.

CMAKE_CURRENT_BINARY_DIR
The path to the binary directory currently being processed.

This is the full path to the build directory that is currently being processed by cmake. Each directory
added by add_subdirectory() will create 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 cmake -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
Added 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_FUNCTION_LIST_FILE and
CMAKE_CURRENT_FUNCTION_LIST_LINE.

CMAKE_CURRENT_FUNCTION_LIST_DIR
Added 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 variables. 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 typically 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 eliminates 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
Added 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
Added 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 always be set to the directory where
the listfile which is currently being processed (CMAKE_CURRENT_LIST_FILE) is located. The value has
dynamic 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 previous value. Therefore the value of the variable inside a macro or function 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 function definition.

VARIABLES THAT CHANGE BEHAVIOR

BUILD_SHARED_LIBS
Tell add_library() to default to SHARED libraries, instead of STATIC libraries, when called with no
explicit library type.

Calls to add_library() without any explicit library type check the current BUILD_SHARED_LIBS variable
value. If it is true, then the default library type is SHARED. Otherwise, the default is STATIC.

For example, the code:

add_library(example ${sources})

behaves as if written

if(BUILD_SHARED_LIBS)
add_library(example SHARED ${sources})
else()
add_library(example STATIC ${sources})
endif()

CMake does not define BUILD_SHARED_LIBS by default, but projects often create a cache entry for it using
the option() command:

option(BUILD_SHARED_LIBS "Build using shared libraries" ON)

This provides a switch that users can control, e.g., with cmake -D. If adding such an option to the
project, do so in the top level CMakeLists.txt file, before any add_library() calls. Note that if
bringing external dependencies directly into the build, such as with FetchContent or a direct call to
add_subdirectory(), and one of those dependencies has such a call to option(BUILD_SHARED_LIBS ...), the
top level project must also call option(BUILD_SHARED_LIBS ...) before bringing in its dependencies.
Failure to do so can lead to different behavior between the first and subsequent CMake runs.

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_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
Added in version 3.27.

Whether to enable the DEPENDS_EXPLICIT_ONLY option by default in add_custom_command().

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

See also the following variables:

• CMAKE_IGNORE_PREFIX_PATH

• CMAKE_SYSTEM_IGNORE_PATH

• CMAKE_PREFIX_PATH

• CMAKE_LIBRARY_PATH

• CMAKE_INCLUDE_PATH

• CMAKE_PROGRAM_PATH

CMAKE_IGNORE_PREFIX_PATH
Added in version 3.23.

Semicolon-separated list of search prefixes to be ignored by the find_program(), find_library(),
find_file(), and find_path() commands. The prefixes are also ignored by the Config mode of the
find_package() command (Module mode is unaffected). To ignore specific directories instead, see
CMAKE_IGNORE_PATH.

By default, CMAKE_IGNORE_PREFIX_PATH is empty. It is intended to be set by the project or the end user.

See also the following variables:

• CMAKE_IGNORE_PATH

• CMAKE_SYSTEM_IGNORE_PREFIX_PATH

• CMAKE_PREFIX_PATH

• CMAKE_LIBRARY_PATH

• CMAKE_INCLUDE_PATH

• CMAKE_PROGRAM_PATH

CMAKE_INCLUDE_DIRECTORIES_BEFORE
Whether to append or prepend directories by default in include_directories().

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.

There is also an environment variable CMAKE_INCLUDE_PATH, which is used as an additional list of search
directories.

See also CMAKE_SYSTEM_INCLUDE_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 default install component will be taken from this variable. It
defaults to Unspecified.

CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
Added in version 3.11.

Default permissions for directories created implicitly during installation 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
Added in version 3.1.

Specify verbosity of installation script code generated by the install() 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 as follows:

• Added in version 3.29: If the CMAKE_INSTALL_PREFIX environment variable is set, its value is used as
default for this variable.

• c:/Program Files/${PROJECT_NAME} on Windows.

• /usr/local on UNIX platforms.

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 to a staging area.
See the DESTDIR environment variable 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. This behavior can
be disabled by setting the CMAKE_FIND_NO_INSTALL_PREFIX to TRUE before the first project() invocation.

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

The CMAKE_INSTALL_PREFIX may be defined when configuring a build tree to set its installation prefix.
Or, when using the cmake(1) command-line tool's --install mode, one may specify a different prefix using
the --prefix option:

cmake --install . --prefix /my/install/prefix

CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
Added 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 and the CMAKE_INSTALL_PREFIX
environment variable is not set on the first run of CMake. 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_property(CACHE CMAKE_INSTALL_PREFIX PROPERTY VALUE "/my/default")
endif()

CMAKE_KATE_FILES_MODE
Added in version 3.27.

This cache variable is used by the Kate project generator and controls to what mode the files entry in
the project file will be set. See cmake-generators(7).

Possible values are AUTO, SVN, GIT, HG, FOSSIL and LIST.

When set to LIST, CMake will put the list of source files known to CMake in the project file. When set
to SVN, GIT, HG or FOSSIL, CMake will set the generated project accordingly to Subversion, git, Mercurial
or Fossil, and Kate will then use the respective command line tool to retrieve the list of files in the
project. When unset or set to AUTO, CMake will try to detect whether the source directory is part of a
git or svn checkout or not, and put the respective entry into the project file.

CMAKE_KATE_MAKE_ARGUMENTS
Added in version 3.0.

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

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

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.

There is also an environment variable CMAKE_LIBRARY_PATH, which is used as an additional list of search
directories.

See also CMAKE_SYSTEM_LIBRARY_PATH and CMAKE_PREFIX_PATH.

CMAKE_LINK_DIRECTORIES_BEFORE
Added in version 3.13.

Whether to append or prepend directories by default in link_directories().

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_LINK_LIBRARIES_ONLY_TARGETS
Added in version 3.23.

Set this variable to initialize the LINK_LIBRARIES_ONLY_TARGETS property of non-imported targets when
they are created. Setting it to true enables an additional check that all items named by
target_link_libraries() that can be target names are actually names of existing targets. See the target
property documentation for details.

CMAKE_MAXIMUM_RECURSION_DEPTH
Added 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 variable_watch()

See also the CMAKE_MAXIMUM_RECURSION_DEPTH environment variable.

CMAKE_MESSAGE_CONTEXT
Added 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 APPEND 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
Added 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 continue 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
Added in version 3.16.

The message() command joins the strings from this list and for log levels 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
Added in version 3.17.

When set, this variable specifies the logging level used by the message() 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 option takes precedence.

The main advantage to using this variable is to make a log level persist 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.

Added in version 3.25: See the cmake_language() cmake_language command for a way to query the current
message logging level.

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 library. 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_MODULE_PATH
Semicolon-separated list of directories, represented using forward slashes, 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.

It's fairly common for a project to have a directory containing various *.cmake files to assist in
development. Adding the directory to the CMAKE_MODULE_PATH simplifies loading them. For example, a
project's top-level CMakeLists.txt file may contain:

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

include(Foo) # Loads ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Foo.cmake

find_package(Bar) # Loads ${CMAKE_CURRENT_SOURCE_DIR}/cmake/FindBar.cmake

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

• CMAKE_POLICY_WARNING_CMP0129 controls the warning for policy CMP0129.

• CMAKE_POLICY_WARNING_CMP0133 controls the warning for policy CMP0133.

• CMAKE_POLICY_WARNING_CMP0172 controls the warning for policy CMP0172.

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 prefixes to be searched by the
find_package(), find_program(), find_library(), 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.

There is also an environment variable CMAKE_PREFIX_PATH, which is used as an additional list of search
prefixes.

See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_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.

There is also an environment variable CMAKE_PROGRAM_PATH, which is used as an additional list of search
directories.

See also CMAKE_SYSTEM_PROGRAM_PATH and CMAKE_PREFIX_PATH.

CMAKE_PROJECT_INCLUDE
Added in version 3.15.

A CMake language file 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 Code Injection for a
more detailed discussion of files potentially included during a project() call.

Added in version 3.29: This variable can be a semicolon-separated list of CMake language files to be
included sequentially. It can also now refer to module names to be found in CMAKE_MODULE_PATH or as a
builtin CMake module.

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

CMAKE_PROJECT_INCLUDE_BEFORE
Added in version 3.15.

A CMake language file 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 Code Injection for a
more detailed discussion of files potentially included during a project() call.

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

CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
A CMake language file 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 Code Injection for a more detailed discussion of files potentially
included during a project() call.

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

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

A CMake language file 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 Code Injection for a more detailed discussion of files potentially
included during a project() call.

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

CMAKE_PROJECT_TOP_LEVEL_INCLUDES
Added in version 3.24.

Semicolon-separated list of CMake language files to include as part of the very first project() call.
The files will be included immediately after the toolchain file has been read (if one is specified) and
platform variables have been set, but before any languages have been enabled. Therefore,
language-specific variables, including things like CMAKE_<LANG>_COMPILER, might not be set. See Code
Injection for a more detailed discussion of files potentially included during a project() call.

Added in version 3.29: This variable can also now refer to module names to be found in CMAKE_MODULE_PATH
or builtin to CMake.

This variable is intended for specifying files that perform one-time setup for the build. It provides an
injection point for things like configuring package managers, adding logic the user shares between
projects (e.g. defining their own custom build types), and so on. It is primarily for users to add things
specific to their environment, but not for specifying the toolchain details (use CMAKE_TOOLCHAIN_FILE for
that).

By default, this variable is empty. It is intended to be set by the user.

See also the following variables:

• CMAKE_SYSTEM_IGNORE_PREFIX_PATH

• CMAKE_SYSTEM_PREFIX_PATH

• CMAKE_SYSTEM_LIBRARY_PATH

• CMAKE_SYSTEM_INCLUDE_PATH

• CMAKE_SYSTEM_PROGRAM_PATH

CMAKE_SYSTEM_IGNORE_PREFIX_PATH
Added in version 3.23.

CMAKE_SYSTEM_IGNORE_PREFIX_PATH is populated by CMake as part of its platform and toolchain setup. Its
purpose is to ignore locations containing incompatible binaries meant for the host rather than the target
platform. The project or end user should not modify this variable, they should use
CMAKE_IGNORE_PREFIX_PATH instead.

See also the following variables:

• CMAKE_SYSTEM_IGNORE_PATH

• CMAKE_SYSTEM_PREFIX_PATH

• CMAKE_SYSTEM_LIBRARY_PATH

• CMAKE_SYSTEM_INCLUDE_PATH

• CMAKE_SYSTEM_PROGRAM_PATH

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 directories for the current system. It is not intended to be modified
by the project; use CMAKE_LIBRARY_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.

CMAKE_SYSTEM_PREFIX_PATH
Semicolon-separated list of directories specifying installation prefixes to be searched by the
find_package(), find_program(), find_library(), 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 installation and staging prefixes may be excluded by setting the
CMAKE_FIND_NO_INSTALL_PREFIX variable before the first project() invocation.

The system directories that are contained in CMAKE_SYSTEM_PREFIX_PATH are locations that typically
include installed software. An example being /usr/local for UNIX based platforms. In addition to standard
platform 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

MSYSTEM environment with MinGW toolchain:
Added in version 3.28.

• ENV{MSYSTEM_PREFIX}/local

• ENV{MSYSTEM_PREFIX}

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 directories for the current system. It is not intended to be modified
by the project; use CMAKE_PROGRAM_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.

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

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

CMAKE_TLS_VERIFY
Specify the default value for the file(DOWNLOAD) and file(UPLOAD) commands' TLS_VERIFY options. If this
variable is not set, the commands check the CMAKE_TLS_VERIFY environment variable. If neither is set,
the default is on.

Changed in version 3.31: The default is on. Previously, the default was off. Users may set the
CMAKE_TLS_VERIFY environment variable to 0 to restore the old default.

This variable is also used by the ExternalProject and FetchContent modules 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_TLS_VERSION
Added in version 3.30.

Specify the default value for the file(DOWNLOAD) and file(UPLOAD) commands' TLS_VERSION option. If this
variable is not set, the commands check the CMAKE_TLS_VERSION environment variable. If neither is set,
the default is TLS 1.2.

Changed in version 3.31: The default is TLS 1.2. Previously, no minimum version was enforced by default.

The value may be one of:

• 1.0

• 1.1

• 1.2

• 1.3

This variable is also used by the ExternalProject and FetchContent modules for internal calls to
file(DOWNLOAD) and git clone.

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 platform information variables to
override CMake's defaults. See CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> for the language-specific version
of this variable.

This feature is intended for use only in overriding information variables 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
default 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
Added 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
Added 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
Added 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
Added 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.