cmake-compile-features

package: cmake

title: cmake-compile-features(7)

summary: CMake Compile Features Reference

text:
# cmake-compile-features(7)

## NAME
cmake-compile-features - CMake Compile Features Reference

## INTRODUCTION
Project source code may depend on, or be conditional on, the availability of certain features of the compiler. There are three use-cases which arise: Compile Feature Requirements, Optional Compile Features and Conditional Compilation Options.

While features are typically specified in programming language standards, CMake provides a primary user interface based on granular handling of the features, not the language standard that introduced the feature.

The CMAKE_C_KNOWN_FEATURES, CMAKE_CUDA_KNOWN_FEATURES, and CMAKE_CXX_KNOWN_FEATURES global properties contain all the features known to CMake, regardless of compiler support for the feature. The CMAKE_C_COMPILE_FEATURES, CMAKE_CUDA_COMPILE_FEATURES , and CMAKE_CXX_COMPILE_FEATURES variables contain all features CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them.

Features known to CMake are named mostly following the same convention as the Clang feature test macros. There are some exceptions, such as CMake using cxx_final and cxx_override instead of the single cxx_override_control used by Clang.

Note that there are no separate compile features properties or variables for the OBJC or OBJCXX languages. These are based off C or C++ respectively, so the properties and variables for their corresponding base language should be used instead.

## COMPILE FEATURE REQUIREMENTS
Compile feature requirements may be specified with the target_compile_features() command. For example, if a target must be compiled with compiler support for the cxx_constexpr feature:

```
add_library(mylib requires_constexpr.cpp)
target_compile_features(mylib PRIVATE cxx_constexpr)
```

In processing the requirement for the cxx_constexpr feature, cmake(1) will ensure that the in-use C++ compiler is capable of the feature, and will add any necessary flags such as -std=gnu++11 to the compile lines of C++ files in the mylib target. A FATAL_ERROR is issued if the compiler is not capable of the feature.

The exact compile flags and language standard are deliberately not part of the user interface for this use-case. CMake will compute the appropriate compile flags to use by considering the features specified for each target.

Such compile flags are added even if the compiler supports the particular feature without the flag. For example, the GNU compiler supports variadic templates (with a warning) even if -std=gnu++98 is used. CMake adds the -std=gnu++11 flag if cxx_variadic_templates is specified as a requirement.

In the above example, mylib requires cxx_constexpr when it is built itself, but consumers of mylib are not required to use a compiler which supports cxx_constexpr. If the interface of mylib does require the cxx_constexpr feature (or any other known feature), that may be specified with the PUBLIC or INTERFACE signatures of target_compile_features():

```
add_library(mylib requires_constexpr.cpp)
# cxx_constexpr is a usage-requirement
target_compile_features(mylib PUBLIC cxx_constexpr)
# main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr.
add_executable(myexe main.cpp)
target_link_libraries(myexe mylib)
```

Feature requirements are evaluated transitively by consuming the link implementation. See cmake-buildsystem(7) for more on transitive behavior of build properties and usage requirements.

### Requiring Language Standards
In projects that use a large number of commonly available features from a particular language standard (e.g. C++ 11) one may specify a meta-feature (e.g. cxx_std_11) that requires use of a compiler mode that is at minimum aware of that standard, but could be greater. This is simpler than specifying all the features individually, but does not guarantee the existence of any particular feature. Diagnosis of use of unsupported features will be delayed until compile time.

For example, if C++ 11 features are used extensively in a project's header files, then clients must use a compiler mode that is no less than C++ 11. This can be requested with the code:

```
target_compile_features(mylib PUBLIC cxx_std_11)
```

In this example, CMake will ensure the compiler is invoked in a mode of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as -std=gnu++11 if necessary. This applies to sources within mylib as well as any dependents (that may include headers from mylib).

NOTE:

If the compiler's default standard level is at least that of the requested feature, CMake may omit the -std= flag. The flag may still be added if the compiler's default extensions mode does not match the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD target property is set.

### Availability of Compiler Extensions
The <LANG>_EXTENSIONS target property defaults to the compiler's default (see CMAKE_<LANG>_EXTENSIONS_DEFAULT). Note that because most compilers enable extensions by default, this may expose portability bugs in user code or in the headers of third-party dependencies.

<LANG>_EXTENSIONS used to default to ON. See CMP0128.

## OPTIONAL COMPILE FEATURES
Compile features may be preferred if available, without creating a hard requirement. This can be achieved by not specifying features with target_compile_features() and instead checking the compiler capabilities with preprocessor conditions in project code.

In this use-case, the project may wish to establish a particular language standard if available from the compiler, and use preprocessor conditions to detect the features actually available. A language standard may be established by Requiring Language Standards using target_compile_features() with meta-features like cxx_std_11, or by setting the CXX_STANDARD target property or CMAKE_CXX_STANDARD variable.

See also policy CMP0120 and legacy documentation on Example Usage of the deprecated WriteCompilerDetectionHeader module.

## CONDITIONAL COMPILATION OPTIONS
Libraries may provide entirely different header files depending on requested compiler features.

For example, a header at with_variadics/interface.h may contain:

```
template<int I, int... Is>
struct Interface;
template<int I>
struct Interface<I>
{

  static int accumulate()

  {

    return I;

  }
};
template<int I, int... Is>
struct Interface
{

  static int accumulate()

  {

    return I + Interface<Is...>::accumulate();

  }
};
```

while a header at no_variadics/interface.h may contain:

```
template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{

  static int accumulate() { return I1 + I2 + I3 + I4; }
};
```

It may be possible to write an abstraction interface.h header containing something like:

```
#ifdef HAVE_CXX_VARIADIC_TEMPLATES
#include "with_variadics/interface.h"
#else
#include "no_variadics/interface.h"
#endif
```

However this could be unmaintainable if there are many files to abstract. What is needed is to use alternative include directories depending on the compiler capabilities.

CMake provides a COMPILE_FEATURES generator expression to implement such conditions. This may be used with the build-property commands such as target_include_directories() and target_link_libraries() to set the appropriate buildsystem properties:

```
add_library(foo INTERFACE)
set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
target_include_directories(foo

  INTERFACE

    "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"

    "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"

  )
```

Consuming code then simply links to the foo target as usual and uses the feature-appropriate include directory

```
add_executable(consumer_with consumer_with.cpp)
target_link_libraries(consumer_with foo)
set_property(TARGET consumer_with CXX_STANDARD 11)
add_executable(consumer_no consumer_no.cpp)
target_link_libraries(consumer_no foo)
```

## SUPPORTED COMPILERS
CMake is currently aware of the C++ standards and compile features available from the following compiler ids as of the versions specified for each:

- AppleClang: Apple Clang for Xcode versions 4.4+.

- Clang: Clang compiler versions 2.9+.

- GNU: GNU compiler versions 4.4+.

- MSVC: Microsoft Visual Studio versions 2010+.

- SunPro: Oracle SolarisStudio versions 12.4+.

- Intel: Intel compiler versions 12.1+.

CMake is currently aware of the C standards and compile features available from the following compiler ids as of the versions specified for each:

- all compilers and versions listed above for C++.

- GNU: GNU compiler versions 3.4+

CMake is currently aware of the C++ standards and their associated meta-features (e.g. cxx_std_11) available from the following compiler ids as of the versions specified for each:

- Cray: Cray Compiler Environment version 8.1+.

- Fujitsu: Fujitsu HPC compiler 4.0+.

- PGI: PGI version 12.10+.

- NVHPC: NVIDIA HPC compilers version 11.0+.

- TI: Texas Instruments compiler.

- TIClang: Texas Instruments Clang-based compilers.

- XL: IBM XL version 10.1+.

CMake is currently aware of the C standards and their associated meta-features (e.g. c_std_99) available from the following compiler ids as of the versions specified for each:

•

all compilers and versions listed above with only meta-features for C++.

CMake is currently aware of the CUDA standards and their associated meta-features (e.g. cuda_std_11) available from the following compiler ids as of the versions specified for each:

- Clang: Clang compiler 5.0+.

- NVIDIA: NVIDIA nvcc compiler 7.5+.

## LANGUAGE STANDARD FLAGS
In order to satisfy requirements specified by the target_compile_features() command or the CMAKE_<LANG>_STANDARD variable, CMake may pass a language standard flag to the compiler, such as -std=c++11.

For Visual Studio Generators, CMake cannot precisely control the placement of the language standard flag on the compiler command line. For Ninja Generators, Makefile Generators, and Xcode, CMake places the language standard flag just after the language-wide flags from CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG>.

Changed in version 3.26: The language standard flag is placed before flags specified by other abstractions such as the target_compile_options() command. Prior to CMake 3.26, the language standard flag was placed after them.

## COPYRIGHT
2000-2026 Kitware, Inc. and Contributors


cmake-configure-log

title: cmake-configure-log(7)

summary: CMake Configure Log

text:
# cmake-configure-log(7)

## NAME
cmake-configure-log - CMake Configure Log

Added in version 3.26.

## INTRODUCTION
CMake writes a running log, known as the configure log, of certain events that occur during the Configure step. The configure log does not contain a log of all output, errors, or messages printed while configuring a project. It is a log of detailed information about specific events, such as toolchain inspection by try_compile(), meant for use in debugging the configuration of a build tree.

For human use, this version of CMake writes the configure log to the file:

```
${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml
```

However, the location and name of the log file may change in future versions of CMake. Tools that read the configure log should get its location using a configureLog query to the cmake-file-api(7). See the Log Versioning section below for details.

## LOG STRUCTURE
The configure log is designed to be both machine- and human-readable.

The log file is a YAML document stream containing zero or more YAML documents separated by document markers. Each document begins with a --- document marker line, contains a single YAML mapping that logs events from one CMake "configure" step, and, if the configure step finished normally, ends with a ... document marker line:

```
---
events:

  -

    kind: "try_compile-v1"

    # (other fields omitted)

  -

    kind: "try_compile-v1"

    # (other fields omitted)
...
```

A new document is appended to the log every time CMake configures the build tree and logs new events.

The keys of each document root mapping are:

events

A YAML block sequence of nodes corresponding to events logged during one CMake "configure" step. Each event is a YAML node containing one of the Event Kinds documented below.

### Log Versioning
Each of the Event Kinds is versioned independently. The set of keys an event's log entry provides is specific to its major version. When an event is logged, the latest version of its event kind that is known to the running version of CMake is always written to the log.

Tools reading the configure log must ignore event kinds and versions they do not understand:

- A future version of CMake may introduce a new event kind or version.

- If an existing build tree is re-configured with a different version of CMake, the log may contain different versions of the same event kind.

- If cmake-file-api(7) queries request one or more configureLog object versions, the log may contain multiple entries for the same event, each with a different version of its event kind.

IDEs should write a cmake-file-api(7) query requesting a specific configureLog object version, before running CMake, and then read the configure log only as described by the file-api reply.

### Text Block Encoding
In order to make the log human-readable, text blocks are always represented using YAML literal block scalars (|). Since literal block scalars do not support escaping, backslashes and non-printable characters are encoded at the application layer:

- \\ encodes a backslash.

- \xXX encodes a byte using two hexadecimal digits, XX.

## EVENT KINDS
Every event kind is represented by a YAML mapping of the form:

```
kind: "<kind>-v<major>"
backtrace:

  - "<file>:<line> (<function>)"
checks:

  - "Checking for something"
#...event-specific keys...
```

The keys common to all events are:

kind

A string identifying the event kind and major version.

backtrace

A YAML block sequence reporting the call stack of CMake source locations at which the event occurred, from most-recent to least-recent. Each node is a string specifying one location formatted as <file>:<line> (<function>).

checks

An optional key that is present when the event occurred with at least one pending message(CHECK_START). Its value is a YAML block sequence reporting the stack of pending checks, from most-recent to least-recent. Each node is a string containing a pending check message.

Additional mapping keys are specific to each (versioned) event kind, described below.

### Event Kind message
The message(CONFIGURE_LOG) command logs message events.

There is only one message event major version, version 1.

### message-v1 Event
A message-v1 event is a YAML mapping:

```
kind: "message-v1"
backtrace:

  - "CMakeLists.txt:123 (message)"
checks:

  - "Checking for something"
message: |

  # ...
```

The keys specific to message-v1 mappings are:

message

A YAML literal block scalar containing the message text, represented using our Text Block Encoding.

### Event Kind try_compile
The try_compile() command logs try_compile events.

There is only one try_compile event major version, version 1.

### try_compile-v1 Event
A try_compile-v1 event is a YAML mapping:

```
kind: "try_compile-v1"
backtrace:

  - "CMakeLists.txt:123 (try_compile)"
checks:

  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:

  source: "/path/to/.../TryCompile-01234"

  binary: "/path/to/.../TryCompile-01234"
cmakeVariables:

  SOME_VARIABLE: "Some Value"
buildResult:

  variable: "COMPILE_RESULT"

  cached: true

  stdout: |

    # ...

  exitCode: 0
```

The keys specific to try_compile-v1 mappings are:

description

An optional key that is present when the LOG_DESCRIPTION <text> option was used. Its value is a string containing the description <text>.

directories

A mapping describing the directories associated with the compilation attempt. It has the following keys:

source

String specifying the source directory of the try_compile() project.

binary

String specifying the binary directory of the try_compile() project. For non-project invocations, this is often the same as the source directory.

cmakeVariables

An optional key that is present when CMake propagates variables into the test project, either automatically or due to the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable. Its value is a mapping from variable names to their values.

buildResult

A mapping describing the result of compiling the test code. It has the following keys:

variable

A string specifying the name of the CMake variable storing the result of trying to build the test project.

cached

A boolean indicating whether the above result variable is stored in the CMake cache.

stdout

A YAML literal block scalar containing the output from building the test project, represented using our Text Block Encoding. This contains build output from both stdout and stderr.

exitCode

An integer specifying the build tool exit code from trying to build the test project.

### Event Kind try_run
The try_run() command logs try_run events.

There is only one try_run event major version, version 1.

### try_run-v1 Event
A try_run-v1 event is a YAML mapping:

```
kind: "try_run-v1"
backtrace:

  - "CMakeLists.txt:456 (try_run)"
checks:

  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:

  source: "/path/to/.../TryCompile-56789"

  binary: "/path/to/.../TryCompile-56789"
buildResult:

  variable: "COMPILE_RESULT"

  cached: true

  stdout: |

    # ...

  exitCode: 0
runResult:

  variable: "RUN_RESULT"

  cached: true

  stdout: |

    # ...

  stderr: |

    # ...

  exitCode: 0
```

The keys specific to try_run-v1 mappings include those documented by the try_compile-v1 event, plus:

runResult

A mapping describing the result of running the test code. It has the following keys:

variable

A string specifying the name of the CMake variable storing the result of trying to run the test executable.

cached

A boolean indicating whether the above result variable is stored in the CMake cache.

stdout

An optional key that is present when the test project built successfully. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding. If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together, so this will contain both. Otherwise, this will contain only the stdout output.

stderr

An optional key that is present when the test project built successfully and the RUN_OUTPUT_VARIABLE option was not used. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding. If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together in the stdout key, and this key will not be present. Otherwise, this will contain the stderr output.

exitCode

An optional key that is present when the test project built successfully. Its value is an integer specifying the exit code, or a string containing an error message, from trying to run the test executable.

## COPYRIGHT
2000-2026 Kitware, Inc. and Contributors


cmake-cxxmodules

title: cmake-cxxmodules(7)

summary: CMake C++ Modules Support Reference

text:
# cmake-cxxmodules(7)

## NAME
cmake-cxxmodules - CMake C++ Modules Support Reference

Added in version 3.28.

C++ 20 introduced the concept of "modules" to the language. The design requires build systems to order compilations among each other to satisfy import statements reliably. CMake's implementation asks the compiler to scan source files for module dependencies during the build, collates scanning results to infer ordering constraints, and tells the build tool how to dynamically update the build graph.

## COMPILATION STRATEGY
With C++ modules, compiling a set of C++ sources is no longer embarrassingly parallel. That is, any given source may first require the compilation of another source file first in order to provide a "CMI" (compiled module interface) or "BMI" (binary module interface) that C++ compilers use to satisfy import statements in other sources. With headers, sources could share their declarations so that any consumers could compile independently. With modules, declarations are now generated into these BMI files by the compiler during compilation based on the contents of the source file and its export statements.

The order necessary for compilation requires build-time resolution of the ordering because the order is controlled by the contents of the sources. This means that the ordering needs extracted from the source during the build to avoid regenerating the build graph via a configure and generate phase for every source change to get a correct build.

The general strategy is to use a "scanner" to extract the ordering dependency information and update the build graph with new edges between existing edges by taking the per-source scan results (represented by P1689R5 files) and "collating" the dependencies within a target and to modules produced by targets visible to the target. The primary task is to generate "module map" files to pass to each compile rule with the paths to the BMIs needed to satisfy import statements. The collator also has tasks to use the build-time information to fill out information including install rules for the module interface units, their BMIs, and properties for any exported targets with C++ modules.

NOTE:

CMake is focusing on correct builds before looking at performance improvements. There are known tactics within the chosen strategy which may offer build performance improvements. However, they are being deferred until we have a working model against which to compare them. It is also important to note that a tactic useful in one situation (e.g., clean builds) may not be performant in a different situation (e.g., incremental builds). Finding a balance and offering controls to select the tactics is future work.

## SCANNING CONTROL
Whether or not sources get scanned for C++ module usage is dependent on the following queries. The first query that provides a yes/no answer is used.

- If the source file belongs to a file set of type CXX_MODULES, it will be scanned.

- If the target does not use at least C++ 20, it will not be scanned.

- If the source file is not the language CXX, it will not be scanned.

- If the CXX_SCAN_FOR_MODULES source file property is set, its value will be used.

- If the CXX_SCAN_FOR_MODULES target property is set, its value will be used. Set the CMAKE_CXX_SCAN_FOR_MODULES variable to initialize this property on all targets as they are created.

- Otherwise, the source file will be scanned if the compiler and generator support scanning. See policy CMP0155.

Note that any scanned source will be excluded from any unity build (see UNITY_BUILD) because module-related statements can only happen at one place within a C++ translation unit.

## COMPILER SUPPORT
Compilers which CMake natively supports module dependency scanning include:

- MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer)

- LLVM/Clang 16.0 and newer

- GCC 14 (for the in-development branch, after 2023-09-20) and newer

## IMPORT STD SUPPORT
Support for import std is limited to the following toolchain and standard library combinations:

- Clang 18.1.2 and newer with -stdlib=libc++

- MSVC toolset 14.36 and newer (provided with Visual Studio 17.6 Preview 2 and newer)

The CMAKE_CXX_COMPILER_IMPORT_STD variable may be used to detect support for a standard level with the active C++ toolchain.

NOTE:

This support is provided only when experimental support for import std; has been enabled by the CMAKE_EXPERIMENTAL_CXX_IMPORT_STD gate.

## GENERATOR SUPPORT
The list of generators which support scanning sources for C++ modules include:

- Ninja

- Ninja Multi-Config

- Visual Studio 17 2022

### Limitations
There are a number of known limitations of the current C++ module support in CMake. This does not document known limitations or bugs in compilers as these can change over time.

For all generators:

- Header units are not supported.

- No builtin support for import std; or other compiler-provided modules.

For the Ninja Generators:

•

ninja 1.11 or newer is required.

For the Visual Studio Generators:

- Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio 17.4) and newer.

- No support for exporting or installing BMI or module information.

- No support for compiling BMIs from IMPORTED targets with C++ modules (including import std).

- No diagnosis of using modules provided by PRIVATE sources from PUBLIC module sources.

## COPYRIGHT
2000-2026 Kitware, Inc. and Contributors


cmake-developer

title: cmake-developer(7)

summary: CMake Developer Reference

text:
# cmake-developer(7)

## NAME
cmake-developer - CMake Developer Reference

## INTRODUCTION
This manual is intended for reference by developers working with cmake-language(7) code, whether writing their own modules, authoring their own build systems, or working on CMake itself.

See https://cmake.org/get-involved/ to get involved in development of CMake upstream. It includes links to contribution instructions, which in turn link to developer guides for CMake itself.

## ACCESSING WINDOWS REGISTRY
CMake offers some facilities to access the registry on Windows platforms.

### Query Windows Registry
Added in version 3.24.

The cmake_host_system_information() command offers the possibility to query the registry on the local computer. See cmake_host_system(QUERY_WINDOWS_REGISTRY) for more information.

### Find Using Windows Registry
Changed in version 3.24.

Options HINTS and PATHS of find_file(), find_library(), find_path(), find_program(), and find_package() commands offer the possibility, on Windows platform, to query the registry.

The formal syntax, as specified using BNF notation with the regular extensions, for registry query is the following:

```
registry_query  ::=  '[' sep_definition? root_key

                         ((key_separator sub_key)? (value_separator value_name_)?)? ']'
sep_definition  ::=  '{' value_separator '}'
root_key        ::=  'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' |

                     'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' |

                     'HKU' | 'HKEY_USERS'
sub_key         ::=  element (key_separator element)*
key_separator   ::=  '/' | '\\'
value_separator ::=  element | ';'
value_name      ::=  element | '(default)'
element         ::=  character\+
character       ::=  <any character except key_separator and value_separator>
```

The sep_definition optional item offers the possibility to specify the string used to separate the sub_key from the value_name item. If not specified, the character ; is used. Multiple registry_query items can be specified as part of a path.

```
# example using default separator
find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]")
# example using different specified separators
find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]")
```

If the value_name item is not specified or has the special name (default), the content of the default value, if any, will be returned. The supported types for the value_name are:

- REG_SZ.

- REG_EXPAND_SZ. The returned data is expanded.

- REG_DWORD.

- REG_QWORD.

When the registry query failed, typically because the key does not exist or the data type is not supported, the string /REGISTRY-NOTFOUND is substituted to the [] query expression.

## FIND MODULES
A "find module" is a Find<PackageName>.cmake file to be loaded by the find_package() command when invoked for <PackageName>.

The primary task of a find module is to determine whether a package is available, set the <PackageName>_FOUND variable to reflect this and provide any variables, macros and imported targets required to use the package. A find module is useful in cases where an upstream library does not provide a config file package.

The traditional approach is to use variables for everything, including libraries and executables: see the Standard Variable Names section below. This is what most of the existing find modules provided by CMake do.

The more modern approach is to behave as much like config file packages files as possible, by providing imported target. This has the advantage of propagating usage requirements to consumers.

In either case (or even when providing both variables and imported targets), find modules should provide backwards compatibility with old versions that had the same name.

A FindFoo.cmake module will typically be loaded by the command:

```
find_package(Foo [major[.minor[.patch[.tweak]]]]

             [EXACT] [QUIET] [REQUIRED]

             [[COMPONENTS] [components...]]

             [OPTIONAL_COMPONENTS components...]

             [NO_POLICY_SCOPE])
```

See the find_package() documentation for details on what variables are set for the find module. Most of these are dealt with by using FindPackageHandleStandardArgs.

Briefly, the module should only locate versions of the package compatible with the requested version, as described by the Foo_FIND_VERSION family of variables. If Foo_FIND_QUIETLY is set to true, it should avoid printing messages, including anything complaining about the package not being found. If Foo_FIND_REQUIRED is set to true, the module should issue a FATAL_ERROR if the package cannot be found. If neither are set to true, it should print a non-fatal message if it cannot find the package.

Packages that find multiple semi-independent parts (like bundles of libraries) should search for the components listed in Foo_FIND_COMPONENTS if it is set , and only set Foo_FOUND to true if for each searched-for component <c> that was not found, Foo_FIND_REQUIRED_<c> is not set to true. The HANDLE_COMPONENTS argument of find_package_handle_standard_args() can be used to implement this.

If Foo_FIND_COMPONENTS is not set, which modules are searched for and required is up to the find module, but should be documented.

For internal implementation, it is a generally accepted convention that variables starting with underscore are for temporary use only.

### Standard Variable Names
For a FindXxx.cmake module that takes the approach of setting variables (either instead of or in addition to creating imported targets), the following variable names should be used to keep things consistent between Find modules. Note that all variables start with Xxx_, which (unless otherwise noted) must match exactly the name of the FindXxx.cmake file, including upper/lowercase. This prefix on the variable names ensures that they do not conflict with variables of other Find modules. The same pattern should also be followed for any macros, functions and imported targets defined by the Find module.

Xxx_INCLUDE_DIRS

The final set of include directories listed in one variable for use by client code. This should not be a cache entry (note that this also means this variable should not be used as the result variable of a find_path() command - see Xxx_INCLUDE_DIR below for that).

Xxx_LIBRARIES

The libraries to use with the module. These may be CMake targets, full absolute paths to a library binary or the name of a library that the linker must find in its search path. This should not be a cache entry (note that this also means this variable should not be used as the result variable of a find_library() command - see Xxx_LIBRARY below for that).

Xxx_DEFINITIONS

The compile definitions to use when compiling code that uses the module. This really shouldn't include options such as -DHAS_JPEG that a client source-code file uses to decide whether to #include <jpeg.h>

Xxx_EXECUTABLE

The full absolute path to an executable. In this case, Xxx might not be the name of the module, it might be the name of the tool (usually converted to all uppercase), assuming that tool has such a well-known name that it is unlikely that another tool with the same name exists. It would be appropriate to use this as the result variable of a find_program() command.

Xxx_YYY_EXECUTABLE

Similar to Xxx_EXECUTABLE except here the Xxx is always the module name and YYY is the tool name (again, usually fully uppercase). Prefer this form if the tool name is not very widely known or has the potential to clash with another tool. For greater consistency, also prefer this form if the module provides more than one executable.

Xxx_LIBRARY_DIRS

Optionally, the final set of library directories listed in one variable for use by client code. This should not be a cache entry.

Xxx_ROOT_DIR

Where to find the base directory of the module.

Xxx_VERSION_VV

Variables of this form specify whether the Xxx module being provided is version VV of the module. There should not be more than one variable of this form set to true for a given module. For example, a module Barry might have evolved over many years and gone through a number of different major versions. Version 3 of the Barry module might set the variable Barry_VERSION_3 to true, whereas an older version of the module might set Barry_VERSION_2 to true instead. It would be an error for both Barry_VERSION_3 and Barry_VERSION_2 to both be set to true.

Xxx_WRAP_YY

When a variable of this form is set to false, it indicates that the relevant wrapping command should not be used. The wrapping command depends on the module, it may be implied by the module name or it might be specified by the YY part of the variable.

Xxx_Yy_FOUND

For variables of this form, Yy is the name of a component for the module. It should match exactly one of the valid component names that may be passed to the find_package() command for the module. If a variable of this form is set to false, it means that the Yy component of module Xxx was not found or is not available. Variables of this form would typically be used for optional components so that the caller can check whether an optional component is available.

Xxx_FOUND

When the find_package() command returns to the caller, this variable will be set to true if the module was deemed to have been found successfully.

Xxx_NOT_FOUND_MESSAGE

Should be set by config-files in the case that it has set Xxx_FOUND to FALSE. The contained message will be printed by the find_package() command and by find_package_handle_standard_args() to inform the user about the problem. Use this instead of calling message() directly to report a reason for failing to find the module or package.

Xxx_RUNTIME_LIBRARY_DIRS

Optionally, the runtime library search path for use when running an executable linked to shared libraries. The list should be used by user code to create the PATH on windows or LD_LIBRARY_PATH on UNIX. This should not be a cache entry.

Xxx_VERSION

The full version string of the package found, if any. Note that many existing modules provide Xxx_VERSION_STRING instead.

Xxx_VERSION_MAJOR

The major version of the package found, if any.

Xxx_VERSION_MINOR

The minor version of the package found, if any.

Xxx_VERSION_PATCH

The patch version of the package found, if any.

The following names should not usually be used in CMakeLists.txt files. They are intended for use by Find modules to specify and cache the locations of specific files or directories. Users are typically able to set and edit these variables to control the behavior of Find modules (like entering the path to a library manually):

Xxx_LIBRARY

The path of the library. Use this form only when the module provides a single library. It is appropriate to use this as the result variable in a find_library() command.

Xxx_Yy_LIBRARY

The path of library Yy provided by the module Xxx. Use this form when the module provides more than one library or where other modules may also provide a library of the same name. It is also appropriate to use this form as the result variable in a find_library() command.

Xxx_INCLUDE_DIR

When the module provides only a single library, this variable can be used to specify where to find headers for using the library (or more accurately, the path that consumers of the library should add to their header search path). It would be appropriate to use this as the result variable in a find_path() command.

Xxx_Yy_INCLUDE_DIR

If the module provides more than one library or where other modules may also provide a library of the same name, this form is recommended for specifying where to find headers for using library Yy provided by the module. Again, it would be appropriate to use this as the result variable in a find_path() command.

To prevent users being overwhelmed with settings to configure, try to keep as many options as possible out of the cache, leaving at least one option which can be used to disable use of the module, or locate a not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark most cache options as advanced. For packages which provide both debug and release binaries, it is common to create cache variables with a _LIBRARY_<CONFIG> suffix, such as Foo_LIBRARY_RELEASE and Foo_LIBRARY_DEBUG. The SelectLibraryConfigurations module can be helpful for such cases.

While these are the standard variable names, you should provide backwards compatibility for any old names that were actually in use. Make sure you comment them as deprecated, so that no-one starts using them.

### A Sample Find Module
We will describe how to create a simple find module for a library Foo.

The top of the module should begin with a license notice, followed by a blank line, and then followed by a Bracket Comment. The comment should begin with .rst: to indicate that the rest of its content is reStructuredText-format documentation. For example:

```
# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#[=======================================================================[.rst:
FindFoo
-------
Finds the Foo library.
Imported Targets
^^^^^^^^^^^^^^^^
This module provides the following imported targets, if found:
``Foo::Foo``

  The Foo library
Result Variables
^^^^^^^^^^^^^^^^
This will define the following variables:
``Foo_FOUND``

  True if the system has the Foo library.
``Foo_VERSION``

  The version of the Foo library which was found.
``Foo_INCLUDE_DIRS``

  Include directories needed to use Foo.
``Foo_LIBRARIES``

  Libraries needed to link to Foo.
Cache Variables
^^^^^^^^^^^^^^^
The following cache variables may also be set:
``Foo_INCLUDE_DIR``

  The directory containing ``foo.h``.
``Foo_LIBRARY``

  The path to the Foo library.
#]=======================================================================]
```

The module documentation consists of:

- An underlined heading specifying the module name.

- A simple description of what the module finds. More description may be required for some packages. If there are caveats or other details users of the module should be aware of, specify them here.

- A section listing imported targets provided by the module, if any.

- A section listing result variables provided by the module.

- Optionally a section listing cache variables used by the module, if any.

If the package provides any macros or functions, they should be listed in an additional section, but can be documented by additional .rst: comment blocks immediately above where those macros or functions are defined.

The find module implementation may begin below the documentation block. Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries.

First, we try to use pkg-config to find the library. Note that we cannot rely on this, as it may not be available, but it provides a good starting point.

```
find_package(PkgConfig)
if(PKG_CONFIG_FOUND)

  pkg_check_modules(PC_Foo QUIET Foo)
endif()
```

This should define some variables starting PC_Foo_ that contain the information from the Foo.pc file.

Now we need to find the libraries and include files; we use the information from pkg-config to provide hints to CMake about where to look.

```
find_path(Foo_INCLUDE_DIR

  NAMES foo.h

  PATHS ${PC_Foo_INCLUDE_DIRS}

  PATH_SUFFIXES Foo
)
find_library(Foo_LIBRARY

  NAMES foo

  PATHS ${PC_Foo_LIBRARY_DIRS}
)
```

Alternatively, if the library is available with multiple configurations, you can use SelectLibraryConfigurations to automatically set the Foo_LIBRARY variable instead:

```
find_library(Foo_LIBRARY_RELEASE

  NAMES foo

  PATHS ${PC_Foo_LIBRARY_DIRS}/Release
)
find_library(Foo_LIBRARY_DEBUG

  NAMES foo

  PATHS ${PC_Foo_LIBRARY_DIRS}/Debug
)
include(SelectLibraryConfigurations)
select_library_configurations(Foo)
```

If you have a good way of getting the version (from a header file, for example), you can use that information to set Foo_VERSION (although note that find modules have traditionally used Foo_VERSION_STRING, so you may want to set both). Otherwise, attempt to use the information from pkg-config

```
set(Foo_VERSION ${PC_Foo_VERSION})
```

Now we can use FindPackageHandleStandardArgs to do most of the rest of the work for us

```
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Foo

  FOUND_VAR Foo_FOUND

  REQUIRED_VARS

    Foo_LIBRARY

    Foo_INCLUDE_DIR

  VERSION_VAR Foo_VERSION
)
```

This will check that the REQUIRED_VARS contain values (that do not end in -NOTFOUND) and set Foo_FOUND appropriately. It will also cache those values. If Foo_VERSION is set, and a required version was passed to find_package(), it will check the requested version against the one in Foo_VERSION. It will also print messages as appropriate; note that if the package was found, it will print the contents of the first required variable to indicate where it was found.

At this point, we have to provide a way for users of the find module to link to the library or libraries that were found. There are two approaches, as discussed in the Find Modules section above. The traditional variable approach looks like

```
if(Foo_FOUND)

  set(Foo_LIBRARIES ${Foo_LIBRARY})

  set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})

  set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
endif()
```

If more than one library was found, all of them should be included in these variables (see the Standard Variable Names section for more information).

When providing imported targets, these should be namespaced (hence the Foo:: prefix); CMake will recognize that values passed to target_link_libraries() that contain :: in their name are supposed to be imported targets (rather than just library names), and will produce appropriate diagnostic messages if that target does not exist (see policy CMP0028).

```
if(Foo_FOUND AND NOT TARGET Foo::Foo)

  add_library(Foo::Foo UNKNOWN IMPORTED)

  set_target_properties(Foo::Foo PROPERTIES

    IMPORTED_LOCATION "${Foo_LIBRARY}"

    INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"

    INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"

  )
endif()
```

One thing to note about this is that the INTERFACE_INCLUDE_DIRECTORIES and similar properties should only contain information about the target itself, and not any of its dependencies. Instead, those dependencies should also be targets, and CMake should be told that they are dependencies of this target. CMake will then combine all the necessary information automatically.

The type of the IMPORTED target created in the add_library() command can always be specified as UNKNOWN type. This simplifies the code in cases where static or shared variants may be found, and CMake will determine the type by inspecting the files.

If the library is available with multiple configurations, the IMPORTED_CONFIGURATIONS target property should also be populated:

```
if(Foo_FOUND)

  if (NOT TARGET Foo::Foo)

    add_library(Foo::Foo UNKNOWN IMPORTED)

  endif()

  if (Foo_LIBRARY_RELEASE)

    set_property(TARGET Foo::Foo APPEND PROPERTY

      IMPORTED_CONFIGURATIONS RELEASE

    )

    set_target_properties(Foo::Foo PROPERTIES

      IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"

    )

  endif()

  if (Foo_LIBRARY_DEBUG)

    set_property(TARGET Foo::Foo APPEND PROPERTY

      IMPORTED_CONFIGURATIONS DEBUG

    )

    set_target_properties(Foo::Foo PROPERTIES

      IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"

    )

  endif()

  set_target_properties(Foo::Foo PROPERTIES

    INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"

    INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"

  )
endif()
```

The RELEASE variant should be listed first in the property so that the variant is chosen if the user uses a configuration which is not an exact match for any listed IMPORTED_CONFIGURATIONS.

Most of the cache variables should be hidden in the ccmake interface unless the user explicitly asks to edit them.

```
mark_as_advanced(

  Foo_INCLUDE_DIR

  Foo_LIBRARY
)
```

If this module replaces an older version, you should set compatibility variables to cause the least disruption possible.

```
# compatibility variables
set(Foo_VERSION_STRING ${Foo_VERSION})
```

## COPYRIGHT
2000-2026 Kitware, Inc. and Contributors


cmake-env-variables

title: cmake-env-variables(7)

summary: CMake Environment Variables Reference

text:
# cmake-env-variables(7)

## NAME
cmake-env-variables - CMake Environment Variables Reference

This page lists environment variables that have special meaning to CMake.

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

## ENVIRONMENT VARIABLES THAT CHANGE BEHAVIOR

### CMAKE_APPBUNDLE_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_APPBUNDLE_PATH environment variable may be set to a list of directories to be searched for macOS application bundles by the find_program() and find_package() commands.

This variable may hold a single directory or a list of directories separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_APPBUNDLE_PATH CMake variable.

### CMAKE_FRAMEWORK_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_FRAMEWORK_PATH environment variable may be set to a list of directories to be searched for macOS frameworks by the find_library(), find_package(), find_path() and find_file() commands.

This variable may hold a single directory or a list of directories separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_FRAMEWORK_PATH CMake variable.

### CMAKE_INCLUDE_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_INCLUDE_PATH environment variable may be set to a list of directories to be searched by the find_file() and find_path() commands.

This variable may hold a single directory or a list of directories separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_INCLUDE_PATH CMake variable.

### CMAKE_LIBRARY_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_LIBRARY_PATH environment variable may be set to a list of directories to be searched by the find_library() command.

This variable may hold a single directory or a list of directories separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_LIBRARY_PATH CMake variable.

### CMAKE_MAXIMUM_RECURSION_DEPTH
Added in version 3.27.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Maximum recursion depth for CMake scripts. This environment variable is used if the CMAKE_MAXIMUM_RECURSION_DEPTH variable is not set. See that variable's documentation for details.

### CMAKE_PREFIX_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_PREFIX_PATH environment variable may be set to a 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.

This variable may hold a single prefix or a list of prefixes separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_PREFIX_PATH CMake variable.

### CMAKE_PROGRAM_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_PROGRAM_PATH environment variable may be set to a list of directories to be searched by the find_program() command.

This variable may hold a single directory or a list of directories separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the CMAKE_PROGRAM_PATH CMake variable.

### CMAKE_TLS_VERIFY
Added in version 3.30.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify the default value for the file(DOWNLOAD) and file(UPLOAD) commands' TLS_VERIFY option. This environment variable is used if the option is not given and the CMAKE_TLS_VERIFY cmake variable is not set.

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

### CMAKE_TLS_VERSION
Added in version 3.30.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify the default value for the file(DOWNLOAD) and file(UPLOAD) commands' TLS_VERSION option. This environment variable is used if the option is not given and the CMAKE_TLS_VERSION cmake variable is not set. See that variable for allowed values.

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

### SSL_CERT_DIR
Added in version 3.25.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify default directory containing CA certificates. It overrides the default CA directory used.

### SSL_CERT_FILE
Added in version 3.25.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify the file name containing CA certificates. It overrides the default, os-specific CA file used.

## ENVIRONMENT VARIABLES THAT CONTROL THE BUILD

### ADSP_ROOT
Added in version 3.24.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The ADSP_ROOT environment variable specifies a default value for the CMAKE_ADSP_ROOT variable when there is no explicit configuration given on the first run while creating a new build tree.

### CMAKE_APPLE_SILICON_PROCESSOR
Added in version 3.19.2.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

On Apple Silicon hosts running macOS, set this environment variable to tell CMake what architecture to use for CMAKE_HOST_SYSTEM_PROCESSOR. The value must be either arm64 or x86_64.

The CMAKE_APPLE_SILICON_PROCESSOR normal variable, if set, overrides this environment variable.

### CMAKE_BUILD_PARALLEL_LEVEL
Added in version 3.12.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specifies the maximum number of concurrent processes to use when building using the cmake --build command line Build Tool Mode. For example, if CMAKE_BUILD_PARALLEL_LEVEL is set to 8, the underlying build tool will execute up to 8 jobs concurrently as if cmake --build were invoked with the --parallel 8 option.

If this variable is defined empty the native build tool's default number is used.

### CMAKE_BUILD_TYPE
Added in version 3.22.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_BUILD_TYPE environment variable specifies a default value for the CMAKE_BUILD_TYPE variable when there is no explicit configuration given on the first run while creating a new build tree.

### CMAKE_COLOR_DIAGNOSTICS
Added in version 3.24.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specifies a default value for the CMAKE_COLOR_DIAGNOSTICS variable when there is no explicit value given on the first run.

### CMAKE_CONFIG_DIR
Added in version 3.31.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify a CMake user-wide configuration directory for cmake-file-api(7) queries.

If this environment variable is not set, the default user-wide configuration directory is platform-specific:

- Windows: %LOCALAPPDATA%\CMake

- macOS: $XDG_CONFIG_HOME/CMake if set, otherwise $HOME/Library/Application Support/CMake

- Linux/Other: $XDG_CONFIG_HOME/cmake if set, otherwise $HOME/.config/cmake

### CMAKE_CONFIG_TYPE
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The default build configuration for Build a Project and ctest build handler when there is no explicit configuration given.

### CMAKE_CONFIGURATION_TYPES
Added in version 3.22.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_CONFIGURATION_TYPES environment variable specifies a default value for the CMAKE_CONFIGURATION_TYPES variable when there is no explicit configuration given on the first run while creating a new build tree.

### CMAKE_CROSSCOMPILING_EMULATOR
Added in version 3.28.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The default value for CMAKE_CROSSCOMPILING_EMULATOR when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_CROSSCOMPILING_EMULATOR.

### CMAKE_EXPORT_BUILD_DATABASE
Added in version 3.31.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The default value for CMAKE_EXPORT_BUILD_DATABASE when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_EXPORT_BUILD_DATABASE.

NOTE:

This variable is meaningful only when experimental support for build databases has been enabled by the CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE gate.

### CMAKE_EXPORT_COMPILE_COMMANDS
Added in version 3.17.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The default value for CMAKE_EXPORT_COMPILE_COMMANDS when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_EXPORT_COMPILE_COMMANDS.

### CMAKE_GENERATOR
Added in version 3.15.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specifies the CMake default generator to use when no generator is supplied with -G. If the provided value doesn't name a generator known by CMake, the internal default is used. Either way the resulting generator selection is stored in the CMAKE_GENERATOR variable.

Some generators may be additionally configured using the environment variables:

- CMAKE_GENERATOR_PLATFORM

- CMAKE_GENERATOR_TOOLSET

- CMAKE_GENERATOR_INSTANCE

### CMAKE_GENERATOR_INSTANCE
Added in version 3.15.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Default value for CMAKE_GENERATOR_INSTANCE if no Cache entry is present. This value is only applied if CMAKE_GENERATOR is set.

### CMAKE_GENERATOR_PLATFORM
Added in version 3.15.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Default value for CMAKE_GENERATOR_PLATFORM if no Cache entry is present and no value is specified by cmake -A option. This value is only applied if CMAKE_GENERATOR is set.

### CMAKE_GENERATOR_TOOLSET
Added in version 3.15.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Default value for CMAKE_GENERATOR_TOOLSET if no Cache entry is present and no value is specified by cmake -T option. This value is only applied if CMAKE_GENERATOR is set.

### CMAKE_INSTALL_MODE
Added in version 3.22.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_INSTALL_MODE environment variable allows users to operate CMake in an alternate mode of file(INSTALL) and install().

The default behavior for an installation is to copy a source file from a source directory into a destination directory. This environment variable however allows the user to override this behavior, causing CMake to create symbolic links instead.

### Usage Scenarios
Installing symbolic links rather than copying files can help in the following ways:

- Conserving storage space because files do not have to be duplicated on disk.

- Changes to the source of the symbolic link are seen at the install destination without having to re-run the install step.

- Editing through the link at the install destination will modify the source of the link. This may be useful when dealing with CMake project hierarchies, i.e. using ExternalProject and consistent source navigation and refactoring is desired across projects.

### Allowed Values
The following values are allowed for CMAKE_INSTALL_MODE:

COPY, empty or unset

Duplicate the file at its destination. This is the default behavior.

ABS_SYMLINK

Create an absolute symbolic link to the source file at the destination. Halt with an error if the link cannot be created.

ABS_SYMLINK_OR_COPY

Like ABS_SYMLINK but fall back to silently copying if the symlink couldn't be created.

REL_SYMLINK

Create a relative symbolic link to the source file at the destination. Halt with an error if the link cannot be created.

REL_SYMLINK_OR_COPY

Like REL_SYMLINK but fall back to silently copying if the symlink couldn't be created.

SYMLINK

Try as if through REL_SYMLINK and fall back to ABS_SYMLINK if the referenced file cannot be expressed using a relative path. Halt with an error if the link cannot be created.

SYMLINK_OR_COPY

Like SYMLINK but fall back to silently copying if the symlink couldn't be created.

NOTE:

A symbolic link consists of a reference file path rather than contents of its own, hence there are two ways to express the relation, either by a relative or an absolute path.

### When To Set The Environment Variable
For the environment variable to take effect, it must be set during the correct build phase(s).

- If the project calls file(INSTALL) directly, the environment variable must be set during the configuration phase.

- In order to apply to install(), the environment variable must be set during installation. This could be during a build if using the install or package build targets, or separate from the build when invoking an install or running cpack from the command line.

- When using ExternalProject, it might be required during the build phase, since the external project's own configure, build and install steps will execute during the main project's build phase.

Given the above, it is recommended to set the environment variable consistently across all phases (configure, build and install).

### Caveats
Use this environment variable with caution. The following highlights some points to be considered:

- CMAKE_INSTALL_MODE only affects files, not directories.

- Symbolic links are not available on all platforms.

- The way this environment variable interacts with the install step of ExternalProject is more complex. For further details, see that module's documentation.

- A symbolic link ties the destination to the source in a persistent way. Writing to either of the two affects both file system objects. This is in contrast to normal install behavior which only copies files as they were at the time the install was performed, with no enduring relationship between the source and destination of the install.

- Combining CMAKE_INSTALL_MODE with IOS_INSTALL_COMBINED is not supported.

- Changing CMAKE_INSTALL_MODE from what it was on a previous run can lead to unexpected results. Moving from a non-symlinking mode to a symlinking mode will discard any previous file at the destination, but the reverse is not true. Once a symlink exists at the destination, even if you switch to a non-symlink mode, the symlink will continue to exist at the destination and will not be replaced by an actual file.

### CMAKE_INSTALL_PARALLEL_LEVEL
Added in version 3.31.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specifies the default maximum number of concurrent processes to use when installing using cmake --install.

This has no impact unless INSTALL_PARALLEL is enabled.

### CMAKE_INSTALL_PREFIX
Added in version 3.29.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_INSTALL_PREFIX environment variable specifies a custom default value for the CMAKE_INSTALL_PREFIX variable in place of the default values specified by CMake itself. The value specified must be an absolute path to a directory.

### CMAKE_<LANG>_COMPILER_LAUNCHER
Added in version 3.17.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Default compiler launcher to use for the specified language. Will only be used by CMake to initialize the variable on the first configuration. Afterwards, it is available through the cache setting of the variable of the same name. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_<LANG>_COMPILER_LAUNCHER variable is defined.

### CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES_EXCLUDE
Added in version 3.27.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

A semicolon-separated list of directories to exclude from the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES variable when it is automatically detected from the <LANG> compiler.

This may be used to work around misconfigured compiler drivers that pass extraneous implicit link directories to their linker.

### CMAKE_<LANG>_LINKER_LAUNCHER
Added in version 3.21.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Default launcher to use when linking a target of the specified language. Will only be used by CMake to initialize the variable on the first configuration. Afterwards, it is available through the cache setting of the variable of the same name. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_<LANG>_LINKER_LAUNCHER variable is defined.

### CMAKE_MSVCIDE_RUN_PATH
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Extra PATH locations for custom commands when using Visual Studio Generators.

The CMAKE_MSVCIDE_RUN_PATH environment variable sets the default value for the CMAKE_MSVCIDE_RUN_PATH variable if not already explicitly set.

### CMAKE_NO_VERBOSE
Added in version 3.14.

Disables verbose output from CMake when VERBOSE environment variable is set.

Only your build tool of choice will still print verbose output when you start to actually build your project.

### CMAKE_OSX_ARCHITECTURES
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Target specific architectures for macOS.

The CMAKE_OSX_ARCHITECTURES environment variable sets the default value for the CMAKE_OSX_ARCHITECTURES variable. See OSX_ARCHITECTURES for more information.

### CMAKE_TEST_LAUNCHER
Added in version 3.29.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The default value for the CMAKE_TEST_LAUNCHER variable when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_TEST_LAUNCHER.

### CMAKE_TOOLCHAIN_FILE
Added in version 3.21.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

The CMAKE_TOOLCHAIN_FILE environment variable specifies a default value for the CMAKE_TOOLCHAIN_FILE variable when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_TOOLCHAIN_FILE.

### DESTDIR
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

On UNIX one can use the DESTDIR mechanism in order to relocate the whole installation. DESTDIR means DESTination DIRectory. It is commonly used by packagers to install software in a staging directory.

For example, running

```
make DESTDIR=/package/stage install
```

will install the software using the installation prefix, e.g. /usr/local, prepended with the DESTDIR value which gives /package/stage/usr/local. The packaging tool may then construct the package from the content of the /package/stage directory.

See the CMAKE_INSTALL_PREFIX variable to control the installation prefix when configuring a build tree. Or, when using the cmake(1) command-line tool's --install mode, one may specify a different prefix using the --prefix option.

NOTE:

DESTDIR may not be used on Windows because installation prefix usually contains a drive letter like in C:/Program Files which cannot be prepended with some other prefix.

### LDFLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Will only be used by CMake on the first configuration to determine the default linker flags, after which the value for LDFLAGS is stored in the cache as CMAKE_EXE_LINKER_FLAGS_INIT, CMAKE_SHARED_LINKER_FLAGS_INIT, and CMAKE_MODULE_LINKER_FLAGS_INIT. For any configuration run (including the first), the environment variable will be ignored if the equivalent CMAKE_<TYPE>_LINKER_FLAGS_INIT variable is defined.

### MACOSX_DEPLOYMENT_TARGET
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify the minimum version of macOS on which the target binaries are to be deployed.

The MACOSX_DEPLOYMENT_TARGET environment variable sets the default value for the CMAKE_OSX_DEPLOYMENT_TARGET variable.

### <PackageName>_ROOT
Added in version 3.12.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Calls to find_package(<PackageName>) will search in prefixes specified by the <PackageName>_ROOT environment variable, where <PackageName> is the (case-preserved) name given to the find_package() call and _ROOT is literal. For example, find_package(Foo) will search prefixes specified in the Foo_ROOT environment variable (if set). See policy CMP0074.

This variable may hold a single prefix or a list of prefixes separated by : on UNIX or ; on Windows (the same as the PATH environment variable convention on those platforms).

See also the <PackageName>_ROOT CMake variable.

<PACKAGENAME>_ROOT

Added in version 3.27.

Calls to find_package(<PackageName>) will also search in prefixes specified by the upper-case <PACKAGENAME>_ROOT environment variable. See policy CMP0144.

NOTE:

Note that the <PackageName>_ROOT and <PACKAGENAME>_ROOT environment variables are distinct only on platforms that have case-sensitive environments.

### VERBOSE
Added in version 3.14.

Activates verbose output from CMake and your build tools of choice when you start to actually build your project.

Note that any given value is ignored. It's just checked for existence.

See also Build Tool Mode and CMAKE_NO_VERBOSE environment variable

## ENVIRONMENT VARIABLES FOR LANGUAGES

### ASM<DIALECT>
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling a specific dialect of assembly language files. ASM<DIALECT> can be one of:

- ASM

- ASM_NASM (Netwide Assembler)

- ASM_MASM (Microsoft Assembler)

- ASM_MARMASM (Microsoft ARM Assembler)

- ASM-ATT (Assembler AT&T)

Will only be used by CMake on the first configuration to determine ASM<DIALECT> compiler, after which the value for ASM<DIALECT> is stored in the cache as CMAKE_ASM<DIALECT>_COMPILER. For subsequent configuration runs, the environment variable will be ignored in favor of CMAKE_ASM<DIALECT>_COMPILER.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export ASM="custom-compiler --arg1 --arg2"
```

### ASM<DIALECT>FLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling a specific dialect of an assembly language. ASM<DIALECT>FLAGS can be one of:

- ASMFLAGS

- ASM_NASMFLAGS

- ASM_MASMFLAGS

- ASM_MARMASMFLAGS

- ASM-ATTFLAGS

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_ASM<DIALECT>_FLAGS cache entry. This occurs the first time a build tree is configured for language ASM<DIALECT>. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_ASM<DIALECT>_FLAGS variable is already defined.

See also CMAKE_ASM<DIALECT>_FLAGS_INIT.

### CC
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling C language files. Will only be used by CMake on the first configuration to determine C compiler, after which the value for CC is stored in the cache as CMAKE_C_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_C_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export CC="custom-compiler --arg1 --arg2"
```

### CFLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling C files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_C_FLAGS cache entry. This occurs the first time a build tree is configured for language C. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_C_FLAGS variable is already defined.

See also CMAKE_C_FLAGS_INIT.

### CSFLAGS
Added in version 3.9.2.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling CSharp files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_CSharp_FLAGS cache entry. This occurs the first time a build tree is configured for language CSharp. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_CSharp_FLAGS variable is already defined.

See also CMAKE_CSharp_FLAGS_INIT.

### CUDAARCHS
Added in version 3.20.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Value used to initialize CMAKE_CUDA_ARCHITECTURES on the first configuration. Subsequent runs will use the value stored in the cache.

This is a semicolon-separated list of architectures as described in CUDA_ARCHITECTURES.

### CUDACXX
Added in version 3.8.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling CUDA language files. Will only be used by CMake on the first configuration to determine CUDA compiler, after which the value for CUDA is stored in the cache as CMAKE_CUDA_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_CUDA_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export CUDACXX="custom-compiler --arg1 --arg2"
```

### CUDAFLAGS
Added in version 3.8.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling CUDA files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_CUDA_FLAGS cache entry. This occurs the first time a build tree is configured for language CUDA. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_CUDA_FLAGS variable is already defined.

See also CMAKE_CUDA_FLAGS_INIT.

### CUDAHOSTCXX
Added in version 3.8.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling host code when compiling CUDA language files. Will only be used by CMake on the first configuration to determine CUDA host compiler, after which the value for CUDAHOSTCXX is stored in the cache as CMAKE_CUDA_HOST_COMPILER. This environment variable is preferred over CMAKE_CUDA_HOST_COMPILER.

This environment variable is primarily meant for use with projects that enable CUDA as a first-class language.

NOTE:

Ignored when using Visual Studio Generators.

Added in version 3.13: The FindCUDA module will use this variable to initialize its CUDA_HOST_COMPILER setting.

### CXX
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling CXX language files. Will only be used by CMake on the first configuration to determine CXX compiler, after which the value for CXX is stored in the cache as CMAKE_CXX_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_CXX_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export CXX="custom-compiler --arg1 --arg2"
```

### CXXFLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling CXX (C++) files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_CXX_FLAGS cache entry. This occurs the first time a build tree is configured for language CXX. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_CXX_FLAGS variable is already defined.

See also CMAKE_CXX_FLAGS_INIT.

### FC
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling Fortran language files. Will only be used by CMake on the first configuration to determine Fortran compiler, after which the value for Fortran is stored in the cache as CMAKE_Fortran_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_Fortran_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export FC="custom-compiler --arg1 --arg2"
```

### FFLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling Fortran files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_Fortran_FLAGS cache entry. This occurs the first time a build tree is configured for language Fortran. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_Fortran_FLAGS variable is already defined.

See also CMAKE_Fortran_FLAGS_INIT.

### HIPCXX
Added in version 3.21.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling HIP language files. Will only be used by CMake on the first configuration to determine HIP compiler, after which the value for HIP is stored in the cache as CMAKE_HIP_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_HIP_COMPILER variable is defined.

### HIPFLAGS
Added in version 3.21.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling HIP files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_HIP_FLAGS cache entry. This occurs the first time a build tree is configured for language HIP. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_HIP_FLAGS variable is already defined.

See also CMAKE_HIP_FLAGS_INIT.

### HIPHOSTCXX
Added in version 3.28.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling host code when compiling HIP language files with the NVIDIA CUDA Compiler. Will only be used by CMake on the first configuration to determine HIP host compiler, after which the value for HIPHOSTCXX is stored in the cache as CMAKE_HIP_HOST_COMPILER.

This environment variable is primarily meant for use with projects that enable HIP as a first-class language.

NOTE:

Ignored when using Visual Studio Generators.

### ISPC
Added in version 3.19.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling ISPC language files. Will only be used by CMake on the first configuration to determine ISPC compiler, after which the value for ISPC is stored in the cache as CMAKE_ISPC_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_ISPC_COMPILER variable is defined.

### ISPCFLAGS
Added in version 3.19.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling ISPC files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_ISPC_FLAGS cache entry. This occurs the first time a build tree is configured for language ISPC. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_ISPC_FLAGS variable is already defined.

See also CMAKE_ISPC_FLAGS_INIT.

### OBJC
Added in version 3.16.7.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling OBJC language files. Will only be used by CMake on the first configuration to determine OBJC compiler, after which the value for OBJC is stored in the cache as CMAKE_OBJC_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_OBJC_COMPILER variable is defined.

If OBJC is not defined, the CC environment variable will be checked instead.

### OBJCFLAGS
Added in version 3.16.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling Objective C files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_OBJC_FLAGS cache entry. This occurs the first time a build tree is configured for language OBJC. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_OBJC_FLAGS variable is already defined.

See also CMAKE_OBJC_FLAGS_INIT.

### OBJCXX
Added in version 3.16.7.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling OBJCXX language files. Will only be used by CMake on the first configuration to determine OBJCXX compiler, after which the value for OBJCXX is stored in the cache as CMAKE_OBJCXX_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_OBJCXX_COMPILER variable is defined.

If OBJCXX is not defined, the CXX environment variable will be checked instead.

### OBJCXXFLAGS
Added in version 3.16.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling Objective C++ (.mm) files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_OBJCXX_FLAGS cache entry. This occurs the first time a build tree is configured for language OBJCXX. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_OBJCXX_FLAGS variable is already defined.

See also CMAKE_OBJCXX_FLAGS_INIT.

### RC
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling resource files. Will only be used by CMake on the first configuration to determine resource compiler, after which the value for RC is stored in the cache as CMAKE_RC_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_RC_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export RC="custom-compiler --arg1 --arg2"
```

### RCFLAGS
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Add default compilation flags to be used when compiling RC (resource) files.

CMake uses this environment variable value, in combination with its own builtin default flags for the toolchain, to initialize and store the CMAKE_RC_FLAGS cache entry. This occurs the first time a build tree is configured for language RC. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_RC_FLAGS variable is already defined.

See also CMAKE_RC_FLAGS_INIT.

### SWIFTC
Added in version 3.15.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Preferred executable for compiling Swift language files. Will only be used by CMake on the first configuration to determine Swift compiler, after which the value for SWIFTC is stored in the cache as CMAKE_Swift_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_Swift_COMPILER variable is defined.

NOTE:

Options that are required to make the compiler work correctly can be included; they can not be changed.

```
$ export SWIFTC="custom-compiler --arg1 --arg2"
```

## ENVIRONMENT VARIABLES FOR CTEST

### CTEST_INTERACTIVE_DEBUG_MODE
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Environment variable that will exist and be set to 1 when a test executed by ctest(1) is run in interactive mode.

### CTEST_NO_TESTS_ACTION
Added in version 3.26.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Environment variable that controls how ctest handles cases when there are no tests to run. Possible values are: error, ignore, empty or unset.

The --no-tests=<action> option to ctest overrides this environment variable if both are given.

### CTEST_OUTPUT_ON_FAILURE
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Boolean environment variable that controls if the output should be logged for failed tests. Set the value to 1, True, or ON to enable output on failure. See ctest(1) for more information on controlling output of failed tests.

### CTEST_PARALLEL_LEVEL
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Specify the number of tests for CTest to run in parallel. For example, if CTEST_PARALLEL_LEVEL is set to 8, CTest will run up to 8 tests concurrently as if ctest were invoked with the --parallel 8 option.

Changed in version 3.29: The value may be empty, or 0, to let ctest use a default level of parallelism, or unbounded parallelism, respectively, as documented by the ctest --parallel option.

On Windows, environment variables cannot be set to an empty string. CTest will interpret a whitespace-only string as empty.

In CMake 3.28 and earlier, an empty or 0 value was equivalent to 1.

See ctest(1) for more information on parallel test execution.

### CTEST_PROGRESS_OUTPUT
Added in version 3.13.

This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Boolean environment variable that affects how ctest command output reports overall progress. When set to 1, TRUE, ON or anything else that evaluates to boolean true, progress is reported by repeatedly updating the same line. This greatly reduces the overall verbosity, but is only supported when output is sent directly to a terminal. If the environment variable is not set or has a value that evaluates to false, output is reported normally with each test having its own start and end lines logged to the output.

The --progress option to ctest overrides this environment variable if both are given.

### CTEST_USE_LAUNCHERS_DEFAULT
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Initializes the CTEST_USE_LAUNCHERS variable if not already defined.

### DASHBOARD_TEST_FROM_CTEST
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.

Environment variable that will exist when a test executed by ctest(1) is run in non-interactive mode. The value will be equal to CMAKE_VERSION.

## ENVIRONMENT VARIABLES FOR THE CMAKE CURSES INTERFACE

### CCMAKE_COLORS
Added in version 3.18.

Determines what colors are used by the CMake curses interface, when run on a terminal that supports colors. The syntax follows the same conventions as LS_COLORS; that is, a list of key/value pairs separated by :.

Keys are a single letter corresponding to a CMake cache variable type:

- s: A STRING.

- p: A FILEPATH.

- c: A value which has an associated list of choices.

- y: A BOOL which has a true-like value (e.g. ON, YES).

- n: A BOOL which has a false-like value (e.g. OFF, NO).

Values are an integer number that specifies what color to use. 0 is black (you probably don't want to use that). Others are determined by your terminal's color support. Most (color) terminals will support at least 8 or 16 colors. Some will support up to 256 colors. The colors will likely match this chart, although the first 16 colors may match the original CGA color palette. (Many modern terminal emulators also allow their color palette, at least for the first 16 colors, to be configured by the user.)

Note that fairly minimal checking is done for bad colors (although a value higher than what curses believes your terminal supports will be silently ignored) or bad syntax.

For example:

```
CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'
```

## COPYRIGHT
2000-2026 Kitware, Inc. and Contributors