.\" 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" "February 06, 2024" "3.28.3" "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\&.
.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_<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_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
.EX
make DESTDIR=/package/stage install
.EE
.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
.EX
$ export ASM=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export CC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export CUDACXX=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export CXX=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export FC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export RC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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
.EX
$ export SWIFTC=\(dqcustom\-compiler \-\-arg1 \-\-arg2\(dq
.EE
.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. 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
.EX
CCMAKE_COLORS=\(aqs=39:p=220:c=207:n=196:y=46\(aq
.EE
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2024 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.