code:
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CMAKE-COMPILE-FEATURES" "7" "Mar 04, 2024" "3.29.0" "CMake"
.SH NAME
cmake-compile-features \- CMake Compile Features Reference
.SH INTRODUCTION
.sp
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:
\fI\%Compile Feature Requirements\fP, \fI\%Optional Compile Features\fP
and \fI\%Conditional Compilation Options\fP\&.
.sp
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.
.sp
The \fI\%CMAKE_C_KNOWN_FEATURES\fP, \fI\%CMAKE_CUDA_KNOWN_FEATURES\fP,
and \fI\%CMAKE_CXX_KNOWN_FEATURES\fP global properties contain all the
features known to CMake, regardless of compiler support for the feature.
The \fI\%CMAKE_C_COMPILE_FEATURES\fP, \fI\%CMAKE_CUDA_COMPILE_FEATURES\fP
, and \fI\%CMAKE_CXX_COMPILE_FEATURES\fP variables contain all features
CMake knows are known to the compiler, regardless of language standard
or compile flags needed to use them.
.sp
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 \fBcxx_final\fP and \fBcxx_override\fP instead of the single
\fBcxx_override_control\fP used by Clang.
.sp
Note that there are no separate compile features properties or variables for
the \fBOBJC\fP or \fBOBJCXX\fP languages.  These are based off \fBC\fP or \fBC++\fP
respectively, so the properties and variables for their corresponding base
language should be used instead.
.SH COMPILE FEATURE REQUIREMENTS
.sp
Compile feature requirements may be specified with the
\fI\%target_compile_features()\fP command.  For example, if a target must
be compiled with compiler support for the
\fI\%cxx_constexpr\fP feature:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(mylib requires_constexpr.cpp)
target_compile_features(mylib PRIVATE cxx_constexpr)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In processing the requirement for the \fBcxx_constexpr\fP feature,
\fI\%cmake(1)\fP will ensure that the in\-use C++ compiler is capable
of the feature, and will add any necessary flags such as \fB\-std=gnu++11\fP
to the compile lines of C++ files in the \fBmylib\fP target.  A
\fBFATAL_ERROR\fP is issued if the compiler is not capable of the
feature.
.sp
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.
.sp
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 \fB\-std=gnu++98\fP is
used.  CMake adds the \fB\-std=gnu++11\fP flag if \fBcxx_variadic_templates\fP
is specified as a requirement.
.sp
In the above example, \fBmylib\fP requires \fBcxx_constexpr\fP when it
is built itself, but consumers of \fBmylib\fP are not required to use a
compiler which supports \fBcxx_constexpr\fP\&.  If the interface of
\fBmylib\fP does require the \fBcxx_constexpr\fP feature (or any other
known feature), that may be specified with the \fBPUBLIC\fP or
\fBINTERFACE\fP signatures of \fI\%target_compile_features()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Feature requirements are evaluated transitively by consuming the link
implementation.  See \fI\%cmake\-buildsystem(7)\fP for more on
transitive behavior of build properties and usage requirements.
.SS Requiring Language Standards
.sp
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. \fBcxx_std_11\fP) 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.
.sp
For example, if C++ 11 features are used extensively in a project\(aqs
header files, then clients must use a compiler mode that is no less
than C++ 11.  This can be requested with the code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_compile_features(mylib PUBLIC cxx_std_11)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
\fB\-std=gnu++11\fP if necessary.  This applies to sources within \fBmylib\fP
as well as any dependents (that may include headers from \fBmylib\fP).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If the compiler\(aqs default standard level is at least that
of the requested feature, CMake may omit the \fB\-std=\fP flag.
The flag may still be added if the compiler\(aqs default extensions mode
does not match the \fI\%<LANG>_EXTENSIONS\fP target property,
or if the \fI\%<LANG>_STANDARD\fP target property is set.
.UNINDENT
.UNINDENT
.SS Availability of Compiler Extensions
.sp
The \fI\%<LANG>_EXTENSIONS\fP target property defaults to the compiler\(aqs
default (see \fI\%CMAKE_<LANG>_EXTENSIONS_DEFAULT\fP). 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.
.sp
\fI\%<LANG>_EXTENSIONS\fP used to default to \fBON\fP\&. See \fI\%CMP0128\fP\&.
.SH OPTIONAL COMPILE FEATURES
.sp
Compile features may be preferred if available, without creating a hard
requirement.   This can be achieved by \fInot\fP specifying features with
\fI\%target_compile_features()\fP and instead checking the compiler
capabilities with preprocessor conditions in project code.
.sp
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 \fI\%Requiring Language Standards\fP using
\fI\%target_compile_features()\fP with meta\-features like \fBcxx_std_11\fP,
or by setting the \fI\%CXX_STANDARD\fP target property or
\fI\%CMAKE_CXX_STANDARD\fP variable.
.sp
See also policy \fI\%CMP0120\fP and legacy documentation on
\fI\%Example Usage\fP of the deprecated
\fI\%WriteCompilerDetectionHeader\fP module.
.SH CONDITIONAL COMPILATION OPTIONS
.sp
Libraries may provide entirely different header files depending on
requested compiler features.
.sp
For example, a header at \fBwith_variadics/interface.h\fP may contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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();
  }
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
while a header at \fBno_variadics/interface.h\fP may contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{
  static int accumulate() { return I1 + I2 + I3 + I4; }
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It may be possible to write an abstraction \fBinterface.h\fP header
containing something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#ifdef HAVE_CXX_VARIADIC_TEMPLATES
#include \(dqwith_variadics/interface.h\(dq
#else
#include \(dqno_variadics/interface.h\(dq
#endif
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.sp
CMake provides a \fBCOMPILE_FEATURES\fP
\fI\%generator expression\fP to implement
such conditions.  This may be used with the build\-property commands such as
\fI\%target_include_directories()\fP and \fI\%target_link_libraries()\fP
to set the appropriate \fI\%buildsystem\fP
properties:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
    \(dq$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>\(dq
    \(dq$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>\(dq
  )
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Consuming code then simply links to the \fBfoo\fP target as usual and uses
the feature\-appropriate include directory
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SUPPORTED COMPILERS
.sp
CMake is currently aware of the \fI\%C++ standards\fP
and \fI\%compile features\fP available from
the following \fI\%compiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBAppleClang\fP: Apple Clang for Xcode versions 4.4+.
.IP \(bu 2
\fBClang\fP: Clang compiler versions 2.9+.
.IP \(bu 2
\fBGNU\fP: GNU compiler versions 4.4+.
.IP \(bu 2
\fBMSVC\fP: Microsoft Visual Studio versions 2010+.
.IP \(bu 2
\fBSunPro\fP: Oracle SolarisStudio versions 12.4+.
.IP \(bu 2
\fBIntel\fP: Intel compiler versions 12.1+.
.UNINDENT
.sp
CMake is currently aware of the \fI\%C standards\fP
and \fI\%compile features\fP available from
the following \fI\%compiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
all compilers and versions listed above for C++.
.IP \(bu 2
\fBGNU\fP: GNU compiler versions 3.4+
.UNINDENT
.sp
CMake is currently aware of the \fI\%C++ standards\fP and
their associated meta\-features (e.g. \fBcxx_std_11\fP) available from the
following \fI\%compiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBCray\fP: Cray Compiler Environment version 8.1+.
.IP \(bu 2
\fBFujitsu\fP: Fujitsu HPC compiler 4.0+.
.IP \(bu 2
\fBPGI\fP: PGI version 12.10+.
.IP \(bu 2
\fBNVHPC\fP: NVIDIA HPC compilers version 11.0+.
.IP \(bu 2
\fBTI\fP: Texas Instruments compiler.
.IP \(bu 2
\fBTIClang\fP: Texas Instruments Clang\-based compilers.
.IP \(bu 2
\fBXL\fP: IBM XL version 10.1+.
.UNINDENT
.sp
CMake is currently aware of the \fI\%C standards\fP and
their associated meta\-features (e.g. \fBc_std_99\fP) available from the
following \fI\%compiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
all compilers and versions listed above with only meta\-features for C++.
.UNINDENT
.sp
CMake is currently aware of the \fI\%CUDA standards\fP and
their associated meta\-features (e.g. \fBcuda_std_11\fP) available from the
following \fI\%compiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBClang\fP: Clang compiler 5.0+.
.IP \(bu 2
\fBNVIDIA\fP: NVIDIA nvcc compiler 7.5+.
.UNINDENT
.SH LANGUAGE STANDARD FLAGS
.sp
In order to satisfy requirements specified by the
\fI\%target_compile_features()\fP command or the
\fI\%CMAKE_<LANG>_STANDARD\fP variable, CMake may pass a
language standard flag to the compiler, such as \fB\-std=c++11\fP\&.
.sp
For \fI\%Visual Studio Generators\fP, CMake cannot precisely control
the placement of the language standard flag on the compiler command line.
For \fI\%Ninja Generators\fP, \fI\%Makefile Generators\fP, and
\fI\%Xcode\fP, CMake places the language standard flag just after
the language\-wide flags from \fI\%CMAKE_<LANG>_FLAGS\fP
and \fI\%CMAKE_<LANG>_FLAGS_<CONFIG>\fP\&.
.sp
Changed in version 3.26: The language standard flag is placed before flags specified by other
abstractions such as the \fI\%target_compile_options()\fP command.
Prior to CMake 3.26, the language standard flag was placed after them.

.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CMAKE-CONFIGURE-LOG" "7" "Mar 04, 2024" "3.29.0" "CMake"
.SH NAME
cmake-configure-log \- CMake Configure Log
.sp
New in version 3.26.

.SH INTRODUCTION
.sp
CMake writes a running log, known as the \fIconfigure log\fP,
of certain events that occur during the Configure step.
The configure log does \fInot\fP 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 \fI\%try_compile()\fP, meant for use in debugging the configuration
of a build tree.
.sp
For human use, this version of CMake writes the configure log to the file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, the \fIlocation and name of the log file may change\fP in future
versions of CMake.  Tools that read the configure log should get its
location using a \fI\%configureLog\fP query to
the \fI\%cmake\-file\-api(7)\fP\&.
See the \fI\%Log Versioning\fP section below for details.
.SH LOG STRUCTURE
.sp
The configure log is designed to be both machine\- and human\-readable.
.sp
The log file is a YAML document stream containing zero or more YAML
documents separated by document markers.  Each document begins
with a \fB\-\-\-\fP document marker line, contains a single YAML mapping
that logs events from one CMake \(dqconfigure\(dq step, and, if the configure
step finished normally, ends with a \fB\&...\fP document marker line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-
events:
  \-
    kind: \(dqtry_compile\-v1\(dq
    # (other fields omitted)
  \-
    kind: \(dqtry_compile\-v1\(dq
    # (other fields omitted)
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A new document is appended to the log every time CMake configures
the build tree and logs new events.
.sp
The keys of the each document root mapping are:
.INDENT 0.0
.TP
.B \fBevents\fP
A YAML block sequence of nodes corresponding to events logged during
one CMake \(dqconfigure\(dq step.  Each event is a YAML node containing one
of the \fI\%Event Kinds\fP documented below.
.UNINDENT
.SS Log Versioning
.sp
Each of the \fI\%Event Kinds\fP is versioned independently.  The set of
keys an event\(aqs 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.
.sp
Tools reading the configure log must ignore event kinds and versions
they do not understand:
.INDENT 0.0
.IP \(bu 2
A future version of CMake may introduce a new event kind or version.
.IP \(bu 2
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.
.IP \(bu 2
If \fI\%cmake\-file\-api(7)\fP queries request one or more
\fI\%configureLog\fP object versions,
the log may contain multiple entries for the same event, each
with a different version of its event kind.
.UNINDENT
.sp
IDEs should write a \fI\%cmake\-file\-api(7)\fP query requesting a
specific \fI\%configureLog\fP object version,
before running CMake, and then read the configure log only as described
by the file\-api reply.
.SS Text Block Encoding
.sp
In order to make the log human\-readable, text blocks are always
represented using YAML literal block scalars (\fB|\fP).
Since literal block scalars do not support escaping, backslashes
and non\-printable characters are encoded at the application layer:
.INDENT 0.0
.IP \(bu 2
\fB\e\e\fP encodes a backslash.
.IP \(bu 2
\fB\exXX\fP encodes a byte using two hexadecimal digits, \fBXX\fP\&.
.UNINDENT
.SH EVENT KINDS
.sp
Every event kind is represented by a YAML mapping of the form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kind: \(dq<kind>\-v<major>\(dq
backtrace:
  \- \(dq<file>:<line> (<function>)\(dq
checks:
  \- \(dqChecking for something\(dq
#...event\-specific keys...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keys common to all events are:
.INDENT 0.0
.TP
.B \fBkind\fP
A string identifying the event kind and major version.
.TP
.B \fBbacktrace\fP
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 \fB<file>:<line> (<function>)\fP\&.
.TP
.B \fBchecks\fP
An optional key that is present when the event occurred with
at least one pending \fI\%message(CHECK_START)\fP\&.  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.
.UNINDENT
.sp
Additional mapping keys are specific to each (versioned) event kind,
described below.
.SS Event Kind \fBmessage\fP
.sp
The \fI\%message(CONFIGURE_LOG)\fP command logs \fBmessage\fP events.
.sp
There is only one \fBmessage\fP event major version, version 1.
.SS \fBmessage\-v1\fP Event
.sp
A \fBmessage\-v1\fP event is a YAML mapping:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kind: \(dqmessage\-v1\(dq
backtrace:
  \- \(dqCMakeLists.txt:123 (message)\(dq
checks:
  \- \(dqChecking for something\(dq
message: |
  # ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keys specific to \fBmessage\-v1\fP mappings are:
.INDENT 0.0
.TP
.B \fBmessage\fP
A YAML literal block scalar containing the message text,
represented using our \fI\%Text Block Encoding\fP\&.
.UNINDENT
.SS Event Kind \fBtry_compile\fP
.sp
The \fI\%try_compile()\fP command logs \fBtry_compile\fP events.
.sp
There is only one \fBtry_compile\fP event major version, version 1.
.SS \fBtry_compile\-v1\fP Event
.sp
A \fBtry_compile\-v1\fP event is a YAML mapping:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kind: \(dqtry_compile\-v1\(dq
backtrace:
  \- \(dqCMakeLists.txt:123 (try_compile)\(dq
checks:
  \- \(dqChecking for something\(dq
description: \(dqExplicit LOG_DESCRIPTION\(dq
directories:
  source: \(dq/path/to/.../TryCompile\-01234\(dq
  binary: \(dq/path/to/.../TryCompile\-01234\(dq
cmakeVariables:
  SOME_VARIABLE: \(dqSome Value\(dq
buildResult:
  variable: \(dqCOMPILE_RESULT\(dq
  cached: true
  stdout: |
    # ...
  exitCode: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keys specific to \fBtry_compile\-v1\fP mappings are:
.INDENT 0.0
.TP
.B \fBdescription\fP
An optional key that is present when the \fBLOG_DESCRIPTION <text>\fP option
was used.  Its value is a string containing the description \fB<text>\fP\&.
.TP
.B \fBdirectories\fP
A mapping describing the directories associated with the
compilation attempt.  It has the following keys:
.INDENT 7.0
.TP
.B \fBsource\fP
String specifying the source directory of the
\fI\%try_compile()\fP project.
.TP
.B \fBbinary\fP
String specifying the binary directory of the
\fI\%try_compile()\fP project.
For non\-project invocations, this is often the same as
the source directory.
.UNINDENT
.TP
.B \fBcmakeVariables\fP
An optional key that is present when CMake propagates variables
into the test project, either automatically or due to the
\fI\%CMAKE_TRY_COMPILE_PLATFORM_VARIABLES\fP variable.
Its value is a mapping from variable names to their values.
.TP
.B \fBbuildResult\fP
A mapping describing the result of compiling the test code.
It has the following keys:
.INDENT 7.0
.TP
.B \fBvariable\fP
A string specifying the name of the CMake variable
storing the result of trying to build the test project.
.TP
.B \fBcached\fP
A boolean indicating whether the above result \fBvariable\fP
is stored in the CMake cache.
.TP
.B \fBstdout\fP
A YAML literal block scalar containing the output from building
the test project, represented using our \fI\%Text Block Encoding\fP\&.
This contains build output from both stdout and stderr.
.TP
.B \fBexitCode\fP
An integer specifying the build tool exit code from trying
to build the test project.
.UNINDENT
.UNINDENT
.SS Event Kind \fBtry_run\fP
.sp
The \fI\%try_run()\fP command logs \fBtry_run\fP events.
.sp
There is only one \fBtry_run\fP event major version, version 1.
.SS \fBtry_run\-v1\fP Event
.sp
A \fBtry_run\-v1\fP event is a YAML mapping:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kind: \(dqtry_run\-v1\(dq
backtrace:
  \- \(dqCMakeLists.txt:456 (try_run)\(dq
checks:
  \- \(dqChecking for something\(dq
description: \(dqExplicit LOG_DESCRIPTION\(dq
directories:
  source: \(dq/path/to/.../TryCompile\-56789\(dq
  binary: \(dq/path/to/.../TryCompile\-56789\(dq
buildResult:
  variable: \(dqCOMPILE_RESULT\(dq
  cached: true
  stdout: |
    # ...
  exitCode: 0
runResult:
  variable: \(dqRUN_RESULT\(dq
  cached: true
  stdout: |
    # ...
  stderr: |
    # ...
  exitCode: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keys specific to \fBtry_run\-v1\fP mappings include those
documented by the \fI\%try_compile\-v1 event\fP, plus:
.INDENT 0.0
.TP
.B \fBrunResult\fP
A mapping describing the result of running the test code.
It has the following keys:
.INDENT 7.0
.TP
.B \fBvariable\fP
A string specifying the name of the CMake variable
storing the result of trying to run the test executable.
.TP
.B \fBcached\fP
A boolean indicating whether the above result \fBvariable\fP
is stored in the CMake cache.
.TP
.B \fBstdout\fP
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 \fI\%Text Block Encoding\fP\&.
.sp
If \fBRUN_OUTPUT_VARIABLE\fP was used, stdout and stderr are captured
together, so this will contain both.  Otherwise, this will contain
only the stdout output.
.TP
.B \fBstderr\fP
An optional key that is present when the test project built successfully
and the \fBRUN_OUTPUT_VARIABLE\fP option was not used.
Its value is a YAML literal block scalar containing output from running
the test executable, represented using our \fI\%Text Block Encoding\fP\&.
.sp
If \fBRUN_OUTPUT_VARIABLE\fP was used, stdout and stderr are captured
together in the \fBstdout\fP key, and this key will not be present.
Otherwise, this will contain the stderr output.
.TP
.B \fBexitCode\fP
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.
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.


code:
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CMAKE-CXXMODULES" "7" "Mar 04, 2024" "3.29.0" "CMake"
.SH NAME
cmake-cxxmodules \- CMake C++ Modules Support Reference
.sp
New in version 3.28.

.sp
C++ 20 introduced the concept of \(dqmodules\(dq to the language.  The design
requires build systems to order compilations among each other to satisfy
\fBimport\fP statements reliably.  CMake\(aqs 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.
.SH SCANNING CONTROL
.sp
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.
.INDENT 0.0
.IP \(bu 2
If the source file belongs to a file set of type \fBCXX_MODULES\fP, it will
be scanned.
.IP \(bu 2
If the target does not use at least C++ 20, it will not be scanned.
.IP \(bu 2
If the source file is not the language \fBCXX\fP, it will not be scanned.
.IP \(bu 2
If the \fI\%CXX_SCAN_FOR_MODULES\fP source file property is set, its
value will be used.
.IP \(bu 2
If the \fI\%CXX_SCAN_FOR_MODULES\fP target property is set, its value
will be used.  Set the \fI\%CMAKE_CXX_SCAN_FOR_MODULES\fP variable
to initialize this property on all targets as they are created.
.IP \(bu 2
Otherwise, the source file will be scanned if the compiler and generator
support scanning.  See policy \fI\%CMP0155\fP\&.
.UNINDENT
.sp
Note that any scanned source will be excluded from any unity build (see
\fI\%UNITY_BUILD\fP) because module\-related statements can only happen at
one place within a C++ translation unit.
.SH COMPILER SUPPORT
.sp
Compilers which CMake natively supports module dependency scanning include:
.INDENT 0.0
.IP \(bu 2
MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer)
.IP \(bu 2
LLVM/Clang 16.0 and newer
.IP \(bu 2
GCC 14 (for the in\-development branch, after 2023\-09\-20) and newer
.UNINDENT
.SH GENERATOR SUPPORT
.sp
The list of generators which support scanning sources for C++ modules include:
.INDENT 0.0
.IP \(bu 2
\fI\%Ninja\fP
.IP \(bu 2
\fI\%Ninja Multi\-Config\fP
.IP \(bu 2
\fI\%Visual Studio 17 2022\fP
.UNINDENT
.SS Limitations
.sp
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.
.sp
For all generators:
.INDENT 0.0
.IP \(bu 2
Header units are not supported.
.IP \(bu 2
No builtin support for \fBimport std;\fP or other compiler\-provided modules.
.UNINDENT
.sp
For the Ninja Generators:
.INDENT 0.0
.IP \(bu 2
\fBninja\fP 1.11 or newer is required.
.UNINDENT
.sp
For the \fI\%Visual Studio Generators\fP:
.INDENT 0.0
.IP \(bu 2
Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio
17.4) and newer.
.IP \(bu 2
No support for exporting or installing BMI or module information.
.IP \(bu 2
No support for compiling BMIs from \fBIMPORTED\fP targets with C++ modules.
.IP \(bu 2
No diagnosis of using modules provided by \fBPRIVATE\fP sources from
\fBPUBLIC\fP module sources.
.UNINDENT
.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.


code:
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CMAKE-DEVELOPER" "7" "Mar 04, 2024" "3.29.0" "CMake"
.SH NAME
cmake-developer \- CMake Developer Reference
.SH INTRODUCTION
.sp
This manual is intended for reference by developers working with
\fI\%cmake\-language(7)\fP code, whether writing their own modules,
authoring their own build systems, or working on CMake itself.
.sp
See \fI\%https://cmake.org/get\-involved/\fP to get involved in development of
CMake upstream.  It includes links to contribution instructions, which
in turn link to developer guides for CMake itself.
.SH ACCESSING WINDOWS REGISTRY
.sp
CMake offers some facilities to access the registry on \fBWindows\fP platforms.
.SS Query Windows Registry
.sp
New in version 3.24.

.sp
The \fI\%cmake_host_system_information()\fP command offers the possibility to
query the registry on the local computer. See
\fI\%cmake_host_system(QUERY_WINDOWS_REGISTRY)\fP for
more information.
.SS Find Using Windows Registry
.sp
Changed in version 3.24.

.sp
Options \fBHINTS\fP and \fBPATHS\fP of \fI\%find_file()\fP,
\fI\%find_library()\fP, \fI\%find_path()\fP, \fI\%find_program()\fP, and
\fI\%find_package()\fP commands offer the possibility, on \fBWindows\fP
platform, to query the registry.
.sp
The formal syntax, as specified using
\fI\%BNF\fP notation with
the regular extensions, for registry query is the following:
.sp
.nf
\fBregistry_query \fP ::=  \(aq[\(aq \fI\%sep_definition\fP? \fI\%root_key\fP
                         ((\fI\%key_separator\fP \fI\%sub_key\fP)? (\fI\%value_separator\fP \fI\%value_name\fP_)?)? \(aq]\(aq
\fBsep_definition \fP ::=  \(aq{\(aq \fI\%value_separator\fP \(aq}\(aq
\fBroot_key       \fP ::=  \(aqHKLM\(aq | \(aqHKEY_LOCAL_MACHINE\(aq | \(aqHKCU\(aq | \(aqHKEY_CURRENT_USER\(aq |
                     \(aqHKCR\(aq | \(aqHKEY_CLASSES_ROOT\(aq | \(aqHKCC\(aq | \(aqHKEY_CURRENT_CONFIG\(aq |
                     \(aqHKU\(aq | \(aqHKEY_USERS\(aq
\fBsub_key        \fP ::=  \fI\%element\fP (\fI\%key_separator\fP \fI\%element\fP)*
\fBkey_separator  \fP ::=  \(aq/\(aq | \(aq\e\e\(aq
\fBvalue_separator\fP ::=  \fI\%element\fP | \(aq;\(aq
\fBvalue_name     \fP ::=  \fI\%element\fP | \(aq(default)\(aq
\fBelement        \fP ::=  \fI\%character\fP\e+
\fBcharacter      \fP ::=  <any character except \fI\%key_separator\fP and \fI\%value_separator\fP>

.fi
.sp
The \fI\%sep_definition\fP optional item offers the possibility to specify
the string used to separate the \fI\%sub_key\fP from the \fI\%value_name\fP
item. If not specified, the character \fB;\fP is used. Multiple
\fI\%registry_query\fP items can be specified as part of a path.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# example using default separator
find_file(... PATHS \(dq/root/[HKLM/Stuff;InstallDir]/lib[HKLM\e\e\e\eStuff;Architecture]\(dq)

# example using different specified separators
find_library(... HINTS \(dq/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\e\e\e\eStuff@@Architecture]\(dq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the \fI\%value_name\fP item is not specified or has the special name
\fB(default)\fP, the content of the default value, if any, will be returned. The
supported types for the \fI\%value_name\fP are:
.INDENT 0.0
.IP \(bu 2
\fBREG_SZ\fP\&.
.IP \(bu 2
\fBREG_EXPAND_SZ\fP\&. The returned data is expanded.
.IP \(bu 2
\fBREG_DWORD\fP\&.
.IP \(bu 2
\fBREG_QWORD\fP\&.
.UNINDENT
.sp
When the registry query failed, typically because the key does not exist or
the data type is not supported, the string \fB/REGISTRY\-NOTFOUND\fP is substituted
to the \fB[]\fP query expression.
.SH FIND MODULES
.sp
A \(dqfind module\(dq is a \fBFind<PackageName>.cmake\fP file to be loaded by the
\fI\%find_package()\fP command when invoked for \fB<PackageName>\fP\&.
.sp
The primary task of a find module is to determine whether a package is
available, set the \fB<PackageName>_FOUND\fP 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 \fI\%config file package\fP\&.
.sp
The traditional approach is to use variables for everything, including
libraries and executables: see the \fI\%Standard Variable Names\fP section
below.  This is what most of the existing find modules provided by CMake
do.
.sp
The more modern approach is to behave as much like
\fI\%config file packages\fP files as possible, by
providing \fI\%imported target\fP\&.  This has the advantage
of propagating \fI\%Transitive Usage Requirements\fP to consumers.
.sp
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.
.sp
A FindFoo.cmake module will typically be loaded by the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Foo [major[.minor[.patch[.tweak]]]]
             [EXACT] [QUIET] [REQUIRED]
             [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [NO_POLICY_SCOPE])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the \fI\%find_package()\fP documentation for details on what
variables are set for the find module.  Most of these are dealt with by
using \fI\%FindPackageHandleStandardArgs\fP\&.
.sp
Briefly, the module should only locate versions of the package
compatible with the requested version, as described by the
\fBFoo_FIND_VERSION\fP family of variables.  If \fBFoo_FIND_QUIETLY\fP is
set to true, it should avoid printing messages, including anything
complaining about the package not being found.  If \fBFoo_FIND_REQUIRED\fP
is set to true, the module should issue a \fBFATAL_ERROR\fP 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.
.sp
Packages that find multiple semi\-independent parts (like bundles of
libraries) should search for the components listed in
\fBFoo_FIND_COMPONENTS\fP if it is set , and only set \fBFoo_FOUND\fP to
true if for each searched\-for component \fB<c>\fP that was not found,
\fBFoo_FIND_REQUIRED_<c>\fP is not set to true.  The \fBHANDLE_COMPONENTS\fP
argument of \fBfind_package_handle_standard_args()\fP can be used to
implement this.
.sp
If \fBFoo_FIND_COMPONENTS\fP is not set, which modules are searched for
and required is up to the find module, but should be documented.
.sp
For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.
.SS Standard Variable Names
.sp
For a \fBFindXxx.cmake\fP 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
\fBXxx_\fP, which (unless otherwise noted) must match exactly the name
of the \fBFindXxx.cmake\fP 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.
.INDENT 0.0
.TP
.B \fBXxx_INCLUDE_DIRS\fP
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
\fI\%find_path()\fP command \- see \fBXxx_INCLUDE_DIR\fP below for that).
.TP
.B \fBXxx_LIBRARIES\fP
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 \fI\%find_library()\fP command \- see
\fBXxx_LIBRARY\fP below for that).
.TP
.B \fBXxx_DEFINITIONS\fP
The compile definitions to use when compiling code that uses the module.
This really shouldn\(aqt include options such as \fB\-DHAS_JPEG\fP that a client
source\-code file uses to decide whether to \fB#include <jpeg.h>\fP
.TP
.B \fBXxx_EXECUTABLE\fP
The full absolute path to an executable.  In this case, \fBXxx\fP 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
\fI\%find_program()\fP command.
.TP
.B \fBXxx_YYY_EXECUTABLE\fP
Similar to \fBXxx_EXECUTABLE\fP except here the \fBXxx\fP is always the module
name and \fBYYY\fP 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.
.TP
.B \fBXxx_LIBRARY_DIRS\fP
Optionally, the final set of library directories listed in one
variable for use by client code. This should not be a cache entry.
.TP
.B \fBXxx_ROOT_DIR\fP
Where to find the base directory of the module.
.TP
.B \fBXxx_VERSION_VV\fP
Variables of this form specify whether the \fBXxx\fP module being provided
is version \fBVV\fP 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 \fBBarry\fP might have evolved over many years and gone through a
number of different major versions.  Version 3 of the \fBBarry\fP module
might set the variable \fBBarry_VERSION_3\fP to true, whereas an older
version of the module might set \fBBarry_VERSION_2\fP to true instead.
It would be an error for both \fBBarry_VERSION_3\fP and \fBBarry_VERSION_2\fP
to both be set to true.
.TP
.B \fBXxx_WRAP_YY\fP
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 \fBYY\fP part of the variable.
.TP
.B \fBXxx_Yy_FOUND\fP
For variables of this form, \fBYy\fP 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 \fI\%find_package()\fP command for the module.
If a variable of this form is set to false, it means that the \fBYy\fP
component of module \fBXxx\fP 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.
.TP
.B \fBXxx_FOUND\fP
When the \fI\%find_package()\fP command returns to the caller, this
variable will be set to true if the module was deemed to have been found
successfully.
.TP
.B \fBXxx_NOT_FOUND_MESSAGE\fP
Should be set by config\-files in the case that it has set
\fBXxx_FOUND\fP to FALSE.  The contained message will be printed by the
\fI\%find_package()\fP command and by
\fI\%find_package_handle_standard_args()\fP to inform the user about the
problem.  Use this instead of calling \fI\%message()\fP directly to
report a reason for failing to find the module or package.
.TP
.B \fBXxx_RUNTIME_LIBRARY_DIRS\fP
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 \fBPATH\fP on windows or \fBLD_LIBRARY_PATH\fP on
UNIX.  This should not be a cache entry.
.TP
.B \fBXxx_VERSION\fP
The full version string of the package found, if any.  Note that many
existing modules provide \fBXxx_VERSION_STRING\fP instead.
.TP
.B \fBXxx_VERSION_MAJOR\fP
The major version of the package found, if any.
.TP
.B \fBXxx_VERSION_MINOR\fP
The minor version of the package found, if any.
.TP
.B \fBXxx_VERSION_PATCH\fP
The patch version of the package found, if any.
.UNINDENT
.sp
The following names should not usually be used in \fBCMakeLists.txt\fP 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):
.INDENT 0.0
.TP
.B \fBXxx_LIBRARY\fP
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 \fI\%find_library()\fP command.
.TP
.B \fBXxx_Yy_LIBRARY\fP
The path of library \fBYy\fP provided by the module \fBXxx\fP\&.  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 \fI\%find_library()\fP command.
.TP
.B \fBXxx_INCLUDE_DIR\fP
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
\fI\%find_path()\fP command.
.TP
.B \fBXxx_Yy_INCLUDE_DIR\fP
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 \fBYy\fP provided by
the module.  Again, it would be appropriate to use this as the result
variable in a \fI\%find_path()\fP command.
.UNINDENT
.sp
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. \fBXxx_ROOT_DIR\fP).  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
\fB_LIBRARY_<CONFIG>\fP suffix, such as \fBFoo_LIBRARY_RELEASE\fP and
\fBFoo_LIBRARY_DEBUG\fP\&.  The \fI\%SelectLibraryConfigurations\fP module
can be helpful for such cases.
.sp
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.
.SS A Sample Find Module
.sp
We will describe how to create a simple find module for a library \fBFoo\fP\&.
.sp
The top of the module should begin with a license notice, followed by
a blank line, and then followed by a \fI\%Bracket Comment\fP\&.  The comment
should begin with \fB\&.rst:\fP to indicate that the rest of its content is
reStructuredText\-format documentation.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# 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:

\(ga\(gaFoo::Foo\(ga\(ga
  The Foo library

Result Variables
^^^^^^^^^^^^^^^^

This will define the following variables:

\(ga\(gaFoo_FOUND\(ga\(ga
  True if the system has the Foo library.
\(ga\(gaFoo_VERSION\(ga\(ga
  The version of the Foo library which was found.
\(ga\(gaFoo_INCLUDE_DIRS\(ga\(ga
  Include directories needed to use Foo.
\(ga\(gaFoo_LIBRARIES\(ga\(ga
  Libraries needed to link to Foo.

Cache Variables
^^^^^^^^^^^^^^^

The following cache variables may also be set:

\(ga\(gaFoo_INCLUDE_DIR\(ga\(ga
  The directory containing \(ga\(gafoo.h\(ga\(ga.
\(ga\(gaFoo_LIBRARY\(ga\(ga
  The path to the Foo library.

#]=======================================================================]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The module documentation consists of:
.INDENT 0.0
.IP \(bu 2
An underlined heading specifying the module name.
.IP \(bu 2
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.
.IP \(bu 2
A section listing imported targets provided by the module, if any.
.IP \(bu 2
A section listing result variables provided by the module.
.IP \(bu 2
Optionally a section listing cache variables used by the module, if any.
.UNINDENT
.sp
If the package provides any macros or functions, they should be listed in
an additional section, but can be documented by additional \fB\&.rst:\fP
comment blocks immediately above where those macros or functions are defined.
.sp
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.
.sp
First, we try to use \fBpkg\-config\fP to find the library.  Note that we
cannot rely on this, as it may not be available, but it provides a good
starting point.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(PkgConfig)
pkg_check_modules(PC_Foo QUIET Foo)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This should define some variables starting \fBPC_Foo_\fP that contain the
information from the \fBFoo.pc\fP file.
.sp
Now we need to find the libraries and include files; we use the
information from \fBpkg\-config\fP to provide hints to CMake about where to
look.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, if the library is available with multiple configurations, you can
use \fI\%SelectLibraryConfigurations\fP to automatically set the
\fBFoo_LIBRARY\fP variable instead:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have a good way of getting the version (from a header file, for
example), you can use that information to set \fBFoo_VERSION\fP (although
note that find modules have traditionally used \fBFoo_VERSION_STRING\fP,
so you may want to set both).  Otherwise, attempt to use the information
from \fBpkg\-config\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(Foo_VERSION ${PC_Foo_VERSION})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now we can use \fI\%FindPackageHandleStandardArgs\fP to do most of the
rest of the work for us
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Foo
  FOUND_VAR Foo_FOUND
  REQUIRED_VARS
    Foo_LIBRARY
    Foo_INCLUDE_DIR
  VERSION_VAR Foo_VERSION
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will check that the \fBREQUIRED_VARS\fP contain values (that do not
end in \fB\-NOTFOUND\fP) and set \fBFoo_FOUND\fP appropriately.  It will also
cache those values.  If \fBFoo_VERSION\fP is set, and a required version
was passed to \fI\%find_package()\fP, it will check the requested version
against the one in \fBFoo_VERSION\fP\&.  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.
.sp
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 \fI\%Find Modules\fP section above.  The
traditional variable approach looks like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(Foo_FOUND)
  set(Foo_LIBRARIES ${Foo_LIBRARY})
  set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
  set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If more than one library was found, all of them should be included in
these variables (see the \fI\%Standard Variable Names\fP section for more
information).
.sp
When providing imported targets, these should be namespaced (hence the
\fBFoo::\fP prefix); CMake will recognize that values passed to
\fI\%target_link_libraries()\fP that contain \fB::\fP 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 \fI\%CMP0028\fP).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(Foo_FOUND AND NOT TARGET Foo::Foo)
  add_library(Foo::Foo UNKNOWN IMPORTED)
  set_target_properties(Foo::Foo PROPERTIES
    IMPORTED_LOCATION \(dq${Foo_LIBRARY}\(dq
    INTERFACE_COMPILE_OPTIONS \(dq${PC_Foo_CFLAGS_OTHER}\(dq
    INTERFACE_INCLUDE_DIRECTORIES \(dq${Foo_INCLUDE_DIR}\(dq
  )
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One thing to note about this is that the \fBINTERFACE_INCLUDE_DIRECTORIES\fP 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.
.sp
The type of the \fI\%IMPORTED\fP target created in the
\fI\%add_library()\fP command can always be specified as \fBUNKNOWN\fP
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.
.sp
If the library is available with multiple configurations, the
\fI\%IMPORTED_CONFIGURATIONS\fP target property should also be
populated:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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 \(dq${Foo_LIBRARY_RELEASE}\(dq
    )
  endif()
  if (Foo_LIBRARY_DEBUG)
    set_property(TARGET Foo::Foo APPEND PROPERTY
      IMPORTED_CONFIGURATIONS DEBUG
    )
    set_target_properties(Foo::Foo PROPERTIES
      IMPORTED_LOCATION_DEBUG \(dq${Foo_LIBRARY_DEBUG}\(dq
    )
  endif()
  set_target_properties(Foo::Foo PROPERTIES
    INTERFACE_COMPILE_OPTIONS \(dq${PC_Foo_CFLAGS_OTHER}\(dq
    INTERFACE_INCLUDE_DIRECTORIES \(dq${Foo_INCLUDE_DIR}\(dq
  )
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBRELEASE\fP 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 \fBIMPORTED_CONFIGURATIONS\fP\&.
.sp
Most of the cache variables should be hidden in the \fBccmake\fP interface unless
the user explicitly asks to edit them.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mark_as_advanced(
  Foo_INCLUDE_DIR
  Foo_LIBRARY
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this module replaces an older version, you should set compatibility variables
to cause the least disruption possible.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# compatibility variables
set(Foo_VERSION_STRING ${Foo_VERSION})
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.


code:
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CMAKE-ENV-VARIABLES" "7" "Mar 04, 2024" "3.29.0" "CMake"
.SH NAME
cmake-env-variables \- CMake Environment Variables Reference
.sp
This page lists environment variables that have special
meaning to CMake.
.sp
For general information on environment variables, see the
\fI\%Environment Variables\fP
section in the cmake\-language manual.
.SH ENVIRONMENT VARIABLES THAT CHANGE BEHAVIOR
.SS CMAKE_APPBUNDLE_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_APPBUNDLE_PATH\fP environment variable may be set to a list of
directories to be searched for macOS application bundles
by the \fI\%find_program()\fP and \fI\%find_package()\fP commands.
.sp
This variable may hold a single directory or a list of directories separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_APPBUNDLE_PATH\fP CMake variable.
.SS CMAKE_FRAMEWORK_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_FRAMEWORK_PATH\fP environment variable may be set to a list of
directories to be searched for macOS frameworks by the \fI\%find_library()\fP,
\fI\%find_package()\fP, \fI\%find_path()\fP and \fI\%find_file()\fP commands.
.sp
This variable may hold a single directory or a list of directories separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_FRAMEWORK_PATH\fP CMake variable.
.SS CMAKE_INCLUDE_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_INCLUDE_PATH\fP environment variable may be set to a list of
directories to be searched by the \fI\%find_file()\fP and \fI\%find_path()\fP commands.
.sp
This variable may hold a single directory or a list of directories separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_INCLUDE_PATH\fP CMake variable.
.SS CMAKE_LIBRARY_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_LIBRARY_PATH\fP environment variable may be set to a list of
directories to be searched by the \fI\%find_library()\fP command.
.sp
This variable may hold a single directory or a list of directories separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_LIBRARY_PATH\fP CMake variable.
.SS CMAKE_MAXIMUM_RECURSION_DEPTH
.sp
New in version 3.27.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Maximum recursion depth for CMake scripts.  This environment variable is
used if the \fI\%CMAKE_MAXIMUM_RECURSION_DEPTH\fP variable is not set.
See that variable\(aqs documentation for details.
.SS CMAKE_PREFIX_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_PREFIX_PATH\fP environment variable may be set to a list of
directories specifying installation \fIprefixes\fP to be searched by the
\fI\%find_package()\fP, \fI\%find_program()\fP, \fI\%find_library()\fP,
\fI\%find_file()\fP, and \fI\%find_path()\fP commands.  Each command will
add appropriate subdirectories (like \fBbin\fP, \fBlib\fP, or \fBinclude\fP)
as specified in its own documentation.
.sp
This variable may hold a single prefix or a list of prefixes separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_PREFIX_PATH\fP CMake variable.
.SS CMAKE_PROGRAM_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_PROGRAM_PATH\fP environment variable may be set to a list of
directories to be searched by the \fI\%find_program()\fP command.
.sp
This variable may hold a single directory or a list of directories separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%CMAKE_PROGRAM_PATH\fP CMake variable.
.SS SSL_CERT_DIR
.sp
New in version 3.25.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specify default directory containing CA certificates.  It overrides
the default CA directory used.
.SS SSL_CERT_FILE
.sp
New in version 3.25.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specify the file name containing CA certificates.  It overrides the
default, os\-specific CA file used.
.SH ENVIRONMENT VARIABLES THAT CONTROL THE BUILD
.SS ADSP_ROOT
.sp
New in version 3.24.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBADSP_ROOT\fP environment variable specifies a default value
for the \fI\%CMAKE_ADSP_ROOT\fP variable when there is no explicit
configuration given on the first run while creating a new build tree.
.SS CMAKE_APPLE_SILICON_PROCESSOR
.sp
New in version 3.19.2.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
On Apple Silicon hosts running macOS, set this environment variable to tell
CMake what architecture to use for \fI\%CMAKE_HOST_SYSTEM_PROCESSOR\fP\&.
The value must be either \fBarm64\fP or \fBx86_64\fP\&.
.sp
The \fI\%CMAKE_APPLE_SILICON_PROCESSOR\fP normal variable, if set,
overrides this environment variable.
.SS CMAKE_BUILD_PARALLEL_LEVEL
.sp
New in version 3.12.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specifies the maximum number of concurrent processes to use when building
using the \fBcmake \-\-build\fP command line
\fI\%Build Tool Mode\fP\&.
For example, if \fBCMAKE_BUILD_PARALLEL_LEVEL\fP is set to 8, the
underlying build tool will execute up to 8 jobs concurrently as if
\fBcmake \-\-build\fP were invoked with the
\fI\%\-\-parallel 8\fP option.
.sp
If this variable is defined empty the native build tool\(aqs default number is
used.
.SS CMAKE_BUILD_TYPE
.sp
New in version 3.22.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_BUILD_TYPE\fP environment variable specifies a default value
for the \fI\%CMAKE_BUILD_TYPE\fP variable when there is no explicit
configuration given on the first run while creating a new build tree.
.SS CMAKE_COLOR_DIAGNOSTICS
.sp
New in version 3.24.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specifies a default value for the \fI\%CMAKE_COLOR_DIAGNOSTICS\fP variable
when there is no explicit value given on the first run.
.SS CMAKE_CONFIGURATION_TYPES
.sp
New in version 3.22.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_CONFIGURATION_TYPES\fP environment variable specifies a
default value for the \fI\%CMAKE_CONFIGURATION_TYPES\fP variable
when there is no explicit configuration given on the first run while
creating a new build tree.
.SS CMAKE_CONFIG_TYPE
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The default build configuration for \fI\%Build a Project\fP and
\fBctest\fP build handler when there is no explicit configuration given.
.SS CMAKE_CROSSCOMPILING_EMULATOR
.sp
New in version 3.28.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The default value for \fI\%CMAKE_CROSSCOMPILING_EMULATOR\fP 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 \fI\%CMAKE_CROSSCOMPILING_EMULATOR\fP\&.
.SS CMAKE_EXPORT_COMPILE_COMMANDS
.sp
New in version 3.17.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The default value for \fI\%CMAKE_EXPORT_COMPILE_COMMANDS\fP 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 \fI\%CMAKE_EXPORT_COMPILE_COMMANDS\fP\&.
.SS CMAKE_GENERATOR
.sp
New in version 3.15.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specifies the CMake default generator to use when no generator is supplied
with \fI\%\-G\fP\&. If the provided value doesn\(aqt name a generator
known by CMake, the internal default is used.  Either way the resulting
generator selection is stored in the \fI\%CMAKE_GENERATOR\fP variable.
.sp
Some generators may be additionally configured using the environment
variables:
.INDENT 0.0
.IP \(bu 2
\fI\%CMAKE_GENERATOR_PLATFORM\fP
.IP \(bu 2
\fI\%CMAKE_GENERATOR_TOOLSET\fP
.IP \(bu 2
\fI\%CMAKE_GENERATOR_INSTANCE\fP
.UNINDENT
.SS CMAKE_GENERATOR_INSTANCE
.sp
New in version 3.15.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fI\%CMAKE_GENERATOR_INSTANCE\fP if no Cache entry is
present. This value is only applied if \fI\%CMAKE_GENERATOR\fP is set.
.SS CMAKE_GENERATOR_PLATFORM
.sp
New in version 3.15.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fI\%CMAKE_GENERATOR_PLATFORM\fP if no Cache entry
is present and no value is specified by \fI\%cmake \-A\fP option.
This value is only applied if \fI\%CMAKE_GENERATOR\fP is set.
.SS CMAKE_GENERATOR_TOOLSET
.sp
New in version 3.15.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fI\%CMAKE_GENERATOR_TOOLSET\fP if no Cache entry
is present and no value is specified by \fI\%cmake \-T\fP option.
This value is only applied if \fI\%CMAKE_GENERATOR\fP is set.
.SS CMAKE_INSTALL_MODE
.sp
New in version 3.22.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_INSTALL_MODE\fP environment variable allows users to operate
CMake in an alternate mode of \fI\%file(INSTALL)\fP and \fI\%install()\fP\&.
.sp
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.
.SS Usage Scenarios
.sp
Installing symbolic links rather than copying files can help in the following
ways:
.INDENT 0.0
.IP \(bu 2
Conserving storage space because files do not have to be duplicated on disk.
.IP \(bu 2
Changes to the source of the symbolic link are seen at the install
destination without having to re\-run the install step.
.IP \(bu 2
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 \fI\%ExternalProject\fP and consistent source navigation and
refactoring is desired across projects.
.UNINDENT
.SS Allowed Values
.sp
The following values are allowed for \fBCMAKE_INSTALL_MODE\fP:
.INDENT 0.0
.TP
.B \fBCOPY\fP, empty or unset
Duplicate the file at its destination.  This is the default behavior.
.TP
.B \fBABS_SYMLINK\fP
Create an \fIabsolute\fP symbolic link to the source file at the destination.
Halt with an error if the link cannot be created.
.TP
.B \fBABS_SYMLINK_OR_COPY\fP
Like \fBABS_SYMLINK\fP but fall back to silently copying if the symlink
couldn\(aqt be created.
.TP
.B \fBREL_SYMLINK\fP
Create a \fIrelative\fP symbolic link to the source file at the destination.
Halt with an error if the link cannot be created.
.TP
.B \fBREL_SYMLINK_OR_COPY\fP
Like \fBREL_SYMLINK\fP but fall back to silently copying if the symlink
couldn\(aqt be created.
.TP
.B \fBSYMLINK\fP
Try as if through \fBREL_SYMLINK\fP and fall back to \fBABS_SYMLINK\fP if the
referenced file cannot be expressed using a relative path.
Halt with an error if the link cannot be created.
.TP
.B \fBSYMLINK_OR_COPY\fP
Like \fBSYMLINK\fP but fall back to silently copying if the symlink couldn\(aqt
be created.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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 \fIrelative\fP
or an \fIabsolute\fP path.
.UNINDENT
.UNINDENT
.SS When To Set The Environment Variable
.sp
For the environment variable to take effect, it must be set during the correct
build phase(s).
.INDENT 0.0
.IP \(bu 2
If the project calls \fI\%file(INSTALL)\fP directly, the environment
variable must be set during the configuration phase.
.IP \(bu 2
In order to apply to \fI\%install()\fP, the environment variable must be
set during installation.  This could be during a build if using the
\fBinstall\fP or \fBpackage\fP build targets, or separate from the build when
invoking an install or running \fI\%cpack\fP from the command
line.
.IP \(bu 2
When using \fI\%ExternalProject\fP, it might be required during the build
phase, since the external project\(aqs own configure, build and install steps
will execute during the main project\(aqs build phase.
.UNINDENT
.sp
Given the above, it is recommended to set the environment variable consistently
across all phases (configure, build and install).
.SS Caveats
.sp
Use this environment variable with caution. The following highlights some
points to be considered:
.INDENT 0.0
.IP \(bu 2
\fBCMAKE_INSTALL_MODE\fP only affects files, not directories.
.IP \(bu 2
Symbolic links are not available on all platforms.
.IP \(bu 2
The way this environment variable interacts with the install step of
\fI\%ExternalProject\fP is more complex. For further details, see that
module\(aqs documentation.
.IP \(bu 2
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.
.IP \(bu 2
Combining \fBCMAKE_INSTALL_MODE\fP with \fI\%IOS_INSTALL_COMBINED\fP is
not supported.
.IP \(bu 2
Changing \fBCMAKE_INSTALL_MODE\fP 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.
.UNINDENT
.SS CMAKE_INSTALL_PREFIX
.sp
New in version 3.29.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_INSTALL_PREFIX\fP environment variable specifies a custom default
value for the \fI\%CMAKE_INSTALL_PREFIX\fP variable in place of the
default values specified by CMake itself. The value specified must be an
absolute path to a directory.
.SS CMAKE_<LANG>_COMPILER_LAUNCHER
.sp
New in version 3.17.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
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 \fI\%CMAKE_<LANG>_COMPILER_LAUNCHER\fP variable is defined.
.SS CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES_EXCLUDE
.sp
New in version 3.27.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
A \fI\%semicolon\-separated list\fP of directories
to exclude from the \fI\%CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES\fP
variable when it is automatically detected from the \fB<LANG>\fP compiler.
.sp
This may be used to work around misconfigured compiler drivers that pass
extraneous implicit link directories to their linker.
.SS CMAKE_<LANG>_LINKER_LAUNCHER
.sp
New in version 3.21.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
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 \fI\%CMAKE_<LANG>_LINKER_LAUNCHER\fP
variable is defined.
.SS CMAKE_MSVCIDE_RUN_PATH
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Extra PATH locations for custom commands when using
\fI\%Visual Studio 9 2008\fP (or above) generators.
.sp
The \fBCMAKE_MSVCIDE_RUN_PATH\fP environment variable sets the default value for
the \fI\%CMAKE_MSVCIDE_RUN_PATH\fP variable if not already explicitly set.
.SS CMAKE_NO_VERBOSE
.sp
New in version 3.14.

.sp
Disables verbose output from CMake when \fI\%VERBOSE\fP environment variable
is set.
.sp
Only your build tool of choice will still print verbose output when you start
to actually build your project.
.SS CMAKE_OSX_ARCHITECTURES
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Target specific architectures for macOS.
.sp
The \fBCMAKE_OSX_ARCHITECTURES\fP environment variable sets the default value for
the \fI\%CMAKE_OSX_ARCHITECTURES\fP variable. See
\fI\%OSX_ARCHITECTURES\fP for more information.
.SS CMAKE_TEST_LAUNCHER
.sp
New in version 3.29.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The default value for the \fI\%CMAKE_TEST_LAUNCHER\fP 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 \fI\%CMAKE_TEST_LAUNCHER\fP\&.
.SS CMAKE_TOOLCHAIN_FILE
.sp
New in version 3.21.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
The \fBCMAKE_TOOLCHAIN_FILE\fP environment variable specifies a default value
for the \fI\%CMAKE_TOOLCHAIN_FILE\fP 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 \fI\%CMAKE_TOOLCHAIN_FILE\fP\&.
.SS DESTDIR
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
On UNIX one can use the \fBDESTDIR\fP mechanism in order to relocate the
whole installation.  \fBDESTDIR\fP means DESTination DIRectory.  It is
commonly used by packagers to install software in a staging directory.
.sp
For example, running
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make DESTDIR=/package/stage install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will install the software using the installation prefix, e.g. \fB/usr/local\fP,
prepended with the \fBDESTDIR\fP value which gives \fB/package/stage/usr/local\fP\&.
The packaging tool may then construct the package from the content of the
\fB/package/stage\fP directory.
.sp
See the \fI\%CMAKE_INSTALL_PREFIX\fP variable to control the
installation prefix when configuring a build tree.  Or, when using
the \fI\%cmake(1)\fP command\-line tool\(aqs \fI\%\-\-install\fP
mode, one may specify a different prefix using the
\fI\%\-\-prefix\fP option.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBDESTDIR\fP may not be used on Windows because installation
prefix usually contains a drive letter like in \fBC:/Program Files\fP
which cannot be prepended with some other prefix.
.UNINDENT
.UNINDENT
.SS LDFLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Will only be used by CMake on the first configuration to determine the default
linker flags, after which the value for \fBLDFLAGS\fP is stored in the cache
as \fI\%CMAKE_EXE_LINKER_FLAGS_INIT\fP,
\fI\%CMAKE_SHARED_LINKER_FLAGS_INIT\fP, and
\fI\%CMAKE_MODULE_LINKER_FLAGS_INIT\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
equivalent  \fBCMAKE_<TYPE>_LINKER_FLAGS_INIT\fP variable is defined.
.SS MACOSX_DEPLOYMENT_TARGET
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specify the minimum version of macOS on which the target binaries are
to be deployed.
.sp
The \fBMACOSX_DEPLOYMENT_TARGET\fP environment variable sets the default value for
the \fI\%CMAKE_OSX_DEPLOYMENT_TARGET\fP variable.
.SS <PackageName>_ROOT
.sp
New in version 3.12.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Calls to \fI\%find_package(<PackageName>)\fP will search in prefixes
specified by the \fB<PackageName>_ROOT\fP environment variable, where
\fB<PackageName>\fP is the (case\-preserved) name given to the
\fI\%find_package()\fP call and \fB_ROOT\fP is literal.
For example, \fBfind_package(Foo)\fP will search prefixes specified in the
\fBFoo_ROOT\fP environment variable (if set).  See policy \fI\%CMP0074\fP\&.
.sp
This variable may hold a single prefix or a list of prefixes separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fI\%<PackageName>_ROOT\fP CMake variable.
.INDENT 0.0
.TP
.B <PACKAGENAME>_ROOT
New in version 3.27.

.sp
Calls to \fI\%find_package(<PackageName>)\fP will also search in
prefixes specified by the upper\-case \fB<PACKAGENAME>_ROOT\fP environment
variable.  See policy \fI\%CMP0144\fP\&.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that the \fB<PackageName>_ROOT\fP and \fB<PACKAGENAME>_ROOT\fP
environment variables are distinct only on platforms that have
case\-sensitive environments.
.UNINDENT
.UNINDENT
.SS VERBOSE
.sp
New in version 3.14.

.sp
Activates verbose output from CMake and your build tools of choice when
you start to actually build your project.
.sp
Note that any given value is ignored. It\(aqs just checked for existence.
.sp
See also \fI\%Build Tool Mode\fP and
\fI\%CMAKE_NO_VERBOSE\fP environment variable
.SH ENVIRONMENT VARIABLES FOR LANGUAGES
.SS ASM<DIALECT>
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling a specific dialect of assembly language
files. \fBASM<DIALECT>\fP can be one of:
.INDENT 0.0
.IP \(bu 2
\fBASM\fP
.IP \(bu 2
\fBASM_NASM\fP (Netwide Assembler)
.IP \(bu 2
\fBASM_MASM\fP (Microsoft Assembler)
.IP \(bu 2
\fBASM_MARMASM\fP (Microsoft ARM Assembler)
.IP \(bu 2
\fBASM\-ATT\fP (Assembler AT&T)
.UNINDENT
.sp
Will only be used by CMake on the first configuration to determine
\fBASM<DIALECT>\fP compiler, after which the value for \fBASM<DIALECT>\fP is stored
in the cache as
\fI\%CMAKE_ASM<DIALECT>_COMPILER\fP\&. For subsequent
configuration runs, the environment variable will be ignored in favor of
\fI\%CMAKE_ASM<DIALECT>_COMPILER\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export ASM=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ASM<DIALECT>FLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling a specific dialect
of an assembly language.  \fBASM<DIALECT>FLAGS\fP can be one of:
.INDENT 0.0
.IP \(bu 2
\fBASMFLAGS\fP
.IP \(bu 2
\fBASM_NASMFLAGS\fP
.IP \(bu 2
\fBASM_MASMFLAGS\fP
.IP \(bu 2
\fBASM_MARMASMFLAGS\fP
.IP \(bu 2
\fBASM\-ATTFLAGS\fP
.UNINDENT
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_ASM<DIALECT>_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBASM<DIALECT>\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_ASM<DIALECT>_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_ASM<DIALECT>_FLAGS_INIT\fP\&.
.SS CC
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBC\fP language files. Will only be used by
CMake on the first configuration to determine \fBC\fP compiler, after which the
value for \fBCC\fP is stored in the cache as
\fI\%CMAKE_C_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fI\%CMAKE_C_COMPILER\fP variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export CC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CFLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBC\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_C_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBC\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_C_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_C_FLAGS_INIT\fP\&.
.SS CSFLAGS
.sp
New in version 3.9.2.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBCSharp\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_CSharp_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBCSharp\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_CSharp_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_CSharp_FLAGS_INIT\fP\&.
.SS CUDAARCHS
.sp
New in version 3.20.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Value used to initialize \fI\%CMAKE_CUDA_ARCHITECTURES\fP on the first
configuration. Subsequent runs will use the value stored in the cache.
.sp
This is a semicolon\-separated list of architectures as described in
\fI\%CUDA_ARCHITECTURES\fP\&.
.SS CUDACXX
.sp
New in version 3.8.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBCUDA\fP language files. Will only be used by
CMake on the first configuration to determine \fBCUDA\fP compiler, after which the
value for \fBCUDA\fP is stored in the cache as
\fI\%CMAKE_CUDA_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_CUDA_COMPILER\fP variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export CUDACXX=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CUDAFLAGS
.sp
New in version 3.8.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBCUDA\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_CUDA_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBCUDA\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_CUDA_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_CUDA_FLAGS_INIT\fP\&.
.SS CUDAHOSTCXX
.sp
New in version 3.8.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling host code when compiling \fBCUDA\fP
language files. Will only be used by CMake on the first configuration to
determine \fBCUDA\fP host compiler, after which the value for \fBCUDAHOSTCXX\fP is
stored in the cache as
\fI\%CMAKE_CUDA_HOST_COMPILER\fP\&.
This environment variable is preferred over
\fI\%CMAKE_CUDA_HOST_COMPILER\fP\&.
.sp
This environment variable is primarily meant for use with projects that
enable \fBCUDA\fP as a first\-class language.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Ignored when using \fI\%Visual Studio Generators\fP\&.
.UNINDENT
.UNINDENT
.sp
New in version 3.13: The \fI\%FindCUDA\fP
module will use this variable to initialize its \fBCUDA_HOST_COMPILER\fP setting.

.SS CXX
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBCXX\fP language files. Will only be used by
CMake on the first configuration to determine \fBCXX\fP compiler, after which the
value for \fBCXX\fP is stored in the cache as
\fI\%CMAKE_CXX_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_CXX_COMPILER\fP variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export CXX=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CXXFLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBCXX\fP (C++) files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_CXX_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBCXX\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_CXX_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_CXX_FLAGS_INIT\fP\&.
.SS FC
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBFortran\fP language files. Will only be used
by CMake on the first configuration to determine \fBFortran\fP compiler, after
which the value for \fBFortran\fP is stored in the cache as
\fI\%CMAKE_Fortran_COMPILER\fP\&. For any
configuration run (including the first), the environment variable will be
ignored if the \fI\%CMAKE_Fortran_COMPILER\fP
variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export FC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FFLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBFortran\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_Fortran_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBFortran\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_Fortran_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_Fortran_FLAGS_INIT\fP\&.
.SS HIPCXX
.sp
New in version 3.21.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBHIP\fP language files. Will only be used by
CMake on the first configuration to determine \fBHIP\fP compiler, after which the
value for \fBHIP\fP is stored in the cache as
\fI\%CMAKE_HIP_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_HIP_COMPILER\fP variable is defined.
.SS HIPFLAGS
.sp
New in version 3.21.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBHIP\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_HIP_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBHIP\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_HIP_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_HIP_FLAGS_INIT\fP\&.
.SS HIPHOSTCXX
.sp
New in version 3.28.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling host code when compiling \fBHIP\fP
language files with the NVIDIA CUDA Compiler. Will only be used by CMake
on the first configuration to determine \fBHIP\fP host compiler, after which
the value for \fBHIPHOSTCXX\fP is stored in the cache as
\fI\%CMAKE_HIP_HOST_COMPILER\fP\&.
.sp
This environment variable is primarily meant for use with projects that
enable \fBHIP\fP as a first\-class language.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Ignored when using \fI\%Visual Studio Generators\fP\&.
.UNINDENT
.UNINDENT
.SS ISPC
.sp
New in version 3.19.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBISPC\fP language files. Will only be used by
CMake on the first configuration to determine \fBISPC\fP compiler, after which the
value for \fBISPC\fP is stored in the cache as
\fI\%CMAKE_ISPC_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_ISPC_COMPILER\fP variable is defined.
.SS ISPCFLAGS
.sp
New in version 3.19.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBISPC\fP files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_ISPC_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBISPC\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_ISPC_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_ISPC_FLAGS_INIT\fP\&.
.SS OBJC
.sp
New in version 3.16.7.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBOBJC\fP language files. Will only be used
by CMake on the first configuration to determine \fBOBJC\fP compiler, after
which the value for \fBOBJC\fP is stored in the cache as
\fI\%CMAKE_OBJC_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_OBJC_COMPILER\fP variable is defined.
.sp
If \fBOBJC\fP is not defined, the \fI\%CC\fP environment variable will
be checked instead.
.SS OBJCXX
.sp
New in version 3.16.7.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBOBJCXX\fP language files. Will only be used
by CMake on the first configuration to determine \fBOBJCXX\fP compiler, after
which the value for \fBOBJCXX\fP is stored in the cache as
\fI\%CMAKE_OBJCXX_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fI\%CMAKE_OBJCXX_COMPILER\fP variable is defined.
.sp
If \fBOBJCXX\fP is not defined, the \fI\%CXX\fP environment variable will
be checked instead.
.SS RC
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBresource\fP files. Will only be used by CMake
on the first configuration to determine \fBresource\fP compiler, after which the
value for \fBRC\fP is stored in the cache as
\fI\%CMAKE_RC_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fI\%CMAKE_RC_COMPILER\fP variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export RC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS RCFLAGS
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Add default compilation flags to be used when compiling \fBRC\fP (resource) files.
.sp
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
\fI\%CMAKE_RC_FLAGS\fP cache entry.
This occurs the first time a build tree is configured for language \fBRC\fP\&.
For any configuration run (including the first), the environment variable
will be ignored if the \fI\%CMAKE_RC_FLAGS\fP variable is already defined.
.sp
See also \fI\%CMAKE_RC_FLAGS_INIT\fP\&.
.SS SWIFTC
.sp
New in version 3.15.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBSwift\fP language files. Will only be used by
CMake on the first configuration to determine \fBSwift\fP compiler, after which the
value for \fBSWIFTC\fP is stored in the cache as
\fI\%CMAKE_Swift_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fI\%CMAKE_Swift_COMPILER\fP variable is defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Options that are required to make the compiler work correctly can be included;
they can not be changed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export SWIFTC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ENVIRONMENT VARIABLES FOR CTEST
.SS CTEST_INTERACTIVE_DEBUG_MODE
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Environment variable that will exist and be set to \fB1\fP when a test executed
by \fI\%ctest(1)\fP is run in interactive mode.
.SS CTEST_NO_TESTS_ACTION
.sp
New in version 3.26.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Environment variable that controls how \fI\%ctest\fP handles
cases when there are no tests to run. Possible values are: \fBerror\fP,
\fBignore\fP, empty or unset.
.sp
The \fI\%\-\-no\-tests=<action>\fP option to
\fI\%ctest\fP overrides this environment variable if both
are given.
.SS CTEST_OUTPUT_ON_FAILURE
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Boolean environment variable that controls if the output should be logged for
failed tests. Set the value to \fB1\fP, \fBTrue\fP, or \fBON\fP to enable output on failure.
See \fI\%ctest(1)\fP for more information on controlling output of failed
tests.
.SS CTEST_PARALLEL_LEVEL
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Specify the number of tests for CTest to run in parallel.
For example, if \fBCTEST_PARALLEL_LEVEL\fP is set to 8, CTest will run
up to 8 tests concurrently as if \fBctest\fP were invoked with the
\fI\%\-\-parallel 8\fP option.
.sp
See \fI\%ctest(1)\fP for more information on parallel test execution.
.SS CTEST_PROGRESS_OUTPUT
.sp
New in version 3.13.

.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Boolean environment variable that affects how \fI\%ctest\fP
command output reports overall progress.  When set to \fB1\fP, \fBTRUE\fP, \fBON\fP 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.
.sp
The \fI\%\-\-progress\fP option to \fI\%ctest\fP
overrides this environment variable if both are given.
.SS CTEST_USE_LAUNCHERS_DEFAULT
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Initializes the \fI\%CTEST_USE_LAUNCHERS\fP variable if not already defined.
.SS DASHBOARD_TEST_FROM_CTEST
.sp
This is a CMake \fI\%Environment Variable\fP\&. Its initial value is taken from
the calling process environment.
.sp
Environment variable that will exist when a test executed by \fI\%ctest(1)\fP
is run in non\-interactive mode.  The value will be equal to
\fI\%CMAKE_VERSION\fP\&.
.SH ENVIRONMENT VARIABLES FOR THE CMAKE CURSES INTERFACE
.SS CCMAKE_COLORS
.sp
New in version 3.18.

.sp
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 \fBLS_COLORS\fP;
that is, a list of key/value pairs separated by \fB:\fP\&.
.sp
Keys are a single letter corresponding to a CMake cache variable type:
.INDENT 0.0
.IP \(bu 2
\fBs\fP: A \fBSTRING\fP\&.
.IP \(bu 2
\fBp\fP: A \fBFILEPATH\fP\&.
.IP \(bu 2
\fBc\fP: A value which has an associated list of choices.
.IP \(bu 2
\fBy\fP: A \fBBOOL\fP which has a true\-like value (e.g. \fBON\fP, \fBYES\fP).
.IP \(bu 2
\fBn\fP: A \fBBOOL\fP which has a false\-like value (e.g. \fBOFF\fP, \fBNO\fP).
.UNINDENT
.sp
Values are an integer number that specifies what color to use.
\fB0\fP is black (you probably don\(aqt want to use that).
Others are determined by your terminal\(aqs 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
\fI\%this chart\fP,
although the first 16 colors may match the original
\fI\%CGA color palette\fP\&.
(Many modern terminal emulators also allow their color palette,
at least for the first 16 colors, to be configured by the user.)
.sp
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.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CCMAKE_COLORS=\(aqs=39:p=220:c=207:n=196:y=46\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.