Ubuntu Manpage: cmake-variables - CMake Variables Reference

Provided by: cmake-data_3.25.1-1ubuntu1_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:

$(ConfigurationName) = Visual Studio 9
$(Configuration) = Visual Studio 11 and above
$(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
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) that can be used for custom
commands or tests to invoke CPack commands.

CMAKE_CROSSCOMPILING
Intended to indicate whether CMake 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 it will otherwise be given the same value as CMAKE_HOST_SYSTEM_NAME if not manually
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 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
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.

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

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) 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
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_FUNCTION_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 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
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 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
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_package() 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 input 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 defined.

This variable is initialized by the first project() or enable_language() command called in
a project when a new build tree is first created. If the CMAKE_BUILD_TYPE environment
variable is set, its value is used. Otherwise, a toolchain-specific default is chosen
when a language 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 sensitive 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 CodeBlocks 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 CMakeLists.txt file, the
generator creates projectfiles based on targets rather than projects.

CMAKE_COLOR_DIAGNOSTICS
New in version 3.24.

Enable color diagnostics throughout.

This variable uses three states: ON, OFF and not defined.

When not defined:

• Makefile Generators initialize the CMAKE_COLOR_MAKEFILE variable to ON. It controls
color buildsystem messages.

• GNU/Clang compilers are not invoked with any color diagnostics flag.

When ON:

• Makefile Generators produce color buildsystem messages by default. CMAKE_COLOR_MAKEFILE
is not initialized, but may be explicitly set to OFF to disable color buildsystem
messages.

• GNU/Clang compilers are invoked with a flag enabling color diagnostics
(-fcolor-diagnostics).

When OFF:

• Makefile Generators do not produce color buildsystem messages by default.
CMAKE_COLOR_MAKEFILE is not initialized, but may be explicitly set to ON to enable color
buildsystem messages.

• GNU/Clang compilers are invoked with a flag disabling color diagnostics
(-fno-color-diagnostics).

If the CMAKE_COLOR_DIAGNOSTICS environment variable is set, its value is used. Otherwise,
CMAKE_COLOR_DIAGNOSTICS is not defined by default.

CMAKE_COLOR_MAKEFILE
Enables color output when using the Makefile Generators.

When enabled, the generated Makefiles will produce colored output. Default 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 custom build types can also be defined.

This variable is initialized by the first project() or enable_language() command called in
a project when a new build tree is first created. 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 Makefile 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, although 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 variables 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 -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 parallel 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 version 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 absolute 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_install.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 execute_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 machine-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 Ninja Generators. 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_EXPORT_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 instead.

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 installations, it is not
desirable to write the user package registry. If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY
variable is enabled, the export(PACKAGE) command will do nothing.

If CMP0090 is set to NEW this variable does nothing, and the CMAKE_EXPORT_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 Application 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 following:

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 Frameworks and unix-style
package components.

On Darwin or systems supporting macOS Frameworks, the CMAKE_FIND_FRAMEWORK 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_library() 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_library() command looks
for libraries. On Windows systems this is typically .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 compiler used and the
<prefix> specified in the CMAKE_FIND_LIBRARY_PREFIXES.

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-destination 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 suppress 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_PACKAGE_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 Registry as if they were called with the
NO_CMAKE_PACKAGE_REGISTRY argument.

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_PACKAGE_REGISTRY variable
instead.

By default this variable is not set. If neither CMAKE_FIND_USE_SYSTEM_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 package
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 version 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
custom 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 interchangeably.

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_TARGETS_GLOBAL
New in version 3.24.

Setting to TRUE promotes all IMPORTED targets discoverd by find_package() to a GLOBAL
scope.

Setting this to TRUE is akin to specifying GLOBAL as an argument to find_package().
Default value is OFF.

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_MODULE_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 enforce 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_SYSROOT 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_SYSROOT are used by
find_library().

CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYSROOT are used by
find_package().

CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
This variable controls whether the CMAKE_FIND_ROOT_PATH and CMAKE_SYSROOT 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_SYSTEM_PATH,
CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_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_ENVIRONMENT_PATH, CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
CMAKE_FIND_USE_PACKAGE_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_ENVIRONMENT_PATH,
CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_REGISTRY, and
CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.

CMAKE_FIND_USE_INSTALL_PREFIX
New in version 3.24.

Controls the default behavior of the following commands for whether or not to search the
locations in the CMAKE_INSTALL_PREFIX and CMAKE_STAGING_PREFIX variables.

• find_program()

• find_library()

• find_file()

• find_path()

• find_package()

This is useful in cross-compiling environments.

Due to backwards compatibility with CMAKE_FIND_NO_INSTALL_PREFIX, the behavior of the find
command change based on if this variable exists.

┌──────────────────────────────┬──────────────────────────────┬────────┐
│CMAKE_FIND_USE_INSTALL_PREFIX │ CMAKE_FIND_NO_INSTALL_PREFIX │ Search │
├──────────────────────────────┼──────────────────────────────┼────────┤
│Not Defined │ On │ NO │
├──────────────────────────────┼──────────────────────────────┼────────┤
│Not Defined │ Off || Not Defined │ YES │
├──────────────────────────────┼──────────────────────────────┼────────┤
│Off │ On │ NO │
├──────────────────────────────┼──────────────────────────────┼────────┤
│Off │ Off || Not Defined │ NO │
├──────────────────────────────┼──────────────────────────────┼────────┤
│On │ On │ YES │
├──────────────────────────────┼──────────────────────────────┼────────┤
│On │ Off || Not Defined │ YES │
└──────────────────────────────┴──────────────────────────────┴────────┘

By default this variable is not defined. Explicit options given to the above commands take
precedence over this variable.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH, CMAKE_FIND_USE_SYSTEM_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_REGISTRY 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_REGISTRY 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_INSTALL_PREFIX,
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_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_ENVIRONMENT_PATH,
CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_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_ENVIRONMENT_PATH,
CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and
CMAKE_FIND_USE_SYSTEM_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_PACKAGE_REGISTRY variable. If that is also
not set, then find_package() will use the System Package Registry unless the
NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is provided.

This variable takes precedence over CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_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_REGISTRY argument.

See also Disabling the Package Registry.

See also the CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_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 various find...() commands.

For find_program(), find_library(), find_file(), and find_path(), any file found in one of
the listed directories will be ignored. The listed directories do not apply recursively,
so any subdirectories to be ignored must also be explicitly listed. CMAKE_IGNORE_PATH
does not affect the search prefixes used by these four commands. To ignore individual
paths under a search prefix (e.g. bin, include, lib, etc.), each path must be listed in
CMAKE_IGNORE_PATH as a full absolute path. CMAKE_IGNORE_PREFIX_PATH provides a more
appropriate way to ignore a whole search prefix.

find_package() is also affected by CMAKE_IGNORE_PATH, but only for Config mode searches.
Any <Name>Config.cmake or <name>-config.cmake file found in one of the specified
directories will be ignored. In addition, any search prefix found in CMAKE_IGNORE_PATH
will be skipped for backward compatibility reasons, but new code should prefer to use
CMAKE_IGNORE_PREFIX_PATH to ignore prefixes instead.

Ignoring search locations can be 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 directories containing
libraries meant for the front-end machine.

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

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
New 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.
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
New 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
New 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 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 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
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_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
New 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
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 variable_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 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
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 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
New 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
New 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.

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

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.

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. 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 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_BEFORE, and
CMAKE_PROJECT_TOP_LEVEL_INCLUDES 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 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 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 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
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 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
New 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.

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 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE,
CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, and CMAKE_PROJECT_<PROJECT-NAME>_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_<PackageName> to TRUE. This can be used to assert
assumptions about build environment 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, independent 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 otherwise 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 CMakeLists.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 system when the target specification source changes.

If this variable evaluates to ON at the end of the top-level CMakeLists.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 compiling 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 directories 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_package(), 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 various find...() commands.

For find_program(), find_library(), find_file(), and find_path(), any file found in one of
the listed directories will be ignored. The listed directories do not apply recursively,
so any subdirectories to be ignored must also be explicitly listed.
CMAKE_SYSTEM_IGNORE_PATH does not affect the search prefixes used by these four commands.
To ignore individual paths under a search prefix (e.g. bin, include, lib, etc.), each path
must be listed in CMAKE_SYSTEM_IGNORE_PATH as a full absolute path.
CMAKE_SYSTEM_IGNORE_PREFIX_PATH provides a more appropriate way to ignore a whole search
prefix.

find_package() is also affected by CMAKE_SYSTEM_IGNORE_PATH, but only for Config mode
searches. Any <Name>Config.cmake or <name>-config.cmake file found in one of the specified
directories will be ignored. In addition, any search prefix found in
CMAKE_SYSTEM_IGNORE_PATH will be skipped for backward compatibility reasons, but new code
should prefer to use CMAKE_SYSTEM_IGNORE_PREFIX_PATH to ignore prefixes instead.

CMAKE_SYSTEM_IGNORE_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_PATH instead.

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
New 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

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 not set, the default is off.

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