CMAKE-ENV-VARIABLES(7)

📦
version 4.4.5 · 21 versions
, in arch rolling

✨ CMAKE-ENV-VARIABLES(7) ✨

okay bestie, welcome to the cmake-env-variables glow-up 💅 this is the CMake manual page for CMake Environment Variables Reference — and no, we are not skipping a single one, there's a whole lotta lore here.

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

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

💖 ENVIRONMENT VARIABLES THAT CHANGE BEHAVIOR 💖

🎀 CLICOLOR 🎀

Added in version 3.21.

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

Set to 0 to tell command-line tools not to print color messages even if connected to a terminal. This is a common convention among command-line tools in general, fr fr.

See also the NO_COLOR and CLICOLOR_FORCE environment variables. If either of them is activated, it takes precedence over CLICOLOR. 👑

See the CMAKE_COLOR_DIAGNOSTICS variable to control color in a generated build system.

🎀 CLICOLOR_FORCE 🎀

Added in version 3.5.

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

Set to a non-empty value, other than 0, to tell command-line tools to print color messages even if not connected to a terminal. Also a common convention among command-line tools in general. slay.

See also the NO_COLOR and CLICOLOR environment variables. If NO_COLOR is activated, it takes precedence over CLICOLOR_FORCE. Otherwise, if CLICOLOR_FORCE is activated, it takes precedence over CLICOLOR. the hierarchy is real 💀

See the CMAKE_COLOR_DIAGNOSTICS variable to control color in a generated build system.

🎀 CMAKE_APPBUNDLE_PATH 🎀

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

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

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

See also the CMAKE_APPBUNDLE_PATH CMake variable.

🎀 CMAKE_FRAMEWORK_PATH 🎀

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

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

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

See also the CMAKE_FRAMEWORK_PATH CMake variable.

🎀 CMAKE_INCLUDE_PATH 🎀

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

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

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

See also the CMAKE_INCLUDE_PATH CMake variable.

🎀 CMAKE_LIBRARY_PATH 🎀

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

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

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

See also the CMAKE_LIBRARY_PATH CMake variable.

🎀 CMAKE_MAXIMUM_RECURSION_DEPTH 🎀

Added in version 3.27.

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

Maximum recursion depth for CMake scripts. This environment variable is used if the CMAKE_MAXIMUM_RECURSION_DEPTH variable is not set. See that variable's documentation for details. 🌀 (yes, it can go deeper, no, you probs shouldn't)

🎀 CMAKE_POLICY_VERSION_MINIMUM 🎀

Added in version 4.0.

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

The default value for CMAKE_POLICY_VERSION_MINIMUM when there is no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_POLICY_VERSION_MINIMUM. ✨ set it once, and it lowkey lives there rent free

🎀 CMAKE_PREFIX_PATH 🎀

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

The CMAKE_PREFIX_PATH environment variable may be set to a list of directories specifying installation prefixes to be searched by the find_package(), find_program(), find_library(), find_file(), and find_path() commands. Each command will add appropriate subdirectories (like bin, lib, or include) as specified in its own documentation. 👑

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

See also the CMAKE_PREFIX_PATH CMake variable.

🎀 CMAKE_PROGRAM_PATH 🎀

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

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

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

See also the CMAKE_PROGRAM_PATH CMake variable.

🎀 CMAKE_TLS_VERIFY 🎀

Added in version 3.30.

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

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

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

🎀 CMAKE_TLS_VERSION 🎀

Added in version 3.30.

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

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

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

🎀 NO_COLOR 🎀

Added in version 4.1.

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

Set to a non-empty value, other than 0, to tell command-line tools not to print color messages even if connected to a terminal. This is a common convention among command-line tools in general. 🚫🌈

See also the CLICOLOR_FORCE and CLICOLOR environment variables. If NO_COLOR is activated, it takes precedence over both of them. 👑 periodt, it's the main character here

See the CMAKE_COLOR_DIAGNOSTICS variable to control color in a generated build system.

🎀 SSL_CERT_DIR 🎀

Added in version 3.25.

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

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

🎀 SSL_CERT_FILE 🎀

Added in version 3.25.

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

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

🌸 ENVIRONMENT VARIABLES THAT CONTROL THE BUILD 🌸

🎀 ADSP_ROOT 🎀

Added in version 3.24.

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

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

🎀 CMAKE_APPLE_SILICON_PROCESSOR 🎀

Added in version 3.19.2.

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

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

more iconic env vars incoming in part 2, don't touch that dial bestie 🦋

The CMAKE_APPLE_SILICON_PROCESSOR normal variable — yeah, that one — if it's set, it straight up overrides this environment variable. periodt 💅

  • CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY — added in version 4.2 ✨

Okay so this is a CMake Environment Variable, and its initial value is taken from the calling process environment (iykyk, that's how all of these roll).

CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY is a string that specifies the strategy to use for autogen-related target intermediate directories. It initializes the CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY variable. Basically it's the vibe-setter, and the variable copies the vibe 🎀

  • CMAKE_BUILD_PARALLEL_LEVEL — added in version 3.12 🔥

CMake Environment Variable, initial value taken from the calling process environment, you know the drill bestie.

This one specifies the maximum number of concurrent processes to use when building via the cmake --build command line Build Tool Mode. For example, if CMAKE_BUILD_PARALLEL_LEVEL is set to 8, the underlying build tool will execute up to 8 jobs concurrently — as if cmake --build were invoked with the --parallel 8 option. She's multitasking, she's iconic 👑

If this variable is defined empty, the native build tool's default number is used. (Empty means "no thoughts, head empty, use your own default" 💀)

  • CMAKE_BUILD_TYPE — added in version 3.22 🌸

CMake Environment Variable, initial value from the calling process environment.

The CMAKE_BUILD_TYPE environment variable specifies a default value for the CMAKE_BUILD_TYPE variable when there's no explicit configuration given on the first run while creating a new build tree. First impressions only, bestie — after that it's somebody else's job 💅

  • CMAKE_COLOR_DIAGNOSTICS — added in version 3.24 🌈

CMake Environment Variable, initial value from the calling process environment.

Specifies a default value for the CMAKE_COLOR_DIAGNOSTICS variable when there is no explicit value given on the first run. Pastel terminal output, we love to see it 🎨

  • CMAKE_CONFIG_DIR — added in version 3.31 🦋

CMake Environment Variable, initial value from the calling process environment.

Specify a CMake user-wide configuration directory for cmake-file-api(7) and cmake-instrumentation(7) queries. It's giving "where do I keep my stuff" energy.

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

  • Windows: %LOCALAPPDATA%\CMake
  • macOS: $XDG_CONFIG_HOME/CMake if set, otherwise $HOME/Library/Application Support/CMake
  • Linux/Other: $XDG_CONFIG_HOME/cmake if set, otherwise $HOME/.config/cmake
Not me noticing macOS and Linux use different capitalisation of CMake/cmake — that's not a typo on my end, that's literally what the page says, so don't come for me 🙈
  • CMAKE_CONFIG_TYPE — 🌟

CMake Environment Variable, initial value from the calling process environment.

The default build configuration for Build a Project and the ctest build handler when there's no explicit configuration given. Default queen behavior 👑

  • CMAKE_CONFIGURATION_TYPES — added in version 3.22 💜

CMake Environment Variable, initial value from the calling process environment.

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

  • CMAKE_CROSSCOMPILING_EMULATOR — added in version 3.28 🧚

CMake Environment Variable, initial value from the calling process environment.

The default value for CMAKE_CROSSCOMPILING_EMULATOR when there's no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree, the value persists in the cache as CMAKE_CROSSCOMPILING_EMULATOR. She lives in the cache now, she pays rent 😭

  • CMAKE_DISABLE_PRECOMPILE_HEADERS — added in version 4.4 ⭐

CMake Environment Variable, initial value from the calling process environment.

The default value for the CMAKE_DISABLE_PRECOMPILE_HEADERS variable when there's no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_DISABLE_PRECOMPILE_HEADERS. Same cache situation, no cap 🫶

  • CMAKE_EXPORT_BUILD_DATABASE — added in version 3.31 🍓

CMake Environment Variable, initial value from the calling process environment.

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

Note: This variable is meaningful only when experimental support for build databases has been enabled by the CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE gate. Otherwise she's just standing there. Experimental, gatekept, main character energy 🔥
  • CMAKE_EXPORT_COMPILE_COMMANDS — added in version 3.17 💖

CMake Environment Variable, initial value from the calling process environment.

The default value for CMAKE_EXPORT_COMPILE_COMMANDS when there's no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree the value persists in the cache as CMAKE_EXPORT_COMPILE_COMMANDS. Iconic compile_commands.json moment, we stan 📓

  • CMAKE_FASTBUILD_VERBOSE_GENERATOR — added in version 4.2 ✨

CMake Environment Variable, initial value from the calling process environment.

The CMAKE_FASTBUILD_VERBOSE_GENERATOR environment variable specifies a custom default value for the CMAKE_FASTBUILD_VERBOSE_GENERATOR variable, in place of the default values specified by CMake itself. You're overriding the factory settings, you're customising your avatar 💅

  • CMAKE_GENERATOR — added in version 3.15 🎀

CMake Environment Variable, initial value from the calling process environment.

Specifies the CMake default generator to use when no generator is supplied with -G. If the provided value doesn't name a generator known by CMake, the internal default is used. Either way, the resulting generator selection is stored in the CMAKE_GENERATOR variable. So like — you tried, and if it didn't work out, CMake picks for you, and either way the receipt goes in CMAKE_GENERATOR 😌

Some generators may be additionally configured using the environment variables:

  • CMAKE_GENERATOR_PLATFORM
  • CMAKE_GENERATOR_TOOLSET
  • CMAKE_GENERATOR_INSTANCE
  • CMAKE_GENERATOR_INSTANCE — added in version 3.15 🌸

CMake Environment Variable, initial value from the calling process environment.

Default value for CMAKE_GENERATOR_INSTANCE if no Cache entry is present. This value is only applied if CMAKE_GENERATOR is set — she does not show up to a party she wasn't invited to 🙈

  • CMAKE_GENERATOR_PLATFORM — added in version 3.15 🌈

CMake Environment Variable, initial value from the calling process environment.

Default value for CMAKE_GENERATOR_PLATFORM if no Cache entry is present and no value is specified by the cmake -A option. This value is only applied if CMAKE_GENERATOR is set. Two conditions and a plus-one, she's picky and honestly? Valid 💅

  • CMAKE_GENERATOR_TOOLSET — added in version 3.15 🦋

CMake Environment Variable, initial value from the calling process environment.

Default value for CMAKE_GENERATOR_TOOLSET if no Cache entry is present and no value is specified by the cmake -T option. This value is only applied if CMAKE_GENERATOR is set. Same rules, different flag, you got this bestie 🫶

  • CMAKE_INSTALL_MODE — added in version 3.22 💀

CMake Environment Variable, initial value from the calling process environment.

Okay this one is actually so fun. The CMAKE_INSTALL_MODE environment variable allows users to operate CMake in an alternate mode of file(INSTALL) and install().

The default behavior for an installation is to copy a source file from a source directory into a destination directory. This environment variable, however, allows the user to override this behavior, causing CMake to create symbolic links instead. It's giving "why duplicate when you could just point at it" 🔗

💫 Usage Scenarios

Installing symbolic links rather than copying files can help in the following ways — all of these are lowkey genius:

  • Conserving storage space, because files do not have to be duplicated on disk. Your drive said thank you 🍓
  • Changes to the source of the symbolic link are seen at the install destination without having to re-run the install step. Live updates, no rebuild, we love her.
  • Editing through the link at the install destination will modify the source of the link. This may be useful when dealing with CMake project hierarchies — i.e. using ExternalProject — and consistent source navigation and refactoring is desired across projects. Sneaky? A little. Useful? Extremely 😭

🎯 Allowed Values

The following values are allowed for CMAKE_INSTALL_MODE:

  • COPY, empty or unset — Duplicate the file at its destination. This is the default behavior. The safe, familiar, "we've been doing this forever" option 💅
  • ABS_SYMLINK — Create an absolute symbolic link to the source file at the destination. Halt with an error if the link cannot be created. No plan B, no backup — it's absolute in more ways than one 🔥
  • ABS_SYMLINK_OR_COPY — Like ABS_SYMLINK, but fall back to silently copying if the symlink couldn't be created. She's flexible, she's got a safety net 🫶
  • REL_SYMLINK — Create a relative symbolic link to the source file at the destination. Halt with an error if the link cannot be created. Same energy as ABS_SYMLINK, but she keeps things local ✨
  • REL_SYMLINK_OR_COPY — Like REL_SYMLINK, but fall back to silently copying if the symlink couldn't be created. Relative and forgiving, the whole package 🌸
  • SYMLINK — Try as if through REL_SYMLINK and fall back to ABS_SYMLINK if the referenced file cannot be expressed using a relative path. Halt with an error if the link cannot be created. She tries relative first (respectful), goes absolute if she has to (dramatic), and if neither works she's throwing hands — I mean an error ⭐
Friendly reminder from your girl: anything that says "halt with an error" means it actually stops. It's not bluffing. Read the value you picked before you set it 🙈
  • SYMLINK_OR_COPY — basically SYMLINK with a safety net 🫶. It tries to make the symlink, and if that symlink couldn't be created, it just silently falls back to copying. No drama, no error, it just quietly copies instead.
Note 💅: a symbolic link isn't really a file with its own contents — it's a reference file path. So there are two ways to express that relation: either by a relative path or by an absolute path. Both are valid, bestie.

When To Set The Environment Variable ⏰

Okay so timing matters here — for the environment variable to actually take effect, it has to be set during the correct build phase(s). Which phase? Depends:

  • If the project calls file(INSTALL) directly, the environment variable must be set during the configuration phase.
  • To apply to install(), the environment variable must be set during installation. That could be during a build, if you're using the install or package build targets — or separate from the build, when you invoke an install or run cpack(1) straight from the command line.
  • When using ExternalProject, you might need it during the build phase, because the external project's own configure, build and install steps all execute during the main project's build phase.

So given all of that 😮‍💨, the recommendation is: set the environment variable consistently across all phases — configure, build and install. All three. Every time. Consistency is the vibe.

Caveats 💀

Use this environment variable with caution, fr fr. Here's what you need to keep in mind:

  • CMAKE_INSTALL_MODE only affects files, not directories.
  • Symbolic links are not available on all platforms. Not every system can slay like that.
  • The way this environment variable interacts with the install step of ExternalProject is more complex. For the full details, go read that module's documentation — it's giving essay.
  • A symbolic link ties the destination to the source in a persistent way. Writing to either one of the two affects both file system objects. That's the opposite of 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 the destination of the install. Two completely different lifetimes, bestie.
  • Combining CMAKE_INSTALL_MODE with IOS_INSTALL_COMBINED is not supported. Don't try it. 🙈
  • Changing CMAKE_INSTALL_MODE from what it was on a previous run can lead to unexpected results. Moving from a non-symlinking mode to a symlinking mode will discard any previous file at the destination — but the reverse is not true. Once a symlink exists at the destination, even if you switch to a non-symlink mode, that symlink will continue to exist at the destination and will not be replaced by an actual file. It just stays there. Iconic but also terrifying.

🌈 CMAKE_INSTALL_PARALLEL_LEVEL

Added in version 3.31.

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

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

Lowkey it has no impact unless INSTALL_PARALLEL is enabled. So if you're not using that, this one's just sitting there being decorative. ✨

🎀 CMAKE_INSTALL_PREFIX

Added in version 3.29.

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

The CMAKE_INSTALL_PREFIX environment variable specifies a custom default value for the CMAKE_INSTALL_PREFIX variable, in place of the default values specified by CMake itself. And heads up: the value you specify must be an absolute path to a directory. No relative-path shenanigans. 🚫

🦋 CMAKE_INTERMEDIATE_DIR_STRATEGY

Added in version 4.2.

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

CMAKE_INTERMEDIATE_DIR_STRATEGY is a string specifying the strategy to use for target intermediate directories. Basically it initializes the CMAKE_INTERMEDIATE_DIR_STRATEGY variable. That's the whole gig. 💅

⭐ CMAKE_<LANG>_COMPILER_LAUNCHER

Added in version 3.17.

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

This is the default compiler launcher to use for the specified language. Key detail tho: CMake will only use it to initialize the variable on the first configuration. Afterwards, it's available through the cache setting of the variable of the same name. And for any configuration run (including the very first one), the environment variable will be ignored if the CMAKE_<LANG>_COMPILER_LAUNCHER variable is already defined. Already-defined wins, always. 👑

Added in version 3.27.

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

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

What's it for? Working around misconfigured compiler drivers that pass extraneous implicit link directories to their linker. Little cleanup crew. 🧹

See also the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES_EXCLUDE environment variable — they're a matching set. 🫶

Added in version 4.1.

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

A semicolon-separated list of libraries to exclude from the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES variable when it's automatically detected from the <LANG> compiler.

This one's for working around detection limitations that result in extraneous implicit link libraries — for example when you're using compiler driver flags that affect the set of implicitly linked libraries. So if the detection gets a little too enthusiastic, this is your fix. 💅

See also the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES_EXCLUDE environment variable.

🔥 CMAKE_<LANG>_LINKER_LAUNCHER

Added in version 3.21.

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

The default launcher to use when linking a target of the specified language. Same rules as the compiler launcher, bestie: CMake will only use it to initialize the variable on the first configuration, and afterwards it's available through the cache setting of the variable of the same name. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_<LANG>_LINKER_LAUNCHER variable is defined. 🙅‍♀️

🍓 CMAKE_MSVCIDE_RUN_PATH

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

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

The CMAKE_MSVCIDE_RUN_PATH environment variable sets the default value for the CMAKE_MSVCIDE_RUN_PATH variable if it's not already explicitly set. If you already set it yourself, congrats, it stays yours. ✨

🧚 CMAKE_NO_VERBOSE

Added in version 3.14.

Disables verbose output from CMake when the VERBOSE environment variable is set. So yes — you set VERBOSE, but this one says "not today". 💀

Only your build tool of choice will still print verbose output when you start to actually build your project. So the build tool keeps yapping, CMake goes quiet. Balance. ⚖️

👑 CMAKE_OSX_ARCHITECTURES

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

Target specific architectures for macOS. 🍎

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

🌈 CMAKE_TEST_LAUNCHER

Added in version 3.29.

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

The default value for the CMAKE_TEST_LAUNCHER variable when there's no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree, the value persists in the cache as CMAKE_TEST_LAUNCHER. So the first run decides, and then the cache remembers forever. Memory like an elephant. 🐘

🎀 CMAKE_TOOLCHAIN_FILE

Added in version 3.21.

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

The CMAKE_TOOLCHAIN_FILE environment variable specifies a default value for the CMAKE_TOOLCHAIN_FILE variable when there's no explicit configuration given on the first run while creating a new build tree. On later runs in an existing build tree, the value persists in the cache as CMAKE_TOOLCHAIN_FILE. Same deal as above — first run sets the vibe, cache keeps it. 💾

🫶 DESTDIR

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

On UNIX you can use the DESTDIR mechanism to relocate the whole installation. DESTDIR means DESTination DIRectory (yes, that's really what it stands for 😭). It's commonly used by packagers to install software in a staging directory.

For example, running:

make DESTDIR=/package/stage install

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

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

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

⭐ LDFLAGS

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

So anyway — the rest of the LDFLAGS tea ☕: it only gets used by CMake on the first configuration, to figure out the default linker flags. After that, the value for LDFLAGS is stored in the cache as CMAKE_EXE_LINKER_FLAGS_INIT, CMAKE_SHARED_LINKER_FLAGS_INIT, and CMAKE_MODULE_LINKER_FLAGS_INIT. And for any configuration run (first one included, bestie 💅), the environment variable gets ignored if the equivalent CMAKE_<TYPE>_LINKER_FLAGS_INIT variable is defined. Cache wins, env loses, that's the rule.

MACOSX_DEPLOYMENT_TARGET 🍎

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

It specifies the minimum version of macOS that the target binaries are gonna be deployed on.

Basically, MACOSX_DEPLOYMENT_TARGET sets the default value for the CMAKE_OSX_DEPLOYMENT_TARGET variable. Iconic, no notes. ✨

<PackageName>_ROOT 📦

Added in version 3.12.

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

When you call find_package(<PackageName>), it will search in the prefixes specified by the <PackageName>_ROOT environment variable — where <PackageName> is the name you gave to the find_package() call (case-preserved, so watch the caps 👀) and _ROOT is literal, like, actual characters. So for example, find_package(Foo) will search the prefixes in the Foo_ROOT environment variable (if it's set). See policy CMP0074.

This variable can hold a single prefix, or a list of prefixes separated by : on UNIX or ; on Windows — literally the same convention as the PATH environment variable on those platforms. Slay.

See also the <PackageName>_ROOT CMake variable.

<PACKAGENAME>_ROOT 🔠

Added in version 3.27.

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

Note: bestie, the <PackageName>_ROOT and <PACKAGENAME>_ROOT environment variables are distinct only on platforms that have case-sensitive environments. Lowkey important. 🫶

VERBOSE 🗣️

Added in version 3.14.

This activates verbose output from CMake and from whatever build tools you chose, at the moment you actually start building your project.

Note that any given value is ignored. It's just checked for existence. So VERBOSE=1, VERBOSE=yes, VERBOSE=lmao — all the same vibe check. 😌

See also Build Tool Mode and the CMAKE_NO_VERBOSE environment variable.

✨ ENVIRONMENT VARIABLES FOR LANGUAGES ✨

ASM<DIALECT> 🛠️

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

This is your preferred executable for compiling a specific dialect of assembly language files. ASM<DIALECT> can be one of:

  • ASM
  • ASM_NASM (Netwide Assembler)
  • ASM_MASM (Microsoft Assembler)
  • ASM_MARMASM (Microsoft ARM Assembler)
  • ASM_POASM (Pelles Macro Assembler)
  • ASM-ATT (Assembler AT&T)

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

Note: options that are required to make the compiler work correctly can be included — but they cannot be changed afterward. So commit, bestie. 💀 $ export ASM="custom-compiler --arg1 --arg2"

ASM<DIALECT>FLAGS 🏴‍☠️

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

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

  • ASMFLAGS
  • ASM_NASMFLAGS
  • ASM_MASMFLAGS
  • ASM_MARMASMFLAGS
  • ASM_POASMFLAGS
  • ASM-ATTFLAGS

CMake takes this environment variable's value, combines it with its own builtin default flags for the toolchain, and uses that to initialize and store the CMAKE_ASM<DIALECT>_FLAGS cache entry. This happens the first time a build tree is configured for language ASM<DIALECT>. And for any configuration run (first one included), the environment variable gets ignored if the CMAKE_ASM<DIALECT>_FLAGS variable is already defined.

See also CMAKE_ASM<DIALECT>_FLAGS_INIT. 🎀

CC 🅲

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

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

Note: options that are required to make the compiler work correctly can be included; they cannot be changed. $ export CC="custom-compiler --arg1 --arg2"

CFLAGS 🏁

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

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

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

See also CMAKE_C_FLAGS_INIT. 💖

CSFLAGS 🎯

Added in version 3.9.2.

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

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

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

See also CMAKE_CSharp_FLAGS_INIT. ✨

CUDAARCHS 🟩

Added in version 3.20.

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

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

It's a semicolon-separated list of architectures, as described in CUDA_ARCHITECTURES. Go off, GPU girlies. 👑

CUDACXX 💚

Added in version 3.8.

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

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

Note: options that are required to make the compiler work correctly can be included; they cannot be changed. $ export CUDACXX="custom-compiler --arg1 --arg2"

CUDAFLAGS 🧪

Added in version 3.8.

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

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

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

See also CMAKE_CUDA_FLAGS_INIT. 🌈

CUDAHOSTCXX 🖥️

Added in version 3.8.

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

Your preferred executable for compiling host code when compiling CUDA language files. Will only be used by CMake on the first configuration to determine the CUDA host compiler, after which the value for CUDAHOSTCXX is stored in the cache as CMAKE_CUDA_HOST_COMPILER. This environment variable is preferred over CMAKE_CUDA_HOST_COMPILER. Env beats variable here, main character energy fr fr. 💅

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

Note: ignored when using Visual Studio Generators.

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

CXX ➕➕

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

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

Note: options that are required to make the compiler work correctly can be included; they cannot be changed. $ export CXX="custom-compiler --arg1 --arg2"

💜 CXXFLAGS

Okay so first things first: this is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

It adds default compilation flags that get used when compiling CXX (C++) files.

CMake takes this environment variable's value — together with its own builtin default flags for the toolchain — to initialize and store the CMAKE_CXX_FLAGS cache entry. This happens the first time a build tree is configured for language CXX. And for any configuration run (including the first one, bestie, no exceptions 💅), the environment variable gets ignored if the CMAKE_CXX_FLAGS variable is already defined.

See also CMAKE_CXX_FLAGS_INIT.

🧚 FC

This is a CMake Environment Variable too, and its initial value is taken from the calling process environment.

It's the preferred executable for compiling Fortran language files. CMake will only use it on the first configuration to determine the Fortran compiler, and after that the value for Fortran is stored in the cache as CMAKE_Fortran_COMPILER. For any configuration run (including the first), the environment variable is ignored if the CMAKE_Fortran_COMPILER variable is defined.

Note: options that are required to make the compiler work correctly can be included — but they can not be changed. 🫶
$ export FC="custom-compiler --arg1 --arg2"

🌸 FFLAGS

This is a CMake Environment Variable — initial value taken from the calling process environment, as always.

It adds default compilation flags to be used when compiling Fortran files.

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

See also CMAKE_Fortran_FLAGS_INIT.

🔥 HIPCXX

Added in version 3.21. ⭐

This is a CMake Environment Variable, and its initial value is taken from the calling process environment.

It's the preferred executable for compiling HIP language files. CMake will only use it on the first configuration to determine the HIP compiler, after which the value for HIP is stored in the cache as CMAKE_HIP_COMPILER. For any configuration run (including the first), the environment variable will be ignored if the CMAKE_HIP_COMPILER variable is defined.

💀 HIPFLAGS

Added in version 3.21. ⭐

This is a CMake Environment Variable, initial value straight outta the calling process environment.

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

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

See also CMAKE_HIP_FLAGS_INIT.

👑 HIPHOSTCXX

Added in version 3.28. ⭐

This is a CMake Environment Variable, and its initial value is taken from the calling process environment.

It's the preferred executable for compiling host code when compiling HIP language files with the NVIDIA CUDA Compiler. CMake will only use it on the first configuration to determine the HIP host compiler, after which the value for HIPHOSTCXX is stored in the cache as CMAKE_HIP_HOST_COMPILER.

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

Note: it's ignored when using Visual Studio Generators. 🙈

🦋 ISPC

Added in version 3.19. ⭐

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

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

🎀 ISPCFLAGS

Added in version 3.19. ⭐

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

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

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

See also CMAKE_ISPC_FLAGS_INIT.

🌈 OBJC

Added in version 3.16.7. ⭐

This is a CMake Environment Variable, and its initial value is taken from the calling process environment.

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

And if OBJC is not defined, the CC environment variable will be checked instead. 🫶

🍓 OBJCFLAGS

Added in version 3.16. ⭐

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

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

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

See also CMAKE_OBJC_FLAGS_INIT.

💖 OBJCXX

Added in version 3.16.7. ⭐

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

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

And if OBJCXX is not defined, the CXX environment variable will be checked instead. ✨

🌟 OBJCXXFLAGS

Added in version 3.16. ⭐

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

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

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

See also CMAKE_OBJCXX_FLAGS_INIT.

🧵 RC

This is a CMake Environment Variable, and its initial value is taken from the calling process environment.

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

Note: options that are required to make the compiler work correctly can be included — but they can not be changed. 💅
$ export RC="custom-compiler --arg1 --arg2"

🫧 RCFLAGS

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

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

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

See also CMAKE_RC_FLAGS_INIT.

🐦 SWIFTC

Added in version 3.15. ⭐

This is a CMake Environment Variable, and its initial value is taken from the calling process environment.

SWIFTC is the preferred executable for compiling Swift language files, bestie. CMake will only use it on the first configuration to determine the Swift compiler, and after that the value for SWIFTC gets stored in the cache as CMAKE_Swift_COMPILER. And for any configuration run (yep, including the very first one), the environment variable gets ignored if the CMAKE_Swift_COMPILER variable is already defined. 🙈

Note, and this one matters: options that are required to make the compiler work correctly can be included — but they can not be changed. So like: console $ export SWIFTC="custom-compiler --arg1 --arg2"

🧪 ENVIRONMENT VARIABLES FOR CTEST 🧪

CTEST_INTERACTIVE_DEBUG_MODE

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

CTEST_NO_TESTS_ACTION

Added in version 3.26.

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

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

When ctest --preset is used, this environment variable, if set, takes precedence over the noTestsAction field of the selected test preset. This includes the case where the variable is instead set via the preset's own environment field, which is equivalent to setting it in the calling process's environment. An explicit --no-tests=<action> on the command line takes precedence over all of the above.

This environment variable, including when set via a test preset's environment field, is also respected when that same preset is used by a ctest_test() command in a Dashboard Client via CTest Script. However — and this is the plot twist — in that case, the preset's noTestsAction field itself has no effect, because ctest_test() has no equivalent argument to apply it through. 😭

CTEST_OUTPUT_ON_FAILURE

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

CTEST_PARALLEL_LEVEL

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

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

CTest will interpret a whitespace-only string as empty.

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

This environment variable is ignored if ctest --parallel is given on the command line, and is overridden by the jobs field of a test preset, if that field is set.

A test preset may also set this variable itself, using its own environment field. Doing so is equivalent to setting the variable in the calling process's environment, except that it takes effect only for the preset's Test step, and only if execution.jobs is not also set (which would take precedence, as noted above).

When a test preset is used by a ctest_test() command in a Dashboard Client via CTest Script, that command's own PARALLEL_LEVEL argument, if given, takes precedence over the preset's execution.jobs field. Together, PARALLEL_LEVEL and execution.jobs take precedence not only over this environment variable, but over an explicit ctest --parallel on the command line as well. This differs from a preset used directly via ctest --preset, where an explicit --parallel always wins over the preset's execution.jobs field. 🫶

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

CTEST_PROGRESS_OUTPUT

Added in version 3.13.

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

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

CTEST_USE_INSTRUMENTATION

Added in version 4.3.

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

Setting this environment variable to 1, True, or ON enables instrumentation for CTest in Dashboard Client mode.

CTEST_USE_LAUNCHERS_DEFAULT

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

Initializes the CTEST_USE_LAUNCHERS variable if not already defined.

CTEST_USE_VERBOSE_INSTRUMENTATION

Added in version 4.3.

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

Setting this environment variable to 1, True, or ON causes CTest to report the full command line (including arguments) to CDash for each instrumented command. By default, CTest truncates the command line at the first space. 😮

See also CTEST_USE_INSTRUMENTATION.

DASHBOARD_TEST_FROM_CTEST

This is a CMake Environment Variable, and its initial value is taken from the calling process environment. ✨

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

🎨 ENVIRONMENT VARIABLES FOR THE CMAKE CURSES INTERFACE 🎨

CCMAKE_COLORS

Added in version 3.18.

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

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

  • s: A STRING.
  • p: A FILEPATH.
  • c: A value which has an associated list of choices.
  • y: A BOOL which has a true-like value (e.g. ON, YES).
  • n: A BOOL which has a false-like value (e.g. OFF, NO).

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

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

For example:

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

2000-2026 Kitware, Inc. and Contributors

Okay bestie, that's the whole page — you made it to the end, and honestly? Iconic. 🎀 The source is version 4.4.5, dated Oct 28, 2026, and this little manpage rewrite is officially a wrap. Go forth and configure slayfully. 👑💖

📦 where this page comes from