1CMAKE-VARIABLES(7) CMake CMAKE-VARIABLES(7)
2
6 cmake-variables - CMake Variables Reference
7 This page documents variables that are provided by CMake or have mean‐
9 ing to CMake when set by project code.
10 For general information on variables, see the Variables section in the
12 cmake-language manual.
13 NOTE:
15 CMake reserves identifiers that:
16 • begin with CMAKE_ (upper-, lower-, or mixed-case), or
18 • begin with _CMAKE_ (upper-, lower-, or mixed-case), or
20 • begin with _ followed by the name of any CMake Command.
22
24 CMAKE_AR
25 Name of archiving tool for static libraries.
26 This specifies the name of the program that creates archive or static
28 libraries.
29 CMAKE_ARGC
31 Number of command line arguments passed to CMake in script mode.
32 When run in -P script mode, CMake sets this variable to the number of
34 command line arguments. See also CMAKE_ARGV0, 1, 2 ...
35 CMAKE_ARGV0
37 Command line argument passed to CMake in script mode.
38 When run in -P script mode, CMake sets this variable to the first com‐
40 mand line argument. It then also sets CMAKE_ARGV1, CMAKE_ARGV2, ...
41 and so on, up to the number of command line arguments given. See also
42 CMAKE_ARGC.
43 CMAKE_BINARY_DIR
45 The path to the top level of the build tree.
46 This is the full path to the top level of the current CMake build tree.
48 For an in-source build, this would be the same as CMAKE_SOURCE_DIR.
49 When run in cmake -P script mode, CMake sets the variables CMAKE_BI‐
51 NARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
52 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
53 CMAKE_BUILD_TOOL
55 This variable exists only for backwards compatibility. It contains the
56 same value as CMAKE_MAKE_PROGRAM. Use that variable instead.
57 CMAKE_CACHE_MAJOR_VERSION
59 Major version of CMake used to create the CMakeCache.txt file
60 This stores the major version of CMake used to write a CMake cache
62 file. It is only different when a different version of CMake is run on
63 a previously created cache file.
64 CMAKE_CACHE_MINOR_VERSION
66 Minor version of CMake used to create the CMakeCache.txt file
67 This stores the minor version of CMake used to write a CMake cache
69 file. It is only different when a different version of CMake is run on
70 a previously created cache file.
71 CMAKE_CACHE_PATCH_VERSION
73 Patch version of CMake used to create the CMakeCache.txt file
74 This stores the patch version of CMake used to write a CMake cache
76 file. It is only different when a different version of CMake is run on
77 a previously created cache file.
78 CMAKE_CACHEFILE_DIR
80 This variable is used internally by CMake, and may not be set during
81 the first configuration of a build tree. When it is set, it has the
82 same value as CMAKE_BINARY_DIR. Use that variable instead.
83 CMAKE_CFG_INTDIR
85 Deprecated since version 3.21: This variable has poor support on Ninja
86 Multi-Config, and predates the existence of the $<CONFIG> generator ex‐
87 pression. Use $<CONFIG> instead.
88 Build-time reference to per-configuration output subdirectory.
91 For native build systems supporting multiple configurations in the
93 build tree (such as Visual Studio Generators and Xcode), the value is a
94 reference to a build-time variable specifying the name of the per-con‐
95 figuration output subdirectory. On Makefile Generators this evaluates
96 to . because there is only one configuration in a build tree. Example
97 values:
98 $(ConfigurationName) = Visual Studio 9
100 $(Configuration) = Visual Studio 11 and above
101 $(CONFIGURATION) = Xcode
102 . = Make-based tools
103 . = Ninja
104 ${CONFIGURATION} = Ninja Multi-Config
105 Since these values are evaluated by the native build system, this vari‐
107 able is suitable only for use in command lines that will be evaluated
108 at build time. Example of intended usage:
109 add_executable(mytool mytool.c)
111 add_custom_command(
112 OUTPUT out.txt
113 COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
114 ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
115 DEPENDS mytool in.txt
116 )
117 add_custom_target(drive ALL DEPENDS out.txt)
118 Note that CMAKE_CFG_INTDIR is no longer necessary for this purpose but
120 has been left for compatibility with existing projects. Instead
121 add_custom_command() recognizes executable target names in its COMMAND
122 option, so ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool can
123 be replaced by just mytool.
124 This variable is read-only. Setting it is undefined behavior. In
126 multi-configuration build systems the value of this variable is passed
127 as the value of preprocessor symbol CMAKE_INTDIR to the compilation of
128 all source files.
129 CMAKE_COMMAND
131 The full path to the cmake(1) executable.
132 This is the full path to the CMake executable cmake(1) which is useful
134 from custom commands that want to use the cmake -E option for portable
135 system commands. (e.g. /usr/local/bin/cmake)
136 CMAKE_CPACK_COMMAND
138 New in version 3.13.
139 Full path to cpack(1) command installed with CMake.
142 This is the full path to the CPack executable cpack(1) that can be used
144 for custom commands or tests to invoke CPack commands.
145 CMAKE_CROSSCOMPILING
147 This variable is set by CMake to indicate whether it is cross compil‐
148 ing, but note limitations discussed below.
149 This variable will be set to true by CMake if the CMAKE_SYSTEM_NAME
151 variable has been set manually (i.e. in a toolchain file or as a cache
152 entry from the cmake command line). In most cases, manually setting
153 CMAKE_SYSTEM_NAME will only be done when cross compiling since, if not
154 manually set, it will be given the same value as
155 CMAKE_HOST_SYSTEM_NAME, which is correct for the non-cross-compiling
156 case. In the event that CMAKE_SYSTEM_NAME is manually set to the same
157 value as CMAKE_HOST_SYSTEM_NAME, then CMAKE_CROSSCOMPILING will still
158 be set to true.
159 Another case to be aware of is that builds targeting Apple platforms
161 other than macOS are handled differently to other cross compiling sce‐
162 narios. Rather than relying on CMAKE_SYSTEM_NAME to select the target
163 platform, Apple device builds use CMAKE_OSX_SYSROOT to select the ap‐
164 propriate SDK, which indirectly determines the target platform. Fur‐
165 thermore, when using the Xcode generator, developers can switch between
166 device and simulator builds at build time rather than having a single
167 choice at configure time, so the concept of whether the build is cross
168 compiling or not is more complex. Therefore, the use of CMAKE_CROSSCOM‐
169 PILING is not recommended for projects targeting Apple devices.
170 CMAKE_CROSSCOMPILING_EMULATOR
172 New in version 3.3.
173 This variable is only used when CMAKE_CROSSCOMPILING is on. It should
176 point to a command on the host system that can run executable built for
177 the target system.
178 New in version 3.15: If this variable contains a semicolon-separated
180 list, then the first value is the command and remaining values are its
181 arguments.
182 The command will be used to run try_run() generated executables, which
185 avoids manual population of the TryRunResults.cmake file.
186 It is also used as the default value for the CROSSCOMPILING_EMULATOR
188 target property of executables.
189 CMAKE_CTEST_COMMAND
191 Full path to ctest(1) command installed with CMake.
192 This is the full path to the CTest executable ctest(1) that can be used
194 for custom commands or tests to invoke CTest commands.
195 CMAKE_CURRENT_BINARY_DIR
197 The path to the binary directory currently being processed.
198 This is the full path to the build directory that is currently being
200 processed by cmake. Each directory added by add_subdirectory() will
201 create a binary directory in the build tree, and as it is being pro‐
202 cessed this variable will be set. For in-source builds this is the
203 current source directory being processed.
204 When run in cmake -P script mode, CMake sets the variables
206 CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
207 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
208 CMAKE_CURRENT_FUNCTION
210 New in version 3.17.
211 When executing code inside a function(), this variable contains the
214 name of the current function. It can be useful for diagnostic or debug
215 messages.
216 See also CMAKE_CURRENT_FUNCTION_LIST_DIR,
218 CMAKE_CURRENT_FUNCTION_LIST_FILE and CMAKE_CURRENT_FUNCTION_LIST_LINE.
219 CMAKE_CURRENT_FUNCTION_LIST_DIR
221 New in version 3.17.
222 When executing code inside a function(), this variable contains the
225 full directory of the listfile that defined the current function.
226 It is quite common practice in CMake for modules to use some additional
228 files, such as templates to be copied in after substituting CMake vari‐
229 ables. In such cases, a function needs to know where to locate those
230 files in a way that doesn't depend on where the function is called.
231 Without CMAKE_CURRENT_FUNCTION_LIST_DIR, the code to do that would typ‐
232 ically use the following pattern:
233 set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
235 function(foo)
237 configure_file(
238 "${_THIS_MODULE_BASE_DIR}/some.template.in"
239 some.output
240 )
241 endfunction()
242 Using CMAKE_CURRENT_FUNCTION_LIST_DIR inside the function instead elim‐
244 inates the need for the extra variable which would otherwise be visible
245 outside the function's scope. The above example can be written in the
246 more concise and more robust form:
247 function(foo)
249 configure_file(
250 "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
251 some.output
252 )
253 endfunction()
254 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_FILE and
256 CMAKE_CURRENT_FUNCTION_LIST_LINE.
257 CMAKE_CURRENT_FUNCTION_LIST_FILE
259 New in version 3.17.
260 When executing code inside a function(), this variable contains the
263 full path to the listfile that defined the current function.
264 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
266 CMAKE_CURRENT_FUNCTION_LIST_LINE.
267 CMAKE_CURRENT_FUNCTION_LIST_LINE
269 New in version 3.17.
270 When executing code inside a function(), this variable contains the
273 line number in the listfile where the current function was defined.
274 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
276 CMAKE_CURRENT_FUNCTION_LIST_FILE.
277 CMAKE_CURRENT_LIST_DIR
279 Full directory of the listfile currently being processed.
280 As CMake processes the listfiles in your project this variable will al‐
282 ways be set to the directory where the listfile which is currently be‐
283 ing processed (CMAKE_CURRENT_LIST_FILE) is located. The value has dy‐
284 namic scope. When CMake starts processing commands in a source file it
285 sets this variable to the directory where this file is located. When
286 CMake finishes processing commands from the file it restores the previ‐
287 ous value. Therefore the value of the variable inside a macro or func‐
288 tion is the directory of the file invoking the bottom-most entry on the
289 call stack, not the directory of the file containing the macro or func‐
290 tion definition.
291 See also CMAKE_CURRENT_LIST_FILE.
293 CMAKE_CURRENT_LIST_FILE
295 Full path to the listfile currently being processed.
296 As CMake processes the listfiles in your project this variable will al‐
298 ways be set to the one currently being processed. The value has dy‐
299 namic scope. When CMake starts processing commands in a source file it
300 sets this variable to the location of the file. When CMake finishes
301 processing commands from the file it restores the previous value.
302 Therefore the value of the variable inside a macro or function is the
303 file invoking the bottom-most entry on the call stack, not the file
304 containing the macro or function definition.
305 See also CMAKE_PARENT_LIST_FILE.
307 CMAKE_CURRENT_LIST_LINE
309 The line number of the current file being processed.
310 This is the line number of the file currently being processed by cmake.
312 If CMake is currently processing deferred calls scheduled by the
314 cmake_language(DEFER) command, this variable evaluates to DEFERRED in‐
315 stead of a specific line number.
316 CMAKE_CURRENT_SOURCE_DIR
318 The path to the source directory currently being processed.
319 This is the full path to the source directory that is currently being
321 processed by cmake.
322 When run in cmake -P script mode, CMake sets the variables
324 CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
325 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
326 CMAKE_DEBUG_TARGET_PROPERTIES
328 Enables tracing output for target properties.
329 This variable can be populated with a list of properties to generate
331 debug output for when evaluating target properties. Currently it can
332 only be used when evaluating:
333 • AUTOUIC_OPTIONS
335 • COMPILE_DEFINITIONS
337 • COMPILE_FEATURES
339 • COMPILE_OPTIONS
341 • INCLUDE_DIRECTORIES
343 • LINK_DIRECTORIES
345 • LINK_OPTIONS
347 • POSITION_INDEPENDENT_CODE
349 • SOURCES
351 target properties and any other property listed in
353 COMPATIBLE_INTERFACE_STRING and other COMPATIBLE_INTERFACE_ properties.
354 It outputs an origin for each entry in the target property. Default is
355 unset.
356 CMAKE_DIRECTORY_LABELS
358 New in version 3.10.
359 Specify labels for the current directory.
362 This is used to initialize the LABELS directory property.
364 CMAKE_DL_LIBS
366 Name of library containing dlopen and dlclose.
367 The name of the library that has dlopen and dlclose in it, usually -ldl
369 on most UNIX machines.
370 CMAKE_DOTNET_SDK
372 New in version 3.23.
373 Default value for DOTNET_SDK property of targets.
376 This variable is used to initialize the DOTNET_SDK property on all tar‐
378 gets. See that target property for additional information.
379 CMAKE_DOTNET_TARGET_FRAMEWORK
381 New in version 3.17.
382 Default value for DOTNET_TARGET_FRAMEWORK property of targets.
385 This variable is used to initialize the DOTNET_TARGET_FRAMEWORK prop‐
387 erty on all targets. See that target property for additional informa‐
388 tion.
389 Setting CMAKE_DOTNET_TARGET_FRAMEWORK may be necessary when working
391 with C# and newer .NET framework versions to avoid referencing errors
392 with the ALL_BUILD CMake target.
393 This variable is only evaluated for Visual Studio Generators VS 2010
395 and above.
396 CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
398 New in version 3.12.
399 Default value for DOTNET_TARGET_FRAMEWORK_VERSION property of targets.
402 This variable is used to initialize the DOTNET_TARGET_FRAMEWORK_VERSION
404 property on all targets. See that target property for additional infor‐
405 mation. When set, CMAKE_DOTNET_TARGET_FRAMEWORK takes precednece over
406 this variable. See that variable or the associated target property
407 DOTNET_TARGET_FRAMEWORK for additional information.
408 Setting CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION may be necessary when
410 working with C# and newer .NET framework versions to avoid referencing
411 errors with the ALL_BUILD CMake target.
412 This variable is only evaluated for Visual Studio Generators VS 2010
414 and above.
415 CMAKE_EDIT_COMMAND
417 Full path to cmake-gui(1) or ccmake(1). Defined only for Makefile Gen‐
418 erators and Ninja Generators when not using any Extra Generators.
419 This is the full path to the CMake executable that can graphically edit
421 the cache. For example, cmake-gui(1) or ccmake(1).
422 CMAKE_EXECUTABLE_SUFFIX
424 The suffix for executables on this platform.
425 The suffix to use for the end of an executable filename if any, .exe on
427 Windows.
428 CMAKE_EXECUTABLE_SUFFIX_<LANG> overrides this for language <LANG>.
430 CMAKE_EXECUTABLE_SUFFIX_<LANG>
432 The suffix to use for the end of an executable filename of <LANG> com‐
433 piler target architecture, if any.
434 It overrides CMAKE_EXECUTABLE_SUFFIX for language <LANG>.
436 CMAKE_EXTRA_GENERATOR
438 Deprecated since version 3.27: Support for Extra Generators is depre‐
439 cated and will be removed from a future version of CMake. IDEs may use
440 the cmake-file-api(7) to view CMake-generated project build trees.
441 The extra generator used to build the project. See
444 cmake-generators(7).
445 When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime genera‐
447 tors, CMake generates Makefiles (CMAKE_GENERATOR) and additionally
448 project files for the respective IDE. This IDE project file generator
449 is stored in CMAKE_EXTRA_GENERATOR (e.g. Eclipse CDT4).
450 CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
452 Additional suffixes for shared libraries.
453 Extensions for shared libraries other than that specified by
455 CMAKE_SHARED_LIBRARY_SUFFIX, if any. CMake uses this to recognize ex‐
456 ternal shared library files during analysis of libraries linked by a
457 target.
458 CMAKE_FIND_DEBUG_MODE
460 New in version 3.17.
461 Print extra find call information for the following commands to stan‐
464 dard error:
465 • find_program()
467 • find_library()
469 • find_file()
471 • find_path()
473 • find_package()
475 Output is designed for human consumption and not for parsing. Enabling
477 this variable is equivalent to using cmake --debug-find with the added
478 ability to enable debugging for a subset of find calls.
479 set(CMAKE_FIND_DEBUG_MODE TRUE)
481 find_program(...)
482 set(CMAKE_FIND_DEBUG_MODE FALSE)
483 Default is unset.
485 CMAKE_FIND_PACKAGE_NAME
487 New in version 3.1.1.
488 Defined by the find_package() command while loading a find module to
491 record the caller-specified package name. See command documentation
492 for details.
493 CMAKE_FIND_PACKAGE_REDIRECTS_DIR
495 New in version 3.24.
496 This read-only variable specifies a directory that the find_package()
499 command will check first before searching anywhere else for a module or
500 config package file. A config package file in this directory will al‐
501 ways be found in preference to any other Find module file or config
502 package file.
503 The primary purpose of this variable is to facilitate integration be‐
505 tween find_package() and FetchContent_MakeAvailable(). The latter com‐
506 mand may create files in the CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory
507 when it populates a dependency. This allows subsequent calls to
508 find_package() for the same dependency to re-use the populated contents
509 instead of trying to satisfy the dependency from somewhere external to
510 the build. Projects may also want to write files into this directory
511 in some situations (see Integrating With find_package() for examples).
512 The directory that CMAKE_FIND_PACKAGE_REDIRECTS_DIR points to will al‐
514 ways be erased and recreated empty at the start of every CMake run.
515 Any files written into this directory during the CMake run will be lost
516 the next time CMake configures the project.
517 CMAKE_FIND_PACKAGE_REDIRECTS_DIR is only set in CMake project mode. It
519 is not set when CMake is run in script mode (i.e. cmake -P).
520 CMAKE_FIND_PACKAGE_SORT_DIRECTION
522 New in version 3.7.
523 The sorting direction used by CMAKE_FIND_PACKAGE_SORT_ORDER. It can
526 assume one of the following values:
527 DEC Default. Ordering is done in descending mode. The highest
529 folder found will be tested first.
530 ASC Ordering is done in ascending mode. The lowest folder found
532 will be tested first.
533 If CMAKE_FIND_PACKAGE_SORT_ORDER is not set or is set to NONE this
535 variable has no effect.
536 CMAKE_FIND_PACKAGE_SORT_ORDER
538 New in version 3.7.
539 The default order for sorting packages found using find_package(). It
542 can assume one of the following values:
543 NONE Default. No attempt is done to sort packages. The first valid
545 package found will be selected.
546 NAME Sort packages lexicographically before selecting one.
548 NATURAL
550 Sort packages using natural order (see strverscmp(3) manual),
551 i.e. such that contiguous digits are compared as whole numbers.
552 Natural sorting can be employed to return the highest version when mul‐
554 tiple versions of the same library are found by find_package(). For
555 example suppose that the following libraries have been found:
556 • libX-1.1.0
558 • libX-1.2.9
560 • libX-1.2.10
562 By setting NATURAL order we can select the one with the highest version
564 number libX-1.2.10.
565 set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
567 find_package(libX CONFIG)
568 The sort direction can be controlled using the
570 CMAKE_FIND_PACKAGE_SORT_DIRECTION variable (by default decrescent, e.g.
571 lib-B will be tested before lib-A).
572 CMAKE_GENERATOR
574 The generator used to build the project. See cmake-generators(7).
575 The name of the generator that is being used to generate the build
577 files. (e.g. Unix Makefiles, Ninja, etc.)
578 The value of this variable should never be modified by project code. A
580 generator may be selected via the cmake -G option, interactively in
581 cmake-gui(1), or via the CMAKE_GENERATOR environment variable.
582 CMAKE_GENERATOR_INSTANCE
584 New in version 3.11.
585 Generator-specific instance specification provided by user.
588 Some CMake generators support selection of an instance of the native
590 build system when multiple instances are available. If the user speci‐
591 fies an instance (e.g. by setting this cache entry or via the
592 CMAKE_GENERATOR_INSTANCE environment variable), or after a default in‐
593 stance is chosen when a build tree is first configured, the value will
594 be available in this variable.
595 The value of this variable should never be modified by project code. A
597 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
598 tialize CMAKE_GENERATOR_INSTANCE as a cache entry. Once a given build
599 tree has been initialized with a particular value for this variable,
600 changing the value has undefined behavior.
601 Instance specification is supported only on specific generators.
603 Visual Studio Instance Selection
605 Visual Studio Generators support instance specification for Visual Stu‐
606 dio 2017 and above. The CMAKE_GENERATOR_INSTANCE variable may be set
607 as a cache entry selecting an instance of Visual Studio via one of the
608 following forms:
609 • location
611 • location[,key=value]*
613 • key=value[,key=value]*
615 The location specifies the absolute path to the top-level directory of
617 the VS installation.
618 The key=value pairs form a comma-separated list of options to specify
620 details of the instance selection. Supported pairs are:
621 version=<major>.<minor>.<date>.<build>
623 New in version 3.23.
624 Specify the 4-component VS Build Version, a.k.a. Build Number.
627 The components are:
629 <major>.<minor>
631 The VS major and minor version numbers. These are the same
632 as the release version numbers.
633 <date>
635 A build date in the format MMMDD, where MMM is a month index
636 since an epoch used by Microsoft, and DD is a day in that
637 month.
638 <build>
640 A build index on the day represented by <date>.
641 The build number is reported by vswhere as installationVersion.
643 For example, VS 16.11.10 has build number 16.11.32126.315.
644 New in version 3.23: A portable VS instance, which is not known to the
646 Visual Studio Installer, may be specified by providing both location
647 and version=.
648 If the value of CMAKE_GENERATOR_INSTANCE is not specified explicitly by
651 the user or a toolchain file, CMake queries the Visual Studio Installer
652 to locate VS instances, chooses one, and sets the variable as a cache
653 entry to hold the value persistently. If an environment variable of
654 the form VS##0COMNTOOLS, where ## the Visual Studio major version num‐
655 ber, is set and points to the Common7/Tools directory within one of the
656 VS instances, that instance will be used. Otherwise, if more than one
657 VS instance is installed we do not define which one is chosen by de‐
658 fault.
659 The VS version build number of the selected VS instance is provided in
661 the CMAKE_VS_VERSION_BUILD_NUMBER variable.
662 CMAKE_GENERATOR_PLATFORM
664 New in version 3.1.
665 Generator-specific target platform specification provided by user.
668 Some CMake generators support a target platform name to be given to the
670 native build system to choose a compiler toolchain. If the user speci‐
671 fies a platform name (e.g. via the cmake -A option or via the
672 CMAKE_GENERATOR_PLATFORM environment variable) the value will be avail‐
673 able in this variable.
674 The value of this variable should never be modified by project code. A
676 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
677 tialize CMAKE_GENERATOR_PLATFORM. Once a given build tree has been
678 initialized with a particular value for this variable, changing the
679 value has undefined behavior.
680 Platform specification is supported only on specific generators:
682 • For Visual Studio Generators with VS 2005 and above this specifies
684 the target architecture.
685 • For Green Hills MULTI this specifies the target architecture.
687 See native build system documentation for allowed platform names.
689 Visual Studio Platform Selection
691 The Visual Studio Generators support platform specification using one
692 of these forms:
693 • platform
695 • platform[,key=value]*
697 • key=value[,key=value]*
699 The platform specifies the target platform (VS target architecture),
701 such as x64, ARM64, or Win32. The selected platform name is provided
702 in the CMAKE_VS_PLATFORM_NAME variable.
703 The key=value pairs form a comma-separated list of options to specify
705 generator-specific details of the platform selection. Supported pairs
706 are:
707 version=<version>
709 New in version 3.27.
710 Specify the Windows SDK version to use. This is supported by VS
713 2015 and above when targeting Windows or Windows Store. CMake
714 will set the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable
715 to the selected SDK version.
716 The <version> may be one of:
718 10.0 Specify that any 10.0 SDK version may be used, and let
720 Visual Studio pick one. This is supported by VS 2019 and
721 above.
722 10.0.<build>.<increment>
724 Specify the exact 4-component SDK version, e.g.,
725 10.0.19041.0. The specified version of the SDK must be
726 installed. It may not exceed the value of
727 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM, if that
728 variable is set.
729 8.1 Specify the 8.1 SDK version. This is always supported by
731 VS 2015. On VS 2017 and above the 8.1 SDK must be in‐
732 stalled.
733 If the version field is not specified, CMake selects a version
735 as described in the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
736 variable documentation.
737 CMAKE_GENERATOR_TOOLSET
739 Native build system toolset specification provided by user.
740 Some CMake generators support a toolset specification to tell the na‐
742 tive build system how to choose a compiler. If the user specifies a
743 toolset (e.g. via the cmake -T option or via the
744 CMAKE_GENERATOR_TOOLSET environment variable) the value will be avail‐
745 able in this variable.
746 The value of this variable should never be modified by project code. A
748 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
749 tialize CMAKE_GENERATOR_TOOLSET. Once a given build tree has been ini‐
750 tialized with a particular value for this variable, changing the value
751 has undefined behavior.
752 Toolset specification is supported only on specific generators:
754 • Visual Studio Generators for VS 2010 and above
756 • The Xcode generator for Xcode 3.0 and above
758 • The Green Hills MULTI generator
760 See native build system documentation for allowed toolset names.
762 Visual Studio Toolset Selection
764 The Visual Studio Generators support toolset specification using one of
765 these forms:
766 • toolset
768 • toolset[,key=value]*
770 • key=value[,key=value]*
772 The toolset specifies the toolset name. The selected toolset name is
774 provided in the CMAKE_VS_PLATFORM_TOOLSET variable.
775 The key=value pairs form a comma-separated list of options to specify
777 generator-specific details of the toolset selection. Supported pairs
778 are:
779 cuda=<version>|<path>
781 Specify the CUDA toolkit version to use or the path to a stand‐
782 alone CUDA toolkit directory. Supported by VS 2010 and above.
783 The version can only be used with the CUDA toolkit VS integra‐
784 tion globally installed. See the CMAKE_VS_PLATFORM_TOOLSET_CUDA
785 and CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR variables.
786 host=<arch>
788 Specify the host tools architecture as x64 or x86. Supported by
789 VS 2013 and above. See the
790 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE variable.
791 version=<version>
793 Specify the toolset version to use. Supported by VS 2017 and
794 above with the specified toolset installed. See the
795 CMAKE_VS_PLATFORM_TOOLSET_VERSION variable.
796 VCTargetsPath=<path>
798 Specify an alternative VCTargetsPath value for Visual Studio
799 project files. This allows use of VS platform extension config‐
800 uration files (.props and .targets) that are not installed with
801 VS.
802 Visual Studio Toolset Customization
804 These are unstable interfaces with no compatibility guarantees because
805 they hook into undocumented internal CMake implementation details. In‐
806 stitutions may use these to internally maintain support for non-public
807 Visual Studio platforms and toolsets, but must accept responsibility to
808 make updates as changes are made to CMake.
809 Additional key=value pairs are available:
811 customFlagTableDir=<path>
813 New in version 3.21.
814 Specify the absolute path to a directory from which to load cus‐
817 tom flag tables stored as JSON documents with file names of the
818 form <platform>_<toolset>_<tool>.json or <platform>_<tool>.json,
819 where <platform> is the CMAKE_VS_PLATFORM_NAME, <toolset> is the
820 CMAKE_VS_PLATFORM_TOOLSET, and <tool> is the tool for which the
821 flag table is meant. This naming pattern is an internal CMake
822 implementation detail. The <tool> names are undocumented. The
823 format of the .json flag table files is undocumented.
824 CMAKE_IMPORT_LIBRARY_PREFIX
826 The prefix for import libraries that you link to.
827 The prefix to use for the name of an import library if used on this
829 platform.
830 CMAKE_IMPORT_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
832 CMAKE_IMPORT_LIBRARY_SUFFIX
834 The suffix for import libraries that you link to.
835 The suffix to use for the end of an import library filename if used on
837 this platform.
838 CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
840 CMAKE_JOB_POOL_COMPILE
842 This variable is used to initialize the JOB_POOL_COMPILE property on
843 all the targets. See JOB_POOL_COMPILE for additional information.
844 CMAKE_JOB_POOL_LINK
846 This variable is used to initialize the JOB_POOL_LINK property on all
847 the targets. See JOB_POOL_LINK for additional information.
848 CMAKE_JOB_POOL_PRECOMPILE_HEADER
850 New in version 3.17.
851 This variable is used to initialize the JOB_POOL_PRECOMPILE_HEADER
854 property on all the targets. See JOB_POOL_PRECOMPILE_HEADER for addi‐
855 tional information.
856 CMAKE_JOB_POOLS
858 New in version 3.11.
859 If the JOB_POOLS global property is not set, the value of this variable
862 is used in its place. See JOB_POOLS for additional information.
863 CMAKE_<LANG>_COMPILER_AR
865 New in version 3.9.
866 A wrapper around ar adding the appropriate --plugin option for the com‐
869 piler.
870 See also CMAKE_AR.
872 CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT
874 New in version 3.14.
875 Identification string of the compiler frontend variant.
878 Some compilers have multiple, different frontends for accepting command
880 line options. (For example Clang originally only had a frontend com‐
881 patible with the GNU compiler but since its port to Windows (Clang-Cl)
882 it now also supports a frontend compatible with MSVC.) When CMake de‐
883 tects such a compiler it sets this variable to what would have been the
884 CMAKE_<LANG>_COMPILER_ID for the compiler whose frontend it resembles.
885 NOTE:
887 In other words, this variable describes what command line options
888 and language extensions the compiler frontend expects.
889 Changed in version 3.26: This variable is set for GNU, MSVC, and Apple‐
891 Clang compilers that have only one frontend variant.
892 CMAKE_<LANG>_COMPILER_RANLIB
895 New in version 3.9.
896 A wrapper around ranlib adding the appropriate --plugin option for the
899 compiler.
900 See also CMAKE_RANLIB.
902 CMAKE_<LANG>_LINK_LIBRARY_SUFFIX
904 New in version 3.16.
905 Language-specific suffix for libraries that you link to.
908 The suffix to use for the end of a library filename, .lib on Windows.
910 CMAKE_LINK_LIBRARY_SUFFIX
912 The suffix for libraries that you link to.
913 The suffix to use for the end of a library filename, .lib on Windows.
915 CMAKE_LINK_SEARCH_END_STATIC
917 New in version 3.4.
918 End a link line such that static system libraries are used.
921 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
923 mine whether to use static or shared libraries for -lXXX options.
924 CMake uses these options to set the link type for libraries whose full
925 paths are not known or (in some cases) are in implicit link directories
926 for the platform. By default CMake adds an option at the end of the
927 library list (if necessary) to set the linker search type back to its
928 starting type. This property switches the final linker search type to
929 -Bstatic regardless of how it started.
930 This variable is used to initialize the target property
932 LINK_SEARCH_END_STATIC for all targets. If set, its value is also used
933 by the try_compile() command.
934 See also CMAKE_LINK_SEARCH_START_STATIC.
936 CMAKE_LINK_SEARCH_START_STATIC
938 New in version 3.4.
939 Assume the linker looks for static libraries by default.
942 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
944 mine whether to use static or shared libraries for -lXXX options.
945 CMake uses these options to set the link type for libraries whose full
946 paths are not known or (in some cases) are in implicit link directories
947 for the platform. By default the linker search type is assumed to be
948 -Bdynamic at the beginning of the library list. This property switches
949 the assumption to -Bstatic. It is intended for use when linking an ex‐
950 ecutable statically (e.g. with the GNU -static option).
951 This variable is used to initialize the target property
953 LINK_SEARCH_START_STATIC for all targets. If set, its value is also
954 used by the try_compile() command.
955 See also CMAKE_LINK_SEARCH_END_STATIC.
957 CMAKE_MAJOR_VERSION
959 First version number component of the CMAKE_VERSION variable.
960 CMAKE_MAKE_PROGRAM
962 Tool that can launch the native build system. The value may be the
963 full path to an executable or just the tool name if it is expected to
964 be in the PATH.
965 The tool selected depends on the CMAKE_GENERATOR used to configure the
967 project:
968 • The Makefile Generators set this to make, gmake, or a generator-spe‐
970 cific tool (e.g. nmake for NMake Makefiles).
971 These generators store CMAKE_MAKE_PROGRAM in the CMake cache so that
973 it may be edited by the user.
974 • The Ninja generator sets this to ninja.
976 This generator stores CMAKE_MAKE_PROGRAM in the CMake cache so that
978 it may be edited by the user.
979 • The Xcode generator sets this to xcodebuild.
981 This generator prefers to lookup the build tool at build time rather
983 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
984 This is because xcodebuild is easy to find.
985 For compatibility with versions of CMake prior to 3.2, if a user or
987 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
988 CMake will use the specified value.
989 • The Visual Studio Generators set this to the full path to MSBuild.exe
991 (VS >= 10), devenv.com (VS 7,8,9), or VCExpress.exe (VS Express 8,9).
992 (See also variables CMAKE_VS_MSBUILD_COMMAND and
993 CMAKE_VS_DEVENV_COMMAND.
994 These generators prefer to lookup the build tool at build time rather
996 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
997 This is because the tools are version-specific and can be located us‐
998 ing the Windows Registry. It is also necessary because the proper
999 build tool may depend on the project content (e.g. the Intel Fortran
1000 plugin to VS 10 and 11 requires devenv.com to build its .vfproj
1001 project files even though MSBuild.exe is normally preferred to sup‐
1002 port the CMAKE_GENERATOR_TOOLSET).
1003 For compatibility with versions of CMake prior to 3.0, if a user or
1005 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
1006 CMake will use the specified value if possible.
1007 • The Green Hills MULTI generator sets this to the full path to
1009 gbuild.exe(Windows) or gbuild(Linux) based upon the toolset being
1010 used.
1011 Once the generator has initialized a particular value for this vari‐
1013 able, changing the value has undefined behavior.
1014 The CMAKE_MAKE_PROGRAM variable is set for use by project code. The
1016 value is also used by the cmake --build and ctest --build-and-test
1017 tools to launch the native build process.
1018 CMAKE_MATCH_COUNT
1020 New in version 3.2.
1021 The number of matches with the last regular expression.
1024 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
1026 variables with the match contents. The CMAKE_MATCH_COUNT variable
1027 holds the number of match expressions when these are filled.
1028 CMAKE_MATCH_<n>
1030 New in version 3.9.
1031 Capture group <n> matched by the last regular expression, for groups 0
1034 through 9. Group 0 is the entire match. Groups 1 through 9 are the
1035 subexpressions captured by () syntax.
1036 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
1038 variables with the match contents. The CMAKE_MATCH_COUNT variable
1039 holds the number of match expressions when these are filled.
1040 CMAKE_MINIMUM_REQUIRED_VERSION
1042 The <min> version of CMake given to the most recent call to the
1043 cmake_minimum_required(VERSION) command in the current variable scope
1044 or any parent variable scope.
1045 CMAKE_MINOR_VERSION
1047 Second version number component of the CMAKE_VERSION variable.
1048 CMAKE_NETRC
1050 New in version 3.11.
1051 This variable is used to initialize the NETRC option for the
1054 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
1055 tional information.
1056 This variable is also used by the ExternalProject and FetchContent mod‐
1058 ules for internal calls to file(DOWNLOAD).
1059 The local option takes precedence over this variable.
1061 CMAKE_NETRC_FILE
1063 New in version 3.11.
1064 This variable is used to initialize the NETRC_FILE option for the
1067 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
1068 tional information.
1069 This variable is also used by the ExternalProject and FetchContent mod‐
1071 ules for internal calls to file(DOWNLOAD).
1072 The local option takes precedence over this variable.
1074 CMAKE_PARENT_LIST_FILE
1076 Full path to the CMake file that included the current one.
1077 While processing a CMake file loaded by include() or find_package()
1079 this variable contains the full path to the file including it. The top
1080 of the include stack is always the CMakeLists.txt for the current di‐
1081 rectory. See also CMAKE_CURRENT_LIST_FILE.
1082 CMAKE_PATCH_VERSION
1084 Third version number component of the CMAKE_VERSION variable.
1085 CMAKE_PROJECT_DESCRIPTION
1087 New in version 3.9.
1088 The description of the top level project.
1091 This variable holds the description of the project as specified in the
1093 top level CMakeLists.txt file by a project() command. In the event
1094 that the top level CMakeLists.txt contains multiple project() calls,
1095 the most recently called one from that top level CMakeLists.txt will
1096 determine the value that CMAKE_PROJECT_DESCRIPTION contains. For exam‐
1097 ple, consider the following top level CMakeLists.txt:
1098 cmake_minimum_required(VERSION 3.0)
1100 project(First DESCRIPTION "I am First")
1101 project(Second DESCRIPTION "I am Second")
1102 add_subdirectory(sub)
1103 project(Third DESCRIPTION "I am Third")
1104 And sub/CMakeLists.txt with the following contents:
1106 project(SubProj DESCRIPTION "I am SubProj")
1108 message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")
1109 The most recently seen project() command from the top level CMake‐
1111 Lists.txt would be project(Second ...), so this will print:
1112 CMAKE_PROJECT_DESCRIPTION = I am Second
1114 To obtain the description from the most recent call to project() in the
1116 current directory scope or above, see the PROJECT_DESCRIPTION variable.
1117 CMAKE_PROJECT_HOMEPAGE_URL
1119 New in version 3.12.
1120 The homepage URL of the top level project.
1123 This variable holds the homepage URL of the project as specified in the
1125 top level CMakeLists.txt file by a project() command. In the event
1126 that the top level CMakeLists.txt contains multiple project() calls,
1127 the most recently called one from that top level CMakeLists.txt will
1128 determine the value that CMAKE_PROJECT_HOMEPAGE_URL contains. For ex‐
1129 ample, consider the following top level CMakeLists.txt:
1130 cmake_minimum_required(VERSION 3.0)
1132 project(First HOMEPAGE_URL "http://first.example.com")
1133 project(Second HOMEPAGE_URL "http://second.example.com")
1134 add_subdirectory(sub)
1135 project(Third HOMEPAGE_URL "http://third.example.com")
1136 And sub/CMakeLists.txt with the following contents:
1138 project(SubProj HOMEPAGE_URL "http://subproj.example.com")
1140 message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}")
1141 The most recently seen project() command from the top level CMake‐
1143 Lists.txt would be project(Second ...), so this will print:
1144 CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com
1146 To obtain the homepage URL from the most recent call to project() in
1148 the current directory scope or above, see the PROJECT_HOMEPAGE_URL
1149 variable.
1150 CMAKE_PROJECT_NAME
1152 The name of the top level project.
1153 This variable holds the name of the project as specified in the top
1155 level CMakeLists.txt file by a project() command. In the event that
1156 the top level CMakeLists.txt contains multiple project() calls, the
1157 most recently called one from that top level CMakeLists.txt will deter‐
1158 mine the name that CMAKE_PROJECT_NAME contains. For example, consider
1159 the following top level CMakeLists.txt:
1160 cmake_minimum_required(VERSION 3.0)
1162 project(First)
1163 project(Second)
1164 add_subdirectory(sub)
1165 project(Third)
1166 And sub/CMakeLists.txt with the following contents:
1168 project(SubProj)
1170 message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")
1171 The most recently seen project() command from the top level CMake‐
1173 Lists.txt would be project(Second), so this will print:
1174 CMAKE_PROJECT_NAME = Second
1176 To obtain the name from the most recent call to project() in the cur‐
1178 rent directory scope or above, see the PROJECT_NAME variable.
1179 CMAKE_PROJECT_VERSION
1181 New in version 3.12.
1182 The version of the top level project.
1185 This variable holds the version of the project as specified in the top
1187 level CMakeLists.txt file by a project() command. In the event that
1188 the top level CMakeLists.txt contains multiple project() calls, the
1189 most recently called one from that top level CMakeLists.txt will deter‐
1190 mine the value that CMAKE_PROJECT_VERSION contains. For example, con‐
1191 sider the following top level CMakeLists.txt:
1192 cmake_minimum_required(VERSION 3.0)
1194 project(First VERSION 1.2.3)
1195 project(Second VERSION 3.4.5)
1196 add_subdirectory(sub)
1197 project(Third VERSION 6.7.8)
1198 And sub/CMakeLists.txt with the following contents:
1200 project(SubProj VERSION 1)
1202 message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")
1203 The most recently seen project() command from the top level CMake‐
1205 Lists.txt would be project(Second ...), so this will print:
1206 CMAKE_PROJECT_VERSION = 3.4.5
1208 To obtain the version from the most recent call to project() in the
1210 current directory scope or above, see the PROJECT_VERSION variable.
1211 CMAKE_PROJECT_VERSION_MAJOR
1213 New in version 3.12.
1214 The major version of the top level project.
1217 This variable holds the major version of the project as specified in
1219 the top level CMakeLists.txt file by a project() command. Please see
1220 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1221 project() commands are used in the sources.
1222 CMAKE_PROJECT_VERSION_MINOR
1224 New in version 3.12.
1225 The minor version of the top level project.
1228 This variable holds the minor version of the project as specified in
1230 the top level CMakeLists.txt file by a project() command. Please see
1231 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1232 project() commands are used in the sources.
1233 CMAKE_PROJECT_VERSION_PATCH
1235 New in version 3.12.
1236 The patch version of the top level project.
1239 This variable holds the patch version of the project as specified in
1241 the top level CMakeLists.txt file by a project() command. Please see
1242 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1243 project() commands are used in the sources.
1244 CMAKE_PROJECT_VERSION_TWEAK
1246 New in version 3.12.
1247 The tweak version of the top level project.
1250 This variable holds the tweak version of the project as specified in
1252 the top level CMakeLists.txt file by a project() command. Please see
1253 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1254 project() commands are used in the sources.
1255 CMAKE_RANLIB
1257 Name of randomizing tool for static libraries.
1258 This specifies name of the program that randomizes libraries on UNIX,
1260 not used on Windows, but may be present.
1261 CMAKE_ROOT
1263 Install directory for running cmake.
1264 This is the install root for the running CMake and the Modules direc‐
1266 tory can be found here. This is commonly used in this format:
1267 ${CMAKE_ROOT}/Modules
1268 CMAKE_RULE_MESSAGES
1270 New in version 3.13.
1271 Specify whether to report a message for each make rule.
1274 If set in the cache it is used to initialize the value of the
1276 RULE_MESSAGES property. Users may disable the option in their local
1277 build tree to disable granular messages and report only as each target
1278 completes in Makefile builds.
1279 CMAKE_SCRIPT_MODE_FILE
1281 Full path to the cmake -P script file currently being processed.
1282 When run in cmake -P script mode, CMake sets this variable to the full
1284 path of the script file. When run to configure a CMakeLists.txt file,
1285 this variable is not set.
1286 CMAKE_SHARED_LIBRARY_PREFIX
1288 The prefix for shared libraries that you link to.
1289 The prefix to use for the name of a shared library, lib on UNIX.
1291 CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1293 CMAKE_SHARED_LIBRARY_SUFFIX
1295 The suffix for shared libraries that you link to.
1296 The suffix to use for the end of a shared library filename, .dll on
1298 Windows.
1299 CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1301 CMAKE_SHARED_MODULE_PREFIX
1303 The prefix for loadable modules that you link to.
1304 The prefix to use for the name of a loadable module on this platform.
1306 CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides this for language <LANG>.
1308 CMAKE_SHARED_MODULE_SUFFIX
1310 The suffix for shared libraries that you link to.
1311 The suffix to use for the end of a loadable module filename on this
1313 platform
1314 CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides this for language <LANG>.
1316 CMAKE_SIZEOF_VOID_P
1318 Size of a void pointer.
1319 This is set to the size of a pointer on the target machine, and is de‐
1321 termined by a try compile. If a 64-bit size is found, then the library
1322 search path is modified to look for 64-bit libraries first.
1323 CMAKE_SKIP_INSTALL_RULES
1325 Whether to disable generation of installation rules.
1326 If TRUE, CMake will neither generate installation rules nor will it
1328 generate cmake_install.cmake files. This variable is FALSE by default.
1329 CMAKE_SKIP_RPATH
1331 If true, do not add run time path information.
1332 If this is set to TRUE, then the rpath information is not added to com‐
1334 piled executables. The default is to add rpath information if the
1335 platform supports it. This allows for easy running from the build
1336 tree. To omit RPATH in the install step, but not the build step, use
1337 CMAKE_SKIP_INSTALL_RPATH instead. To omit RPATH in the build step, use
1338 CMAKE_SKIP_BUILD_RPATH.
1339 For more information on RPATH handling see the INSTALL_RPATH and
1341 BUILD_RPATH target properties.
1342 CMAKE_SOURCE_DIR
1344 The path to the top level of the source tree.
1345 This is the full path to the top level of the current CMake source
1347 tree. For an in-source build, this would be the same as
1348 CMAKE_BINARY_DIR.
1349 When run in cmake -P script mode, CMake sets the variables
1351 CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
1352 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
1353 CMAKE_STATIC_LIBRARY_PREFIX
1355 The prefix for static libraries that you link to.
1356 The prefix to use for the name of a static library, lib on UNIX.
1358 CMAKE_STATIC_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1360 CMAKE_STATIC_LIBRARY_SUFFIX
1362 The suffix for static libraries that you link to.
1363 The suffix to use for the end of a static library filename, .lib on
1365 Windows.
1366 CMAKE_STATIC_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1368 CMAKE_Swift_MODULE_DIRECTORY
1370 New in version 3.15.
1371 Swift module output directory.
1374 This variable is used to initialize the Swift_MODULE_DIRECTORY property
1376 on all the targets. See the target property for additional informa‐
1377 tion.
1378 CMAKE_Swift_NUM_THREADS
1380 New in version 3.15.1.
1381 Number of threads for parallel compilation for Swift targets.
1384 This variable controls the number of parallel jobs that the swift
1386 driver creates for building targets. If not specified, it will default
1387 to the number of logical CPUs on the host.
1388 CMAKE_TOOLCHAIN_FILE
1390 Path to toolchain file supplied to cmake(1).
1391 This variable is specified on the command line when cross-compiling
1393 with CMake. It is the path to a file which is read early in the CMake
1394 run and which specifies locations for compilers and toolchain utili‐
1395 ties, and other target platform and compiler related information.
1396 Relative paths are allowed and are interpreted first as relative to the
1398 build directory, and if not found, relative to the source directory.
1399 This is initialized by the CMAKE_TOOLCHAIN_FILE environment variable if
1401 it is set when a new build tree is first created.
1402 See the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable for setting other
1404 things not directly related to the toolchain.
1405 CMAKE_TWEAK_VERSION
1407 Defined to 0 for compatibility with code written for older CMake ver‐
1408 sions that may have defined higher values.
1409 NOTE:
1411 In CMake versions 2.8.2 through 2.8.12, this variable holds the
1412 fourth version number component of the CMAKE_VERSION variable.
1413 CMAKE_VERBOSE_MAKEFILE
1415 Enable verbose output from Makefile builds.
1416 This variable is a cache entry initialized (to FALSE) by the project()
1418 command. Users may enable the option in their local build tree to get
1419 more verbose output from Makefile builds and show each command line as
1420 it is launched.
1421 CMAKE_VERSION
1423 The CMake version string as three non-negative integer components sepa‐
1424 rated by . and possibly followed by - and other information. The first
1425 two components represent the feature level and the third component rep‐
1426 resents either a bug-fix level or development date.
1427 Release versions and release candidate versions of CMake use the for‐
1429 mat:
1430 <major>.<minor>.<patch>[-rc<n>]
1432 where the <patch> component is less than 20000000. Development ver‐
1434 sions of CMake use the format:
1435 <major>.<minor>.<date>[-<id>]
1437 where the <date> component is of format CCYYMMDD and <id> may contain
1439 arbitrary text. This represents development as of a particular date
1440 following the <major>.<minor> feature release.
1441 Individual component values are also available in variables:
1443 • CMAKE_MAJOR_VERSION
1445 • CMAKE_MINOR_VERSION
1447 • CMAKE_PATCH_VERSION
1449 • CMAKE_TWEAK_VERSION
1451 Use the if() command VERSION_LESS, VERSION_GREATER, VERSION_EQUAL, VER‐
1453 SION_LESS_EQUAL, or VERSION_GREATER_EQUAL operators to compare version
1454 string values against CMAKE_VERSION using a component-wise test. Ver‐
1455 sion component values may be 10 or larger so do not attempt to compare
1456 version strings as floating-point numbers.
1457 NOTE:
1459 CMake versions 2.8.2 through 2.8.12 used three components for the
1460 feature level. Release versions represented the bug-fix level in a
1461 fourth component, i.e. <major>.<minor>.<patch>[.<tweak>][-rc<n>].
1462 Development versions represented the development date in the fourth
1463 component, i.e. <major>.<minor>.<patch>.<date>[-<id>].
1464 CMake versions prior to 2.8.2 used three components for the feature
1466 level and had no bug-fix component. Release versions used an
1467 even-valued second component, i.e. <major>.<even-mi‐
1468 nor>.<patch>[-rc<n>]. Development versions used an odd-valued sec‐
1469 ond component with the development date as the third component, i.e.
1470 <major>.<odd-minor>.<date>.
1471 The CMAKE_VERSION variable is defined by CMake 2.6.3 and higher.
1473 Earlier versions defined only the individual component variables.
1474 CMAKE_VS_DEVENV_COMMAND
1476 The generators for Visual Studio 9 2008 and above set this variable to
1477 the devenv.com command installed with the corresponding Visual Studio
1478 version. Note that this variable may be empty on Visual Studio Express
1479 editions because they do not provide this tool.
1480 This variable is not defined by other generators even if devenv.com is
1482 installed on the computer.
1483 The CMAKE_VS_MSBUILD_COMMAND is also provided for Visual Studio 11 2012
1485 and above. See also the CMAKE_MAKE_PROGRAM variable.
1486 CMAKE_VS_MSBUILD_COMMAND
1488 The generators for Visual Studio 11 2012 and above set this variable to
1489 the MSBuild.exe command installed with the corresponding Visual Studio
1490 version.
1491 This variable is not defined by other generators even if MSBuild.exe is
1493 installed on the computer.
1494 The CMAKE_VS_DEVENV_COMMAND is also provided for the non-Express edi‐
1496 tions of Visual Studio. See also the CMAKE_MAKE_PROGRAM variable.
1497 CMAKE_VS_NsightTegra_VERSION
1499 New in version 3.1.
1500 When using a Visual Studio generator with the CMAKE_SYSTEM_NAME vari‐
1503 able set to Android, this variable contains the version number of the
1504 installed NVIDIA Nsight Tegra Visual Studio Edition.
1505 CMAKE_VS_NUGET_PACKAGE_RESTORE
1507 New in version 3.23.
1508 When using a Visual Studio generator, this cache variable controls if
1511 msbuild should automatically attempt to restore NuGet packages prior to
1512 a build. NuGet packages can be defined using the VS_PACKAGE_REFERENCES
1513 property on a target. If no package references are defined, this set‐
1514 ting will do nothing.
1515 The command line option --resolve-package-references can be used alter‐
1517 natively to control the resolve behavior globally. This option will
1518 take precedence over the cache variable.
1519 Targets that use the DOTNET_SDK are required to run a restore before
1521 building. Disabling this option may cause the build to fail in such
1522 projects.
1523 This setting is stored as a cache entry. Default value is ON.
1525 See also the VS_PACKAGE_REFERENCES property.
1527 CMAKE_VS_PLATFORM_NAME
1529 New in version 3.1.
1530 Visual Studio target platform name used by the current generator.
1533 VS 8 and above allow project files to specify a target platform. CMake
1535 provides the name of the chosen platform in this variable. See the
1536 CMAKE_GENERATOR_PLATFORM variable for details.
1537 See also the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.
1539 CMAKE_VS_PLATFORM_NAME_DEFAULT
1541 New in version 3.14.3.
1542 Default for the Visual Studio target platform name for the current gen‐
1545 erator without considering the value of the CMAKE_GENERATOR_PLATFORM
1546 variable. For Visual Studio Generators for VS 2017 and below this is
1547 always Win32. For VS 2019 and above this is based on the host plat‐
1548 form.
1549 See also the CMAKE_VS_PLATFORM_NAME variable.
1551 CMAKE_VS_PLATFORM_TOOLSET
1553 Visual Studio Platform Toolset name.
1554 VS 10 and above use MSBuild under the hood and support multiple com‐
1556 piler toolchains. CMake may specify a toolset explicitly, such as v110
1557 for VS 11 or Windows7.1SDK for 64-bit support in VS 10 Express. CMake
1558 provides the name of the chosen toolset in this variable.
1559 See the CMAKE_GENERATOR_TOOLSET variable for details.
1561 CMAKE_VS_PLATFORM_TOOLSET_CUDA
1563 New in version 3.9.
1564 NVIDIA CUDA Toolkit version whose Visual Studio toolset to use.
1567 The Visual Studio Generators for VS 2010 and above support using a CUDA
1569 toolset provided by a CUDA Toolkit. The toolset version number may be
1570 specified by a field in CMAKE_GENERATOR_TOOLSET of the form cuda=8.0.
1571 Or it is automatically detected if a path to a standalone CUDA direc‐
1572 tory is specified in the form cuda=C:\path\to\cuda. If none is speci‐
1573 fied CMake will choose a default version. CMake provides the selected
1574 CUDA toolset version in this variable. The value may be empty if no
1575 CUDA Toolkit with Visual Studio integration is installed.
1576 CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
1578 New in version 3.16.
1579 Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer).
1582 The Visual Studio Generators for VS 2010 and above support using a
1584 standalone (non-installed) NVIDIA CUDA toolkit. The path may be speci‐
1585 fied by a field in CMAKE_GENERATOR_TOOLSET of the form
1586 cuda=C:\path\to\cuda. The given directory must at least contain the
1587 nvcc compiler in path .\bin and must provide Visual Studio integration
1588 files in path .\extras\visual_studio_integration\ MSBuildExtensions\.
1589 One can create a standalone CUDA toolkit directory by either opening a
1590 installer with 7zip or copying the files that are extracted by the run‐
1591 ning installer. The value may be empty if no path to a standalone CUDA
1592 Toolkit was specified.
1593 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
1595 New in version 3.8.
1596 Visual Studio preferred tool architecture.
1599 The Visual Studio Generators for VS 2013 and above support using either
1601 the 32-bit or 64-bit host toolchains by specifying a host=x86 or
1602 host=x64 value in the CMAKE_GENERATOR_TOOLSET option. CMake provides
1603 the selected toolchain architecture preference in this variable (x86,
1604 x64, ARM64 or empty).
1605 CMAKE_VS_PLATFORM_TOOLSET_VERSION
1607 New in version 3.12.
1608 Visual Studio Platform Toolset version.
1611 The Visual Studio Generators for VS 2017 and above allow to select mi‐
1613 nor versions of the same toolset. The toolset version number may be
1614 specified by a field in CMAKE_GENERATOR_TOOLSET of the form ver‐
1615 sion=14.11. If none is specified CMake will choose a default toolset.
1616 The value may be empty if no minor version was selected and the default
1617 is used.
1618 If the value is not empty, it is the version number that MSBuild uses
1620 in its Microsoft.VCToolsVersion.*.props file names.
1621 New in version 3.19.7: VS 16.9's toolset may also be specified as
1623 14.28.16.9 because VS 16.10 uses the file name Microsoft.VCToolsVer‐
1624 sion.14.28.16.9.props.
1625 Three-Component MSVC Toolset Versions
1628 New in version 3.19.7.
1629 The version= field may be given a three-component toolset version such
1632 as 14.28.29910, and CMake will convert it to the name used by MSBuild
1633 Microsoft.VCToolsVersion.*.props files. This is useful to distinguish
1634 between VS 16.8's 14.28.29333 toolset and VS 16.9's 14.28.29910
1635 toolset. It also matches vcvarsall's -vcvars_ver= behavior.
1636 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
1638 New in version 3.22.
1639 Visual Studio target framework identifier.
1642 In some cases, the Visual Studio Generators may use an explicit value
1644 for the MSBuild TargetFrameworkIdentifier setting in .csproj files.
1645 CMake provides the chosen value in this variable.
1646 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1648 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1649 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
1651 New in version 3.22.
1652 Visual Studio target framework targets version.
1655 In some cases, the Visual Studio Generators may use an explicit value
1657 for the MSBuild TargetFrameworkTargetsVersion setting in .csproj files.
1658 CMake provides the chosen value in this variable.
1659 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1661 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.
1662 CMAKE_VS_TARGET_FRAMEWORK_VERSION
1664 New in version 3.22.
1665 Visual Studio target framework version.
1668 In some cases, the Visual Studio Generators may use an explicit value
1670 for the MSBuild TargetFrameworkVersion setting in .csproj files. CMake
1671 provides the chosen value in this variable.
1672 See the CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION variable and
1674 DOTNET_TARGET_FRAMEWORK_VERSION target property to specify custom Tar‐
1675 getFrameworkVersion values for project targets.
1676 See also CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER and
1678 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1679 CMAKE_VS_VERSION_BUILD_NUMBER
1681 New in version 3.26.
1682 Visual Studio version.
1685 Visual Studio Generators for VS 2017 and above set this variable to the
1687 Visual Studio version build number in the format <major>.<mi‐
1688 nor>.<date>.<build>.
1689 The components are:
1691 <major>.<minor>
1693 The VS major and minor version numbers. These are the same as the
1694 release version numbers.
1695 <date>
1697 A build date in the format MMMDD, where MMM is a month index since
1698 an epoch used by Microsoft, and DD is a day in that month.
1699 <build>
1701 A build index on the day represented by <date>.
1702 The build number is reported by vswhere as installationVersion. For
1704 example, VS 16.11.10 has build number 16.11.32126.315.
1705 See also the CMAKE_GENERATOR_INSTANCE variable.
1707 CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
1709 New in version 3.27.
1710 Tell Visual Studio Generators to use the given Windows Target Platform
1713 Minimum Version.
1714 This variable is used to initialize the
1716 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION property on all targets when
1717 they are created. See that target property for additional information.
1718 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
1720 New in version 3.4.
1721 Visual Studio Windows Target Platform Version.
1724 When targeting Windows 10 and above, Visual Studio Generators for VS
1726 2015 and above support specification of a Windows SDK version:
1727 • If CMAKE_GENERATOR_PLATFORM specifies a version= field, as documented
1729 by Visual Studio Platform Selection, that SDK version is selected.
1730 • Otherwise, if the WindowsSDKVersion environment variable is set to an
1732 available SDK version, that version is selected. This is intended
1733 for use in environments established by vcvarsall.bat or similar
1734 scripts.
1735 New in version 3.27: This is enabled by policy CMP0149.
1737 • Otherwise, if CMAKE_SYSTEM_VERSION is set to an available SDK ver‐
1740 sion, that version is selected.
1741 Changed in version 3.27: This is disabled by policy CMP0149.
1743 • Otherwise, CMake uses the latest Windows SDK version available.
1746 The chosen Windows target version number is provided in CMAKE_VS_WIN‐
1748 DOWS_TARGET_PLATFORM_VERSION. If no Windows 10 SDK is available this
1749 value will be empty.
1750 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to an ab‐
1752 solute path to tell CMake to look for Windows 10 SDKs in a custom loca‐
1753 tion. The specified directory is expected to contain Include/10.0.*
1754 directories.
1755 See also CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.
1757 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
1759 New in version 3.19.
1760 Override the Windows 10 SDK Maximum Version for VS 2015 and beyond.
1763 The CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM variable may be
1765 set to a false value (e.g. OFF, FALSE, or 0) or the SDK version to use
1766 as the maximum (e.g. 10.0.14393.0). If unset, the default depends on
1767 which version of Visual Studio is targeted by the current generator.
1768 This can be used to exclude Windows SDK versions from consideration for
1770 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.
1771 CMAKE_XCODE_BUILD_SYSTEM
1773 New in version 3.19.
1774 Xcode build system selection.
1777 The Xcode generator defines this variable to indicate which variant of
1779 the Xcode build system will be used. The value is the version of Xcode
1780 in which the corresponding build system first became mature enough for
1781 use by CMake. The possible values are:
1782 1 The original Xcode build system. This is the default when using
1784 Xcode 11.x or below.
1785 12 The Xcode "new build system" introduced by Xcode 10. It became
1787 mature enough for use by CMake in Xcode 12. This is the default
1788 when using Xcode 12.x or above.
1789 The CMAKE_XCODE_BUILD_SYSTEM variable is informational and should not
1791 be modified by project code. See the Toolset and Build System Selec‐
1792 tion documentation section to select the Xcode build system.
1793 CMAKE_XCODE_PLATFORM_TOOLSET
1795 Xcode compiler selection.
1796 Xcode supports selection of a compiler from one of the installed
1798 toolsets. CMake provides the name of the chosen toolset in this vari‐
1799 able, if any is explicitly selected (e.g. via the cmake -T option).
1800 <PROJECT-NAME>_BINARY_DIR
1802 Top level binary directory for the named project.
1803 A variable is created with the name used in the project() command, and
1805 is the binary directory for the project. This can be useful when
1806 add_subdirectory() is used to connect several projects.
1807 <PROJECT-NAME>_DESCRIPTION
1809 New in version 3.12.
1810 Value given to the DESCRIPTION option of the most recent call to the
1813 project() command with project name <PROJECT-NAME>, if any.
1814 <PROJECT-NAME>_HOMEPAGE_URL
1816 New in version 3.12.
1817 Value given to the HOMEPAGE_URL option of the most recent call to the
1820 project() command with project name <PROJECT-NAME>, if any.
1821 <PROJECT-NAME>_IS_TOP_LEVEL
1823 New in version 3.21.
1824 A boolean variable indicating whether the named project was called in a
1827 top level CMakeLists.txt file.
1828 To obtain the value from the most recent call to project() in the cur‐
1830 rent directory scope or above, see the PROJECT_IS_TOP_LEVEL variable.
1831 The variable value will be true in:
1833 • the top-level directory of the project
1835 • the top-level directory of an external project added by
1837 ExternalProject
1838 • a directory added by add_subdirectory() that does not also contain a
1840 project() call
1841 • a directory added by FetchContent_MakeAvailable(), if the fetched
1843 content does not contain a project() call
1844 The variable value will be false in:
1846 • a directory added by add_subdirectory() that also contains a
1848 project() call
1849 • a directory added by FetchContent_MakeAvailable(), if the fetched
1851 content contains a project() call
1852 <PROJECT-NAME>_SOURCE_DIR
1854 Top level source directory for the named project.
1855 A variable is created with the name used in the project() command, and
1857 is the source directory for the project. This can be useful when
1858 add_subdirectory() is used to connect several projects.
1859 <PROJECT-NAME>_VERSION
1861 Value given to the VERSION option of the most recent call to the
1862 project() command with project name <PROJECT-NAME>, if any.
1863 See also the component-wise version variables
1865 <PROJECT-NAME>_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MINOR,
1866 <PROJECT-NAME>_VERSION_PATCH, and <PROJECT-NAME>_VERSION_TWEAK.
1867 <PROJECT-NAME>_VERSION_MAJOR
1869 First version number component of the <PROJECT-NAME>_VERSION variable
1870 as set by the project() command.
1871 <PROJECT-NAME>_VERSION_MINOR
1873 Second version number component of the <PROJECT-NAME>_VERSION variable
1874 as set by the project() command.
1875 <PROJECT-NAME>_VERSION_PATCH
1877 Third version number component of the <PROJECT-NAME>_VERSION variable
1878 as set by the project() command.
1879 <PROJECT-NAME>_VERSION_TWEAK
1881 Fourth version number component of the <PROJECT-NAME>_VERSION variable
1882 as set by the project() command.
1883 PROJECT_BINARY_DIR
1885 Full path to build directory for project.
1886 This is the binary directory of the most recent project() command.
1888 PROJECT_DESCRIPTION
1890 New in version 3.9.
1891 Short project description given to the project command.
1894 This is the description given to the most recently called project()
1896 command in the current directory scope or above. To obtain the de‐
1897 scription of the top level project, see the CMAKE_PROJECT_DESCRIPTION
1898 variable.
1899 PROJECT_HOMEPAGE_URL
1901 New in version 3.12.
1902 The homepage URL of the project.
1905 This is the homepage URL given to the most recently called project()
1907 command in the current directory scope or above. To obtain the home‐
1908 page URL of the top level project, see the CMAKE_PROJECT_HOMEPAGE_URL
1909 variable.
1910 PROJECT_IS_TOP_LEVEL
1912 New in version 3.21.
1913 A boolean variable indicating whether the most recently called
1916 project() command in the current scope or above was in the top level
1917 CMakeLists.txt file.
1918 Some modules should only be included as part of the top level CMake‐
1920 Lists.txt file to not cause unintended side effects in the build tree,
1921 and this variable can be used to conditionally execute such code. For
1922 example, consider the CTest module, which creates targets and options:
1923 project(MyProject)
1925 ...
1926 if(PROJECT_IS_TOP_LEVEL)
1927 include(CTest)
1928 endif()
1929 The variable value will be true in:
1931 • the top-level directory of the project
1933 • the top-level directory of an external project added by
1935 ExternalProject
1936 • a directory added by add_subdirectory() that does not also contain a
1938 project() call
1939 • a directory added by FetchContent_MakeAvailable(), if the fetched
1941 content does not contain a project() call
1942 The variable value will be false in:
1944 • a directory added by add_subdirectory() that also contains a
1946 project() call
1947 • a directory added by FetchContent_MakeAvailable(), if the fetched
1949 content contains a project() call
1950 PROJECT_NAME
1952 Name of the project given to the project command.
1953 This is the name given to the most recently called project() command in
1955 the current directory scope or above. To obtain the name of the top
1956 level project, see the CMAKE_PROJECT_NAME variable.
1957 PROJECT_SOURCE_DIR
1959 This is the source directory of the last call to the project() command
1960 made in the current directory scope or one of its parents. Note, it is
1961 not affected by calls to project() made within a child directory scope
1962 (i.e. from within a call to add_subdirectory() from the current scope).
1963 PROJECT_VERSION
1965 Value given to the VERSION option of the most recent call to the
1966 project() command, if any.
1967 See also the component-wise version variables PROJECT_VERSION_MAJOR,
1969 PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH, and
1970 PROJECT_VERSION_TWEAK.
1971 PROJECT_VERSION_MAJOR
1973 First version number component of the PROJECT_VERSION variable as set
1974 by the project() command.
1975 PROJECT_VERSION_MINOR
1977 Second version number component of the PROJECT_VERSION variable as set
1978 by the project() command.
1979 PROJECT_VERSION_PATCH
1981 Third version number component of the PROJECT_VERSION variable as set
1982 by the project() command.
1983 PROJECT_VERSION_TWEAK
1985 Fourth version number component of the PROJECT_VERSION variable as set
1986 by the project() command.
1987
1989 BUILD_SHARED_LIBS
1990 Global flag to cause add_library() to create shared libraries if on.
1991 If present and true, this will cause all libraries to be built shared
1993 unless the library was explicitly added as a static library. This
1994 variable is often added to projects as an option() so that each user of
1995 a project can decide if they want to build the project using shared or
1996 static libraries.
1997 CMAKE_ABSOLUTE_DESTINATION_FILES
1999 List of files which have been installed using an ABSOLUTE DESTINATION
2000 path.
2001 This variable is defined by CMake-generated cmake_install.cmake
2003 scripts. It can be used (read-only) by programs or scripts that source
2004 those install scripts. This is used by some CPack generators (e.g.
2005 RPM).
2006 CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
2008 New in version 3.27.
2009 Whether to enable the DEPENDS_EXPLICIT_ONLY option by default in
2012 add_custom_command().
2013 This variable affects the default behavior of the add_custom_command()
2015 command. Setting this variable to ON is equivalent to using the DE‐
2016 PENDS_EXPLICIT_ONLY option in all uses of that command.
2017 See also CMAKE_OPTIMIZE_DEPENDENCIES.
2019 CMAKE_APPBUNDLE_PATH
2021 Semicolon-separated list of directories specifying a search path for
2022 macOS application bundles used by the find_program(), and
2023 find_package() commands.
2024 There is also an environment variable CMAKE_APPBUNDLE_PATH, which is
2026 used as an additional list of search directories.
2027 CMAKE_AUTOMOC_RELAXED_MODE
2029 Deprecated since version 3.15.
2030 Switch between strict and relaxed automoc mode.
2033 By default, AUTOMOC behaves exactly as described in the documentation
2035 of the AUTOMOC target property. When set to TRUE, it accepts more in‐
2036 put and tries to find the correct input file for moc even if it differs
2037 from the documented behavior. In this mode it e.g. also checks
2038 whether a header file is intended to be processed by moc when a
2039 "foo.moc" file has been included.
2040 Relaxed mode has to be enabled for KDE4 compatibility.
2042 CMAKE_BACKWARDS_COMPATIBILITY
2044 Deprecated. See CMake Policy CMP0001 documentation.
2045 CMAKE_BUILD_TYPE
2047 Specifies the build type on single-configuration generators (e.g.
2048 Makefile Generators or Ninja). Typical values include Debug, Release,
2049 RelWithDebInfo and MinSizeRel, but custom build types can also be de‐
2050 fined.
2051 This variable is initialized by the first project() or
2053 enable_language() command called in a project when a new build tree is
2054 first created. If the CMAKE_BUILD_TYPE environment variable is set,
2055 its value is used. Otherwise, a toolchain-specific default is chosen
2056 when a language is enabled. The default value is often an empty
2057 string, but this is usually not desirable and one of the other standard
2058 build types is usually more appropriate.
2059 Depending on the situation, the value of this variable may be treated
2061 case-sensitively or case-insensitively. See Build Configurations for
2062 discussion of this and other related topics.
2063 For multi-config generators, see CMAKE_CONFIGURATION_TYPES.
2065 CMAKE_CLANG_VFS_OVERLAY
2067 New in version 3.19.
2068 When cross compiling for windows with clang-cl, this variable can be an
2071 absolute path pointing to a clang virtual file system yaml file, which
2072 will enable clang-cl to resolve windows header names on a case sensi‐
2073 tive file system.
2074 CMAKE_CODEBLOCKS_COMPILER_ID
2076 New in version 3.11.
2077 Change the compiler id in the generated CodeBlocks project files.
2080 CodeBlocks uses its own compiler id string which differs from
2082 CMAKE_<LANG>_COMPILER_ID. If this variable is left empty, CMake tries
2083 to recognize the CodeBlocks compiler id automatically. Otherwise the
2084 specified string is used in the CodeBlocks project file. See the Code‐
2085 Blocks documentation for valid compiler id strings.
2086 Other IDEs like QtCreator that also use the CodeBlocks generator may
2088 ignore this setting.
2089 CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
2091 New in version 3.10.
2092 Change the way the CodeBlocks generator creates project files.
2095 If this variable evaluates to ON the generator excludes from the
2097 project file any files that are located outside the project root.
2098 CMAKE_CODELITE_USE_TARGETS
2100 New in version 3.7.
2101 Change the way the CodeLite generator creates projectfiles.
2104 If this variable evaluates to ON at the end of the top-level CMake‐
2106 Lists.txt file, the generator creates projectfiles based on targets
2107 rather than projects.
2108 CMAKE_COLOR_DIAGNOSTICS
2110 New in version 3.24.
2111 Enable color diagnostics throughout.
2114 This variable uses three states: ON, OFF and not defined.
2116 When not defined:
2118 • Makefile Generators initialize the CMAKE_COLOR_MAKEFILE variable to
2120 ON. It controls color buildsystem messages.
2121 • GNU/Clang compilers are not invoked with any color diagnostics flag.
2123 When ON:
2125 • Makefile Generators produce color buildsystem messages by default.
2127 CMAKE_COLOR_MAKEFILE is not initialized, but may be explicitly set to
2128 OFF to disable color buildsystem messages.
2129 • GNU/Clang compilers are invoked with a flag enabling color diagnos‐
2131 tics (-fcolor-diagnostics).
2132 When OFF:
2134 • Makefile Generators do not produce color buildsystem messages by de‐
2136 fault. CMAKE_COLOR_MAKEFILE is not initialized, but may be explic‐
2137 itly set to ON to enable color buildsystem messages.
2138 • GNU/Clang compilers are invoked with a flag disabling color diagnos‐
2140 tics (-fno-color-diagnostics).
2141 If the CMAKE_COLOR_DIAGNOSTICS environment variable is set, its value
2143 is used. Otherwise, CMAKE_COLOR_DIAGNOSTICS is not defined by default.
2144 CMAKE_COLOR_MAKEFILE
2146 Enables color output when using the Makefile Generators.
2147 When enabled, the generated Makefiles will produce colored output. De‐
2149 fault is ON.
2150 CMAKE_CONFIGURATION_TYPES
2152 Specifies the available build types (configurations) on multi-config
2153 generators (e.g. Visual Studio, Xcode, or Ninja Multi-Config) as a
2154 semicolon-separated list. Typical entries include Debug, Release, Rel‐
2155 WithDebInfo and MinSizeRel, but custom build types can also be defined.
2156 This variable is initialized by the first project() or
2158 enable_language() command called in a project when a new build tree is
2159 first created. If the CMAKE_CONFIGURATION_TYPES environment variable
2160 is set, its value is used. Otherwise, the default value is genera‐
2161 tor-specific.
2162 Depending on the situation, the values in this variable may be treated
2164 case-sensitively or case-insensitively. See Build Configurations for
2165 discussion of this and other related topics.
2166 For single-config generators, see CMAKE_BUILD_TYPE.
2168 CMAKE_DEPENDS_IN_PROJECT_ONLY
2170 New in version 3.6.
2171 When set to TRUE in a directory, the build system produced by the
2174 Makefile Generators is set up to only consider dependencies on source
2175 files that appear either in the source or in the binary directories.
2176 Changes to source files outside of these directories will not cause re‐
2177 builds.
2178 This should be used carefully in cases where some source files are
2180 picked up through external headers during the build.
2181 CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
2183 Variable for disabling find_package() calls.
2184 Every non-REQUIRED find_package() call in a project can be disabled by
2186 setting the variable CMAKE_DISABLE_FIND_PACKAGE_<PackageName> to TRUE.
2187 This can be used to build a project without an optional package, al‐
2188 though that package is installed.
2189 This switch should be used during the initial CMake run. Otherwise if
2191 the package has already been found in a previous CMake run, the vari‐
2192 ables which have been stored in the cache will still be there. In that
2193 case it is recommended to remove the cache variables for this package
2194 from the cache using the cache editor or cmake -U.
2195 See also the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable.
2197 CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
2199 New in version 3.6.
2200 This cache variable is used by the Eclipse project generator. See
2203 cmake-generators(7).
2204 The Eclipse project generator generates so-called linked resources e.g.
2206 to the subproject root dirs in the source tree or to the source files
2207 of targets. This can be disabled by setting this variable to FALSE.
2208 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
2210 New in version 3.6.
2211 This cache variable is used by the Eclipse project generator. See
2214 cmake-generators(7).
2215 If this variable is set to TRUE, the Eclipse project generator will
2217 generate an Eclipse project in CMAKE_SOURCE_DIR . This project can then
2218 be used in Eclipse e.g. for the version control functionality.
2219 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT defaults to FALSE; so nothing is
2220 written into the source directory.
2221 CMAKE_ECLIPSE_MAKE_ARGUMENTS
2223 New in version 3.6.
2224 This cache variable is used by the Eclipse project generator. See
2227 cmake-generators(7).
2228 This variable holds arguments which are used when Eclipse invokes the
2230 make tool. By default it is initialized to hold flags to enable paral‐
2231 lel builds (using -j typically).
2232 CMAKE_ECLIPSE_RESOURCE_ENCODING
2234 New in version 3.16.
2235 This cache variable tells the Eclipse CDT4 project generator to set the
2238 resource encoding to the given value in generated project files. If no
2239 value is given, no encoding will be set.
2240 CMAKE_ECLIPSE_VERSION
2242 New in version 3.6.
2243 This cache variable is used by the Eclipse project generator. See
2246 cmake-generators(7).
2247 When using the Eclipse project generator, CMake tries to find the
2249 Eclipse executable and detect the version of it. Depending on the ver‐
2250 sion it finds, some features are enabled or disabled. If CMake doesn't
2251 find Eclipse, it assumes the oldest supported version, Eclipse Callisto
2252 (3.2).
2253 CMAKE_ERROR_DEPRECATED
2255 Whether to issue errors for deprecated functionality.
2256 If TRUE, use of deprecated functionality will issue fatal errors. If
2258 this variable is not set, CMake behaves as if it were set to FALSE.
2259 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
2261 Ask cmake_install.cmake script to error out as soon as a file with ab‐
2262 solute INSTALL DESTINATION is encountered.
2263 The fatal error is emitted before the installation of the offending
2265 file takes place. This variable is used by CMake-generated cmake_in‐
2266 stall.cmake scripts. If one sets this variable to ON while running the
2267 script, it may get fatal error messages from the script.
2268 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
2270 New in version 3.15.
2271 If this variable is set to STDERR, STDOUT or NONE then commands in
2274 execute_process() calls will be printed to either stderr or stdout or
2275 not at all.
2276 CMAKE_EXPORT_COMPILE_COMMANDS
2278 New in version 3.5.
2279 Enable/Disable output of compile commands during generation.
2282 If enabled, generates a compile_commands.json file containing the exact
2284 compiler calls for all translation units of the project in ma‐
2285 chine-readable form. The format of the JSON file looks like:
2286 [
2288 {
2289 "directory": "/home/user/development/project",
2290 "command": "/usr/bin/c++ ... -c ../foo/foo.cc",
2291 "file": "../foo/foo.cc"
2292 },
2293 ...
2295 {
2297 "directory": "/home/user/development/project",
2298 "command": "/usr/bin/c++ ... -c ../foo/bar.cc",
2299 "file": "../foo/bar.cc"
2300 }
2301 ]
2302 This is initialized by the CMAKE_EXPORT_COMPILE_COMMANDS environment
2304 variable, and initializes the EXPORT_COMPILE_COMMANDS target property
2305 for all targets.
2306 NOTE:
2308 This option is implemented only by Makefile Generators and Ninja
2309 Generators. It is ignored on other generators.
2310 This option currently does not work well in combination with the
2312 UNITY_BUILD target property or the CMAKE_UNITY_BUILD variable.
2313 CMAKE_EXPORT_PACKAGE_REGISTRY
2315 New in version 3.15.
2316 Enables the export(PACKAGE) command when CMP0090 is set to NEW.
2319 The export(PACKAGE) command does nothing by default. In some cases it
2321 is desirable to write to the user package registry, so the CMAKE_EX‐
2322 PORT_PACKAGE_REGISTRY variable may be set to enable it.
2323 If CMP0090 is not set to NEW this variable does nothing, and the
2325 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable controls the behavior in‐
2326 stead.
2327 See also Disabling the Package Registry.
2329 CMAKE_EXPORT_NO_PACKAGE_REGISTRY
2331 New in version 3.1.
2332 Disable the export(PACKAGE) command when CMP0090 is not set to NEW.
2335 In some cases, for example for packaging and for system wide installa‐
2337 tions, it is not desirable to write the user package registry. If the
2338 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the
2339 export(PACKAGE) command will do nothing.
2340 If CMP0090 is set to NEW this variable does nothing, and the
2342 CMAKE_EXPORT_PACKAGE_REGISTRY variable controls the behavior instead.
2343 See also Disabling the Package Registry.
2345 CMAKE_FIND_APPBUNDLE
2347 New in version 3.4.
2348 This variable affects how find_* commands choose between macOS Applica‐
2351 tion Bundles and unix-style package components.
2352 On Darwin or systems supporting macOS Application Bundles, the
2354 CMAKE_FIND_APPBUNDLE variable can be set to empty or one of the follow‐
2355 ing:
2356 FIRST Try to find application bundles before standard programs. This
2358 is the default on Darwin.
2359 LAST Try to find application bundles after standard programs.
2361 ONLY Only try to find application bundles.
2363 NEVER Never try to find application bundles.
2365 CMAKE_FIND_FRAMEWORK
2367 New in version 3.4.
2368 This variable affects how find_* commands choose between macOS Frame‐
2371 works and unix-style package components.
2372 On Darwin or systems supporting macOS Frameworks, the CMAKE_FIND_FRAME‐
2374 WORK variable can be set to empty or one of the following:
2375 FIRST Try to find frameworks before standard libraries or headers.
2377 This is the default on Darwin.
2378 LAST Try to find frameworks after standard libraries or headers.
2380 ONLY Only try to find frameworks.
2382 NEVER Never try to find frameworks.
2384 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
2386 New in version 3.9.
2387 Specify a <suffix> to tell the find_library() command to search in a
2390 lib<suffix> directory before each lib directory that would normally be
2391 searched.
2392 This overrides the behavior of related global properties:
2394 • FIND_LIBRARY_USE_LIB32_PATHS
2396 • FIND_LIBRARY_USE_LIB64_PATHS
2398 • FIND_LIBRARY_USE_LIBX32_PATHS
2400 CMAKE_FIND_LIBRARY_PREFIXES
2402 Prefixes to prepend when looking for libraries.
2403 This specifies what prefixes to add to library names when the
2405 find_library() command looks for libraries. On UNIX systems this is
2406 typically lib, meaning that when trying to find the foo library it will
2407 look for libfoo.
2408 CMAKE_FIND_LIBRARY_SUFFIXES
2410 Suffixes to append when looking for libraries.
2411 This specifies what suffixes to add to library names when the
2413 find_library() command looks for libraries. On Windows systems this is
2414 typically .lib and, depending on the compiler, .dll.a, .a (e.g. GCC and
2415 Clang), so when it tries to find the foo library, it will look for
2416 [<prefix>]foo.lib and/or [<prefix>]foo[.dll].a, depending on the com‐
2417 piler used and the <prefix> specified in the
2418 CMAKE_FIND_LIBRARY_PREFIXES.
2419 CMAKE_FIND_NO_INSTALL_PREFIX
2421 Exclude the values of the CMAKE_INSTALL_PREFIX and CMAKE_STAGING_PREFIX
2422 variables from CMAKE_SYSTEM_PREFIX_PATH. CMake adds these project-des‐
2423 tination prefixes to CMAKE_SYSTEM_PREFIX_PATH by default in order to
2424 support building a series of dependent packages and installing them
2425 into a common prefix. Set CMAKE_FIND_NO_INSTALL_PREFIX to TRUE to sup‐
2426 press this behavior.
2427 The CMAKE_SYSTEM_PREFIX_PATH is initialized on the first call to a
2429 project() or enable_language() command. Therefore one must set
2430 CMAKE_FIND_NO_INSTALL_PREFIX before this in order to take effect. A
2431 user may set the variable as a cache entry on the command line to
2432 achieve this.
2433 Note that the prefix(es) may still be searched for other reasons, such
2435 as being the same prefix as the CMake installation, or for being a
2436 built-in system prefix.
2437 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
2439 New in version 3.1.
2440 Deprecated since version 3.16: Use the CMAKE_FIND_USE_PACKAGE_REGISTRY
2443 variable instead.
2444 By default this variable is not set. If neither
2447 CMAKE_FIND_USE_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_PACKAGE_REG‐
2448 ISTRY is set, then find_package() will use the User Package Registry
2449 unless the NO_CMAKE_PACKAGE_REGISTRY option is provided.
2450 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY is ignored if
2452 CMAKE_FIND_USE_PACKAGE_REGISTRY is set.
2453 In some cases, for example to locate only system wide installations, it
2455 is not desirable to use the User Package Registry when searching for
2456 packages. If the CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable is
2457 TRUE, all the find_package() commands will skip the User Package Reg‐
2458 istry as if they were called with the NO_CMAKE_PACKAGE_REGISTRY argu‐
2459 ment.
2460 See also Disabling the Package Registry.
2462 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
2464 New in version 3.1.
2465 Deprecated since version 3.16: Use the
2468 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable instead.
2469 By default this variable is not set. If neither
2472 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_SYS‐
2473 TEM_PACKAGE_REGISTRY is set, then find_package() will use the System
2474 Package Registry unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is
2475 provided.
2476 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY is ignored if
2478 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY is set.
2479 In some cases, it is not desirable to use the System Package Registry
2481 when searching for packages. If the CMAKE_FIND_PACKAGE_NO_SYSTEM_PACK‐
2482 AGE_REGISTRY variable is TRUE, all the find_package() commands will
2483 skip the System Package Registry as if they were called with the
2484 NO_CMAKE_SYSTEM_PACKAGE_REGISTRY argument.
2485 See also Disabling the Package Registry.
2487 CMAKE_FIND_PACKAGE_PREFER_CONFIG
2489 New in version 3.15.
2490 Tell find_package() to try "Config" mode before "Module" mode if no
2493 mode was specified.
2494 The command find_package() operates without an explicit mode when the
2496 reduced signature is used without the MODULE option. In this case, by
2497 default, CMake first tries Module mode by searching for a
2498 Find<pkg>.cmake module. If it fails, CMake then searches for the pack‐
2499 age using Config mode.
2500 Set CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to tell find_package() to
2502 first search using Config mode before falling back to Module mode.
2503 This variable may be useful when a developer has compiled a custom ver‐
2505 sion of a common library and wishes to link it to a dependent project.
2506 If this variable is set to TRUE, it would prevent a dependent project's
2507 call to find_package() from selecting the default library located by
2508 the system's Find<pkg>.cmake module before finding the developer's cus‐
2509 tom built library.
2510 Once this variable is set, it is the responsibility of the exported
2512 <pkg>Config.cmake files to provide the same result variables as the
2513 Find<pkg>.cmake modules so that dependent projects can use them inter‐
2514 changeably.
2515 CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
2517 New in version 3.14.
2518 Set to TRUE to tell find_package() calls to resolve symbolic links in
2521 the value of <PackageName>_DIR.
2522 This is helpful in use cases where the package search path points at a
2524 proxy directory in which symlinks to the real package locations appear.
2525 This is not enabled by default because there are also common use cases
2526 in which the symlinks should be preserved.
2527 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
2529 New in version 3.24.
2530 Setting to TRUE promotes all IMPORTED targets discoverd by
2533 find_package() to a GLOBAL scope.
2534 Setting this to TRUE is akin to specifying GLOBAL as an argument to
2536 find_package(). Default value is OFF.
2537 CMAKE_FIND_PACKAGE_WARN_NO_MODULE
2539 Tell find_package() to warn if called without an explicit mode.
2540 If find_package() is called without an explicit mode option (MODULE,
2542 CONFIG, or NO_MODULE) and no Find<pkg>.cmake module is in
2543 CMAKE_MODULE_PATH then CMake implicitly assumes that the caller intends
2544 to search for a package configuration file. If no package configura‐
2545 tion file is found then the wording of the failure message must account
2546 for both the case that the package is really missing and the case that
2547 the project has a bug and failed to provide the intended Find module.
2548 If instead the caller specifies an explicit mode option then the fail‐
2549 ure message can be more specific.
2550 Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_package() to
2552 warn when it implicitly assumes Config mode. This helps developers en‐
2553 force use of an explicit mode in all calls to find_package() within a
2554 project.
2555 This variable has no effect if CMAKE_FIND_PACKAGE_PREFER_CONFIG is set
2557 to TRUE.
2558 CMAKE_FIND_ROOT_PATH
2560 Semicolon-separated list of root paths to search on the filesystem.
2561 This variable is most useful when cross-compiling. CMake uses the paths
2563 in this list as alternative roots to find filesystem items with
2564 find_package(), find_library() etc.
2565 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
2567 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2568 CMAKE_SYSROOT are used by find_file() and find_path().
2569 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2571 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2572 be ignored and only the host system root will be used. If set to BOTH,
2573 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2574 be searched.
2575 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
2577 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2578 CMAKE_SYSROOT are used by find_library().
2579 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2581 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2582 be ignored and only the host system root will be used. If set to BOTH,
2583 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2584 be searched.
2585 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
2587 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2588 CMAKE_SYSROOT are used by find_package().
2589 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2591 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2592 be ignored and only the host system root will be used. If set to BOTH,
2593 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2594 be searched.
2595 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
2597 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2598 CMAKE_SYSROOT are used by find_program().
2599 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2601 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2602 be ignored and only the host system root will be used. If set to BOTH,
2603 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2604 be searched.
2605 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
2607 New in version 3.16.
2608 Controls the default behavior of the following commands for whether or
2611 not to search paths provided by cmake-specific environment variables:
2612 • find_program()
2614 • find_library()
2616 • find_file()
2618 • find_path()
2620 • find_package()
2622 This is useful in cross-compiling environments.
2624 By default this variable is not set, which is equivalent to it having a
2626 value of TRUE. Explicit options given to the above commands take
2627 precedence over this variable.
2628 See also the CMAKE_FIND_USE_CMAKE_PATH,
2630 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2631 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2632 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2633 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2634 variables.
2635 CMAKE_FIND_USE_CMAKE_PATH
2637 New in version 3.16.
2638 Controls the default behavior of the following commands for whether or
2641 not to search paths provided by cmake-specific cache variables:
2642 • find_program()
2644 • find_library()
2646 • find_file()
2648 • find_path()
2650 • find_package()
2652 This is useful in cross-compiling environments.
2654 By default this variable is not set, which is equivalent to it having a
2656 value of TRUE. Explicit options given to the above commands take
2657 precedence over this variable.
2658 See also the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2660 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2661 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2662 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2663 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2664 variables.
2665 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
2667 New in version 3.16.
2668 Controls the default behavior of the following commands for whether or
2671 not to search paths provided by platform-specific cmake variables:
2672 • find_program()
2674 • find_library()
2676 • find_file()
2678 • find_path()
2680 • find_package()
2682 This is useful in cross-compiling environments.
2684 By default this variable is not set, which is equivalent to it having a
2686 value of TRUE. Explicit options given to the above commands take
2687 precedence over this variable.
2688 See also the CMAKE_FIND_USE_CMAKE_PATH,
2690 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2691 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2692 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2693 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2694 variables.
2695 CMAKE_FIND_USE_INSTALL_PREFIX
2697 New in version 3.24.
2698 Controls the default behavior of the following commands for whether or
2701 not to search the locations in the CMAKE_INSTALL_PREFIX and
2702 CMAKE_STAGING_PREFIX variables.
2703 • find_program()
2705 • find_library()
2707 • find_file()
2709 • find_path()
2711 • find_package()
2713 This is useful in cross-compiling environments.
2715 Due to backwards compatibility with CMAKE_FIND_NO_INSTALL_PREFIX, the
2717 behavior of the find command change based on if this variable exists.
2718 ┌───────────────────┬────────────────────┬────────┐
2720 │CMAKE_FIND_USE_IN‐ │ CMAKE_FIND_NO_IN‐ │ Search │
2721 │STALL_PREFIX │ STALL_PREFIX │ │
2722 ├───────────────────┼────────────────────┼────────┤
2723 │Not Defined │ On │ NO │
2724 ├───────────────────┼────────────────────┼────────┤
2725 │Not Defined │ Off || Not Defined │ YES │
2726 ├───────────────────┼────────────────────┼────────┤
2727 │Off │ On │ NO │
2728 ├───────────────────┼────────────────────┼────────┤
2729 │Off │ Off || Not Defined │ NO │
2730 └───────────────────┴────────────────────┴────────┘
2731 │On │ On │ YES │
2734 ├───────────────────┼────────────────────┼────────┤
2735 │On │ Off || Not Defined │ YES │
2736 └───────────────────┴────────────────────┴────────┘
2737 By default this variable is not defined. Explicit options given to the
2739 above commands take precedence over this variable.
2740 See also the CMAKE_FIND_USE_CMAKE_PATH,
2742 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2743 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2744 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2745 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2746 variables.
2747 CMAKE_FIND_USE_PACKAGE_REGISTRY
2749 New in version 3.16.
2750 Controls the default behavior of the find_package() command for whether
2753 or not to search paths provided by the User Package Registry.
2754 By default this variable is not set and the behavior will fall back to
2756 that determined by the deprecated
2757 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable. If that is also not
2758 set, then find_package() will use the User Package Registry unless the
2759 NO_CMAKE_PACKAGE_REGISTRY option is provided.
2760 This variable takes precedence over
2762 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY when both are set.
2763 In some cases, for example to locate only system wide installations, it
2765 is not desirable to use the User Package Registry when searching for
2766 packages. If the CMAKE_FIND_USE_PACKAGE_REGISTRY variable is FALSE,
2767 all the find_package() commands will skip the User Package Registry as
2768 if they were called with the NO_CMAKE_PACKAGE_REGISTRY argument.
2769 See also Disabling the Package Registry and the
2771 CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2772 CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2773 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2774 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2775 CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.
2776 CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2778 New in version 3.16.
2779 Controls the default behavior of the following commands for whether or
2782 not to search paths provided by <PackageName>_ROOT variables:
2783 • find_program()
2785 • find_library()
2787 • find_file()
2789 • find_path()
2791 • find_package()
2793 By default this variable is not set, which is equivalent to it having a
2795 value of TRUE. Explicit options given to the above commands take
2796 precedence over this variable.
2797 See also the CMAKE_FIND_USE_CMAKE_PATH,
2799 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2800 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2801 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2802 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2803 CMAKE_FIND_USE_PACKAGE_REGISTRY variables.
2804 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
2806 New in version 3.16.
2807 Controls the default behavior of the following commands for whether or
2810 not to search paths provided by standard system environment variables:
2811 • find_program()
2813 • find_library()
2815 • find_file()
2817 • find_path()
2819 • find_package()
2821 This is useful in cross-compiling environments.
2823 By default this variable is not set, which is equivalent to it having a
2825 value of TRUE. Explicit options given to the above commands take
2826 precedence over this variable.
2827 See also the CMAKE_FIND_USE_CMAKE_PATH,
2829 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2830 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_PACKAGE_REGISTRY,
2831 CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and
2832 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variables.
2833 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
2835 New in version 3.16.
2836 Controls searching the System Package Registry by the find_package()
2839 command.
2840 By default this variable is not set and the behavior will fall back to
2842 that determined by the deprecated
2843 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable. If that is
2844 also not set, then find_package() will use the System Package Registry
2845 unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is provided.
2846 This variable takes precedence over
2848 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY when both are set.
2849 In some cases, for example to locate only user specific installations,
2851 it is not desirable to use the System Package Registry when searching
2852 for packages. If the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable is
2853 FALSE, all the find_package() commands will skip the System Package
2854 Registry as if they were called with the NO_CMAKE_SYSTEM_PACKAGE_REG‐
2855 ISTRY argument.
2856 See also Disabling the Package Registry.
2858 See also the CMAKE_FIND_USE_CMAKE_PATH,
2860 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2861 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2862 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2863 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2864 variables.
2865 CMAKE_FRAMEWORK_PATH
2867 Semicolon-separated list of directories specifying a search path for
2868 macOS frameworks used by the find_library(), find_package(),
2869 find_path(), and find_file() commands.
2870 There is also an environment variable CMAKE_FRAMEWORK_PATH, which is
2872 used as an additional list of search directories.
2873 CMAKE_IGNORE_PATH
2875 Semicolon-separated list of directories to be ignored by the various
2876 find...() commands.
2877 For find_program(), find_library(), find_file(), and find_path(), any
2879 file found in one of the listed directories will be ignored. The listed
2880 directories do not apply recursively, so any subdirectories to be ig‐
2881 nored must also be explicitly listed. CMAKE_IGNORE_PATH does not af‐
2882 fect the search prefixes used by these four commands. To ignore indi‐
2883 vidual paths under a search prefix (e.g. bin, include, lib, etc.), each
2884 path must be listed in CMAKE_IGNORE_PATH as a full absolute path.
2885 CMAKE_IGNORE_PREFIX_PATH provides a more appropriate way to ignore a
2886 whole search prefix.
2887 find_package() is also affected by CMAKE_IGNORE_PATH, but only for Con‐
2889 fig mode searches. Any <Name>Config.cmake or <name>-config.cmake file
2890 found in one of the specified directories will be ignored. In addition,
2891 any search prefix found in CMAKE_IGNORE_PATH will be skipped for back‐
2892 ward compatibility reasons, but new code should prefer to use
2893 CMAKE_IGNORE_PREFIX_PATH to ignore prefixes instead.
2894 Ignoring search locations can be useful in cross-compiling environments
2896 where some system directories contain incompatible but possibly link‐
2897 able libraries. For example, on cross-compiled cluster environments,
2898 this allows a user to ignore directories containing libraries meant for
2899 the front-end machine.
2900 By default, CMAKE_IGNORE_PATH is empty. It is intended to be set by the
2902 project or the end user.
2903 See also the following variables:
2905 • CMAKE_IGNORE_PREFIX_PATH
2907 • CMAKE_SYSTEM_IGNORE_PATH
2909 • CMAKE_PREFIX_PATH
2911 • CMAKE_LIBRARY_PATH
2913 • CMAKE_INCLUDE_PATH
2915 • CMAKE_PROGRAM_PATH
2917 CMAKE_IGNORE_PREFIX_PATH
2919 New in version 3.23.
2920 Semicolon-separated list of search prefixes to be ignored by the
2923 find_program(), find_library(), find_file(), and find_path() commands.
2924 The prefixes are also ignored by the Config mode of the find_package()
2925 command (Module mode is unaffected). To ignore specific directories
2926 instead, see CMAKE_IGNORE_PATH.
2927 Ignoring search locations can be useful in cross-compiling environments
2929 where some system directories contain incompatible but possibly link‐
2930 able libraries. For example, on cross-compiled cluster environments,
2931 this allows a user to ignore directories containing libraries meant for
2932 the front-end machine.
2933 By default, CMAKE_IGNORE_PREFIX_PATH is empty. It is intended to be set
2935 by the project or the end user.
2936 See also the following variables:
2938 • CMAKE_IGNORE_PATH
2940 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
2942 • CMAKE_PREFIX_PATH
2944 • CMAKE_LIBRARY_PATH
2946 • CMAKE_INCLUDE_PATH
2948 • CMAKE_PROGRAM_PATH
2950 CMAKE_INCLUDE_DIRECTORIES_BEFORE
2952 Whether to append or prepend directories by default in
2953 include_directories().
2954 This variable affects the default behavior of the include_directories()
2956 command. Setting this variable to ON is equivalent to using the BEFORE
2957 option in all uses of that command.
2958 CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
2960 Whether to force prepending of project include directories.
2961 This variable affects the order of include directories generated in
2963 compiler command lines. If set to ON, it causes the CMAKE_SOURCE_DIR
2964 and the CMAKE_BINARY_DIR to appear first.
2965 CMAKE_INCLUDE_PATH
2967 Semicolon-separated list of directories specifying a search path for
2968 the find_file() and find_path() commands. By default it is empty, it
2969 is intended to be set by the project.
2970 There is also an environment variable CMAKE_INCLUDE_PATH, which is used
2972 as an additional list of search directories.
2973 See also CMAKE_SYSTEM_INCLUDE_PATH and CMAKE_PREFIX_PATH.
2975 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
2977 Default component used in install() commands.
2978 If an install() command is used without the COMPONENT argument, these
2980 files will be grouped into a default component. The name of this de‐
2981 fault install component will be taken from this variable. It defaults
2982 to Unspecified.
2983 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2985 New in version 3.11.
2986 Default permissions for directories created implicitly during installa‐
2989 tion of files by install() and file(INSTALL).
2990 If make install is invoked and directories are implicitly created they
2992 get permissions set by CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2993 variable or platform specific default permissions if the variable is
2994 not set.
2995 Implicitly created directories are created if they are not explicitly
2997 installed by install() command but are needed to install a file on a
2998 certain path. Example of such locations are directories created due to
2999 the setting of CMAKE_INSTALL_PREFIX.
3000 Expected content of the CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
3002 variable is a list of permissions that can be used by install() command
3003 PERMISSIONS section.
3004 Example usage:
3006 set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
3008 OWNER_READ
3009 OWNER_WRITE
3010 OWNER_EXECUTE
3011 GROUP_READ
3012 )
3013 CMAKE_INSTALL_MESSAGE
3015 New in version 3.1.
3016 Specify verbosity of installation script code generated by the
3019 install() command (using the file(INSTALL) command). For paths that
3020 are newly installed or updated, installation may print lines like:
3021 -- Installing: /some/destination/path
3023 For paths that are already up to date, installation may print lines
3025 like:
3026 -- Up-to-date: /some/destination/path
3028 The CMAKE_INSTALL_MESSAGE variable may be set to control which messages
3030 are printed:
3031 ALWAYS Print both Installing and Up-to-date messages.
3033 LAZY Print Installing but not Up-to-date messages.
3035 NEVER Print neither Installing nor Up-to-date messages.
3037 Other values have undefined behavior and may not be diagnosed.
3039 If this variable is not set, the default behavior is ALWAYS.
3041 CMAKE_INSTALL_PREFIX
3043 Install directory used by install().
3044 If make install is invoked or INSTALL is built, this directory is
3046 prepended onto all install directories. This variable defaults to
3047 /usr/local on UNIX and c:/Program Files/${PROJECT_NAME} on Windows.
3048 See CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT for how a project might
3049 choose its own default.
3050 On UNIX one can use the DESTDIR mechanism in order to relocate the
3052 whole installation to a staging area. See the DESTDIR environment
3053 variable for more information.
3054 The installation prefix is also added to CMAKE_SYSTEM_PREFIX_PATH so
3056 that find_package(), find_program(), find_library(), find_path(), and
3057 find_file() will search the prefix for other software. This behavior
3058 can be disabled by setting the CMAKE_FIND_NO_INSTALL_PREFIX to TRUE be‐
3059 fore the first project() invocation.
3060 NOTE:
3062 Use the GNUInstallDirs module to provide GNU-style options for the
3063 layout of directories within the installation.
3064 The CMAKE_INSTALL_PREFIX may be defined when configuring a build tree
3066 to set its installation prefix. Or, when using the cmake(1) com‐
3067 mand-line tool's --install mode, one may specify a different prefix us‐
3068 ing the --prefix option:
3069 cmake --install . --prefix /my/install/prefix
3071 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
3073 New in version 3.7.1.
3074 CMake sets this variable to a TRUE value when the CMAKE_INSTALL_PREFIX
3077 has just been initialized to its default value, typically on the first
3078 run of CMake within a new build tree. This can be used by project code
3079 to change the default without overriding a user-provided value:
3080 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
3082 set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
3083 endif()
3084 CMAKE_KATE_FILES_MODE
3086 New in version 3.27.
3087 This cache variable is used by the Kate project generator and controls
3090 to what mode the files entry in the project file will be set. See
3091 cmake-generators(7).
3092 Possible values are AUTO, SVN, GIT, HG, FOSSIL and LIST.
3094 When set to LIST, CMake will put the list of source files known to
3096 CMake in the project file. When set to SVN, GIT, HG or FOSSIL, CMake
3097 will set the generated project accordingly to Subversion, git, Mercu‐
3098 rial or Fossil, and Kate will then use the respective command line tool
3099 to retrieve the list of files in the project. When unset or set to
3100 AUTO, CMake will try to detect whether the source directory is part of
3101 a git or svn checkout or not, and put the respective entry into the
3102 project file.
3103 CMAKE_KATE_MAKE_ARGUMENTS
3105 New in version 3.0.
3106 This cache variable is used by the Kate project generator. See
3109 cmake-generators(7).
3110 This variable holds arguments which are used when Kate invokes the make
3112 tool. By default it is initialized to hold flags to enable parallel
3113 builds (using -j typically).
3114 CMAKE_LIBRARY_PATH
3116 Semicolon-separated list of directories specifying a search path for
3117 the find_library() command. By default it is empty, it is intended to
3118 be set by the project.
3119 There is also an environment variable CMAKE_LIBRARY_PATH, which is used
3121 as an additional list of search directories.
3122 See also CMAKE_SYSTEM_LIBRARY_PATH and CMAKE_PREFIX_PATH.
3124 CMAKE_LINK_DIRECTORIES_BEFORE
3126 New in version 3.13.
3127 Whether to append or prepend directories by default in
3130 link_directories().
3131 This variable affects the default behavior of the link_directories()
3133 command. Setting this variable to ON is equivalent to using the BEFORE
3134 option in all uses of that command.
3135 CMAKE_LINK_LIBRARIES_ONLY_TARGETS
3137 New in version 3.23.
3138 Set this variable to initialize the LINK_LIBRARIES_ONLY_TARGETS prop‐
3141 erty of non-imported targets when they are created. Setting it to true
3142 enables an additional check that all items named by
3143 target_link_libraries() that can be target names are actually names of
3144 existing targets. See the target property documentation for details.
3145 CMAKE_MAXIMUM_RECURSION_DEPTH
3147 New in version 3.14.
3148 Maximum recursion depth for CMake scripts. It is intended to be set on
3151 the command line with -DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>, or within
3152 CMakeLists.txt by projects that require a large recursion depth.
3153 Projects that set this variable should provide the user with a way to
3154 override it. For example:
3155 # About to perform deeply recursive actions
3157 if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
3158 set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
3159 endif()
3160 If it is not set, or is set to a non-integer value, a sensible default
3162 limit is used. If the recursion limit is reached, the script terminates
3163 immediately with a fatal error.
3164 Calling any of the following commands increases the recursion depth:
3166 • include()
3168 • find_package()
3170 • add_subdirectory()
3172 • try_compile()
3174 • ctest_read_custom_files()
3176 • ctest_run_script() (unless NEW_PROCESS is specified)
3178 • User-defined function()'s and macro()'s (note that function() and
3180 macro() themselves don't increase recursion depth)
3181 • Reading or writing variables that are being watched by a
3183 variable_watch()
3184 See also the CMAKE_MAXIMUM_RECURSION_DEPTH environment variable.
3186 CMAKE_MESSAGE_CONTEXT
3188 New in version 3.17.
3189 When enabled by the cmake --log-context command line option or the
3192 CMAKE_MESSAGE_CONTEXT_SHOW variable, the message() command converts the
3193 CMAKE_MESSAGE_CONTEXT list into a dot-separated string surrounded by
3194 square brackets and prepends it to each line for messages of log levels
3195 NOTICE and below.
3196 For logging contexts to work effectively, projects should generally AP‐
3198 PEND and POP_BACK an item to the current value of CMAKE_MESSAGE_CONTEXT
3199 rather than replace it. Projects should not assume the message context
3200 at the top of the source tree is empty, as there are scenarios where
3201 the context might have already been set (e.g. hierarchical projects).
3202 WARNING:
3204 Valid context names are restricted to anything that could be used as
3205 a CMake variable name. All names that begin with an underscore or
3206 the string cmake_ are also reserved for use by CMake and should not
3207 be used by projects.
3208 Example:
3210 function(bar)
3212 list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
3213 message(VERBOSE "bar VERBOSE message")
3214 endfunction()
3215 function(baz)
3217 list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
3218 message(DEBUG "baz DEBUG message")
3219 endfunction()
3220 function(foo)
3222 list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
3223 bar()
3224 message(TRACE "foo TRACE message")
3225 baz()
3226 endfunction()
3227 list(APPEND CMAKE_MESSAGE_CONTEXT "top")
3229 message(VERBOSE "Before `foo`")
3231 foo()
3232 message(VERBOSE "After `foo`")
3233 list(POP_BACK CMAKE_MESSAGE_CONTEXT)
3235 Which results in the following output:
3237 -- [top] Before `foo`
3239 -- [top.foo.bar] bar VERBOSE message
3240 -- [top.foo] foo TRACE message
3241 -- [top.foo.baz] baz DEBUG message
3242 -- [top] After `foo`
3243 CMAKE_MESSAGE_CONTEXT_SHOW
3245 New in version 3.17.
3246 Setting this variable to true enables showing a context with each line
3249 logged by the message() command (see CMAKE_MESSAGE_CONTEXT for how the
3250 context itself is specified).
3251 This variable is an alternative to providing the --log-context option
3253 on the cmake command line. Whereas the command line option will apply
3254 only to that one CMake run, setting CMAKE_MESSAGE_CONTEXT_SHOW to true
3255 as a cache variable will ensure that subsequent CMake runs will con‐
3256 tinue to show the message context.
3257 Projects should not set CMAKE_MESSAGE_CONTEXT_SHOW. It is intended for
3259 users so that they may control whether or not to include context with
3260 messages.
3261 CMAKE_MESSAGE_INDENT
3263 New in version 3.16.
3264 The message() command joins the strings from this list and for log lev‐
3267 els of NOTICE and below, it prepends the resultant string to each line
3268 of the message.
3269 Example:
3271 list(APPEND listVar one two three)
3273 message(VERBOSE [[Collected items in the "listVar":]])
3275 list(APPEND CMAKE_MESSAGE_INDENT " ")
3276 foreach(item IN LISTS listVar)
3278 message(VERBOSE ${item})
3279 endforeach()
3280 list(POP_BACK CMAKE_MESSAGE_INDENT)
3282 message(VERBOSE "No more indent")
3283 Which results in the following output:
3285 -- Collected items in the "listVar":
3287 -- one
3288 -- two
3289 -- three
3290 -- No more indent
3291 CMAKE_MESSAGE_LOG_LEVEL
3293 New in version 3.17.
3294 When set, this variable specifies the logging level used by the
3297 message() command. Valid values are the same as those for the
3298 --log-level command line option of the cmake(1) program. If this vari‐
3299 able is set and the --log-level command line option is given, the com‐
3300 mand line option takes precedence.
3301 The main advantage to using this variable is to make a log level per‐
3303 sist between CMake runs. Setting it as a cache variable will ensure
3304 that subsequent CMake runs will continue to use the chosen log level.
3305 Projects should not set this variable, it is intended for users so that
3307 they may control the log level according to their own needs.
3308 New in version 3.25: See the cmake_language() cmake_language command
3310 for a way to query the current message logging level.
3311 CMAKE_MFC_FLAG
3314 Use the MFC library for an executable or dll.
3315 Enables the use of the Microsoft Foundation Classes (MFC). It should
3317 be set to 1 for the static MFC library, and 2 for the shared MFC li‐
3318 brary. This is used in Visual Studio project files.
3319 Usage example:
3321 add_definitions(-D_AFXDLL)
3323 set(CMAKE_MFC_FLAG 2)
3324 add_executable(CMakeSetup WIN32 ${SRCS})
3325 Contents of CMAKE_MFC_FLAG may use generator expressions.
3327 CMAKE_MODULE_PATH
3329 Semicolon-separated list of directories, represented using forward
3330 slashes, specifying a search path for CMake modules to be loaded by the
3331 include() or find_package() commands before checking the default mod‐
3332 ules that come with CMake. By default it is empty. It is intended to
3333 be set by the project.
3334 CMAKE_POLICY_DEFAULT_CMP<NNNN>
3336 Default for CMake Policy CMP<NNNN> when it is otherwise left unset.
3337 Commands cmake_minimum_required(VERSION) and cmake_policy(VERSION) by
3339 default leave policies introduced after the given version unset. Set
3340 CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to specify the default for
3341 policy CMP<NNNN>, where <NNNN> is the policy number.
3342 This variable should not be set by a project in CMake code as a way to
3344 set its own policies; use cmake_policy(SET) instead. This variable is
3345 meant to externally set policies for which a project has not itself
3346 been updated:
3347 • Users running CMake may set this variable in the cache (e.g. -DC‐
3349 MAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>). Set it to OLD to quiet a
3350 policy warning while using old behavior or to NEW to try building the
3351 project with new behavior.
3352 • Projects may set this variable before a call to add_subdirectory()
3354 that adds a third-party project in order to set its policies without
3355 modifying third-party code.
3356 CMAKE_POLICY_WARNING_CMP<NNNN>
3358 Explicitly enable or disable the warning when CMake Policy CMP<NNNN>
3359 has not been set explicitly by cmake_policy() or implicitly by
3360 cmake_minimum_required(). This is meaningful only for the policies that
3361 do not warn by default:
3362 • CMAKE_POLICY_WARNING_CMP0025 controls the warning for policy CMP0025.
3364 • CMAKE_POLICY_WARNING_CMP0047 controls the warning for policy CMP0047.
3366 • CMAKE_POLICY_WARNING_CMP0056 controls the warning for policy CMP0056.
3368 • CMAKE_POLICY_WARNING_CMP0060 controls the warning for policy CMP0060.
3370 • CMAKE_POLICY_WARNING_CMP0065 controls the warning for policy CMP0065.
3372 • CMAKE_POLICY_WARNING_CMP0066 controls the warning for policy CMP0066.
3374 • CMAKE_POLICY_WARNING_CMP0067 controls the warning for policy CMP0067.
3376 • CMAKE_POLICY_WARNING_CMP0082 controls the warning for policy CMP0082.
3378 • CMAKE_POLICY_WARNING_CMP0089 controls the warning for policy CMP0089.
3380 • CMAKE_POLICY_WARNING_CMP0102 controls the warning for policy CMP0102.
3382 • CMAKE_POLICY_WARNING_CMP0112 controls the warning for policy CMP0112.
3384 • CMAKE_POLICY_WARNING_CMP0116 controls the warning for policy CMP0116.
3386 • CMAKE_POLICY_WARNING_CMP0126 controls the warning for policy CMP0126.
3388 • CMAKE_POLICY_WARNING_CMP0128 controls the warning for policy CMP0128.
3390 • CMAKE_POLICY_WARNING_CMP0129 controls the warning for policy CMP0129.
3392 • CMAKE_POLICY_WARNING_CMP0133 controls the warning for policy CMP0133.
3394 This variable should not be set by a project in CMake code. Project
3396 developers running CMake may set this variable in their cache to enable
3397 the warning (e.g. -DCMAKE_POLICY_WARNING_CMP<NNNN>=ON). Alternatively,
3398 running cmake(1) with the --debug-output, --trace, or --trace-expand
3399 option will also enable the warning.
3400 CMAKE_PREFIX_PATH
3402 Semicolon-separated list of directories specifying installation pre‐
3403 fixes to be searched by the find_package(), find_program(),
3404 find_library(), find_file(), and find_path() commands. Each command
3405 will add appropriate subdirectories (like bin, lib, or include) as
3406 specified in its own documentation.
3407 By default this is empty. It is intended to be set by the project.
3409 There is also an environment variable CMAKE_PREFIX_PATH, which is used
3411 as an additional list of search prefixes.
3412 See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH,
3414 CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH, and CMAKE_IGNORE_PATH.
3415 CMAKE_PROGRAM_PATH
3417 Semicolon-separated list of directories specifying a search path for
3418 the find_program() command. By default it is empty, it is intended to
3419 be set by the project.
3420 There is also an environment variable CMAKE_PROGRAM_PATH, which is used
3422 as an additional list of search directories.
3423 See also CMAKE_SYSTEM_PROGRAM_PATH and CMAKE_PREFIX_PATH.
3425 CMAKE_PROJECT_INCLUDE
3427 New in version 3.15.
3428 A CMake language file or module to be included as the last step of all
3431 project() command calls. This is intended for injecting custom code
3432 into project builds without modifying their source. See Code Injection
3433 for a more detailed discussion of files potentially included during a
3434 project() call.
3435 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3437 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3438 CMAKE_PROJECT_INCLUDE_BEFORE, and CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3439 variables.
3440 CMAKE_PROJECT_INCLUDE_BEFORE
3442 New in version 3.15.
3443 A CMake language file or module to be included as the first step of all
3446 project() command calls. This is intended for injecting custom code
3447 into project builds without modifying their source. See Code Injection
3448 for a more detailed discussion of files potentially included during a
3449 project() call.
3450 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3452 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, CMAKE_PROJECT_INCLUDE, and
3453 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3454 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
3456 A CMake language file or module to be included as the last step of any
3457 project() command calls that specify <PROJECT-NAME> as the project
3458 name. This is intended for injecting custom code into project builds
3459 without modifying their source. See Code Injection for a more detailed
3460 discussion of files potentially included during a project() call.
3461 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3463 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3464 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3465 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
3467 New in version 3.17.
3468 A CMake language file or module to be included as the first step of any
3471 project() command calls that specify <PROJECT-NAME> as the project
3472 name. This is intended for injecting custom code into project builds
3473 without modifying their source. See Code Injection for a more detailed
3474 discussion of files potentially included during a project() call.
3475 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3477 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3478 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3479 CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3481 New in version 3.24.
3482 Semicolon-separated list of CMake language files to include as part of
3485 the very first project() call. The files will be included immediately
3486 after the toolchain file has been read (if one is specified) and plat‐
3487 form variables have been set, but before any languages have been en‐
3488 abled. Therefore, language-specific variables, including things like
3489 CMAKE_<LANG>_COMPILER, might not be set. See Code Injection for a more
3490 detailed discussion of files potentially included during a project()
3491 call.
3492 This variable is intended for specifying files that perform one-time
3494 setup for the build. It provides an injection point for things like
3495 configuring package managers, adding logic the user shares between
3496 projects (e.g. defining their own custom build types), and so on. It is
3497 primarily for users to add things specific to their environment, but
3498 not for specifying the toolchain details (use CMAKE_TOOLCHAIN_FILE for
3499 that).
3500 By default, this variable is empty. It is intended to be set by the
3502 user.
3503 See also the CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE,
3505 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, and
3506 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables.
3507 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>
3509 New in version 3.22.
3510 Variable for making find_package() call REQUIRED.
3513 Every non-REQUIRED find_package() call in a project can be turned into
3515 REQUIRED by setting the variable CMAKE_REQUIRE_FIND_PACKAGE_<Package‐
3516 Name> to TRUE. This can be used to assert assumptions about build en‐
3517 vironment and to ensure the build will fail early if they do not hold.
3518 See also the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable.
3520 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
3522 Don't make the install target depend on the all target.
3523 By default, the install target depends on the all target. This has the
3525 effect, that when make install is invoked or INSTALL is built, first
3526 the all target is built, then the installation starts. If
3527 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is set to TRUE, this dependency is
3528 not created, so the installation process will start immediately, inde‐
3529 pendent from whether the project has been completely built or not.
3530 CMAKE_STAGING_PREFIX
3532 This variable may be set to a path to install to when cross-compiling.
3533 This can be useful if the path in CMAKE_SYSROOT is read-only, or other‐
3534 wise should remain pristine.
3535 The CMAKE_STAGING_PREFIX location is also used as a search prefix by
3537 the find_* commands. This can be controlled by setting the
3538 CMAKE_FIND_NO_INSTALL_PREFIX variable.
3539 If any RPATH/RUNPATH entries passed to the linker contain the
3541 CMAKE_STAGING_PREFIX, the matching path fragments are replaced with the
3542 CMAKE_INSTALL_PREFIX.
3543 CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3545 New in version 3.8.
3546 This variable contains a list of env vars as a list of tokens with the
3549 syntax var=value.
3550 Example:
3552 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3554 "FOO=FOO1\;FOO2\;FOON"
3555 "BAR=BAR1\;BAR2\;BARN"
3556 "BAZ=BAZ1\;BAZ2\;BAZN"
3557 "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN"
3558 "VALID="
3559 )
3560 In case of malformed variables CMake will fail:
3562 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3564 "THIS_IS_NOT_VALID"
3565 )
3566 CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
3568 New in version 3.8.
3569 If this variable evaluates to ON at the end of the top-level CMake‐
3572 Lists.txt file, the Sublime Text 2 extra generator excludes the build
3573 tree from the .sublime-project if it is inside the source tree.
3574 CMAKE_SUPPRESS_REGENERATION
3576 New in version 3.12.
3577 If CMAKE_SUPPRESS_REGENERATION is OFF, which is default, then CMake
3580 adds a special target on which all other targets depend that checks the
3581 build system and optionally re-runs CMake to regenerate the build sys‐
3582 tem when the target specification source changes.
3583 If this variable evaluates to ON at the end of the top-level CMake‐
3585 Lists.txt file, CMake will not add the regeneration target to the build
3586 system or perform any build system checks.
3587 CMAKE_SYSROOT
3589 Path to pass to the compiler in the --sysroot flag.
3590 The CMAKE_SYSROOT content is passed to the compiler in the --sysroot
3592 flag, if supported. The path is also stripped from the RPATH/RUNPATH
3593 if necessary on installation. The CMAKE_SYSROOT is also used to prefix
3594 paths searched by the find_* commands.
3595 This variable may only be set in a toolchain file specified by the
3597 CMAKE_TOOLCHAIN_FILE variable.
3598 See also the CMAKE_SYSROOT_COMPILE and CMAKE_SYSROOT_LINK variables.
3600 CMAKE_SYSROOT_COMPILE
3602 New in version 3.9.
3603 Path to pass to the compiler in the --sysroot flag when compiling
3606 source files. This is the same as CMAKE_SYSROOT but is used only for
3607 compiling sources and not linking.
3608 This variable may only be set in a toolchain file specified by the
3610 CMAKE_TOOLCHAIN_FILE variable.
3611 CMAKE_SYSROOT_LINK
3613 New in version 3.9.
3614 Path to pass to the compiler in the --sysroot flag when linking. This
3617 is the same as CMAKE_SYSROOT but is used only for linking and not com‐
3618 piling sources.
3619 This variable may only be set in a toolchain file specified by the
3621 CMAKE_TOOLCHAIN_FILE variable.
3622 CMAKE_SYSTEM_APPBUNDLE_PATH
3624 New in version 3.4.
3625 Search path for macOS application bundles used by the find_program(),
3628 and find_package() commands. By default it contains the standard di‐
3629 rectories for the current system. It is not intended to be modified by
3630 the project, use CMAKE_APPBUNDLE_PATH for this.
3631 CMAKE_SYSTEM_FRAMEWORK_PATH
3633 New in version 3.4.
3634 Search path for macOS frameworks used by the find_library(),
3637 find_package(), find_path(), and find_file() commands. By default it
3638 contains the standard directories for the current system. It is not
3639 intended to be modified by the project, use CMAKE_FRAMEWORK_PATH for
3640 this.
3641 CMAKE_SYSTEM_IGNORE_PATH
3643 Semicolon-separated list of directories to be ignored by the various
3644 find...() commands.
3645 For find_program(), find_library(), find_file(), and find_path(), any
3647 file found in one of the listed directories will be ignored. The listed
3648 directories do not apply recursively, so any subdirectories to be ig‐
3649 nored must also be explicitly listed. CMAKE_SYSTEM_IGNORE_PATH does
3650 not affect the search prefixes used by these four commands. To ignore
3651 individual paths under a search prefix (e.g. bin, include, lib, etc.),
3652 each path must be listed in CMAKE_SYSTEM_IGNORE_PATH as a full absolute
3653 path. CMAKE_SYSTEM_IGNORE_PREFIX_PATH provides a more appropriate way
3654 to ignore a whole search prefix.
3655 find_package() is also affected by CMAKE_SYSTEM_IGNORE_PATH, but only
3657 for Config mode searches. Any <Name>Config.cmake or <name>-config.cmake
3658 file found in one of the specified directories will be ignored. In ad‐
3659 dition, any search prefix found in CMAKE_SYSTEM_IGNORE_PATH will be
3660 skipped for backward compatibility reasons, but new code should prefer
3661 to use CMAKE_SYSTEM_IGNORE_PREFIX_PATH to ignore prefixes instead.
3662 Ignoring search locations can be useful in cross-compiling environments
3664 where some system directories contain incompatible but possibly link‐
3665 able libraries. For example, on cross-compiled cluster environments,
3666 this allows a user to ignore directories containing libraries meant for
3667 the front-end machine.
3668 CMAKE_SYSTEM_IGNORE_PATH is populated by CMake as part of its platform
3670 and toolchain setup. Its purpose is to ignore locations containing in‐
3671 compatible binaries meant for the host rather than the target platform.
3672 The project or end user should not modify this variable, they should
3673 use CMAKE_IGNORE_PATH instead.
3674 See also the following variables:
3676 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3678 • CMAKE_SYSTEM_PREFIX_PATH
3680 • CMAKE_SYSTEM_LIBRARY_PATH
3682 • CMAKE_SYSTEM_INCLUDE_PATH
3684 • CMAKE_SYSTEM_PROGRAM_PATH
3686 CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3688 New in version 3.23.
3689 Semicolon-separated list of search prefixes to be ignored by the
3692 find_program(), find_library(), find_file(), and find_path() commands.
3693 The prefixes are also ignored by the Config mode of the find_package()
3694 command (Module mode is unaffected). To ignore specific directories
3695 instead, see CMAKE_SYSTEM_IGNORE_PATH.
3696 Ignoring search locations can be useful in cross-compiling environments
3698 where some system directories contain incompatible but possibly link‐
3699 able libraries. For example, on cross-compiled cluster environments,
3700 this allows a user to ignore directories containing libraries meant for
3701 the front-end machine.
3702 CMAKE_SYSTEM_IGNORE_PREFIX_PATH is populated by CMake as part of its
3704 platform and toolchain setup. Its purpose is to ignore locations con‐
3705 taining incompatible binaries meant for the host rather than the target
3706 platform. The project or end user should not modify this variable,
3707 they should use CMAKE_IGNORE_PREFIX_PATH instead.
3708 See also the following variables:
3710 • CMAKE_SYSTEM_IGNORE_PATH
3712 • CMAKE_SYSTEM_PREFIX_PATH
3714 • CMAKE_SYSTEM_LIBRARY_PATH
3716 • CMAKE_SYSTEM_INCLUDE_PATH
3718 • CMAKE_SYSTEM_PROGRAM_PATH
3720 CMAKE_SYSTEM_INCLUDE_PATH
3722 Semicolon-separated list of directories specifying a search path for
3723 the find_file() and find_path() commands. By default this contains the
3724 standard directories for the current system. It is not intended to be
3725 modified by the project; use CMAKE_INCLUDE_PATH for this. See also
3726 CMAKE_SYSTEM_PREFIX_PATH.
3727 CMAKE_SYSTEM_LIBRARY_PATH
3729 Semicolon-separated list of directories specifying a search path for
3730 the find_library() command. By default this contains the standard di‐
3731 rectories for the current system. It is not intended to be modified by
3732 the project; use CMAKE_LIBRARY_PATH for this. See also
3733 CMAKE_SYSTEM_PREFIX_PATH.
3734 CMAKE_SYSTEM_PREFIX_PATH
3736 Semicolon-separated list of directories specifying installation pre‐
3737 fixes to be searched by the find_package(), find_program(),
3738 find_library(), find_file(), and find_path() commands. Each command
3739 will add appropriate subdirectories (like bin, lib, or include) as
3740 specified in its own documentation.
3741 By default this contains the system directories for the current system,
3743 the CMAKE_INSTALL_PREFIX, and the CMAKE_STAGING_PREFIX. The installa‐
3744 tion and staging prefixes may be excluded by setting the
3745 CMAKE_FIND_NO_INSTALL_PREFIX variable before the first project() invo‐
3746 cation.
3747 The system directories that are contained in CMAKE_SYSTEM_PREFIX_PATH
3749 are locations that typically include installed software. An example be‐
3750 ing /usr/local for UNIX based platforms. In addition to standard plat‐
3751 form locations, CMake will also add values to CMAKE_SYSTEM_PREFIX_PATH
3752 based on environment variables. The environment variables and search
3753 locations that CMake uses may evolve over time, as platforms and their
3754 conventions also evolve. The following provides an indicative list of
3755 environment variables and locations that CMake searches, but they are
3756 subject to change:
3757 CrayLinuxEnvironment:
3759 • ENV{SYSROOT_DIR}/
3761 • ENV{SYSROOT_DIR}/usr
3763 • ENV{SYSROOT_DIR}/usr/local
3765 Darwin:
3767 • ENV{SDKROOT}/usr When CMAKE_OSX_SYSROOT is not explicitly
3769 specified.
3770 OpenBSD:
3772 • ENV{LOCALBASE}
3774 Unix:
3776 • ENV{CONDA_PREFIX} when using a conda compiler
3778 Windows:
3780 • ENV{ProgramW6432}
3782 • ENV{ProgramFiles}
3784 • ENV{ProgramFiles(x86)}
3786 • ENV{SystemDrive}/Program Files
3788 • ENV{SystemDrive}/Program Files (x86)
3790 CMAKE_SYSTEM_PREFIX_PATH is not intended to be modified by the project;
3792 use CMAKE_PREFIX_PATH for this.
3793 See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
3795 CMAKE_SYSTEM_PROGRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.
3796 CMAKE_SYSTEM_PROGRAM_PATH
3798 Semicolon-separated list of directories specifying a search path for
3799 the find_program() command. By default this contains the standard di‐
3800 rectories for the current system. It is not intended to be modified by
3801 the project; use CMAKE_PROGRAM_PATH for this. See also
3802 CMAKE_SYSTEM_PREFIX_PATH.
3803 CMAKE_TLS_CAINFO
3805 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3806 mands' TLS_CAINFO options. It is unset by default.
3807 This variable is also used by the ExternalProject and FetchContent mod‐
3809 ules for internal calls to file(DOWNLOAD).
3810 CMAKE_TLS_VERIFY
3812 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3813 mands' TLS_VERIFY options. If not set, the default is off.
3814 This variable is also used by the ExternalProject and FetchContent mod‐
3816 ules for internal calls to file(DOWNLOAD).
3817 TLS verification can help provide confidence that one is connecting to
3819 the desired server. When downloading known content, one should also
3820 use file hashes to verify it.
3821 set(CMAKE_TLS_VERIFY TRUE)
3823 CMAKE_USER_MAKE_RULES_OVERRIDE
3825 Specify a CMake file that overrides platform information.
3826 CMake loads the specified file while enabling support for each language
3828 from either the project() or enable_language() commands. It is loaded
3829 after CMake's builtin compiler and platform information modules have
3830 been loaded but before the information is used. The file may set plat‐
3831 form information variables to override CMake's defaults. See
3832 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> for the language-specific version
3833 of this variable.
3834 This feature is intended for use only in overriding information vari‐
3836 ables that must be set before CMake builds its first test project to
3837 check that the compiler for a language works. It should not be used to
3838 load a file in cases that a normal include() will work. Use it only as
3839 a last resort for behavior that cannot be achieved any other way. For
3840 example, one may set the CMAKE_C_FLAGS_INIT variable to change the de‐
3841 fault value used to initialize the CMAKE_C_FLAGS variable before it is
3842 cached. The override file should NOT be used to set anything that
3843 could be set after languages are enabled, such as variables like
3844 CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries.
3845 Information set in the file will be used for try_compile() and
3846 try_run() builds too.
3847 CMAKE_WARN_DEPRECATED
3849 Whether to issue warnings for deprecated functionality.
3850 If not FALSE, use of deprecated functionality will issue warnings. If
3852 this variable is not set, CMake behaves as if it were set to TRUE.
3853 When running cmake(1), this option can be enabled with the -Wdeprecated
3855 option, or disabled with the -Wno-deprecated option.
3856 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
3858 Ask cmake_install.cmake script to warn each time a file with absolute
3859 INSTALL DESTINATION is encountered.
3860 This variable is used by CMake-generated cmake_install.cmake scripts.
3862 If one sets this variable to ON while running the script, it may get
3863 warning messages from the script.
3864 CMAKE_XCODE_GENERATE_SCHEME
3866 New in version 3.9.
3867 If enabled, the Xcode generator will generate schema files. These are
3870 useful to invoke analyze, archive, build-for-testing and test actions
3871 from the command line.
3872 This variable initializes the XCODE_GENERATE_SCHEME target property on
3874 all targets.
3875 CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
3877 New in version 3.11.
3878 If enabled, the Xcode generator will generate only a single Xcode
3881 project file for the topmost project() command instead of generating
3882 one for every project() command.
3883 This could be useful to speed up the CMake generation step for large
3885 projects and to work-around a bug in the ZERO_CHECK logic.
3886 CMAKE_XCODE_LINK_BUILD_PHASE_MODE
3888 New in version 3.19.
3889 This variable is used to initialize the XCODE_LINK_BUILD_PHASE_MODE
3892 property on targets. It affects the methods that the Xcode generator
3893 uses to link different kinds of libraries. Its default value is NONE.
3894 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
3896 New in version 3.13.
3897 Whether to enable Address Sanitizer in the Diagnostics section of the
3900 generated Xcode scheme.
3901 This variable initializes the XCODE_SCHEME_ADDRESS_SANITIZER property
3903 on all targets.
3904 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3906 to see all Xcode schema related properties.
3907 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
3909 New in version 3.13.
3910 Whether to enable Detect use of stack after return in the Diagnostics
3913 section of the generated Xcode scheme.
3914 This variable initializes the
3916 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN property on all tar‐
3917 gets.
3918 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3920 to see all Xcode schema related properties.
3921 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3923 New in version 3.16.
3924 Whether to enable Allow debugging when using document Versions Browser
3927 in the Options section of the generated Xcode scheme.
3928 This variable initializes the XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3930 property on all targets.
3931 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3933 to see all Xcode schema related properties.
3934 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3936 New in version 3.13.
3937 Whether to disable the Main Thread Checker in the Diagnostics section
3940 of the generated Xcode scheme.
3941 This variable initializes the XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3943 property on all targets.
3944 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3946 to see all Xcode schema related properties.
3947 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
3949 New in version 3.13.
3950 Whether to enable Dynamic Library Loads in the Diagnostics section of
3953 the generated Xcode scheme.
3954 This variable initializes the XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS prop‐
3956 erty on all targets.
3957 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3959 to see all Xcode schema related properties.
3960 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3962 New in version 3.13.
3963 Whether to enable Dynamic Linker API usage in the Diagnostics section
3966 of the generated Xcode scheme.
3967 This variable initializes the XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3969 property on all targets.
3970 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3972 to see all Xcode schema related properties.
3973 CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3975 New in version 3.25.
3976 Property value for Metal: API Validation in the Options section of the
3979 generated Xcode scheme.
3980 This variable initializes the XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3982 property on all targets.
3983 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3985 to see all Xcode schema related properties.
3986 CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
3988 New in version 3.23.
3989 Property value for GPU Frame Capture in the Options section of the gen‐
3992 erated Xcode scheme. Example values are Metal and Disabled.
3993 This variable initializes the
3995 XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE property on all targets.
3996 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3998 to see all Xcode schema related properties.
3999 CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
4001 New in version 3.25.
4002 Property value for Metal: Shader Validation in the Options section of
4005 the generated Xcode scheme.
4006 This variable initializes the XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
4008 property on all targets.
4009 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4011 to see all Xcode schema related properties.
4012 CMAKE_XCODE_SCHEME_ENVIRONMENT
4014 New in version 3.17.
4015 Specify environment variables that should be added to the Arguments
4018 section of the generated Xcode scheme.
4019 If set to a list of environment variables and values of the form MY‐
4021 VAR=value those environment variables will be added to the scheme.
4022 This variable initializes the XCODE_SCHEME_ENVIRONMENT property on all
4024 targets.
4025 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4027 to see all Xcode schema related properties.
4028 CMAKE_XCODE_SCHEME_GUARD_MALLOC
4030 New in version 3.13.
4031 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
4034 ated Xcode scheme.
4035 This variable initializes the XCODE_SCHEME_GUARD_MALLOC property on all
4037 targets.
4038 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4040 to see all Xcode schema related properties.
4041 CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION
4043 New in version 3.25.
4044 Set the build configuration to run the target.
4047 This variable initializes the XCODE_SCHEME_LAUNCH_CONFIGURATION prop‐
4049 erty on all targets.
4050 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4052 to see all Xcode schema related properties.
4053 CMAKE_XCODE_SCHEME_LAUNCH_MODE
4055 New in version 3.25.
4056 Property value for Launch in the Info section of the generated Xcode
4059 scheme.
4060 This variable initializes the XCODE_SCHEME_LAUNCH_MODE property on all
4062 targets.
4063 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4065 to see all Xcode schema related properties.
4066 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
4068 New in version 3.13.
4069 Whether to enable the Main Thread Checker option Pause on issues in the
4072 Diagnostics section of the generated Xcode scheme.
4073 This variable initializes the XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
4075 property on all targets.
4076 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4078 to see all Xcode schema related properties.
4079 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
4081 New in version 3.13.
4082 Whether to enable Malloc Guard Edges in the Diagnostics section of the
4085 generated Xcode scheme.
4086 This variable initializes the XCODE_SCHEME_MALLOC_GUARD_EDGES property
4088 on all targets.
4089 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4091 to see all Xcode schema related properties.
4092 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
4094 New in version 3.13.
4095 Whether to enable Malloc Scribble in the Diagnostics section of the
4098 generated Xcode scheme.
4099 This variable initializes the XCODE_SCHEME_MALLOC_SCRIBBLE property on
4101 all targets.
4102 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4104 to see all Xcode schema related properties.
4105 CMAKE_XCODE_SCHEME_MALLOC_STACK
4107 New in version 3.13.
4108 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
4111 ated Xcode scheme.
4112 This variable initializes the XCODE_SCHEME_MALLOC_STACK property on all
4114 targets.
4115 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4117 to see all Xcode schema related properties.
4118 CMAKE_XCODE_SCHEME_THREAD_SANITIZER
4120 New in version 3.13.
4121 Whether to enable Thread Sanitizer in the Diagnostics section of the
4124 generated Xcode scheme.
4125 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER property on
4127 all targets.
4128 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4130 to see all Xcode schema related properties.
4131 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
4133 New in version 3.13.
4134 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
4137 section of the generated Xcode scheme.
4138 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER_STOP prop‐
4140 erty on all targets.
4141 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4143 to see all Xcode schema related properties.
4144 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
4146 New in version 3.13.
4147 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
4150 tion of the generated Xcode scheme.
4151 This variable initializes the
4153 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER property on all targets.
4154 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4156 to see all Xcode schema related properties.
4157 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
4159 New in version 3.13.
4160 Whether to enable Undefined Behavior Sanitizer option Pause on issues
4163 in the Diagnostics section of the generated Xcode scheme.
4164 This variable initializes the
4166 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP property on all tar‐
4167 gets.
4168 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4170 to see all Xcode schema related properties.
4171 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
4173 New in version 3.17.
4174 Specify the Working Directory of the Run and Profile actions in the
4177 generated Xcode scheme.
4178 This variable initializes the XCODE_SCHEME_WORKING_DIRECTORY property
4180 on all targets.
4181 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4183 to see all Xcode schema related properties.
4184 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
4186 New in version 3.13.
4187 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
4190 erated Xcode scheme.
4191 This variable initializes the XCODE_SCHEME_ZOMBIE_OBJECTS property on
4193 all targets.
4194 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4196 to see all Xcode schema related properties.
4197 CMAKE_XCODE_XCCONFIG
4199 New in version 3.24.
4200 If set, the Xcode generator will register the specified file as a
4203 global XCConfig file. For target-level XCConfig files see the
4204 XCODE_XCCONFIG target property.
4205 This feature is intended to ease migration from native Xcode projects
4207 to CMake projects.
4208 Contents of CMAKE_XCODE_XCCONFIG may use generator expressions.
4210 <PackageName>_ROOT
4212 New in version 3.12.
4213 Calls to find_package(<PackageName>) will search in prefixes specified
4216 by the <PackageName>_ROOT CMake variable, where <PackageName> is the
4217 (case-preserved) name given to the find_package() call and _ROOT is
4218 literal. For example, find_package(Foo) will search prefixes specified
4219 in the Foo_ROOT CMake variable (if set). See policy CMP0074.
4220 This variable may hold a single prefix or a semicolon-separated list of
4222 multiple prefixes.
4223 See also the <PackageName>_ROOT environment variable.
4225 <PACKAGENAME>_ROOT
4227 New in version 3.27.
4228 Calls to find_package(<PackageName>) will also search in pre‐
4231 fixes specified by the upper-case <PACKAGENAME>_ROOT CMake vari‐
4232 able. See policy CMP0144.
4233
4235 ANDROID
4236 New in version 3.7.
4237 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is Android.
4240 APPLE
4242 Set to True when the target system is an Apple platform (macOS, iOS,
4243 tvOS or watchOS).
4244 BORLAND
4246 True if the Borland compiler is being used.
4247 This is set to true if the Borland compiler is being used.
4249 BSD
4251 New in version 3.25.
4252 Set to a string value when the target system is BSD. This value can be
4255 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4256 CMAKE_ANDROID_NDK_VERSION
4258 New in version 3.20.
4259 When Cross Compiling for Android with the NDK and using an Android NDK
4262 version 11 or higher, this variable is provided by CMake to report the
4263 NDK version number.
4264 CMAKE_CL_64
4266 Discouraged. Use CMAKE_SIZEOF_VOID_P instead.
4267 Set to a true value when using a Microsoft Visual Studio cl compiler
4269 that targets a 64-bit architecture.
4270 CMAKE_COMPILER_2005
4272 Using the Visual Studio 2005 compiler from Microsoft
4273 Set to true when using the Visual Studio 2005 compiler from Microsoft.
4275 CMAKE_HOST_APPLE
4277 True for Apple macOS operating systems.
4278 Set to true when the host system is Apple macOS.
4280 CMAKE_HOST_BSD
4282 New in version 3.25.
4283 Set to a string value when the host system is BSD. This value can be
4286 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4287 CMAKE_HOST_LINUX
4289 New in version 3.25.
4290 Set to true when the host system is Linux.
4293 CMAKE_HOST_SOLARIS
4295 New in version 3.6.
4296 True for Oracle Solaris operating systems.
4299 Set to true when the host system is Oracle Solaris.
4301 CMAKE_HOST_SYSTEM
4303 Composite Name of OS CMake is being run on.
4304 This variable is the composite of CMAKE_HOST_SYSTEM_NAME and
4306 CMAKE_HOST_SYSTEM_VERSION, e.g. ${CMAKE_HOST_SYS‐
4307 TEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}. If CMAKE_HOST_SYSTEM_VERSION
4308 is not set, then this variable is the same as CMAKE_HOST_SYSTEM_NAME.
4309 CMAKE_HOST_SYSTEM_NAME
4311 Name of the OS CMake is running on.
4312 On systems that have the uname command, this variable is set to the
4314 output of uname -s. Linux, Windows, and Darwin for macOS are the val‐
4315 ues found on the big three operating systems.
4316 CMAKE_HOST_SYSTEM_PROCESSOR
4318 The name of the CPU CMake is running on.
4319 Windows Platforms
4321 On Windows, this variable is set to the value of the environment vari‐
4322 able PROCESSOR_ARCHITECTURE.
4323 Unix Platforms
4325 On systems that support uname, this variable is set to the output of:
4326 • uname -m on GNU, Linux, Cygwin, Android, or
4328 • arch on OpenBSD, or
4330 • on other systems,
4332 • uname -p if its exit code is nonzero, or
4334 • uname -m otherwise.
4336 macOS Platforms
4338 The value of uname -m is used by default.
4339 On Apple Silicon hosts, the architecture printed by uname -m may vary
4341 based on CMake's own architecture and that of the invoking process
4342 tree.
4343 New in version 3.19.2: On Apple Silicon hosts:
4345 • The CMAKE_APPLE_SILICON_PROCESSOR variable or the
4347 CMAKE_APPLE_SILICON_PROCESSOR environment variable may be set to
4348 specify the host architecture explicitly.
4349 • If CMAKE_OSX_ARCHITECTURES is not set, CMake adds explicit flags to
4351 tell the compiler to build for the host architecture so the toolchain
4352 does not have to guess based on the process tree's architecture.
4353 CMAKE_HOST_SYSTEM_VERSION
4356 The OS version CMake is running on.
4357 A numeric version string for the system. On systems that support un‐
4359 ame, this variable is set to the output of uname -r. On other systems
4360 this is set to major-minor version numbers.
4361 CMAKE_HOST_UNIX
4363 True for UNIX and UNIX like operating systems.
4364 Set to true when the host system is UNIX or UNIX like (i.e. APPLE and
4366 CYGWIN).
4367 CMAKE_HOST_WIN32
4369 True if the host system is running Windows, including Windows 64-bit
4370 and MSYS.
4371 Set to false on Cygwin.
4373 CMAKE_LIBRARY_ARCHITECTURE
4375 Target architecture library directory name, if detected.
4376 This is the value of CMAKE_<LANG>_LIBRARY_ARCHITECTURE as detected for
4378 one of the enabled languages.
4379 CMAKE_LIBRARY_ARCHITECTURE_REGEX
4381 Regex matching possible target architecture library directory names.
4382 This is used to detect CMAKE_<LANG>_LIBRARY_ARCHITECTURE from the im‐
4384 plicit linker search path by matching the <arch> name.
4385 CMAKE_OBJECT_PATH_MAX
4387 Maximum object file full-path length allowed by native build tools.
4388 CMake computes for every source file an object file name that is unique
4390 to the source file and deterministic with respect to the full path to
4391 the source file. This allows multiple source files in a target to
4392 share the same name if they lie in different directories without re‐
4393 building when one is added or removed. However, it can produce long
4394 full paths in a few cases, so CMake shortens the path using a hashing
4395 scheme when the full path to an object file exceeds a limit. CMake has
4396 a built-in limit for each platform that is sufficient for common tools,
4397 but some native tools may have a lower limit. This variable may be set
4398 to specify the limit explicitly. The value must be an integer no less
4399 than 128.
4400 CMAKE_SYSTEM
4402 Composite name of operating system CMake is compiling for.
4403 This variable is the composite of CMAKE_SYSTEM_NAME and
4405 CMAKE_SYSTEM_VERSION, e.g. ${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VER‐
4406 SION}. If CMAKE_SYSTEM_VERSION is not set, then this variable is the
4407 same as CMAKE_SYSTEM_NAME.
4408 CMAKE_SYSTEM_NAME
4410 The name of the operating system for which CMake is to build. See the
4411 CMAKE_SYSTEM_VERSION variable for the OS version.
4412 Note that CMAKE_SYSTEM_NAME is not set to anything by default when run‐
4414 ning in script mode, since it's not building anything.
4415 System Name for Host Builds
4417 CMAKE_SYSTEM_NAME is by default set to the same value as the
4418 CMAKE_HOST_SYSTEM_NAME variable so that the build targets the host sys‐
4419 tem.
4420 System Name for Cross Compiling
4422 CMAKE_SYSTEM_NAME may be set explicitly when first configuring a new
4423 build tree in order to enable cross compiling. In this case the
4424 CMAKE_SYSTEM_VERSION variable must also be set explicitly.
4425 CMAKE_SYSTEM_PROCESSOR
4427 When not cross-compiling, this variable has the same value as the
4428 CMAKE_HOST_SYSTEM_PROCESSOR variable. In many cases, this will corre‐
4429 spond to the target architecture for the build, but this is not guaran‐
4430 teed. (E.g. on Windows, the host may be AMD64 even when using a MSVC
4431 cl compiler with a 32-bit target.)
4432 When cross-compiling, a CMAKE_TOOLCHAIN_FILE should set the CMAKE_SYS‐
4434 TEM_PROCESSOR variable to match target architecture that it specifies
4435 (via CMAKE_<LANG>_COMPILER and perhaps CMAKE_<LANG>_COMPILER_TARGET).
4436 CMAKE_SYSTEM_VERSION
4438 The version of the operating system for which CMake is to build. See
4439 the CMAKE_SYSTEM_NAME variable for the OS name.
4440 System Version for Host Builds
4442 When the CMAKE_SYSTEM_NAME variable takes its default value then
4443 CMAKE_SYSTEM_VERSION is by default set to the same value as the
4444 CMAKE_HOST_SYSTEM_VERSION variable so that the build targets the host
4445 system version.
4446 In the case of a host build then CMAKE_SYSTEM_VERSION may be set ex‐
4448 plicitly when first configuring a new build tree in order to enable
4449 targeting the build for a different version of the host operating sys‐
4450 tem than is actually running on the host. This is allowed and not con‐
4451 sidered cross compiling so long as the binaries built for the specified
4452 OS version can still run on the host.
4453 System Version for Cross Compiling
4455 When the CMAKE_SYSTEM_NAME variable is set explicitly to enable cross
4456 compiling then the value of CMAKE_SYSTEM_VERSION must also be set ex‐
4457 plicitly to specify the target system version.
4458 CYGWIN
4460 True for Cygwin.
4461 Set to true when using Cygwin.
4463 GHSMULTI
4465 New in version 3.3.
4466 1 when using Green Hills MULTI generator.
4469 Also, Set to 1 when the target system is a Green Hills platform (i.e.
4471 When CMAKE_SYSTEM_NAME is GHS-MULTI).
4472 IOS
4474 New in version 3.14.
4475 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is iOS.
4478 LINUX
4480 New in version 3.25.
4481 Set to true when the target system is Linux.
4484 MINGW
4486 New in version 3.2.
4487 Set to a true value when at least one language is enabled with a com‐
4490 piler targeting the GNU ABI on Windows (MinGW).
4491 Otherwise, this variable is not set by CMake.
4493 MSVC
4495 Set to true when the compiler is some version of Microsoft Visual C++
4496 or another compiler simulating the Visual C++ cl command-line syntax.
4497 See also the MSVC_VERSION variable.
4499 MSVC10
4501 Discouraged. Use the MSVC_VERSION variable instead.
4502 True when using the Microsoft Visual Studio v100 toolset (cl version
4504 16) or another compiler that simulates it.
4505 MSVC11
4507 Discouraged. Use the MSVC_VERSION variable instead.
4508 True when using the Microsoft Visual Studio v110 toolset (cl version
4510 17) or another compiler that simulates it.
4511 MSVC12
4513 Discouraged. Use the MSVC_VERSION variable instead.
4514 True when using the Microsoft Visual Studio v120 toolset (cl version
4516 18) or another compiler that simulates it.
4517 MSVC14
4519 New in version 3.1.
4520 Discouraged. Use the MSVC_VERSION variable instead.
4523 True when using the Microsoft Visual Studio v140 or v141 toolset (cl
4525 version 19) or another compiler that simulates it.
4526 MSVC60
4528 Discouraged. Use the MSVC_VERSION variable instead.
4529 True when using Microsoft Visual C++ 6.0.
4531 Set to true when the compiler is version 6.0 of Microsoft Visual C++.
4533 MSVC70
4535 Discouraged. Use the MSVC_VERSION variable instead.
4536 True when using Microsoft Visual C++ 7.0.
4538 Set to true when the compiler is version 7.0 of Microsoft Visual C++.
4540 MSVC71
4542 Discouraged. Use the MSVC_VERSION variable instead.
4543 True when using Microsoft Visual C++ 7.1.
4545 Set to true when the compiler is version 7.1 of Microsoft Visual C++.
4547 MSVC80
4549 Discouraged. Use the MSVC_VERSION variable instead.
4550 True when using the Microsoft Visual Studio v80 toolset (cl version 14)
4552 or another compiler that simulates it.
4553 MSVC90
4555 Discouraged. Use the MSVC_VERSION variable instead.
4556 True when using the Microsoft Visual Studio v90 toolset (cl version 15)
4558 or another compiler that simulates it.
4559 MSVC_IDE
4561 True when using the Microsoft Visual C++ IDE.
4562 Set to true when the target platform is the Microsoft Visual C++ IDE,
4564 as opposed to the command line compiler.
4565 NOTE:
4567 This variable is only available after compiler detection has been
4568 performed, so it is not available to toolchain files or before the
4569 first project() or enable_language() call which uses an MSVC-like
4570 compiler.
4571 MSVC_TOOLSET_VERSION
4573 New in version 3.12.
4574 The toolset version of Microsoft Visual C/C++ being used if any. If
4577 MSVC-like is being used, this variable is set based on the version of
4578 the compiler as given by the MSVC_VERSION variable.
4579 Known toolset version numbers are:
4581 80 = VS 2005 (8.0)
4583 90 = VS 2008 (9.0)
4584 100 = VS 2010 (10.0)
4585 110 = VS 2012 (11.0)
4586 120 = VS 2013 (12.0)
4587 140 = VS 2015 (14.0)
4588 141 = VS 2017 (15.0)
4589 142 = VS 2019 (16.0)
4590 143 = VS 2022 (17.0)
4591 Compiler versions newer than those known to CMake will be reported as
4593 the latest known toolset version.
4594 See also the MSVC_VERSION variable.
4596 MSVC_VERSION
4598 The version of Microsoft Visual C/C++ being used if any. If a compiler
4599 simulating Visual C++ is being used, this variable is set to the
4600 toolset version simulated as given by the _MSC_VER preprocessor defini‐
4601 tion.
4602 Known version numbers are:
4604 1200 = VS 6.0
4606 1300 = VS 7.0
4607 1310 = VS 7.1
4608 1400 = VS 8.0 (v80 toolset)
4609 1500 = VS 9.0 (v90 toolset)
4610 1600 = VS 10.0 (v100 toolset)
4611 1700 = VS 11.0 (v110 toolset)
4612 1800 = VS 12.0 (v120 toolset)
4613 1900 = VS 14.0 (v140 toolset)
4614 1910-1919 = VS 15.0 (v141 toolset)
4615 1920-1929 = VS 16.0 (v142 toolset)
4616 1930-1939 = VS 17.0 (v143 toolset)
4617 See also the CMAKE_<LANG>_COMPILER_VERSION and MSVC_TOOLSET_VERSION
4619 variable.
4620 MSYS
4622 New in version 3.14.
4623 True when using the MSYS Makefiles generator.
4626 UNIX
4628 Set to True when the target system is UNIX or UNIX-like (e.g. APPLE and
4629 CYGWIN). The CMAKE_SYSTEM_NAME variable should be queried if a more
4630 specific understanding of the target system is required.
4631 WIN32
4633 Set to True when the target system is Windows, including Win64.
4634 WINCE
4636 New in version 3.1.
4637 True when the CMAKE_SYSTEM_NAME variable is set to WindowsCE.
4640 WINDOWS_PHONE
4642 New in version 3.1.
4643 True when the CMAKE_SYSTEM_NAME variable is set to WindowsPhone.
4646 WINDOWS_STORE
4648 New in version 3.1.
4649 True when the CMAKE_SYSTEM_NAME variable is set to WindowsStore.
4652 XCODE
4654 New in version 3.7.
4655 True when using Xcode generator.
4658 XCODE_VERSION
4660 Version of Xcode (Xcode generator only).
4661 Under the Xcode generator, this is the version of Xcode as specified in
4663 Xcode.app/Contents/version.plist (such as 3.1.2).
4664
4666 CMAKE_ADSP_ROOT
4667 New in version 3.24.
4668 When Cross Compiling for ADSP SHARC/Blackfin, this variable holds the
4671 absolute path to the latest CCES or VDSP++ install. The directory is
4672 expected to contain the cc21k.exe and ccblkfn.exe compilers. This will
4673 be set automatically if a default install of CCES or VDSP++ can be
4674 found.
4675 See also the ADSP_ROOT environment variable.
4677 CMAKE_AIX_EXPORT_ALL_SYMBOLS
4679 New in version 3.17.
4680 Default value for AIX_EXPORT_ALL_SYMBOLS target property. This vari‐
4683 able is used to initialize the property on each target as it is cre‐
4684 ated.
4685 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
4687 New in version 3.4.
4688 Default value for the ANDROID_ANT_ADDITIONAL_OPTIONS target property.
4691 See that target property for additional information.
4692 CMAKE_ANDROID_API
4694 New in version 3.1.
4695 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4698 Edition, this variable may be set to specify the default value for the
4699 ANDROID_API target property. See that target property for additional
4700 information.
4701 When Cross Compiling for Android, the CMAKE_SYSTEM_VERSION variable
4703 represents the Android API version number targeted. For historical
4704 reasons, if a toolchain file sets CMAKE_ANDROID_API, but not CMAKE_SYS‐
4705 TEM_VERSION, the latter will be initialized using the former.
4706 CMAKE_ANDROID_API_MIN
4708 New in version 3.2.
4709 Default value for the ANDROID_API_MIN target property. See that target
4712 property for additional information.
4713 CMAKE_ANDROID_ARCH
4715 New in version 3.4.
4716 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4719 Edition, this variable may be set to specify the default value for the
4720 ANDROID_ARCH target property. See that target property for additional
4721 information.
4722 Otherwise, when Cross Compiling for Android, this variable provides the
4724 name of the Android architecture corresponding to the value of the
4725 CMAKE_ANDROID_ARCH_ABI variable. The architecture name may be one of:
4726 • arm
4728 • arm64
4730 • mips
4732 • mips64
4734 • x86
4736 • x86_64
4738 CMAKE_ANDROID_ARCH_ABI
4740 New in version 3.7.
4741 When Cross Compiling for Android, this variable specifies the target
4744 architecture and ABI to be used. Valid values are:
4745 • arm64-v8a
4747 • armeabi-v7a
4749 • armeabi-v6
4751 • armeabi
4753 • mips
4755 • mips64
4757 • x86
4759 • x86_64
4761 See also the CMAKE_ANDROID_ARM_MODE and CMAKE_ANDROID_ARM_NEON vari‐
4763 ables.
4764 CMAKE_ANDROID_ARM_MODE
4766 New in version 3.7.
4767 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4770 one of the armeabi architectures, set CMAKE_ANDROID_ARM_MODE to ON to
4771 target 32-bit ARM processors (-marm). Otherwise, the default is to
4772 target the 16-bit Thumb processors (-mthumb).
4773 CMAKE_ANDROID_ARM_NEON
4775 New in version 3.7.
4776 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4779 armeabi-v7a set CMAKE_ANDROID_ARM_NEON to ON to target ARM NEON de‐
4780 vices.
4781 CMAKE_ANDROID_ASSETS_DIRECTORIES
4783 New in version 3.4.
4784 Default value for the ANDROID_ASSETS_DIRECTORIES target property. See
4787 that target property for additional information.
4788 CMAKE_ANDROID_EXCEPTIONS
4790 New in version 3.20.
4791 When Cross Compiling for Android with the NDK, this variable may be set
4794 to specify whether exceptions are enabled.
4795 CMAKE_ANDROID_GUI
4797 New in version 3.1.
4798 Default value for the ANDROID_GUI target property of executables. See
4801 that target property for additional information.
4802 CMAKE_ANDROID_JAR_DEPENDENCIES
4804 New in version 3.4.
4805 Default value for the ANDROID_JAR_DEPENDENCIES target property. See
4808 that target property for additional information.
4809 CMAKE_ANDROID_JAR_DIRECTORIES
4811 New in version 3.4.
4812 Default value for the ANDROID_JAR_DIRECTORIES target property. See
4815 that target property for additional information.
4816 CMAKE_ANDROID_JAVA_SOURCE_DIR
4818 New in version 3.4.
4819 Default value for the ANDROID_JAVA_SOURCE_DIR target property. See
4822 that target property for additional information.
4823 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
4825 New in version 3.4.
4826 Default value for the ANDROID_NATIVE_LIB_DEPENDENCIES target property.
4829 See that target property for additional information.
4830 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
4832 New in version 3.4.
4833 Default value for the ANDROID_NATIVE_LIB_DIRECTORIES target property.
4836 See that target property for additional information.
4837 CMAKE_ANDROID_NDK
4839 New in version 3.7.
4840 When Cross Compiling for Android with the NDK, this variable holds the
4843 absolute path to the root directory of the NDK. The directory must
4844 contain a platforms subdirectory holding the android-<api> directories.
4845 CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
4847 New in version 3.9.
4848 When Cross Compiling for Android with the NDK, this variable may be set
4851 to specify whether to use the deprecated per-api-level headers instead
4852 of the unified headers.
4853 If not specified, the default will be false if using a NDK version that
4855 provides the unified headers and true otherwise.
4856 CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
4858 New in version 3.7.1.
4859 When Cross Compiling for Android with the NDK, this variable provides
4862 the NDK's "host tag" used to construct the path to prebuilt toolchains
4863 that run on the host.
4864 CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
4866 New in version 3.7.
4867 When Cross Compiling for Android with the NDK, this variable may be set
4870 to specify the version of the toolchain to be used as the compiler.
4871 On NDK r19 or above, this variable must be unset or set to clang.
4873 On NDK r18 or below, this variable must be set to one of these forms:
4875 • <major>.<minor>: GCC of specified version
4877 • clang<major>.<minor>: Clang of specified version
4879 • clang: Clang of most recent available version
4881 A toolchain of the requested version will be selected automatically to
4883 match the ABI named in the CMAKE_ANDROID_ARCH_ABI variable.
4884 If not specified, the default will be a value that selects the latest
4886 available GCC toolchain.
4887 CMAKE_ANDROID_PROCESS_MAX
4889 New in version 3.4.
4890 Default value for the ANDROID_PROCESS_MAX target property. See that
4893 target property for additional information.
4894 CMAKE_ANDROID_PROGUARD
4896 New in version 3.4.
4897 Default value for the ANDROID_PROGUARD target property. See that tar‐
4900 get property for additional information.
4901 CMAKE_ANDROID_PROGUARD_CONFIG_PATH
4903 New in version 3.4.
4904 Default value for the ANDROID_PROGUARD_CONFIG_PATH target property.
4907 See that target property for additional information.
4908 CMAKE_ANDROID_RTTI
4910 New in version 3.20.
4911 When Cross Compiling for Android with the NDK, this variable may be set
4914 to specify whether RTTI is enabled.
4915 CMAKE_ANDROID_SECURE_PROPS_PATH
4917 New in version 3.4.
4918 Default value for the ANDROID_SECURE_PROPS_PATH target property. See
4921 that target property for additional information.
4922 CMAKE_ANDROID_SKIP_ANT_STEP
4924 New in version 3.4.
4925 Default value for the ANDROID_SKIP_ANT_STEP target property. See that
4928 target property for additional information.
4929 CMAKE_ANDROID_STANDALONE_TOOLCHAIN
4931 New in version 3.7.
4932 When Cross Compiling for Android with a Standalone Toolchain, this
4935 variable holds the absolute path to the root directory of the
4936 toolchain. The specified directory must contain a sysroot subdirec‐
4937 tory.
4938 CMAKE_ANDROID_STL_TYPE
4940 New in version 3.4.
4941 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4944 Edition, this variable may be set to specify the default value for the
4945 ANDROID_STL_TYPE target property. See that target property for addi‐
4946 tional information.
4947 When Cross Compiling for Android with the NDK, this variable may be set
4949 to specify the STL variant to be used. The value may be one of:
4950 none No C++ Support
4952 system Minimal C++ without STL
4954 gabi++_static
4956 GAbi++ Static
4957 gabi++_shared
4959 GAbi++ Shared
4960 gnustl_static
4962 GNU libstdc++ Static
4963 gnustl_shared
4965 GNU libstdc++ Shared
4966 c++_static
4968 LLVM libc++ Static
4969 c++_shared
4971 LLVM libc++ Shared
4972 stlport_static
4974 STLport Static
4975 stlport_shared
4977 STLport Shared
4978 The default value is gnustl_static on NDK versions that provide it and
4980 otherwise c++_static. Note that this default differs from the native
4981 NDK build system because CMake may be used to build projects for An‐
4982 droid that are not natively implemented for it and use the C++ standard
4983 library.
4984 CMAKE_APPLE_SILICON_PROCESSOR
4986 New in version 3.19.2.
4987 On Apple Silicon hosts running macOS, set this variable to tell CMake
4990 what architecture to use for CMAKE_HOST_SYSTEM_PROCESSOR. The value
4991 must be either arm64 or x86_64.
4992 The value of this variable should never be modified by project code.
4994 It is meant to be set as a cache entry provided by the user, e.g. via
4995 -DCMAKE_APPLE_SILICON_PROCESSOR=....
4996 See also the CMAKE_APPLE_SILICON_PROCESSOR environment variable.
4998 CMAKE_ARCHIVE_OUTPUT_DIRECTORY
5000 Where to put all the ARCHIVE target files when built.
5001 This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY prop‐
5003 erty on all the targets. See that target property for additional in‐
5004 formation.
5005 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
5007 New in version 3.3.
5008 Where to put all the ARCHIVE target files when built for a specific
5011 configuration.
5012 This variable is used to initialize the
5014 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
5015 that target property for additional information.
5016 CMAKE_AUTOGEN_ORIGIN_DEPENDS
5018 New in version 3.14.
5019 Switch for forwarding origin target dependencies to the corresponding
5022 _autogen targets.
5023 This variable is used to initialize the AUTOGEN_ORIGIN_DEPENDS property
5025 on all the targets. See that target property for additional informa‐
5026 tion.
5027 By default CMAKE_AUTOGEN_ORIGIN_DEPENDS is ON.
5029 CMAKE_AUTOGEN_PARALLEL
5031 New in version 3.11.
5032 Number of parallel moc or uic processes to start when using AUTOMOC and
5035 AUTOUIC.
5036 This variable is used to initialize the AUTOGEN_PARALLEL property on
5038 all the targets. See that target property for additional information.
5039 By default CMAKE_AUTOGEN_PARALLEL is unset.
5041 CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
5043 New in version 3.27.
5044 This variable is used to initialize the AUTOGEN_USE_SYSTEM_INCLUDE
5047 property on all targets as they are created. See that target property
5048 for additional information.
5049 By default CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE is unset.
5051 CMAKE_AUTOGEN_VERBOSE
5053 New in version 3.13.
5054 Sets the verbosity of AUTOMOC, AUTOUIC and AUTORCC. A positive integer
5057 value or a true boolean value lets the AUTO* generators output addi‐
5058 tional processing information.
5059 Setting CMAKE_AUTOGEN_VERBOSE has the same effect as setting the VER‐
5061 BOSE environment variable during generation (e.g. by calling make VER‐
5062 BOSE=1). The extra verbosity is limited to the AUTO* generators
5063 though.
5064 By default CMAKE_AUTOGEN_VERBOSE is unset.
5066 CMAKE_AUTOMOC
5068 Whether to handle moc automatically for Qt targets.
5069 This variable is used to initialize the AUTOMOC property on all the
5071 targets. See that target property for additional information.
5072 CMAKE_AUTOMOC_COMPILER_PREDEFINES
5074 New in version 3.10.
5075 This variable is used to initialize the AUTOMOC_COMPILER_PREDEFINES
5078 property on all the targets. See that target property for additional
5079 information.
5080 By default it is ON.
5082 CMAKE_AUTOMOC_DEPEND_FILTERS
5084 New in version 3.9.
5085 Filter definitions used by CMAKE_AUTOMOC to extract file names from
5088 source code as additional dependencies for the moc file.
5089 This variable is used to initialize the AUTOMOC_DEPEND_FILTERS property
5091 on all the targets. See that target property for additional informa‐
5092 tion.
5093 By default it is empty.
5095 CMAKE_AUTOMOC_MACRO_NAMES
5097 New in version 3.10.
5098 Semicolon-separated list list of macro names used by CMAKE_AUTOMOC to
5101 determine if a C++ file needs to be processed by moc.
5102 This variable is used to initialize the AUTOMOC_MACRO_NAMES property on
5104 all the targets. See that target property for additional information.
5105 The default value is Q_OBJECT;Q_GADGET;Q_NAMESPACE;Q_NAMESPACE_EXPORT.
5107 Example
5109 Let CMake know that source files that contain CUSTOM_MACRO must be moc
5110 processed as well:
5111 set(CMAKE_AUTOMOC ON)
5113 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
5114 CMAKE_AUTOMOC_MOC_OPTIONS
5116 Additional options for moc when using CMAKE_AUTOMOC.
5117 This variable is used to initialize the AUTOMOC_MOC_OPTIONS property on
5119 all the targets. See that target property for additional information.
5120 CMAKE_AUTOMOC_PATH_PREFIX
5122 New in version 3.16.
5123 Whether to generate the -p path prefix option for moc on AUTOMOC en‐
5126 abled Qt targets.
5127 This variable is used to initialize the AUTOMOC_PATH_PREFIX property on
5129 all the targets. See that target property for additional information.
5130 The default value is OFF.
5132 CMAKE_AUTOMOC_EXECUTABLE
5134 New in version 3.27.
5135 This variable is used to initialize the AUTOMOC_EXECUTABLE property on
5138 all the targets. See that target property for additional information.
5139 By default it is empty.
5141 CMAKE_AUTORCC
5143 Whether to handle rcc automatically for Qt targets.
5144 This variable is used to initialize the AUTORCC property on all the
5146 targets. See that target property for additional information.
5147 CMAKE_AUTORCC_OPTIONS
5149 Additional options for rcc when using CMAKE_AUTORCC.
5150 This variable is used to initialize the AUTORCC_OPTIONS property on all
5152 the targets. See that target property for additional information.
5153 EXAMPLE
5155 # ...
5156 set(CMAKE_AUTORCC_OPTIONS "--compress;9")
5157 # ...
5158 CMAKE_AUTORCC_EXECUTABLE
5160 New in version 3.27.
5161 This variable is used to initialize the AUTORCC_EXECUTABLE property on
5164 all the targets. See that target property for additional information.
5165 By default it is empty.
5167 CMAKE_AUTOUIC
5169 Whether to handle uic automatically for Qt targets.
5170 This variable is used to initialize the AUTOUIC property on all the
5172 targets. See that target property for additional information.
5173 CMAKE_AUTOUIC_OPTIONS
5175 Additional options for uic when using CMAKE_AUTOUIC.
5176 This variable is used to initialize the AUTOUIC_OPTIONS property on all
5178 the targets. See that target property for additional information.
5179 EXAMPLE
5181 # ...
5182 set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection")
5183 # ...
5184 CMAKE_AUTOUIC_SEARCH_PATHS
5186 New in version 3.9.
5187 Search path list used by CMAKE_AUTOUIC to find included .ui files.
5190 This variable is used to initialize the AUTOUIC_SEARCH_PATHS property
5192 on all the targets. See that target property for additional informa‐
5193 tion.
5194 By default it is empty.
5196 CMAKE_AUTOUIC_EXECUTABLE
5198 New in version 3.27.
5199 This variable is used to initialize the AUTOUIC_EXECUTABLE property on
5202 all the targets. See that target property for additional information.
5203 By default it is empty.
5205 CMAKE_BUILD_RPATH
5207 New in version 3.8.
5208 Semicolon-separated list specifying runtime path (RPATH) entries to add
5211 to binaries linked in the build tree (for platforms that support it).
5212 The entries will not be used for binaries in the install tree. See
5213 also the CMAKE_INSTALL_RPATH variable.
5214 This is used to initialize the BUILD_RPATH target property for all tar‐
5216 gets.
5217 CMAKE_BUILD_RPATH_USE_ORIGIN
5219 New in version 3.14.
5220 Whether to use relative paths for the build RPATH.
5223 This is used to initialize the BUILD_RPATH_USE_ORIGIN target property
5225 for all targets, see that property for more details.
5226 CMAKE_BUILD_WITH_INSTALL_NAME_DIR
5228 New in version 3.9.
5229 Whether to use INSTALL_NAME_DIR on targets in the build tree.
5232 This variable is used to initialize the BUILD_WITH_INSTALL_NAME_DIR
5234 property on all targets.
5235 CMAKE_BUILD_WITH_INSTALL_RPATH
5237 Use the install path for the RPATH.
5238 Normally CMake uses the build tree for the RPATH when building executa‐
5240 bles etc on systems that use RPATH. When the software is installed the
5241 executables etc are relinked by CMake to have the install RPATH. If
5242 this variable is set to true then the software is always built with the
5243 install path for the RPATH and does not need to be relinked when in‐
5244 stalled.
5245 This is used to initialize the BUILD_WITH_INSTALL_RPATH target property
5247 for all targets.
5248 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
5250 New in version 3.1.
5251 Output directory for MS debug symbol .pdb files generated by the com‐
5254 piler while building source files.
5255 This variable is used to initialize the COMPILE_PDB_OUTPUT_DIRECTORY
5257 property on all the targets.
5258 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
5260 New in version 3.1.
5261 Per-configuration output directory for MS debug symbol .pdb files gen‐
5264 erated by the compiler while building source files.
5265 This is a per-configuration version of
5267 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY. This variable is used to initial‐
5268 ize the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property on all the tar‐
5269 gets.
5270 CMAKE_COMPILE_WARNING_AS_ERROR
5272 New in version 3.24.
5273 Specify whether to treat warnings on compile as errors.
5276 This variable is used to initialize the COMPILE_WARNING_AS_ERROR prop‐
5278 erty on all the targets.
5279 CMAKE_<CONFIG>_POSTFIX
5281 Default filename postfix for libraries under configuration <CONFIG>.
5282 When a non-executable target is created its <CONFIG>_POSTFIX target
5284 property is initialized with the value of this variable if it is set.
5285 CMAKE_CROSS_CONFIGS
5287 New in version 3.17.
5288 Specifies a semicolon-separated list of configurations available from
5291 all build-<Config>.ninja files in the Ninja Multi-Config generator.
5292 This variable activates cross-config mode. Targets from each config
5293 specified in this variable can be built from any build-<Config>.ninja
5294 file. Custom commands will use the configuration native to build-<Con‐
5295 fig>.ninja. If it is set to all, all configurations from
5296 CMAKE_CONFIGURATION_TYPES are cross-configs. If it is not specified, or
5297 empty, each build-<Config>.ninja file will only contain build rules for
5298 its own configuration.
5299 The value of this variable must be a subset of
5301 CMAKE_CONFIGURATION_TYPES.
5302 CMAKE_CTEST_ARGUMENTS
5304 New in version 3.17.
5305 Set this to a semicolon-separated list of command-line arguments to
5308 pass to ctest(1) when running tests through the test (or RUN_TESTS)
5309 target of the generated build system.
5310 CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
5312 New in version 3.16.
5313 Default value for CUDA_RESOLVE_DEVICE_SYMBOLS target property when de‐
5316 fined. By default this variable is not defined.
5317 This variable is used to initialize the property on each target as it
5319 is created.
5320 CMAKE_CUDA_RUNTIME_LIBRARY
5322 New in version 3.17.
5323 Select the CUDA runtime library for use when compiling and linking
5326 CUDA. This variable is used to initialize the CUDA_RUNTIME_LIBRARY
5327 property on all targets as they are created.
5328 The allowed case insensitive values are:
5330 None Link with -cudart=none or equivalent flag(s) to use no CUDA run‐
5332 time library.
5333 Shared Link with -cudart=shared or equivalent flag(s) to use a dynami‐
5335 cally-linked CUDA runtime library.
5336 Static Link with -cudart=static or equivalent flag(s) to use a stati‐
5338 cally-linked CUDA runtime library.
5339 Contents of CMAKE_CUDA_RUNTIME_LIBRARY may use generator expressions.
5341 If this variable is not set then the CUDA_RUNTIME_LIBRARY target prop‐
5343 erty will not be set automatically. If that property is not set then
5344 CMake uses an appropriate default value based on the compiler to select
5345 the CUDA runtime library.
5346 NOTE:
5348 This property has effect only when the CUDA language is enabled. To
5349 control the CUDA runtime linking when only using the CUDA SDK with
5350 the C or C++ language we recommend using the FindCUDAToolkit module.
5351 CMAKE_CUDA_SEPARABLE_COMPILATION
5353 New in version 3.11.
5354 Default value for CUDA_SEPARABLE_COMPILATION target property. This
5357 variable is used to initialize the property on each target as it is
5358 created.
5359 CMAKE_CXX_SCAN_FOR_MODULES
5361 New in version 3.26.
5362 Whether to scan C++ source files for module dependencies.
5365 This variable is used to initialize the CXX_SCAN_FOR_MODULES property
5367 on all the targets. See that target property for additional informa‐
5368 tion.
5369 NOTE:
5371 This setting is meaningful only when experimental support for C++
5372 modules has been enabled by the CMAKE_EXPERIMENTAL_CXX_MOD‐
5373 ULE_CMAKE_API gate.
5374 CMAKE_DEBUG_POSTFIX
5376 See variable CMAKE_<CONFIG>_POSTFIX.
5377 This variable is a special case of the more-general
5379 CMAKE_<CONFIG>_POSTFIX variable for the DEBUG configuration.
5380 CMAKE_DEFAULT_BUILD_TYPE
5382 New in version 3.17.
5383 Specifies the configuration to use by default in a build.ninja file in
5386 the Ninja Multi-Config generator. If this variable is specified,
5387 build.ninja uses build rules from build-<Config>.ninja by default. All
5388 custom commands are executed with this configuration. If the variable
5389 is not specified, the first item from CMAKE_CONFIGURATION_TYPES is used
5390 instead.
5391 The value of this variable must be one of the items from
5393 CMAKE_CONFIGURATION_TYPES.
5394 CMAKE_DEFAULT_CONFIGS
5396 New in version 3.17.
5397 Specifies a semicolon-separated list of configurations to build for a
5400 target in build.ninja if no :<Config> suffix is specified in the Ninja
5401 Multi-Config generator. If it is set to all, all configurations from
5402 CMAKE_CROSS_CONFIGS are used. If it is not specified, it defaults to
5403 CMAKE_DEFAULT_BUILD_TYPE.
5404 For example, if you set CMAKE_DEFAULT_BUILD_TYPE to Release, but set
5406 CMAKE_DEFAULT_CONFIGS to Debug or all, all <target> aliases in
5407 build.ninja will resolve to <target>:Debug or <target>:all, but custom
5408 commands will still use the Release configuration.
5409 The value of this variable must be a subset of CMAKE_CROSS_CONFIGS or
5411 be the same as CMAKE_DEFAULT_BUILD_TYPE. It must not be specified if
5412 CMAKE_DEFAULT_BUILD_TYPE or CMAKE_CROSS_CONFIGS is not used.
5413 CMAKE_DEPENDS_USE_COMPILER
5415 New in version 3.20.
5416 For the Makefile Generators, source dependencies are now, for a selec‐
5419 tion of compilers, generated by the compiler itself. By defining this
5420 variable with value FALSE, you can restore the legacy behavior (i.e.
5421 using CMake for dependencies discovery).
5422 CMAKE_DISABLE_PRECOMPILE_HEADERS
5424 New in version 3.16.
5425 Default value for DISABLE_PRECOMPILE_HEADERS of targets.
5428 By default CMAKE_DISABLE_PRECOMPILE_HEADERS is OFF.
5430 CMAKE_DLL_NAME_WITH_SOVERSION
5432 New in version 3.27.
5433 This variable is used to initialize the DLL_NAME_WITH_SOVERSION prop‐
5436 erty on shared library targets for the Windows platform, which is se‐
5437 lected when the WIN32 variable is set.
5438 See this target property for additional information.
5440 Please note that setting this variable has no effect if versioned file‐
5442 names are globally disabled with the CMAKE_PLATFORM_NO_VERSIONED_SONAME
5443 variable.
5444 CMAKE_ENABLE_EXPORTS
5446 New in version 3.4.
5447 Specify whether executables export symbols for loadable modules.
5450 This variable is used to initialize the ENABLE_EXPORTS target property
5452 for executable targets when they are created by calls to the
5453 add_executable() command. See the property documentation for details.
5454 This variable has been superseded by the
5456 CMAKE_EXECUTABLE_ENABLE_EXPORTS variable. It is provided for backward
5457 compatibility with older CMake code, but should not be used in new
5458 projects.
5459 CMAKE_EXECUTABLE_ENABLE_EXPORTS
5461 New in version 3.27.
5462 Specify whether executables export symbols for loadable modules.
5465 This variable is used to initialize the ENABLE_EXPORTS target property
5467 for executable targets when they are created by calls to the
5468 add_executable() command. See the property documentation for details.
5469 This variable supersede the CMAKE_ENABLE_EXPORTS variable.
5471 CMAKE_EXE_LINKER_FLAGS
5473 Linker flags to be used to create executables.
5474 These flags will be used by the linker when creating an executable.
5476 CMAKE_EXE_LINKER_FLAGS_<CONFIG>
5478 Flags to be used when linking an executable.
5479 Same as CMAKE_C_FLAGS_* but used by the linker when creating executa‐
5481 bles.
5482 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT
5484 New in version 3.7.
5485 Value used to initialize the CMAKE_EXE_LINKER_FLAGS_<CONFIG> cache en‐
5488 try the first time a build tree is configured. This variable is meant
5489 to be set by a toolchain file. CMake may prepend or append content to
5490 the value based on the environment and target platform.
5491 See also CMAKE_EXE_LINKER_FLAGS_INIT.
5493 CMAKE_EXE_LINKER_FLAGS_INIT
5495 New in version 3.7.
5496 Value used to initialize the CMAKE_EXE_LINKER_FLAGS cache entry the
5499 first time a build tree is configured. This variable is meant to be
5500 set by a toolchain file. CMake may prepend or append content to the
5501 value based on the environment and target platform.
5502 See also the configuration-specific variable
5504 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT.
5505 CMAKE_FOLDER
5507 New in version 3.12.
5508 Set the folder name. Use to organize targets in an IDE.
5511 This variable is used to initialize the FOLDER property on all the tar‐
5513 gets. See that target property for additional information.
5514 CMAKE_Fortran_FORMAT
5516 Set to FIXED or FREE to indicate the Fortran source layout.
5517 This variable is used to initialize the Fortran_FORMAT property on all
5519 the targets. See that target property for additional information.
5520 CMAKE_Fortran_MODULE_DIRECTORY
5522 Fortran module output directory.
5523 This variable is used to initialize the Fortran_MODULE_DIRECTORY prop‐
5525 erty on all the targets. See that target property for additional in‐
5526 formation.
5527 CMAKE_Fortran_PREPROCESS
5529 New in version 3.18.
5530 Default value for Fortran_PREPROCESS of targets.
5533 This variable is used to initialize the Fortran_PREPROCESS property on
5535 all the targets. See that target property for additional information.
5536 CMAKE_FRAMEWORK
5538 New in version 3.15.
5539 Default value for FRAMEWORK of targets.
5542 This variable is used to initialize the FRAMEWORK property on all the
5544 targets. See that target property for additional information.
5545 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
5547 New in version 3.18.
5548 Default framework filename postfix under configuration <CONFIG> when
5551 using a multi-config generator.
5552 When a framework target is created its
5554 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property is initialized
5555 with the value of this variable if it is set.
5556 CMAKE_GHS_NO_SOURCE_GROUP_FILE
5558 New in version 3.14.
5559 ON / OFF boolean to control if the project file for a target should be
5562 one single file or multiple files. Refer to GHS_NO_SOURCE_GROUP_FILE
5563 for further details.
5564 CMAKE_GLOBAL_AUTOGEN_TARGET
5566 New in version 3.14.
5567 Switch to enable generation of a global autogen target.
5570 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a custom target autogen is
5572 generated. This target depends on all AUTOMOC and AUTOUIC generated
5573 <ORIGIN>_autogen targets in the project. By building the global auto‐
5574 gen target, all AUTOMOC and AUTOUIC files in the project will be gener‐
5575 ated.
5576 The name of the global autogen target can be changed by setting
5578 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.
5579 By default CMAKE_GLOBAL_AUTOGEN_TARGET is unset.
5581 See the cmake-qt(7) manual for more information on using CMake with Qt.
5583 Note
5585 <ORIGIN>_autogen targets by default inherit their origin target's de‐
5586 pendencies. This might result in unintended dependency target builds
5587 when only <ORIGIN>_autogen targets are built. A solution is to disable
5588 AUTOGEN_ORIGIN_DEPENDS on the respective origin targets.
5589 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME
5591 New in version 3.14.
5592 Change the name of the global autogen target.
5595 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a global custom target
5597 named autogen is created. CMAKE_GLOBAL_AUTOGEN_TARGET_NAME allows to
5598 set a different name for that target.
5599 By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.
5601 See the cmake-qt(7) manual for more information on using CMake with Qt.
5603 CMAKE_GLOBAL_AUTORCC_TARGET
5605 New in version 3.14.
5606 Switch to enable generation of a global autorcc target.
5609 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a custom target autorcc is
5611 generated. This target depends on all AUTORCC generated <ORI‐
5612 GIN>_arcc_<QRC> targets in the project. By building the global autorcc
5613 target, all AUTORCC files in the project will be generated.
5614 The name of the global autorcc target can be changed by setting
5616 CMAKE_GLOBAL_AUTORCC_TARGET_NAME.
5617 By default CMAKE_GLOBAL_AUTORCC_TARGET is unset.
5619 See the cmake-qt(7) manual for more information on using CMake with Qt.
5621 CMAKE_GLOBAL_AUTORCC_TARGET_NAME
5623 New in version 3.14.
5624 Change the name of the global autorcc target.
5627 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a global custom target
5629 named autorcc is created. CMAKE_GLOBAL_AUTORCC_TARGET_NAME allows to
5630 set a different name for that target.
5631 By default CMAKE_GLOBAL_AUTORCC_TARGET_NAME is unset.
5633 See the cmake-qt(7) manual for more information on using CMake with Qt.
5635 CMAKE_GNUtoMS
5637 Convert GNU import libraries (.dll.a) to MS format (.lib).
5638 This variable is used to initialize the GNUtoMS property on targets
5640 when they are created. See that target property for additional infor‐
5641 mation.
5642 CMAKE_INCLUDE_CURRENT_DIR
5644 Automatically add the current source and build directories to the in‐
5645 clude path.
5646 If this variable is enabled, CMake automatically adds
5648 CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include
5649 path for each directory. These additional include directories do not
5650 propagate down to subdirectories. This is useful mainly for
5651 out-of-source builds, where files generated into the build tree are in‐
5652 cluded by files located in the source tree.
5653 By default CMAKE_INCLUDE_CURRENT_DIR is OFF.
5655 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
5657 Automatically add the current source and build directories to the
5658 INTERFACE_INCLUDE_DIRECTORIES target property.
5659 If this variable is enabled, CMake automatically adds for each shared
5661 library target, static library target, module target and executable
5662 target, CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the
5663 INTERFACE_INCLUDE_DIRECTORIES target property. By default CMAKE_IN‐
5664 CLUDE_CURRENT_DIR_IN_INTERFACE is OFF.
5665 CMAKE_INSTALL_NAME_DIR
5667 Directory name for installed targets on Apple platforms.
5668 CMAKE_INSTALL_NAME_DIR is used to initialize the INSTALL_NAME_DIR prop‐
5670 erty on all targets. See that target property for more information.
5671 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH
5673 New in version 3.16.
5674 Sets the default for whether toolchain-defined rpaths should be removed
5677 during installation.
5678 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH is a boolean that provides the
5680 default value for the INSTALL_REMOVE_ENVIRONMENT_RPATH property of all
5681 subsequently created targets.
5682 CMAKE_INSTALL_RPATH
5684 The rpath to use for installed targets.
5685 A semicolon-separated list specifying the rpath to use in installed
5687 targets (for platforms that support it). This is used to initialize
5688 the target property INSTALL_RPATH for all targets.
5689 CMAKE_INSTALL_RPATH_USE_LINK_PATH
5691 Add paths to linker search and installed rpath.
5692 CMAKE_INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to True will
5694 append to the runtime search path (rpath) of installed binaries any di‐
5695 rectories outside the project that are in the linker search path or
5696 contain linked library files. The directories are appended after the
5697 value of the INSTALL_RPATH target property.
5698 This variable is used to initialize the target property
5700 INSTALL_RPATH_USE_LINK_PATH for all targets.
5701 CMAKE_INTERPROCEDURAL_OPTIMIZATION
5703 New in version 3.9.
5704 Default value for INTERPROCEDURAL_OPTIMIZATION of targets.
5707 This variable is used to initialize the INTERPROCEDURAL_OPTIMIZATION
5709 property on all the targets. See that target property for additional
5710 information.
5711 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5713 New in version 3.9.
5714 Default value for INTERPROCEDURAL_OPTIMIZATION_<CONFIG> of targets.
5717 This variable is used to initialize the
5719 INTERPROCEDURAL_OPTIMIZATION_<CONFIG> property on all the targets. See
5720 that target property for additional information.
5721 CMAKE_IOS_INSTALL_COMBINED
5723 New in version 3.5.
5724 Default value for IOS_INSTALL_COMBINED of targets.
5727 This variable is used to initialize the IOS_INSTALL_COMBINED property
5729 on all the targets. See that target property for additional informa‐
5730 tion.
5731 CMAKE_<LANG>_CLANG_TIDY
5733 New in version 3.6.
5734 Default value for <LANG>_CLANG_TIDY target property when <LANG> is C,
5737 CXX, OBJC or OBJCXX.
5738 This variable is used to initialize the property on each target as it
5740 is created. For example:
5741 set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*)
5743 add_executable(foo foo.cxx)
5744 CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR
5746 New in version 3.26.
5747 Default value for <LANG>_CLANG_TIDY_EXPORT_FIXES_DIR target property
5750 when <LANG> is C, CXX, OBJC or OBJCXX.
5751 This variable is used to initialize the property on each target as it
5753 is created. For example:
5754 set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR clang-tidy-fixes)
5756 add_executable(foo foo.cxx)
5757 CMAKE_<LANG>_COMPILER_LAUNCHER
5759 New in version 3.4.
5760 Default value for <LANG>_COMPILER_LAUNCHER target property. This vari‐
5763 able is used to initialize the property on each target as it is cre‐
5764 ated. This is done only when <LANG> is C, CXX, Fortran, HIP, ISPC,
5765 OBJC, OBJCXX, or CUDA.
5766 This variable is initialized to the CMAKE_<LANG>_COMPILER_LAUNCHER en‐
5768 vironment variable if it is set.
5769 CMAKE_<LANG>_CPPCHECK
5771 New in version 3.10.
5772 Default value for <LANG>_CPPCHECK target property. This variable is
5775 used to initialize the property on each target as it is created. This
5776 is done only when <LANG> is C or CXX.
5777 CMAKE_<LANG>_CPPLINT
5779 New in version 3.8.
5780 Default value for <LANG>_CPPLINT target property. This variable is used
5783 to initialize the property on each target as it is created. This is
5784 done only when <LANG> is C or CXX.
5785 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE
5787 New in version 3.3.
5788 Default value for <LANG>_INCLUDE_WHAT_YOU_USE target property. This
5791 variable is used to initialize the property on each target as it is
5792 created. This is done only when <LANG> is C or CXX.
5793 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
5795 New in version 3.24.
5796 This variable defines how to link a group of libraries for the speci‐
5799 fied <FEATURE> when a LINK_GROUP generator expression is used and the
5800 link language for the target is <LANG>. For this variable to have any
5801 effect, the associated
5802 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be set
5803 to true.
5804 The CMAKE_LINK_GROUP_USING_<FEATURE> variable should be defined instead
5806 for features that are independent of the link language.
5807 Feature names are case-sensitive and may only contain letters, numbers
5809 and underscores. Feature names defined in all uppercase are reserved
5810 for CMake's own built-in features (see Predefined Features further be‐
5811 low).
5812 Feature Definitions
5814 A group feature definition is a list that contains exactly two ele‐
5815 ments:
5816 <PREFIX> <SUFFIX>
5818 On the linker command line, <PREFIX> will precede the list of libraries
5820 in the group and <SUFFIX> will follow after.
5821 For the elements of this variable, the LINKER: prefix can be used.
5823 To pass options to the linker tool, each compiler driver has its own
5825 syntax. The LINKER: prefix and , separator can be used to specify, in
5826 a portable way, options to pass to the linker tool. LINKER: is replaced
5827 by the appropriate driver option and , by the appropriate driver sepa‐
5828 rator. The driver prefix and driver separator are given by the values
5829 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
5830 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
5831 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5833 Clang and -Wl,-z,defs for GNU GCC.
5834 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5836 sion.
5837 The LINKER: prefix supports, as an alternative syntax, specification of
5839 arguments using the SHELL: prefix and space as separator. The previous
5840 example then becomes "LINKER:SHELL:-z defs".
5841 NOTE:
5843 Specifying the SHELL: prefix anywhere other than at the beginning of
5844 the LINKER: prefix is not supported.
5845 Examples
5847 Solving cross-references between two static libraries
5848 A project may define two or more static libraries which have circular
5849 dependencies between them. In order for the linker to resolve all sym‐
5850 bols at link time, it may need to search repeatedly among the libraries
5851 until no new undefined references are created. Different linkers use
5852 different syntax for achieving this. The following example shows how
5853 this may be implemented for some linkers. Note that this is for illus‐
5854 tration purposes only. Projects should use the built-in RESCAN group
5855 feature instead (see Predefined Features), which provides a more com‐
5856 plete and more robust implementation of this functionality.
5857 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
5859 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
5860 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5861 "LINKER:--start-group"
5862 "LINKER:--end-group"
5863 )
5864 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
5865 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5866 "LINKER:-z,rescan-start"
5867 "LINKER:-z,rescan-end"
5868 )
5869 else()
5870 # feature not yet supported for the other environments
5871 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
5872 endif()
5873 add_library(lib1 STATIC ...)
5875 add_library(lib2 SHARED ...)
5876 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
5878 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
5879 else()
5880 target_link_libraries(lib2 PRIVATE lib1 external)
5881 endif()
5882 CMake will generate the following linker command line fragments when
5884 linking lib2:
5885 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
5887 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
5889 can-end
5890 Predefined Features
5892 The following built-in group features are pre-defined by CMake:
5893 RESCAN Some linkers are single-pass only. For such linkers, circular
5895 references between libraries typically result in unresolved sym‐
5896 bols. This feature instructs the linker to search the specified
5897 static libraries repeatedly until no new undefined references
5898 are created.
5899 Normally, a static library is searched only once in the order
5901 that it is specified on the command line. If a symbol in that
5902 library is needed to resolve an undefined symbol referred to by
5903 an object in a library that appears later on the command line,
5904 the linker would not be able to resolve that reference. By
5905 grouping the static libraries with the RESCAN feature, they will
5906 all be searched repeatedly until all possible references are re‐
5907 solved. This will use linker options like --start-group and
5908 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
5909 Using this feature has a significant performance cost. It is
5911 best to use it only when there are unavoidable circular refer‐
5912 ences between two or more static libraries.
5913 This feature is available when using toolchains that target
5915 Linux, BSD, and SunOS. It can also be used when targeting Win‐
5916 dows platforms if the GNU toolchain is used.
5917 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
5919 New in version 3.24.
5920 This variable specifies whether the <FEATURE> is supported for the link
5923 language <LANG>. If this variable is true, then the <FEATURE> must be
5924 defined by CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>, and the more
5925 generic CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED and
5926 CMAKE_LINK_GROUP_USING_<FEATURE> variables are not used.
5927 If CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is false or is not
5929 set, then the CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable will
5930 determine whether <FEATURE> is deemed to be supported.
5931 CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG
5933 New in version 3.16.
5934 Language-specific flag to be used to link a library specified by a path
5937 to its file.
5938 The flag will be used before a library file path is given to the
5940 linker. This is needed only on very few platforms.
5941 CMAKE_<LANG>_LINK_LIBRARY_FLAG
5943 New in version 3.16.
5944 Flag to be used to link a library into a shared library or executable.
5947 This flag will be used to specify a library to link to a shared library
5949 or an executable for the specific language. On most compilers this is
5950 -l.
5951 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>
5953 New in version 3.24.
5954 This variable defines how to link a library or framework for the speci‐
5957 fied <FEATURE> when a LINK_LIBRARY generator expression is used and the
5958 link language for the target is <LANG>. For this variable to have any
5959 effect, the associated
5960 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
5961 set to true.
5962 The CMAKE_LINK_LIBRARY_USING_<FEATURE> variable should be defined in‐
5964 stead for features that are independent of the link language.
5965 Feature names are case-sensitive and may only contain letters, numbers
5967 and underscores. Feature names defined in all uppercase are reserved
5968 for CMake's own built-in features (see Predefined Features further be‐
5969 low).
5970 Feature Definitions
5972 A library feature definition is a list that contains one or three ele‐
5973 ments:
5974 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
5976 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
5978 spectively the whole list of libraries specified in the LINK_LIBRARY
5979 expression, not each library item individually. There is no guarantee
5980 that the list of specified libraries will be kept grouped together
5981 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
5982 library list is reorganized by CMake to satisfy other constraints.
5983 This means constructs like --start-group and --end-group, as supported
5984 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
5985 erator expression should be used instead for such constructs.
5986 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
5988 the corresponding fragment on the linker command line for each library.
5989 The following placeholders can be used in the expression:
5990 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
5992 gets, or to a platform-specific value based on the item otherwise
5993 (the same as <LINK_ITEM> on Windows, or the library base name for
5994 other platforms).
5995 • <LINK_ITEM> is expanded to how the library would normally be linked
5997 on the linker command line.
5998 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
6000 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
6001 SION> otherwise.
6002 In addition to the above, it is possible to have one pattern for paths
6004 (CMake targets and external libraries specified with file paths) and
6005 another for other items specified by name only. The PATH{} and NAME{}
6006 wrappers can be used to provide the expansion for those two cases, re‐
6007 spectively. When wrappers are used, both must be present. For exam‐
6008 ple:
6009 set(CMAKE_LINK_LIBRARY_USING_weak_library
6011 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6012 )
6013 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
6015 SION>, and <SUFFIX>), the LINKER: prefix can be used.
6016 To pass options to the linker tool, each compiler driver has its own
6018 syntax. The LINKER: prefix and , separator can be used to specify, in
6019 a portable way, options to pass to the linker tool. LINKER: is replaced
6020 by the appropriate driver option and , by the appropriate driver sepa‐
6021 rator. The driver prefix and driver separator are given by the values
6022 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6023 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6024 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6026 Clang and -Wl,-z,defs for GNU GCC.
6027 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6029 sion.
6030 The LINKER: prefix supports, as an alternative syntax, specification of
6032 arguments using the SHELL: prefix and space as separator. The previous
6033 example then becomes "LINKER:SHELL:-z defs".
6034 NOTE:
6036 Specifying the SHELL: prefix anywhere other than at the beginning of
6037 the LINKER: prefix is not supported.
6038 Examples
6040 Loading a whole static library
6041 A common need is to prevent the linker from discarding any symbols from
6042 a static library. Different linkers use different syntax for achieving
6043 this. The following example shows how this may be implemented for some
6044 linkers. Note that this is for illustration purposes only. Projects
6045 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
6046 Features), which provides a more complete and more robust implementa‐
6047 tion of this functionality.
6048 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
6050 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6051 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
6052 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6053 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
6054 "LINKER:--push-state,--whole-archive"
6055 "<LINK_ITEM>"
6056 "LINKER:--pop-state"
6057 )
6058 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
6059 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
6060 else()
6061 # feature not yet supported for the other environments
6062 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
6063 endif()
6064 add_library(lib1 STATIC ...)
6066 add_library(lib2 SHARED ...)
6067 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
6069 # The -force_load Apple linker option requires a file name
6070 set(external_lib
6071 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
6072 )
6073 target_link_libraries(lib2 PRIVATE
6074 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
6075 )
6076 else()
6077 target_link_libraries(lib2 PRIVATE lib1 external)
6078 endif()
6079 CMake will generate the following link expressions:
6081 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
6083 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
6085 -Wl,--pop-state
6086 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
6088 Linking a library as weak
6090 On macOS, it is possible to link a library in weak mode (the library
6091 and all references are marked as weak imports). Different flags must
6092 be used for a library specified by file path compared to one specified
6093 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
6094 pers. Again, the following example shows how this may be implemented
6095 for some linkers, but it is for illustration purposes only. Projects
6096 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
6097 (see Predefined Features), which provide more complete and more robust
6098 implementations of this functionality.
6099 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6101 set(CMAKE_LINK_LIBRARY_USING_weak_library
6102 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6103 )
6104 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
6105 endif()
6106 add_library(lib SHARED ...)
6108 add_executable(main ...)
6109 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
6110 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
6111 else()
6112 target_link_libraries(main PRIVATE lib external)
6113 endif()
6114 CMake will generate the following linker command line fragment when
6116 linking main using the AppleClang toolchain:
6117 -weak_library /path/to/lib -Xlinker -weak-lexternal.
6119 Predefined Features
6121 The following built-in library features are pre-defined by CMake:
6122 DEFAULT
6124 This feature corresponds to standard linking, essentially equiv‐
6125 alent to using no feature at all. It is typically only used
6126 with the LINK_LIBRARY_OVERRIDE and
6127 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
6128 WHOLE_ARCHIVE
6130 Force inclusion of all members of a static library. This fea‐
6131 ture is only supported for the following platforms, with limita‐
6132 tions as noted:
6133 • Linux.
6135 • All BSD variants.
6137 • SunOS.
6139 • All Apple variants. The library must be specified as a CMake
6141 target name, a library file name (such as libfoo.a), or a li‐
6142 brary file path (such as /path/to/libfoo.a). Due to a limita‐
6143 tion of the Apple linker, it cannot be specified as a plain
6144 library name like foo, where foo is not a CMake target.
6145 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
6147 version must be greater than 1900.
6148 • Cygwin.
6150 • MSYS.
6152 FRAMEWORK
6154 This option tells the linker to search for the specified frame‐
6155 work using the -framework linker option. It can only be used on
6156 Apple platforms, and only with a linker that understands the op‐
6157 tion used (i.e. the linker provided with Xcode, or one compati‐
6158 ble with it).
6159 The framework can be specified as a CMake framework target, a
6161 bare framework name, or a file path. If a target is given, that
6162 target must have the FRAMEWORK target property set to true. For
6163 a file path, if it contains a directory part, that directory
6164 will be added as a framework search path.
6165 add_library(lib SHARED ...)
6167 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
6168 # The constructed linker command line will contain:
6170 # -F/path/to -framework my_framework
6171 File paths must conform to one of the following patterns (* is a
6173 wildcard, and optional parts are shown as [...]):
6174 • [/path/to/]FwName[.framework]
6176 • [/path/to/]FwName.framework/FwName[suffix]
6178 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
6180 Note that CMake recognizes and automatically handles framework
6182 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
6183 expression. The generator expression can still be used with a
6184 CMake target if the project wants to be explicit about it, but
6185 it is not required to do so. The linker command line may have
6186 some differences between using the generator expression or not,
6187 but the final result should be the same. On the other hand, if
6188 a file path is given, CMake will recognize some paths automati‐
6189 cally, but not all cases. The project may want to use
6190 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
6191 pected behavior is clear.
6192 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
6194 target property as well as the suffix of the framework library
6195 name are now supported by the FRAMEWORK features.
6196 NEEDED_FRAMEWORK
6199 This is similar to the FRAMEWORK feature, except it forces the
6200 linker to link with the framework even if no symbols are used
6201 from it. It uses the -needed_framework option and has the same
6202 linker constraints as FRAMEWORK.
6203 REEXPORT_FRAMEWORK
6205 This is similar to the FRAMEWORK feature, except it tells the
6206 linker that the framework should be available to clients linking
6207 to the library being created. It uses the -reexport_framework
6208 option and has the same linker constraints as FRAMEWORK.
6209 WEAK_FRAMEWORK
6211 This is similar to the FRAMEWORK feature, except it forces the
6212 linker to mark the framework and all references to it as weak
6213 imports. It uses the -weak_framework option and has the same
6214 linker constraints as FRAMEWORK.
6215 NEEDED_LIBRARY
6217 This is similar to the NEEDED_FRAMEWORK feature, except it is
6218 for use with non-framework targets or libraries (Apple platforms
6219 only). It uses the -needed_library or -needed-l option as ap‐
6220 propriate, and has the same linker constraints as NEEDED_FRAME‐
6221 WORK.
6222 REEXPORT_LIBRARY
6224 This is similar to the REEXPORT_FRAMEWORK feature, except it is
6225 for use with non-framework targets or libraries (Apple platforms
6226 only). It uses the -reexport_library or -reexport-l option as
6227 appropriate, and has the same linker constraints as REEX‐
6228 PORT_FRAMEWORK.
6229 WEAK_LIBRARY
6231 This is similar to the WEAK_FRAMEWORK feature, except it is for
6232 use with non-framework targets or libraries (Apple platforms
6233 only). It uses the -weak_library or -weak-l option as appropri‐
6234 ate, and has the same linker constraints as WEAK_FRAMEWORK.
6235 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
6237 New in version 3.24.
6238 Set to TRUE if the <FEATURE>, as defined by variable
6241 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>, is supported for the linker
6242 language <LANG>.
6243 NOTE:
6245 This variable is evaluated before the more generic variable
6246 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED.
6247 CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG
6249 New in version 3.22.
6250 Linker flag to be used to configure linker so that all specified li‐
6253 braries on the command line will be linked into the target.
6254 See also variable CMAKE_LINK_WHAT_YOU_USE_CHECK.
6256 CMAKE_<LANG>_LINKER_LAUNCHER
6258 New in version 3.21.
6259 Default value for <LANG>_LINKER_LAUNCHER target property. This variable
6262 is used to initialize the property on each target as it is created.
6263 This is done only when <LANG> is C, CXX, OBJC, or OBJCXX.
6264 This variable is initialized to the CMAKE_<LANG>_LINKER_LAUNCHER envi‐
6266 ronment variable if it is set.
6267 CMAKE_<LANG>_VISIBILITY_PRESET
6269 Default value for the <LANG>_VISIBILITY_PRESET target property when a
6270 target is created.
6271 CMAKE_LIBRARY_OUTPUT_DIRECTORY
6273 Where to put all the LIBRARY target files when built.
6274 This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY prop‐
6276 erty on all the targets. See that target property for additional in‐
6277 formation.
6278 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
6280 New in version 3.3.
6281 Where to put all the LIBRARY target files when built for a specific
6284 configuration.
6285 This variable is used to initialize the
6287 LIBRARY_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
6288 that target property for additional information.
6289 CMAKE_LIBRARY_PATH_FLAG
6291 The flag to be used to add a library search path to a compiler.
6292 The flag will be used to specify a library directory to the compiler.
6294 On most compilers this is -L.
6295 CMAKE_LINK_DEF_FILE_FLAG
6297 Linker flag to be used to specify a .def file for dll creation.
6298 The flag will be used to add a .def file when creating a dll on Win‐
6300 dows; this is only defined on Windows.
6301 CMAKE_LINK_DEPENDS_NO_SHARED
6303 Whether to skip link dependencies on shared library files.
6304 This variable initializes the LINK_DEPENDS_NO_SHARED property on tar‐
6306 gets when they are created. See that target property for additional
6307 information.
6308 CMAKE_LINK_DEPENDS_USE_LINKER
6310 New in version 3.27.
6311 For the Makefile and Ninja generators, link dependencies are now, for a
6314 selection of linkers, generated by the linker itself. By defining this
6315 variable with value FALSE, you can deactivate this feature.
6316 This feature is also deactivated if the LINK_DEPENDS_NO_SHARED target
6318 property is true.
6319 NOTE:
6321 CMake version 3.27.7 defaults this variable to FALSE because GNU
6322 binutils linkers (ld, ld.bfd, ld.gold) generate spurious dependen‐
6323 cies on temporary files when LTO is enabled. See GNU bug 30568.
6324 CMAKE_LINK_GROUP_USING_<FEATURE>
6326 New in version 3.24.
6327 This variable defines how to link a group of libraries for the speci‐
6330 fied <FEATURE> when a LINK_GROUP generator expression is used. Both of
6331 the following conditions must be met for this variable to have any ef‐
6332 fect:
6333 • The associated CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable
6335 must be set to true.
6336 • There is no language-specific definition for the same <FEATURE>.
6338 This means CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED cannot
6339 be true for the link language used by the target for which the
6340 LINK_GROUP generator expression is evaluated.
6341 The CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable should be defined
6343 instead for features that are dependent on the link language.
6344 Feature names are case-sensitive and may only contain letters, numbers
6346 and underscores. Feature names defined in all uppercase are reserved
6347 for CMake's own built-in features (see Predefined Features further be‐
6348 low).
6349 Feature Definitions
6351 A group feature definition is a list that contains exactly two ele‐
6352 ments:
6353 <PREFIX> <SUFFIX>
6355 On the linker command line, <PREFIX> will precede the list of libraries
6357 in the group and <SUFFIX> will follow after.
6358 For the elements of this variable, the LINKER: prefix can be used.
6360 To pass options to the linker tool, each compiler driver has its own
6362 syntax. The LINKER: prefix and , separator can be used to specify, in
6363 a portable way, options to pass to the linker tool. LINKER: is replaced
6364 by the appropriate driver option and , by the appropriate driver sepa‐
6365 rator. The driver prefix and driver separator are given by the values
6366 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6367 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6368 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6370 Clang and -Wl,-z,defs for GNU GCC.
6371 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6373 sion.
6374 The LINKER: prefix supports, as an alternative syntax, specification of
6376 arguments using the SHELL: prefix and space as separator. The previous
6377 example then becomes "LINKER:SHELL:-z defs".
6378 NOTE:
6380 Specifying the SHELL: prefix anywhere other than at the beginning of
6381 the LINKER: prefix is not supported.
6382 Examples
6384 Solving cross-references between two static libraries
6385 A project may define two or more static libraries which have circular
6386 dependencies between them. In order for the linker to resolve all sym‐
6387 bols at link time, it may need to search repeatedly among the libraries
6388 until no new undefined references are created. Different linkers use
6389 different syntax for achieving this. The following example shows how
6390 this may be implemented for some linkers. Note that this is for illus‐
6391 tration purposes only. Projects should use the built-in RESCAN group
6392 feature instead (see Predefined Features), which provides a more com‐
6393 plete and more robust implementation of this functionality.
6394 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
6396 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6397 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6398 "LINKER:--start-group"
6399 "LINKER:--end-group"
6400 )
6401 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
6402 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6403 "LINKER:-z,rescan-start"
6404 "LINKER:-z,rescan-end"
6405 )
6406 else()
6407 # feature not yet supported for the other environments
6408 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
6409 endif()
6410 add_library(lib1 STATIC ...)
6412 add_library(lib2 SHARED ...)
6413 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
6415 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
6416 else()
6417 target_link_libraries(lib2 PRIVATE lib1 external)
6418 endif()
6419 CMake will generate the following linker command line fragments when
6421 linking lib2:
6422 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
6424 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
6426 can-end
6427 Predefined Features
6429 The following built-in group features are pre-defined by CMake:
6430 RESCAN Some linkers are single-pass only. For such linkers, circular
6432 references between libraries typically result in unresolved sym‐
6433 bols. This feature instructs the linker to search the specified
6434 static libraries repeatedly until no new undefined references
6435 are created.
6436 Normally, a static library is searched only once in the order
6438 that it is specified on the command line. If a symbol in that
6439 library is needed to resolve an undefined symbol referred to by
6440 an object in a library that appears later on the command line,
6441 the linker would not be able to resolve that reference. By
6442 grouping the static libraries with the RESCAN feature, they will
6443 all be searched repeatedly until all possible references are re‐
6444 solved. This will use linker options like --start-group and
6445 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
6446 Using this feature has a significant performance cost. It is
6448 best to use it only when there are unavoidable circular refer‐
6449 ences between two or more static libraries.
6450 This feature is available when using toolchains that target
6452 Linux, BSD, and SunOS. It can also be used when targeting Win‐
6453 dows platforms if the GNU toolchain is used.
6454 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
6456 New in version 3.24.
6457 This variable specifies whether the <FEATURE> is supported regardless
6460 of the link language. If this variable is true, then the <FEATURE>
6461 must be defined by CMAKE_LINK_GROUP_USING_<FEATURE>.
6462 Note that this variable has no effect if
6464 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is true for the link
6465 language of the target.
6466 CMAKE_LINK_INTERFACE_LIBRARIES
6468 Default value for LINK_INTERFACE_LIBRARIES of targets.
6469 This variable is used to initialize the LINK_INTERFACE_LIBRARIES prop‐
6471 erty on all the targets. See that target property for additional in‐
6472 formation.
6473 CMAKE_LINK_LIBRARY_FILE_FLAG
6475 Flag to be used to link a library specified by a path to its file.
6476 The flag will be used before a library file path is given to the
6478 linker. This is needed only on very few platforms.
6479 CMAKE_LINK_LIBRARY_FLAG
6481 Flag to be used to link a library into an executable.
6482 The flag will be used to specify a library to link to an executable.
6484 On most compilers this is -l.
6485 CMAKE_LINK_LIBRARY_USING_<FEATURE>
6487 New in version 3.24.
6488 This variable defines how to link a library or framework for the speci‐
6491 fied <FEATURE> when a LINK_LIBRARY generator expression is used. Both
6492 of the following conditions must be met for this variable to have any
6493 effect:
6494 • The associated CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
6496 must be set to true.
6497 • There is no language-specific definition for the same <FEATURE>.
6499 This means CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED cannot
6500 be true for the link language used by the target for which the
6501 LINK_LIBRARY generator expression is evaluated.
6502 Feature names are case-sensitive and may only contain letters, numbers
6504 and underscores. Feature names defined in all uppercase are reserved
6505 for CMake's own built-in features (see Predefined Features further be‐
6506 low).
6507 Feature Definitions
6509 A library feature definition is a list that contains one or three ele‐
6510 ments:
6511 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
6513 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
6515 spectively the whole list of libraries specified in the LINK_LIBRARY
6516 expression, not each library item individually. There is no guarantee
6517 that the list of specified libraries will be kept grouped together
6518 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
6519 library list is reorganized by CMake to satisfy other constraints.
6520 This means constructs like --start-group and --end-group, as supported
6521 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
6522 erator expression should be used instead for such constructs.
6523 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
6525 the corresponding fragment on the linker command line for each library.
6526 The following placeholders can be used in the expression:
6527 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
6529 gets, or to a platform-specific value based on the item otherwise
6530 (the same as <LINK_ITEM> on Windows, or the library base name for
6531 other platforms).
6532 • <LINK_ITEM> is expanded to how the library would normally be linked
6534 on the linker command line.
6535 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
6537 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
6538 SION> otherwise.
6539 In addition to the above, it is possible to have one pattern for paths
6541 (CMake targets and external libraries specified with file paths) and
6542 another for other items specified by name only. The PATH{} and NAME{}
6543 wrappers can be used to provide the expansion for those two cases, re‐
6544 spectively. When wrappers are used, both must be present. For exam‐
6545 ple:
6546 set(CMAKE_LINK_LIBRARY_USING_weak_library
6548 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6549 )
6550 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
6552 SION>, and <SUFFIX>), the LINKER: prefix can be used.
6553 To pass options to the linker tool, each compiler driver has its own
6555 syntax. The LINKER: prefix and , separator can be used to specify, in
6556 a portable way, options to pass to the linker tool. LINKER: is replaced
6557 by the appropriate driver option and , by the appropriate driver sepa‐
6558 rator. The driver prefix and driver separator are given by the values
6559 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6560 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6561 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6563 Clang and -Wl,-z,defs for GNU GCC.
6564 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6566 sion.
6567 The LINKER: prefix supports, as an alternative syntax, specification of
6569 arguments using the SHELL: prefix and space as separator. The previous
6570 example then becomes "LINKER:SHELL:-z defs".
6571 NOTE:
6573 Specifying the SHELL: prefix anywhere other than at the beginning of
6574 the LINKER: prefix is not supported.
6575 Examples
6577 Loading a whole static library
6578 A common need is to prevent the linker from discarding any symbols from
6579 a static library. Different linkers use different syntax for achieving
6580 this. The following example shows how this may be implemented for some
6581 linkers. Note that this is for illustration purposes only. Projects
6582 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
6583 Features), which provides a more complete and more robust implementa‐
6584 tion of this functionality.
6585 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
6587 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6588 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
6589 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6590 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
6591 "LINKER:--push-state,--whole-archive"
6592 "<LINK_ITEM>"
6593 "LINKER:--pop-state"
6594 )
6595 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
6596 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
6597 else()
6598 # feature not yet supported for the other environments
6599 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
6600 endif()
6601 add_library(lib1 STATIC ...)
6603 add_library(lib2 SHARED ...)
6604 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
6606 # The -force_load Apple linker option requires a file name
6607 set(external_lib
6608 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
6609 )
6610 target_link_libraries(lib2 PRIVATE
6611 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
6612 )
6613 else()
6614 target_link_libraries(lib2 PRIVATE lib1 external)
6615 endif()
6616 CMake will generate the following link expressions:
6618 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
6620 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
6622 -Wl,--pop-state
6623 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
6625 Linking a library as weak
6627 On macOS, it is possible to link a library in weak mode (the library
6628 and all references are marked as weak imports). Different flags must
6629 be used for a library specified by file path compared to one specified
6630 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
6631 pers. Again, the following example shows how this may be implemented
6632 for some linkers, but it is for illustration purposes only. Projects
6633 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
6634 (see Predefined Features), which provide more complete and more robust
6635 implementations of this functionality.
6636 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6638 set(CMAKE_LINK_LIBRARY_USING_weak_library
6639 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6640 )
6641 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
6642 endif()
6643 add_library(lib SHARED ...)
6645 add_executable(main ...)
6646 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
6647 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
6648 else()
6649 target_link_libraries(main PRIVATE lib external)
6650 endif()
6651 CMake will generate the following linker command line fragment when
6653 linking main using the AppleClang toolchain:
6654 -weak_library /path/to/lib -Xlinker -weak-lexternal.
6656 Predefined Features
6658 The following built-in library features are pre-defined by CMake:
6659 DEFAULT
6661 This feature corresponds to standard linking, essentially equiv‐
6662 alent to using no feature at all. It is typically only used
6663 with the LINK_LIBRARY_OVERRIDE and
6664 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
6665 WHOLE_ARCHIVE
6667 Force inclusion of all members of a static library. This fea‐
6668 ture is only supported for the following platforms, with limita‐
6669 tions as noted:
6670 • Linux.
6672 • All BSD variants.
6674 • SunOS.
6676 • All Apple variants. The library must be specified as a CMake
6678 target name, a library file name (such as libfoo.a), or a li‐
6679 brary file path (such as /path/to/libfoo.a). Due to a limita‐
6680 tion of the Apple linker, it cannot be specified as a plain
6681 library name like foo, where foo is not a CMake target.
6682 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
6684 version must be greater than 1900.
6685 • Cygwin.
6687 • MSYS.
6689 FRAMEWORK
6691 This option tells the linker to search for the specified frame‐
6692 work using the -framework linker option. It can only be used on
6693 Apple platforms, and only with a linker that understands the op‐
6694 tion used (i.e. the linker provided with Xcode, or one compati‐
6695 ble with it).
6696 The framework can be specified as a CMake framework target, a
6698 bare framework name, or a file path. If a target is given, that
6699 target must have the FRAMEWORK target property set to true. For
6700 a file path, if it contains a directory part, that directory
6701 will be added as a framework search path.
6702 add_library(lib SHARED ...)
6704 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
6705 # The constructed linker command line will contain:
6707 # -F/path/to -framework my_framework
6708 File paths must conform to one of the following patterns (* is a
6710 wildcard, and optional parts are shown as [...]):
6711 • [/path/to/]FwName[.framework]
6713 • [/path/to/]FwName.framework/FwName[suffix]
6715 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
6717 Note that CMake recognizes and automatically handles framework
6719 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
6720 expression. The generator expression can still be used with a
6721 CMake target if the project wants to be explicit about it, but
6722 it is not required to do so. The linker command line may have
6723 some differences between using the generator expression or not,
6724 but the final result should be the same. On the other hand, if
6725 a file path is given, CMake will recognize some paths automati‐
6726 cally, but not all cases. The project may want to use
6727 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
6728 pected behavior is clear.
6729 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
6731 target property as well as the suffix of the framework library
6732 name are now supported by the FRAMEWORK features.
6733 NEEDED_FRAMEWORK
6736 This is similar to the FRAMEWORK feature, except it forces the
6737 linker to link with the framework even if no symbols are used
6738 from it. It uses the -needed_framework option and has the same
6739 linker constraints as FRAMEWORK.
6740 REEXPORT_FRAMEWORK
6742 This is similar to the FRAMEWORK feature, except it tells the
6743 linker that the framework should be available to clients linking
6744 to the library being created. It uses the -reexport_framework
6745 option and has the same linker constraints as FRAMEWORK.
6746 WEAK_FRAMEWORK
6748 This is similar to the FRAMEWORK feature, except it forces the
6749 linker to mark the framework and all references to it as weak
6750 imports. It uses the -weak_framework option and has the same
6751 linker constraints as FRAMEWORK.
6752 NEEDED_LIBRARY
6754 This is similar to the NEEDED_FRAMEWORK feature, except it is
6755 for use with non-framework targets or libraries (Apple platforms
6756 only). It uses the -needed_library or -needed-l option as ap‐
6757 propriate, and has the same linker constraints as NEEDED_FRAME‐
6758 WORK.
6759 REEXPORT_LIBRARY
6761 This is similar to the REEXPORT_FRAMEWORK feature, except it is
6762 for use with non-framework targets or libraries (Apple platforms
6763 only). It uses the -reexport_library or -reexport-l option as
6764 appropriate, and has the same linker constraints as REEX‐
6765 PORT_FRAMEWORK.
6766 WEAK_LIBRARY
6768 This is similar to the WEAK_FRAMEWORK feature, except it is for
6769 use with non-framework targets or libraries (Apple platforms
6770 only). It uses the -weak_library or -weak-l option as appropri‐
6771 ate, and has the same linker constraints as WEAK_FRAMEWORK.
6772 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
6774 New in version 3.24.
6775 Set to TRUE if the <FEATURE>, as defined by variable
6778 CMAKE_LINK_LIBRARY_USING_<FEATURE>, is supported regardless the linker
6779 language.
6780 NOTE:
6782 This variable is evaluated if, and only if, the variable
6783 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED is not defined.
6784 CMAKE_LINK_WHAT_YOU_USE
6786 New in version 3.7.
6787 Default value for LINK_WHAT_YOU_USE target property. This variable is
6790 used to initialize the property on each target as it is created.
6791 CMAKE_LINK_WHAT_YOU_USE_CHECK
6793 New in version 3.22.
6794 Defines the command executed after the link step to check libraries us‐
6797 age. This check is currently only defined on ELF platforms with value
6798 ldd -u -r.
6799 See also CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG variables.
6801 CMAKE_MACOSX_BUNDLE
6803 Default value for MACOSX_BUNDLE of targets.
6804 This variable is used to initialize the MACOSX_BUNDLE property on all
6806 the targets. See that target property for additional information.
6807 This variable is set to ON by default if CMAKE_SYSTEM_NAME equals to
6809 iOS, tvOS or watchOS.
6810 CMAKE_MACOSX_RPATH
6812 Whether to use rpaths on macOS and iOS.
6813 This variable is used to initialize the MACOSX_RPATH property on all
6815 targets.
6816 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>
6818 Default value for MAP_IMPORTED_CONFIG_<CONFIG> of targets.
6819 This variable is used to initialize the MAP_IMPORTED_CONFIG_<CONFIG>
6821 property on all the targets. See that target property for additional
6822 information.
6823 CMAKE_MODULE_LINKER_FLAGS
6825 Linker flags to be used to create modules.
6826 These flags will be used by the linker when creating a module.
6828 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
6830 Flags to be used when linking a module.
6831 Same as CMAKE_C_FLAGS_* but used by the linker when creating modules.
6833 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT
6835 New in version 3.7.
6836 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS_<CONFIG> cache
6839 entry the first time a build tree is configured. This variable is
6840 meant to be set by a toolchain file. CMake may prepend or append con‐
6841 tent to the value based on the environment and target platform.
6842 See also CMAKE_MODULE_LINKER_FLAGS_INIT.
6844 CMAKE_MODULE_LINKER_FLAGS_INIT
6846 New in version 3.7.
6847 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS cache entry the
6850 first time a build tree is configured. This variable is meant to be
6851 set by a toolchain file. CMake may prepend or append content to the
6852 value based on the environment and target platform.
6853 See also the configuration-specific variable
6855 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT.
6856 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
6858 New in version 3.25.
6859 Select the MSVC debug information format targeting the MSVC ABI. This
6862 variable is used to initialize the MSVC_DEBUG_INFORMATION_FORMAT prop‐
6863 erty on all targets as they are created. It is also propagated by
6864 calls to the try_compile() command into the test project.
6865 The allowed values are:
6867 Embedded
6869 Compile with -Z7 or equivalent flag(s) to produce object files
6870 with full symbolic debugging information.
6871 ProgramDatabase
6873 Compile with -Zi or equivalent flag(s) to produce a program
6874 database that contains all the symbolic debugging information.
6875 EditAndContinue
6877 Compile with -ZI or equivalent flag(s) to produce a program
6878 database that supports the Edit and Continue feature.
6879 The value is ignored on compilers not targeting the MSVC ABI, but an
6881 unsupported value will be rejected as an error when using a compiler
6882 targeting the MSVC ABI.
6883 The value may also be the empty string (""), in which case no debug in‐
6885 formation format flag will be added explicitly by CMake.
6886 Use generator expressions to support per-configuration specification.
6888 For example, the code:
6889 set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
6891 selects for all following targets the program database debug informa‐
6893 tion format for the Debug configuration.
6894 If this variable is not set, the MSVC_DEBUG_INFORMATION_FORMAT target
6896 property will not be set automatically. If that property is not set,
6897 CMake selects a debug information format using the default value
6898 $<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>, if supported by the
6899 compiler, and otherwise $<$<CONFIG:Debug,RelWithDebInfo>:Embedded>.
6900 NOTE:
6902 This variable has effect only when policy CMP0141 is set to NEW
6903 prior to the first project() or enable_language() command that en‐
6904 ables a language using a compiler targeting the MSVC ABI.
6905 CMAKE_MSVC_RUNTIME_LIBRARY
6907 New in version 3.15.
6908 Select the MSVC runtime library for use by compilers targeting the MSVC
6911 ABI. This variable is used to initialize the MSVC_RUNTIME_LIBRARY
6912 property on all targets as they are created. It is also propagated by
6913 calls to the try_compile() command into the test project.
6914 The allowed values are:
6916 MultiThreaded
6918 Compile with -MT or equivalent flag(s) to use a multi-threaded
6919 statically-linked runtime library.
6920 MultiThreadedDLL
6922 Compile with -MD or equivalent flag(s) to use a multi-threaded
6923 dynamically-linked runtime library.
6924 MultiThreadedDebug
6926 Compile with -MTd or equivalent flag(s) to use a multi-threaded
6927 statically-linked runtime library.
6928 MultiThreadedDebugDLL
6930 Compile with -MDd or equivalent flag(s) to use a multi-threaded
6931 dynamically-linked runtime library.
6932 The value is ignored on compilers not targeting the MSVC ABI, but an
6934 unsupported value will be rejected as an error when using a compiler
6935 targeting the MSVC ABI.
6936 The value may also be the empty string ("") in which case no runtime
6938 library selection flag will be added explicitly by CMake. Note that
6939 with Visual Studio Generators the native build system may choose to add
6940 its own default runtime library selection flag.
6941 Use generator expressions to support per-configuration specification.
6943 For example, the code:
6944 set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
6946 selects for all following targets a multi-threaded statically-linked
6948 runtime library with or without debug information depending on the con‐
6949 figuration.
6950 If this variable is not set then the MSVC_RUNTIME_LIBRARY target prop‐
6952 erty will not be set automatically. If that property is not set then
6953 CMake uses the default value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL
6954 to select a MSVC runtime library.
6955 NOTE:
6957 This variable has effect only when policy CMP0091 is set to NEW
6958 prior to the first project() or enable_language() command that en‐
6959 ables a language using a compiler targeting the MSVC ABI.
6960 CMAKE_MSVCIDE_RUN_PATH
6962 New in version 3.10.
6963 Extra PATH locations that should be used when executing
6966 add_custom_command() or add_custom_target() when using the Visual Stu‐
6967 dio 9 2008 (or above) generator. This allows for running commands and
6968 using dll's that the IDE environment is not aware of.
6969 If not set explicitly the value is initialized by the CMAKE_MSV‐
6971 CIDE_RUN_PATH environment variable, if set, and otherwise left empty.
6972 CMAKE_NINJA_OUTPUT_PATH_PREFIX
6974 New in version 3.6.
6975 Tell the Ninja Generators to add a prefix to every output path in
6978 build.ninja. A trailing slash is appended to the prefix, if missing.
6979 This is useful when the generated ninja file is meant to be embedded as
6981 a subninja file into a super ninja project. For example, the command:
6982 cd super-build-dir &&
6984 cmake -G Ninja -S /path/to/src -B sub -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/
6985 # ^^^---------- these match -----------^^^
6986 generates a build directory with its top-level (CMAKE_BINARY_DIR) in
6988 super-build-dir/sub. The path to the build directory ends in the out‐
6989 put path prefix. This makes it suitable for use in a separately-writ‐
6990 ten super-build-dir/build.ninja file with a directive like this:
6991 subninja sub/build.ninja
6993 The auto-regeneration rule in super-build-dir/build.ninja must have an
6995 order-only dependency on sub/build.ninja.
6996 New in version 3.27: The Ninja Multi-Config generator supports this
6998 variable.
6999 NOTE:
7002 When CMAKE_NINJA_OUTPUT_PATH_PREFIX is set, the project generated by
7003 CMake cannot be used as a standalone project. No default targets
7004 are specified.
7005 The value of CMAKE_NINJA_OUTPUT_PATH_PREFIX must match one or more
7007 path components at the end of CMAKE_BINARY_DIR, or the behavior is
7008 undefined. However, this requirement is not checked automatically.
7009 CMAKE_NO_BUILTIN_CHRPATH
7011 Do not use the builtin binary editor to fix runtime library search
7012 paths on installation.
7013 When an ELF or XCOFF binary needs to have a different runtime library
7015 search path after installation than it does in the build tree, CMake
7016 uses a builtin editor to change the runtime search path in the in‐
7017 stalled copy. If this variable is set to true then CMake will relink
7018 the binary before installation instead of using its builtin editor.
7019 For more information on RPATH handling see the INSTALL_RPATH and
7021 BUILD_RPATH target properties.
7022 New in version 3.20: This variable also applies to XCOFF binaries' LIB‐
7024 PATH. Prior to the addition of the XCOFF editor in CMake 3.20, this
7025 variable applied only to ELF binaries' RPATH/RUNPATH.
7026 CMAKE_NO_SYSTEM_FROM_IMPORTED
7029 Default value for NO_SYSTEM_FROM_IMPORTED of targets.
7030 This variable is used to initialize the NO_SYSTEM_FROM_IMPORTED prop‐
7032 erty on all the targets. See that target property for additional in‐
7033 formation.
7034 CMAKE_OPTIMIZE_DEPENDENCIES
7036 New in version 3.19.
7037 Initializes the OPTIMIZE_DEPENDENCIES target property.
7040 CMAKE_OSX_ARCHITECTURES
7042 Target specific architectures for macOS and iOS.
7043 This variable is used to initialize the OSX_ARCHITECTURES property on
7045 each target as it is created. See that target property for additional
7046 information.
7047 The value of this variable should be set prior to the first project()
7049 or enable_language() command invocation because it may influence con‐
7050 figuration of the toolchain and flags. It is intended to be set lo‐
7051 cally by the user creating a build tree. This variable should be set
7052 as a CACHE entry (or else CMake may remove it while initializing a
7053 cache entry of the same name) unless policy CMP0126 is set to NEW.
7054 Despite the OSX part in the variable name(s) they apply also to other
7056 SDKs than macOS like iOS, tvOS, or watchOS.
7057 This variable is ignored on platforms other than Apple.
7059 CMAKE_OSX_DEPLOYMENT_TARGET
7061 Specify the minimum version of the target platform (e.g. macOS or iOS)
7062 on which the target binaries are to be deployed. CMake uses this vari‐
7063 able value for the -mmacosx-version-min flag or their respective target
7064 platform equivalents. For older Xcode versions that shipped multiple
7065 macOS SDKs this variable also helps to choose the SDK in case
7066 CMAKE_OSX_SYSROOT is unset.
7067 If not set explicitly the value is initialized by the MACOSX_DEPLOY‐
7069 MENT_TARGET environment variable, if set, and otherwise computed based
7070 on the host platform.
7071 The value of this variable should be set prior to the first project()
7073 or enable_language() command invocation because it may influence con‐
7074 figuration of the toolchain and flags. It is intended to be set lo‐
7075 cally by the user creating a build tree. This variable should be set
7076 as a CACHE entry (or else CMake may remove it while initializing a
7077 cache entry of the same name) unless policy CMP0126 is set to NEW.
7078 Despite the OSX part in the variable name(s) they apply also to other
7080 SDKs than macOS like iOS, tvOS, or watchOS.
7081 This variable is ignored on platforms other than Apple.
7083 CMAKE_OSX_SYSROOT
7085 Specify the location or name of the macOS platform SDK to be used.
7086 CMake uses this value to compute the value of the -isysroot flag or
7087 equivalent and to help the find_* commands locate files in the SDK.
7088 If not set explicitly the value is initialized by the SDKROOT environ‐
7090 ment variable, if set, and otherwise computed based on the
7091 CMAKE_OSX_DEPLOYMENT_TARGET or the host platform.
7092 The value of this variable should be set prior to the first project()
7094 or enable_language() command invocation because it may influence con‐
7095 figuration of the toolchain and flags. It is intended to be set lo‐
7096 cally by the user creating a build tree. This variable should be set
7097 as a CACHE entry (or else CMake may remove it while initializing a
7098 cache entry of the same name) unless policy CMP0126 is set to NEW.
7099 Despite the OSX part in the variable name(s) they apply also to other
7101 SDKs than macOS like iOS, tvOS, or watchOS.
7102 This variable is ignored on platforms other than Apple.
7104 CMAKE_PCH_INSTANTIATE_TEMPLATES
7106 New in version 3.19.
7107 This variable is used to initialize the PCH_INSTANTIATE_TEMPLATES prop‐
7110 erty of targets when they are created.
7111 CMAKE_PCH_WARN_INVALID
7113 New in version 3.18.
7114 This variable is used to initialize the PCH_WARN_INVALID property of
7117 targets when they are created.
7118 CMAKE_PDB_OUTPUT_DIRECTORY
7120 Output directory for MS debug symbol .pdb files generated by the linker
7121 for executable and shared library targets.
7122 This variable is used to initialize the PDB_OUTPUT_DIRECTORY property
7124 on all the targets. See that target property for additional informa‐
7125 tion.
7126 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>
7128 Per-configuration output directory for MS debug symbol .pdb files gen‐
7129 erated by the linker for executable and shared library targets.
7130 This is a per-configuration version of CMAKE_PDB_OUTPUT_DIRECTORY.
7132 This variable is used to initialize the PDB_OUTPUT_DIRECTORY_<CONFIG>
7133 property on all the targets. See that target property for additional
7134 information.
7135 CMAKE_PLATFORM_NO_VERSIONED_SONAME
7137 New in version 3.1.
7138 This variable is used to globally control whether the VERSION and
7141 SOVERSION target properties should be used for shared libraries. When
7142 set to true, adding version information to each shared library target
7143 is disabled.
7144 By default this variable is set only on platforms where CMake knows it
7146 is needed. On other platforms, the specified properties will be used
7147 for shared libraries.
7148 CMAKE_POSITION_INDEPENDENT_CODE
7150 Default value for POSITION_INDEPENDENT_CODE of targets.
7151 This variable is used to initialize the POSITION_INDEPENDENT_CODE prop‐
7153 erty on all the targets. See that target property for additional in‐
7154 formation. If set, its value is also used by the try_compile() com‐
7155 mand.
7156 CMAKE_RUNTIME_OUTPUT_DIRECTORY
7158 Where to put all the RUNTIME target files when built.
7159 This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY prop‐
7161 erty on all the targets. See that target property for additional in‐
7162 formation.
7163 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
7165 New in version 3.3.
7166 Where to put all the RUNTIME target files when built for a specific
7169 configuration.
7170 This variable is used to initialize the
7172 RUNTIME_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
7173 that target property for additional information.
7174 CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS
7176 New in version 3.27.
7177 Specify whether shared library generates an import file.
7180 This variable is used to initialize the ENABLE_EXPORTS target property
7182 for shared library targets when they are created by calls to the
7183 add_library() command. See the property documentation for details.
7184 CMAKE_SHARED_LINKER_FLAGS
7186 Linker flags to be used to create shared libraries.
7187 These flags will be used by the linker when creating a shared library.
7189 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
7191 Flags to be used when linking a shared library.
7192 Same as CMAKE_C_FLAGS_* but used by the linker when creating shared li‐
7194 braries.
7195 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT
7197 New in version 3.7.
7198 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS_<CONFIG> cache
7201 entry the first time a build tree is configured. This variable is
7202 meant to be set by a toolchain file. CMake may prepend or append con‐
7203 tent to the value based on the environment and target platform.
7204 See also CMAKE_SHARED_LINKER_FLAGS_INIT.
7206 CMAKE_SHARED_LINKER_FLAGS_INIT
7208 New in version 3.7.
7209 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS cache entry the
7212 first time a build tree is configured. This variable is meant to be
7213 set by a toolchain file. CMake may prepend or append content to the
7214 value based on the environment and target platform.
7215 See also the configuration-specific variable
7217 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT.
7218 CMAKE_SKIP_BUILD_RPATH
7220 Do not include RPATHs in the build tree.
7221 Normally CMake uses the build tree for the RPATH when building executa‐
7223 bles etc on systems that use RPATH. When the software is installed the
7224 executables etc are relinked by CMake to have the install RPATH. If
7225 this variable is set to TRUE then the software is always built with no
7226 RPATH.
7227 This is used to initialize the SKIP_BUILD_RPATH target property for all
7229 targets. For more information on RPATH handling see the INSTALL_RPATH
7230 and BUILD_RPATH target properties.
7231 See also the CMAKE_SKIP_INSTALL_RPATH variable. To omit RPATH in both
7233 the build and install steps, use CMAKE_SKIP_RPATH instead.
7234 CMAKE_SKIP_INSTALL_RPATH
7236 Do not include RPATHs in the install tree.
7237 Normally CMake uses the build tree for the RPATH when building executa‐
7239 bles etc on systems that use RPATH. When the software is installed the
7240 executables etc are relinked by CMake to have the install RPATH. If
7241 this variable is set to true then the software is always installed
7242 without RPATH, even if RPATH is enabled when building. This can be
7243 useful for example to allow running tests from the build directory with
7244 RPATH enabled before the installation step.
7245 See also the CMAKE_SKIP_BUILD_RPATH variable. To omit RPATH in both
7247 the build and install steps, use CMAKE_SKIP_RPATH instead.
7248 For more information on RPATH handling see the INSTALL_RPATH and
7250 BUILD_RPATH target properties.
7251 CMAKE_STATIC_LINKER_FLAGS
7253 Flags to be used to create static libraries. These flags will be
7254 passed to the archiver when creating a static library.
7255 See also CMAKE_STATIC_LINKER_FLAGS_<CONFIG>.
7257 NOTE:
7259 Static libraries do not actually link. They are essentially ar‐
7260 chives of object files. The use of the name "linker" in the name of
7261 this variable is kept for compatibility.
7262 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
7264 Flags to be used to create static libraries. These flags will be
7265 passed to the archiver when creating a static library in the <CONFIG>
7266 configuration.
7267 See also CMAKE_STATIC_LINKER_FLAGS.
7269 NOTE:
7271 Static libraries do not actually link. They are essentially ar‐
7272 chives of object files. The use of the name "linker" in the name of
7273 this variable is kept for compatibility.
7274 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT
7276 New in version 3.7.
7277 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS_<CONFIG> cache
7280 entry the first time a build tree is configured. This variable is
7281 meant to be set by a toolchain file. CMake may prepend or append con‐
7282 tent to the value based on the environment and target platform.
7283 See also CMAKE_STATIC_LINKER_FLAGS_INIT.
7285 CMAKE_STATIC_LINKER_FLAGS_INIT
7287 New in version 3.7.
7288 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS cache entry the
7291 first time a build tree is configured. This variable is meant to be
7292 set by a toolchain file. CMake may prepend or append content to the
7293 value based on the environment and target platform.
7294 See also the configuration-specific variable
7296 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT.
7297 CMAKE_TASKING_TOOLSET
7299 New in version 3.25.
7300 Select the Tasking toolset which provides the compiler
7303 Architecture compilers are provided by different toolchains with incom‐
7305 patible versioning schemes. Set this variable in a toolchain file so
7306 CMake can detect the compiler features correctly. If no toolset is
7307 specified, Standalone is assumed.
7308 Due to the different versioning schemes, the compiler version (‐
7310 CMAKE_<LANG>_COMPILER_VERSION) depends on the toolset and architecture
7311 in use. If projects can be built with multiple toolsets or architec‐
7312 tures, the specified CMAKE_TASKING_TOOLSET and the automatically deter‐
7313 mined CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID must be taken into account
7314 when comparing against the CMAKE_<LANG>_COMPILER_VERSION.
7315 TriCore
7317 Compilers are provided by the TriCore toolset.
7318 SmartCode
7320 Compilers are provided by the SmartCode toolset.
7321 Standalone
7323 Compilers are provided by the standalone toolsets.
7324 NOTE:
7326 For the TriCore architecture, the compiler from the TriCore
7327 toolset is selected as standalone compiler.
7328 CMAKE_TRY_COMPILE_CONFIGURATION
7330 Build configuration used for try_compile() and try_run() projects.
7331 Projects built by try_compile() and try_run() are built synchronously
7333 during the CMake configuration step. Therefore a specific build con‐
7334 figuration must be chosen even if the generated build system supports
7335 multiple configurations.
7336 CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
7338 New in version 3.24.
7339 Set to a true value to tell the try_compile() command not to propagate
7342 any platform variables into the test project.
7343 The try_compile() command normally passes some CMake variables that
7345 configure the platform and toolchain behavior into test projects. See
7346 policy CMP0137. This variable may be set to disable that behavior.
7347 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
7349 New in version 3.6.
7350 List of variables that the try_compile() command source file signature
7353 must propagate into the test project in order to target the same plat‐
7354 form as the host project.
7355 This variable should not be set by project code. It is meant to be set
7357 by CMake's platform information modules for the current toolchain, or
7358 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
7359 Variables meaningful to CMake, such as CMAKE_<LANG>_FLAGS, are propa‐
7361 gated automatically. The CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable
7362 may be set to pass custom variables meaningful to a toolchain file.
7363 For example, a toolchain file may contain:
7364 set(CMAKE_SYSTEM_NAME ...)
7366 set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE)
7367 # ... use MY_CUSTOM_VARIABLE ...
7368 If a user passes -DMY_CUSTOM_VARIABLE=SomeValue to CMake then this set‐
7370 ting will be made visible to the toolchain file both for the main
7371 project and for test projects generated by the try_compile() command
7372 source file signature.
7373 Changed in version 3.24: Listed variables are propagated to the
7375 try_compile() whole-project signature too. See CMP0137.
7376 New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES vari‐
7379 able may be set to disable passing platform variables into the test
7380 project.
7381 CMAKE_TRY_COMPILE_TARGET_TYPE
7384 New in version 3.6.
7385 Type of target generated for try_compile() calls using the source file
7388 signature. Valid values are:
7389 EXECUTABLE
7391 Use add_executable() to name the source file in the generated
7392 project. This is the default if no value is given.
7393 STATIC_LIBRARY
7395 Use add_library() with the STATIC option to name the source file
7396 in the generated project. This avoids running the linker and is
7397 intended for use with cross-compiling toolchains that cannot
7398 link without custom flags or linker scripts.
7399 CMAKE_UNITY_BUILD
7401 New in version 3.16.
7402 This variable is used to initialize the UNITY_BUILD property of targets
7405 when they are created. Setting it to true enables batch compilation of
7406 multiple sources within each target. This feature is known as a Unity
7407 or Jumbo build.
7408 Projects should not set this variable, it is intended as a developer
7410 control to be set on the cmake(1) command line or other equivalent
7411 methods. The developer must have the ability to enable or disable
7412 unity builds according to the capabilities of their own machine and
7413 compiler.
7414 By default, this variable is not set, which will result in unity builds
7416 being disabled.
7417 NOTE:
7419 This option currently does not work well in combination with the
7420 CMAKE_EXPORT_COMPILE_COMMANDS variable.
7421 CMAKE_UNITY_BUILD_BATCH_SIZE
7423 New in version 3.16.
7424 This variable is used to initialize the UNITY_BUILD_BATCH_SIZE property
7427 of targets when they are created. It specifies the default upper limit
7428 on the number of source files that may be combined in any one unity
7429 source file when unity builds are enabled for a target.
7430 CMAKE_UNITY_BUILD_UNIQUE_ID
7432 New in version 3.20.
7433 This variable is used to initialize the UNITY_BUILD_UNIQUE_ID property
7436 of targets when they are created. It specifies the name of the unique
7437 identifier generated per file in a unity build.
7438 CMAKE_USE_RELATIVE_PATHS
7440 This variable has no effect. The partially implemented effect it had
7441 in previous releases was removed in CMake 3.4.
7442 CMAKE_VERIFY_INTERFACE_HEADER_SETS
7444 New in version 3.24.
7445 This variable is used to initialize the VERIFY_INTERFACE_HEADER_SETS
7448 property of targets when they are created. Setting it to true enables
7449 header set verification.
7450 Projects should not normally set this variable, it is intended as a de‐
7452 veloper control to be set on the cmake(1) command line or other equiva‐
7453 lent methods. The developer must have the ability to enable or disable
7454 header set verification according to the capabilities of their own ma‐
7455 chine and compiler.
7456 Verification of a dependency's header sets is not typically of interest
7458 to developers. Therefore, FetchContent_MakeAvailable() explicitly sets
7459 CMAKE_VERIFY_INTERFACE_HEADER_SETS to false for the duration of its
7460 call, but restores its original value before returning. If a project
7461 brings a dependency directly into the main build (e.g. calling
7462 add_subdirectory() on a vendored project from a git submodule), it
7463 should also do likewise. For example:
7464 # Save original setting so we can restore it later
7466 set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS})
7467 # Include the vendored dependency with header set verification disabled
7469 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF)
7470 add_subdirectory(...) # Vendored sources, e.g. from git submodules
7471 # Add the project's own sources. Restore the developer's original choice
7473 # for whether to enable header set verification.
7474 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification})
7475 add_subdirectory(src)
7476 By default, this variable is not set, which will result in header set
7478 verification being disabled.
7479 CMAKE_VISIBILITY_INLINES_HIDDEN
7481 Default value for the VISIBILITY_INLINES_HIDDEN target property when a
7482 target is created.
7483 CMAKE_VS_DEBUGGER_COMMAND
7485 New in version 3.27.
7486 This variable is used to initialize the VS_DEBUGGER_COMMAND property on
7489 each target as it is created. See that target property for additional
7490 information.
7491 CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS
7493 New in version 3.27.
7494 This variable is used to initialize the VS_DEBUGGER_COMMAND_ARGUMENTS
7497 property on each target as it is created. See that target property for
7498 additional information.
7499 CMAKE_VS_DEBUGGER_ENVIRONMENT
7501 New in version 3.27.
7502 This variable is used to initialize the VS_DEBUGGER_ENVIRONMENT prop‐
7505 erty on each target as it is created. See that target property for ad‐
7506 ditional information.
7507 CMAKE_VS_DEBUGGER_WORKING_DIRECTORY
7509 New in version 3.27.
7510 This variable is used to initialize the VS_DEBUGGER_WORKING_DIRECTORY
7513 property on each target as it is created. See that target property for
7514 additional information.
7515 CMAKE_VS_GLOBALS
7517 New in version 3.13.
7518 List of Key=Value records to be set per target as target properties
7521 VS_GLOBAL_<variable> with variable=Key and value Value.
7522 For example:
7524 set(CMAKE_VS_GLOBALS
7526 "DefaultLanguage=en-US"
7527 "MinimumVisualStudioVersion=14.0"
7528 )
7529 will set properties VS_GLOBAL_DefaultLanguage to en-US and
7531 VS_GLOBAL_MinimumVisualStudioVersion to 14.0 for all targets (except
7532 for INTERFACE libraries).
7533 This variable is meant to be set by a toolchain file.
7535 CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
7537 New in version 3.3.
7538 Include INSTALL target to default build.
7541 In Visual Studio solution, by default the INSTALL target will not be
7543 part of the default build. Setting this variable will enable the IN‐
7544 STALL target to be part of the default build.
7545 CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
7547 New in version 3.8.
7548 Include PACKAGE target to default build.
7551 In Visual Studio solution, by default the PACKAGE target will not be
7553 part of the default build. Setting this variable will enable the PACK‐
7554 AGE target to be part of the default build.
7555 CMAKE_VS_JUST_MY_CODE_DEBUGGING
7557 New in version 3.15.
7558 Enable Just My Code with Visual Studio debugger.
7561 This variable is used to initialize the VS_JUST_MY_CODE_DEBUGGING prop‐
7563 erty on all targets when they are created. See that target property
7564 for additional information.
7565 CMAKE_VS_NO_COMPILE_BATCHING
7567 New in version 3.24.
7568 Turn off compile batching when using Visual Studio Generators.
7571 This variable is used to initialize the VS_NO_COMPILE_BATCHING property
7573 on all targets when they are created. See that target property for ad‐
7574 ditional information.
7575 Example
7577 This shows setting the property for the target foo using the variable.
7578 set(CMAKE_VS_NO_COMPILE_BATCHING ON)
7580 add_library(foo SHARED foo.cpp)
7581 CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
7583 New in version 3.12.
7584 This variable allows to override Visual Studio default Exclude Directo‐
7587 ries.
7588 CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
7590 New in version 3.12.
7591 This variable allows to override Visual Studio default Executable Di‐
7594 rectories.
7595 CMAKE_VS_SDK_INCLUDE_DIRECTORIES
7597 New in version 3.12.
7598 This variable allows to override Visual Studio default Include Directo‐
7601 ries.
7602 CMAKE_VS_SDK_LIBRARY_DIRECTORIES
7604 New in version 3.12.
7605 This variable allows to override Visual Studio default Library Directo‐
7608 ries.
7609 CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
7611 New in version 3.12.
7612 This variable allows to override Visual Studio default Library WinRT
7615 Directories.
7616 CMAKE_VS_SDK_REFERENCE_DIRECTORIES
7618 New in version 3.12.
7619 This variable allows to override Visual Studio default Reference Direc‐
7622 tories.
7623 CMAKE_VS_SDK_SOURCE_DIRECTORIES
7625 New in version 3.12.
7626 This variable allows to override Visual Studio default Source Directo‐
7629 ries.
7630 CMAKE_VS_WINRT_BY_DEFAULT
7632 New in version 3.13.
7633 Inform Visual Studio Generators for VS 2010 and above that the target
7636 platform enables WinRT compilation by default and it needs to be ex‐
7637 plicitly disabled if /ZW or VS_WINRT_COMPONENT is omitted (as opposed
7638 to enabling it when either of those options is present)
7639 This makes cmake configuration consistent in terms of WinRT among plat‐
7641 forms - if you did not enable the WinRT compilation explicitly, it will
7642 be disabled (by either not enabling it or explicitly disabling it)
7643 Note: WinRT compilation is always explicitly disabled for C language
7645 source files, even if it is expliclty enabled for a project
7646 This variable is meant to be set by a toolchain file for such plat‐
7648 forms.
7649 CMAKE_WATCOM_RUNTIME_LIBRARY
7651 New in version 3.24.
7652 Select the Watcom runtime library for use by compilers targeting the
7655 Watcom ABI. This variable is used to initialize the
7656 WATCOM_RUNTIME_LIBRARY property on all targets as they are created. It
7657 is also propagated by calls to the try_compile() command into the test
7658 project.
7659 The allowed values are:
7661 SingleThreaded
7663 Compile without additional flags to use a single-threaded stati‐
7664 cally-linked runtime library.
7665 SingleThreadedDLL
7667 Compile with -br or equivalent flag(s) to use a single-threaded
7668 dynamically-linked runtime library. This is not available for
7669 Linux targets.
7670 MultiThreaded
7672 Compile with -bm or equivalent flag(s) to use a multi-threaded
7673 statically-linked runtime library.
7674 MultiThreadedDLL
7676 Compile with -bm -br or equivalent flag(s) to use a
7677 multi-threaded dynamically-linked runtime library. This is not
7678 available for Linux targets.
7679 The value is ignored on non-Watcom compilers but an unsupported value
7681 will be rejected as an error when using a compiler targeting the Watcom
7682 ABI.
7683 The value may also be the empty string ("") in which case no runtime
7685 library selection flag will be added explicitly by CMake.
7686 Use generator expressions to support per-configuration specification.
7688 For example, the code:
7690 set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded")
7692 selects for all following targets a multi-threaded statically-linked
7694 runtime library.
7695 If this variable is not set then the WATCOM_RUNTIME_LIBRARY target
7697 property will not be set automatically. If that property is not set
7698 then CMake uses the default value MultiThreadedDLL on Windows and Sin‐
7699 gleThreaded on other platforms to select a Watcom runtime library.
7700 NOTE:
7702 This variable has effect only when policy CMP0136 is set to NEW
7703 prior to the first project() or enable_language() command that en‐
7704 ables a language using a compiler targeting the Watcom ABI.
7705 CMAKE_WIN32_EXECUTABLE
7707 Default value for WIN32_EXECUTABLE of targets.
7708 This variable is used to initialize the WIN32_EXECUTABLE property on
7710 all the targets. See that target property for additional information.
7711 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
7713 New in version 3.4.
7714 Default value for WINDOWS_EXPORT_ALL_SYMBOLS target property. This
7717 variable is used to initialize the property on each target as it is
7718 created.
7719 CMAKE_XCODE_ATTRIBUTE_<an-attribute>
7721 New in version 3.1.
7722 Set Xcode target attributes directly.
7725 Tell the Xcode generator to set <an-attribute> to a given value in the
7727 generated Xcode project. Ignored on other generators.
7728 This offers low-level control over the generated Xcode project file.
7730 It is meant as a last resort for specifying settings that CMake does
7731 not otherwise have a way to control. Although this can override a set‐
7732 ting CMake normally produces on its own, doing so bypasses CMake's
7733 model of the project and can break things.
7734 See the XCODE_ATTRIBUTE_<an-attribute> target property to set at‐
7736 tributes on a specific target.
7737 Contents of CMAKE_XCODE_ATTRIBUTE_<an-attribute> may use "generator ex‐
7739 pressions" with the syntax $<...>. See the
7740 cmake-generator-expressions(7) manual for available expressions. See
7741 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
7742 erties.
7743 EXECUTABLE_OUTPUT_PATH
7745 Old executable location variable.
7746 The target property RUNTIME_OUTPUT_DIRECTORY supersedes this variable
7748 for a target if it is set. Executable targets are otherwise placed in
7749 this directory.
7750 LIBRARY_OUTPUT_PATH
7752 Old library location variable.
7753 The target properties ARCHIVE_OUTPUT_DIRECTORY,
7755 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY supersede this
7756 variable for a target if they are set. Library targets are otherwise
7757 placed in this directory.
7758
7760 CMAKE_C_COMPILE_FEATURES
7761 New in version 3.1.
7762 List of features known to the C compiler
7765 These features are known to be available for use with the C compiler.
7767 This list is a subset of the features listed in the
7768 CMAKE_C_KNOWN_FEATURES global property.
7769 See the cmake-compile-features(7) manual for information on compile
7771 features and a list of supported compilers.
7772 CMAKE_C_EXTENSIONS
7774 New in version 3.1.
7775 Default value for C_EXTENSIONS target property if set when a target is
7778 created.
7779 See the cmake-compile-features(7) manual for information on compile
7781 features and a list of supported compilers.
7782 CMAKE_C_STANDARD
7784 New in version 3.1.
7785 Default value for C_STANDARD target property if set when a target is
7788 created.
7789 See the cmake-compile-features(7) manual for information on compile
7791 features and a list of supported compilers.
7792 CMAKE_C_STANDARD_REQUIRED
7794 New in version 3.1.
7795 Default value for C_STANDARD_REQUIRED target property if set when a
7798 target is created.
7799 See the cmake-compile-features(7) manual for information on compile
7801 features and a list of supported compilers.
7802 CMAKE_COMPILER_IS_GNUCC
7804 True if the C compiler is GNU.
7805 This variable is deprecated. Use CMAKE_C_COMPILER_ID instead.
7807 CMAKE_COMPILER_IS_GNUCXX
7809 True if the C++ (CXX) compiler is GNU.
7810 This variable is deprecated. Use CMAKE_CXX_COMPILER_ID instead.
7812 CMAKE_COMPILER_IS_GNUG77
7814 True if the Fortran compiler is GNU.
7815 This variable is deprecated. Use CMAKE_Fortran_COMPILER_ID instead.
7817 CMAKE_CUDA_ARCHITECTURES
7819 New in version 3.18.
7820 Default value for CUDA_ARCHITECTURES property of targets.
7823 Initialized by the CUDAARCHS environment variable if set. Otherwise as
7825 follows depending on CMAKE_CUDA_COMPILER_ID:
7826 • For Clang: the oldest architecture that works.
7828 • For NVIDIA: the default architecture chosen by the compiler. See
7830 policy CMP0104.
7831 Users are encouraged to override this, as the default varies across
7833 compilers and compiler versions.
7834 This variable is used to initialize the CUDA_ARCHITECTURES property on
7836 all targets. See the target property for additional information.
7837 Examples
7839 cmake_minimum_required(VERSION)
7840 if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
7842 set(CMAKE_CUDA_ARCHITECTURES 75)
7843 endif()
7844 project(example LANGUAGES CUDA)
7846 CMAKE_CUDA_ARCHITECTURES will default to 75 unless overridden by the
7848 user.
7849 CMAKE_CUDA_COMPILE_FEATURES
7851 New in version 3.17.
7852 List of features known to the CUDA compiler
7855 These features are known to be available for use with the CUDA com‐
7857 piler. This list is a subset of the features listed in the
7858 CMAKE_CUDA_KNOWN_FEATURES global property.
7859 See the cmake-compile-features(7) manual for information on compile
7861 features and a list of supported compilers.
7862 CMAKE_CUDA_EXTENSIONS
7864 New in version 3.8.
7865 Default value for CUDA_EXTENSIONS target property if set when a target
7868 is created.
7869 See the cmake-compile-features(7) manual for information on compile
7871 features and a list of supported compilers.
7872 CMAKE_CUDA_HOST_COMPILER
7874 New in version 3.10.
7875 When CMAKE_CUDA_COMPILER_ID is NVIDIA, CMAKE_CUDA_HOST_COMPILER selects
7878 the compiler executable to use when compiling host code for CUDA lan‐
7879 guage files. This maps to the nvcc -ccbin option.
7880 The CMAKE_CUDA_HOST_COMPILER variable may be set explicitly before CUDA
7882 is first enabled by a project() or enable_language() command. This can
7883 be done via -DCMAKE_CUDA_HOST_COMPILER=... on the command line or in a
7884 toolchain file. Or, one may set the CUDAHOSTCXX environment variable
7885 to provide a default value.
7886 Once the CUDA language is enabled, the CMAKE_CUDA_HOST_COMPILER vari‐
7888 able is read-only and changes to it are undefined behavior.
7889 NOTE:
7891 Since CMAKE_CUDA_HOST_COMPILER is meaningful only when the
7892 CMAKE_CUDA_COMPILER_ID is NVIDIA, it does not make sense to set
7893 CMAKE_CUDA_HOST_COMPILER without also setting CMAKE_CUDA_COMPILER to
7894 NVCC.
7895 NOTE:
7897 Ignored when using Visual Studio Generators.
7898 CMAKE_CUDA_STANDARD
7900 New in version 3.8.
7901 Default value for CUDA_STANDARD target property if set when a target is
7904 created.
7905 See the cmake-compile-features(7) manual for information on compile
7907 features and a list of supported compilers.
7908 CMAKE_CUDA_STANDARD_REQUIRED
7910 New in version 3.8.
7911 Default value for CUDA_STANDARD_REQUIRED target property if set when a
7914 target is created.
7915 See the cmake-compile-features(7) manual for information on compile
7917 features and a list of supported compilers.
7918 CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES
7920 New in version 3.8.
7921 When the CUDA language has been enabled, this provides a
7924 semicolon-separated list of include directories provided by the CUDA
7925 Toolkit. The value may be useful for C++ source files to include CUDA
7926 headers.
7927 CMAKE_CXX_COMPILE_FEATURES
7929 New in version 3.1.
7930 List of features known to the C++ compiler
7933 These features are known to be available for use with the C++ compiler.
7935 This list is a subset of the features listed in the
7936 CMAKE_CXX_KNOWN_FEATURES global property.
7937 See the cmake-compile-features(7) manual for information on compile
7939 features and a list of supported compilers.
7940 CMAKE_CXX_EXTENSIONS
7942 New in version 3.1.
7943 Default value for CXX_EXTENSIONS target property if set when a target
7946 is created.
7947 See the cmake-compile-features(7) manual for information on compile
7949 features and a list of supported compilers.
7950 CMAKE_CXX_STANDARD
7952 New in version 3.1.
7953 Default value for CXX_STANDARD target property if set when a target is
7956 created.
7957 See the cmake-compile-features(7) manual for information on compile
7959 features and a list of supported compilers.
7960 CMAKE_CXX_STANDARD_REQUIRED
7962 New in version 3.1.
7963 Default value for CXX_STANDARD_REQUIRED target property if set when a
7966 target is created.
7967 See the cmake-compile-features(7) manual for information on compile
7969 features and a list of supported compilers.
7970 CMAKE_Fortran_MODDIR_DEFAULT
7972 Fortran default module output directory.
7973 Most Fortran compilers write .mod files to the current working direc‐
7975 tory. For those that do not, this is set to . and used when the
7976 Fortran_MODULE_DIRECTORY target property is not set.
7977 CMAKE_Fortran_MODDIR_FLAG
7979 Fortran flag for module output directory.
7980 This stores the flag needed to pass the value of the
7982 Fortran_MODULE_DIRECTORY target property to the compiler.
7983 CMAKE_Fortran_MODOUT_FLAG
7985 Fortran flag to enable module output.
7986 Most Fortran compilers write .mod files out by default. For others,
7988 this stores the flag needed to enable module output.
7989 CMAKE_HIP_ARCHITECTURES
7991 New in version 3.21.
7992 Default value for HIP_ARCHITECTURES property of targets.
7995 This is initialized to the architectures reported by rocm_agent_enumer‐
7997 ator, if available, and otherwise to the default chosen by the com‐
7998 piler.
7999 This variable is used to initialize the HIP_ARCHITECTURES property on
8001 all targets. See the target property for additional information.
8002 CMAKE_HIP_EXTENSIONS
8004 New in version 3.21.
8005 Default value for HIP_EXTENSIONS target property if set when a target
8008 is created.
8009 See the cmake-compile-features(7) manual for information on compile
8011 features and a list of supported compilers.
8012 CMAKE_HIP_STANDARD
8014 New in version 3.21.
8015 Default value for HIP_STANDARD target property if set when a target is
8018 created.
8019 See the cmake-compile-features(7) manual for information on compile
8021 features and a list of supported compilers.
8022 CMAKE_HIP_STANDARD_REQUIRED
8024 New in version 3.21.
8025 Default value for HIP_STANDARD_REQUIRED target property if set when a
8028 target is created.
8029 See the cmake-compile-features(7) manual for information on compile
8031 features and a list of supported compilers.
8032 CMAKE_ISPC_HEADER_DIRECTORY
8034 New in version 3.19.
8035 ISPC generated header output directory.
8038 This variable is used to initialize the ISPC_HEADER_DIRECTORY property
8040 on all the targets. See the target property for additional informa‐
8041 tion.
8042 CMAKE_ISPC_HEADER_SUFFIX
8044 New in version 3.19.2.
8045 Output suffix to be used for ISPC generated headers.
8048 This variable is used to initialize the ISPC_HEADER_SUFFIX property on
8050 all the targets. See the target property for additional information.
8051 CMAKE_ISPC_INSTRUCTION_SETS
8053 New in version 3.19.
8054 Default value for ISPC_INSTRUCTION_SETS property of targets.
8057 This variable is used to initialize the ISPC_INSTRUCTION_SETS property
8059 on all targets. See the target property for additional information.
8060 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE
8062 New in version 3.7.1.
8063 When Cross Compiling for Android this variable contains the toolchain
8066 binutils machine name (e.g. gcc -dumpmachine). The binutils typically
8067 have a <machine>- prefix on their name.
8068 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
8070 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.
8071 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
8073 New in version 3.7.
8074 When Cross Compiling for Android this variable contains the absolute
8077 path prefixing the toolchain GNU compiler and its binutils.
8078 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX and
8080 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
8081 For example, the path to the linker is:
8083 ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX}
8085 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
8087 New in version 3.7.
8088 When Cross Compiling for Android this variable contains the host plat‐
8091 form suffix of the toolchain GNU compiler and its binutils.
8092 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
8094 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
8095 CMAKE_<LANG>_ARCHIVE_APPEND
8097 Rule variable to append to a static archive.
8098 This is a rule variable that tells CMake how to append to a static ar‐
8100 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8101 some platforms in order to support large object counts. See also
8102 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_FINISH.
8103 CMAKE_<LANG>_ARCHIVE_CREATE
8105 Rule variable to create a new static archive.
8106 This is a rule variable that tells CMake how to create a static ar‐
8108 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8109 some platforms in order to support large object counts. See also
8110 CMAKE_<LANG>_ARCHIVE_APPEND and CMAKE_<LANG>_ARCHIVE_FINISH.
8111 CMAKE_<LANG>_ARCHIVE_FINISH
8113 Rule variable to finish an existing static archive.
8114 This is a rule variable that tells CMake how to finish a static ar‐
8116 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8117 some platforms in order to support large object counts. See also
8118 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_APPEND.
8119 CMAKE_<LANG>_BYTE_ORDER
8121 New in version 3.20.
8122 Byte order of <LANG> compiler target architecture, if known. If de‐
8125 fined and not empty, the value is one of:
8126 BIG_ENDIAN
8128 The target architecture is Big Endian.
8129 LITTLE_ENDIAN
8131 The target architecture is Little Endian.
8132 This is defined for languages C, CXX, OBJC, OBJCXX, and CUDA.
8134 If CMAKE_OSX_ARCHITECTURES specifies multiple architectures, the value
8136 of CMAKE_<LANG>_BYTE_ORDER is non-empty only if all architectures share
8137 the same byte order.
8138 CMAKE_<LANG>_COMPILE_OBJECT
8140 Rule variable to compile a single object file.
8141 This is a rule variable that tells CMake how to compile a single object
8143 file for the language <LANG>.
8144 CMAKE_<LANG>_COMPILER
8146 The full path to the compiler for LANG.
8147 This is the command that will be used as the <LANG> compiler. Once
8149 set, you can not change this variable.
8150 Usage
8152 This variable can be set by the user during the first time a build tree
8153 is configured.
8154 If a non-full path value is supplied then CMake will resolve the full
8156 path of the compiler.
8157 The variable could be set in a user supplied toolchain file or via -D
8159 on the command line.
8160 NOTE:
8162 Options that are required to make the compiler work correctly can be
8163 included as items in a list; they can not be changed.
8164 #set within user supplied toolchain file
8166 set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2)
8167 or
8169 $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2'
8171 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN
8173 The external toolchain for cross-compiling, if supported.
8174 Some compiler toolchains do not ship their own auxiliary utilities such
8176 as archivers and linkers. The compiler driver may support a com‐
8177 mand-line argument to specify the location of such tools.
8178 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN may be set to a path to the
8179 external toolchain and will be passed to the compiler driver if sup‐
8180 ported.
8181 This variable may only be set in a toolchain file specified by the
8183 CMAKE_TOOLCHAIN_FILE variable.
8184 CMAKE_<LANG>_COMPILER_ID
8186 Compiler identification string.
8187 A short string unique to the compiler vendor. Possible values include:
8189 ┌─────────────────────┬────────────────────────────┐
8191 │Value │ Name │
8192 ├─────────────────────┼────────────────────────────┤
8193 │Absoft │ Absoft Fortran │
8194 ├─────────────────────┼────────────────────────────┤
8195 │ADSP │ Analog VisualDSP++ │
8196 ├─────────────────────┼────────────────────────────┤
8197 │AppleClang │ Apple Clang │
8198 ├─────────────────────┼────────────────────────────┤
8199 │ARMCC │ ARM Compiler │
8200 ├─────────────────────┼────────────────────────────┤
8201 │ARMClang │ ARM Compiler based on │
8202 │ │ Clang │
8203 ├─────────────────────┼────────────────────────────┤
8204 │Bruce │ Bruce C Compiler │
8205 ├─────────────────────┼────────────────────────────┤
8206 │CCur │ Concurrent Fortran │
8207 ├─────────────────────┼────────────────────────────┤
8208 │Clang │ LLVM Clang │
8209 ├─────────────────────┼────────────────────────────┤
8210 │Cray │ Cray Compiler │
8211 ├─────────────────────┼────────────────────────────┤
8212 │Embarcadero, Borland │ Embarcadero │
8213 ├─────────────────────┼────────────────────────────┤
8214 │Flang │ Classic Flang Fortran Com‐ │
8215 │ │ piler │
8216 ├─────────────────────┼────────────────────────────┤
8217 │LLVMFlang │ LLVM Flang Fortran Com‐ │
8218 │ │ piler │
8219 ├─────────────────────┼────────────────────────────┤
8220 │Fujitsu │ Fujitsu HPC compiler (Trad │
8221 │ │ mode) │
8222 ├─────────────────────┼────────────────────────────┤
8223 │FujitsuClang │ Fujitsu HPC compiler │
8224 │ │ (Clang mode) │
8225 ├─────────────────────┼────────────────────────────┤
8226 │G95 │ G95 Fortran │
8227 ├─────────────────────┼────────────────────────────┤
8228 │GNU │ GNU Compiler Collection │
8229 ├─────────────────────┼────────────────────────────┤
8230 │GHS │ Green Hills Software │
8231 ├─────────────────────┼────────────────────────────┤
8232 │HP │ Hewlett-Packard Compiler │
8233 ├─────────────────────┼────────────────────────────┤
8234 │IAR │ IAR Systems │
8235 └─────────────────────┴────────────────────────────┘
8236 │Intel │ Intel Classic Compiler │
8239 ├─────────────────────┼────────────────────────────┤
8240 │IntelLLVM │ Intel LLVM-Based Compiler │
8241 ├─────────────────────┼────────────────────────────┤
8242 │LCC │ MCST Elbrus C/C++/Fortran │
8243 │ │ Compiler │
8244 ├─────────────────────┼────────────────────────────┤
8245 │MSVC │ Microsoft Visual Studio │
8246 ├─────────────────────┼────────────────────────────┤
8247 │NVHPC │ NVIDIA HPC Compiler │
8248 ├─────────────────────┼────────────────────────────┤
8249 │NVIDIA │ NVIDIA CUDA Compiler │
8250 ├─────────────────────┼────────────────────────────┤
8251 │OpenWatcom │ Open Watcom │
8252 ├─────────────────────┼────────────────────────────┤
8253 │PGI │ The Portland Group │
8254 ├─────────────────────┼────────────────────────────┤
8255 │PathScale │ PathScale │
8256 ├─────────────────────┼────────────────────────────┤
8257 │SDCC │ Small Device C Compiler │
8258 ├─────────────────────┼────────────────────────────┤
8259 │SunPro │ Oracle Solaris Studio │
8260 ├─────────────────────┼────────────────────────────┤
8261 │Tasking │ Tasking Compiler Toolsets │
8262 ├─────────────────────┼────────────────────────────┤
8263 │TI │ Texas Instruments │
8264 ├─────────────────────┼────────────────────────────┤
8265 │TinyCC │ Tiny C Compiler │
8266 ├─────────────────────┼────────────────────────────┤
8267 │XL, VisualAge, zOS │ IBM XL │
8268 ├─────────────────────┼────────────────────────────┤
8269 │XLClang │ IBM Clang-based XL │
8270 ├─────────────────────┼────────────────────────────┤
8271 │IBMClang │ IBM LLVM-based Compiler │
8272 └─────────────────────┴────────────────────────────┘
8273 This variable is not guaranteed to be defined for all compilers or lan‐
8275 guages.
8276 CMAKE_<LANG>_COMPILER_LOADED
8278 Defined to true if the language is enabled.
8279 When language <LANG> is enabled by project() or enable_language() this
8281 variable is defined to 1.
8282 CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND
8284 New in version 3.10.
8285 Command that outputs the compiler pre definitions.
8288 See AUTOMOC which uses CMAKE_CXX_COMPILER_PREDEFINES_COMMAND to gener‐
8290 ate the AUTOMOC_COMPILER_PREDEFINES.
8291 CMAKE_<LANG>_COMPILER_TARGET
8293 The target for cross-compiling, if supported.
8294 Some compiler drivers are inherently cross-compilers, such as clang and
8296 QNX qcc. These compiler drivers support a command-line argument to
8297 specify the target to cross-compile for.
8298 This variable may only be set in a toolchain file specified by the
8300 CMAKE_TOOLCHAIN_FILE variable.
8301 CMAKE_<LANG>_COMPILER_VERSION
8303 Compiler version string.
8304 Compiler version in major[.minor[.patch[.tweak]]] format. This vari‐
8306 able is not guaranteed to be defined for all compilers or languages.
8307 For example CMAKE_C_COMPILER_VERSION and CMAKE_CXX_COMPILER_VERSION
8309 might indicate the respective C and C++ compiler version.
8310 CMAKE_<LANG>_CREATE_SHARED_LIBRARY
8312 Rule variable to create a shared library.
8313 This is a rule variable that tells CMake how to create a shared library
8315 for the language <LANG>. This rule variable is a ; delimited list of
8316 commands to run to perform the linking step.
8317 CMAKE_<LANG>_CREATE_SHARED_MODULE
8319 Rule variable to create a shared module.
8320 This is a rule variable that tells CMake how to create a shared library
8322 for the language <LANG>. This rule variable is a ; delimited list of
8323 commands to run.
8324 CMAKE_<LANG>_CREATE_STATIC_LIBRARY
8326 Rule variable to create a static library.
8327 This is a rule variable that tells CMake how to create a static library
8329 for the language <LANG>.
8330 CMAKE_<LANG>_EXTENSIONS
8332 The variations are:
8333 • CMAKE_C_EXTENSIONS
8335 • CMAKE_CXX_EXTENSIONS
8337 • CMAKE_CUDA_EXTENSIONS
8339 • CMAKE_HIP_EXTENSIONS
8341 • CMAKE_OBJC_EXTENSIONS
8343 • CMAKE_OBJCXX_EXTENSIONS
8345 Default values for <LANG>_EXTENSIONS target properties if set when a
8347 target is created. For the compiler's default setting see
8348 CMAKE_<LANG>_EXTENSIONS_DEFAULT.
8349 For supported CMake versions see the respective pages.
8351 See the cmake-compile-features(7) manual for information on compile
8353 features and a list of supported compilers.
8354 CMAKE_<LANG>_EXTENSIONS_DEFAULT
8356 New in version 3.22.
8357 Compiler's default extensions mode. Used as the default for the
8360 <LANG>_EXTENSIONS target property when CMAKE_<LANG>_EXTENSIONS is not
8361 set (see CMP0128).
8362 This variable is read-only. Modifying it is undefined behavior.
8364 CMAKE_<LANG>_FLAGS
8366 Language-wide flags for language <LANG> used when building for all con‐
8367 figurations. These flags will be passed to all invocations of the com‐
8368 piler. This includes invocations that drive compiling and those that
8369 drive linking.
8370 For each language, if this variable is not defined, it is initialized
8372 and stored in the cache using values from environment variables in com‐
8373 bination with CMake's builtin defaults for the toolchain:
8374 • CMAKE_C_FLAGS: Initialized by the CFLAGS environment variable.
8376 • CMAKE_CXX_FLAGS: Initialized by the CXXFLAGS environment variable.
8378 • CMAKE_CUDA_FLAGS: Initialized by the CUDAFLAGS environment variable.
8380 • CMAKE_Fortran_FLAGS: Initialized by the FFLAGS environment variable.
8382 • CMAKE_CSharp_FLAGS: Initialized by the CSFLAGS environment variable.
8384 • CMAKE_HIP_FLAGS: Initialized by the HIPFLAGS environment variable.
8386 • CMAKE_ISPC_FLAGS: Initialized by the ISPCFLAGS environment variable.
8388 This value is a command-line string fragment. Therefore, multiple op‐
8390 tions should be separated by spaces, and options with spaces should be
8391 quoted.
8392 The flags in this variable will be passed before those in the per-con‐
8394 figuration CMAKE_<LANG>_FLAGS_<CONFIG> variable. On invocations driv‐
8395 ing compiling, flags from both variables will be passed before flags
8396 added by commands such as add_compile_options() and
8397 target_compile_options(). On invocations driving linking, they will be
8398 passed before flags added by commands such as add_link_options() and
8399 target_link_options().
8400 CMAKE_<LANG>_FLAGS_<CONFIG>
8402 Language-wide flags for language <LANG> used when building for the
8403 <CONFIG> configuration. These flags will be passed to all invocations
8404 of the compiler in the corresponding configuration. This includes in‐
8405 vocations that drive compiling and those that drive linking.
8406 The flags in this variable will be passed after those in the
8408 CMAKE_<LANG>_FLAGS variable. On invocations driving compiling, flags
8409 from both variables will be passed before flags added by commands such
8410 as add_compile_options() and target_compile_options(). On invocations
8411 driving linking, they will be passed before flags added by commands
8412 such as add_link_options() and target_link_options().
8413 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8415 New in version 3.11.
8416 Value used to initialize the CMAKE_<LANG>_FLAGS_<CONFIG> cache entry
8419 the first time a build tree is configured for language <LANG>. This
8420 variable is meant to be set by a toolchain file. CMake may prepend or
8421 append content to the value based on the environment and target plat‐
8422 form.
8423 See also CMAKE_<LANG>_FLAGS_INIT.
8425 CMAKE_<LANG>_FLAGS_DEBUG
8427 This variable is the Debug variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8428 variable.
8429 CMAKE_<LANG>_FLAGS_DEBUG_INIT
8431 New in version 3.7.
8432 This variable is the Debug variant of the
8435 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8436 CMAKE_<LANG>_FLAGS_INIT
8438 New in version 3.7.
8439 Value used to initialize the CMAKE_<LANG>_FLAGS cache entry the first
8442 time a build tree is configured for language <LANG>. This variable is
8443 meant to be set by a toolchain file. CMake may prepend or append con‐
8444 tent to the value based on the environment and target platform. For
8445 example, the contents of a xxxFLAGS environment variable will be
8446 prepended, where xxx will be language-specific but not necessarily the
8447 same as <LANG> (e.g. CXXFLAGS for CXX, FFLAGS for Fortran, and so on).
8448 This value is a command-line string fragment. Therefore, multiple op‐
8449 tions should be separated by spaces, and options with spaces should be
8450 quoted.
8451 See also the configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8453 variable.
8454 CMAKE_<LANG>_FLAGS_MINSIZEREL
8456 This variable is the MinSizeRel variant of the
8457 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8458 CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
8460 New in version 3.7.
8461 This variable is the MinSizeRel variant of the
8464 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8465 CMAKE_<LANG>_FLAGS_RELEASE
8467 This variable is the Release variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8468 variable.
8469 CMAKE_<LANG>_FLAGS_RELEASE_INIT
8471 New in version 3.7.
8472 This variable is the Release variant of the
8475 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8476 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
8478 This variable is the RelWithDebInfo variant of the
8479 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8480 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT
8482 New in version 3.7.
8483 This variable is the RelWithDebInfo variant of the
8486 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8487 CMAKE_<LANG>_IGNORE_EXTENSIONS
8489 File extensions that should be ignored by the build.
8490 This is a list of file extensions that may be part of a project for a
8492 given language but are not compiled.
8493 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
8495 Directories implicitly searched by the compiler for header files.
8496 CMake does not explicitly specify these directories on compiler command
8498 lines for language <LANG>. This prevents system include directories
8499 from being treated as user include directories on some compilers, which
8500 is important for C, CXX, and CUDA to avoid overriding standard library
8501 headers.
8502 This value is not used for Fortran because it has no standard library
8504 headers and some compilers do not search their implicit include direc‐
8505 tories for module .mod files.
8506 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8508 Implicit linker search path detected for language <LANG>.
8509 Compilers typically pass directories containing language runtime li‐
8511 braries and default library search paths when they invoke a linker.
8512 These paths are implicit linker search directories for the compiler's
8513 language.
8514 For each language enabled by the project() or enable_language() com‐
8516 mand, CMake automatically detects these directories and reports the re‐
8517 sults in this variable. The
8518 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES_EXCLUDE environment variable may
8519 be set to exclude specific directories from the automatically detected
8520 results.
8521 When linking to a static library, CMake adds the implicit link directo‐
8523 ries from this variable for each language used in the static library
8524 (except the language whose compiler is used to drive linking). In the
8525 case of an imported static library, the
8526 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8527 whose implicit link information is needed. If any of the languages is
8528 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8529 variable may instead be provided by the project. Or, a toolchain file
8530 may set the variable to a value known for the specified toolchain. It
8531 will either be overridden when the language is enabled, or used as a
8532 fallback.
8533 Some toolchains read implicit directories from an environment variable
8535 such as LIBRARY_PATH. If using such an environment variable, keep its
8536 value consistent when operating in a given build tree because CMake
8537 saves the value detected when first creating a build tree.
8538 If policy CMP0060 is not set to NEW, then when a library in one of
8540 these directories is given by full path to target_link_libraries()
8541 CMake will generate the -l<name> form on link lines for historical pur‐
8542 poses.
8543 See also the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES variable.
8545 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
8547 Implicit linker framework search path detected for language <LANG>.
8548 These paths are implicit linker framework search directories for the
8550 compiler's language. CMake automatically detects these directories for
8551 each language and reports the results in this variable.
8552 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8554 Implicit link libraries and flags detected for language <LANG>.
8555 Compilers typically pass language runtime library names and other flags
8557 when they invoke a linker. These flags are implicit link options for
8558 the compiler's language. For each language enabled by the project() or
8559 enable_language() command, CMake automatically detects these libraries
8560 and flags and reports the results in this variable.
8561 When linking to a static library, CMake adds the implicit link li‐
8563 braries and flags from this variable for each language used in the
8564 static library (except the language whose compiler is used to drive
8565 linking). In the case of an imported static library, the
8566 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8567 whose implicit link information is needed. If any of the languages is
8568 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8569 variable may instead be provided by the project. Or, a toolchain file
8570 may set the variable to a value known for the specified toolchain. It
8571 will either be overridden when the language is enabled, or used as a
8572 fallback.
8573 See also the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES variable.
8575 CMAKE_<LANG>_LIBRARY_ARCHITECTURE
8577 Target architecture library directory name detected for <LANG>.
8578 If the <LANG> compiler passes to the linker an architecture-specific
8580 system library search directory such as <prefix>/lib/<arch> this vari‐
8581 able contains the <arch> name if/as detected by CMake.
8582 CMAKE_<LANG>_LINK_EXECUTABLE
8584 Rule variable to link an executable.
8585 Rule variable to link an executable for the given language.
8587 CMAKE_<LANG>_LINKER_WRAPPER_FLAG
8589 New in version 3.13.
8590 Defines the syntax of compiler driver option to pass options to the
8593 linker tool. It will be used to translate the LINKER: prefix in the
8594 link options (see add_link_options() and target_link_options()).
8595 This variable holds a semicolon-separated list of tokens. If a space
8597 (i.e. " ") is specified as last token, flag and LINKER: arguments will
8598 be specified as separate arguments to the compiler driver. The
8599 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variable can be specified to man‐
8600 age concatenation of arguments.
8601 For example, for Clang we have:
8603 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")
8605 Specifying "LINKER:-z,defs" will be transformed in -Xlinker -z -Xlinker
8607 defs.
8608 For GNU GCC:
8610 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
8612 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8613 Specifying "LINKER:-z,defs" will be transformed in -Wl,-z,defs.
8615 And for SunPro:
8617 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
8619 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8620 Specifying "LINKER:-z,defs" will be transformed in -Qoption ld -z,defs.
8622 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
8624 New in version 3.13.
8625 This variable is used with CMAKE_<LANG>_LINKER_WRAPPER_FLAG variable to
8628 format LINKER: prefix in the link options (see add_link_options() and
8629 target_link_options()).
8630 When specified, arguments of the LINKER: prefix will be concatenated
8632 using this value as separator.
8633 CMAKE_<LANG>_OUTPUT_EXTENSION
8635 Extension for the output of a compile for a single file.
8636 This is the extension for an object file for the given <LANG>. For ex‐
8638 ample .obj for C on Windows.
8639 CMAKE_<LANG>_SIMULATE_ID
8641 Identification string of the "simulated" compiler.
8642 Some compilers simulate other compilers to serve as drop-in replace‐
8644 ments. When CMake detects such a compiler it sets this variable to
8645 what would have been the CMAKE_<LANG>_COMPILER_ID for the simulated
8646 compiler.
8647 NOTE:
8649 In other words, this variable describes the ABI compatibility of the
8650 generated code.
8651 CMAKE_<LANG>_SIMULATE_VERSION
8653 Version string of "simulated" compiler.
8654 Some compilers simulate other compilers to serve as drop-in replace‐
8656 ments. When CMake detects such a compiler it sets this variable to
8657 what would have been the CMAKE_<LANG>_COMPILER_VERSION for the simu‐
8658 lated compiler.
8659 CMAKE_<LANG>_SIZEOF_DATA_PTR
8661 Size of pointer-to-data types for language <LANG>.
8662 This holds the size (in bytes) of pointer-to-data types in the target
8664 platform ABI. It is defined for languages C and CXX (C++).
8665 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
8667 Extensions of source files for the given language.
8668 This is the list of extensions for a given language's source files.
8670 CMAKE_<LANG>_STANDARD
8672 The variations are:
8673 • CMAKE_C_STANDARD
8675 • CMAKE_CXX_STANDARD
8677 • CMAKE_CUDA_STANDARD
8679 • CMAKE_HIP_STANDARD
8681 • CMAKE_OBJC_STANDARD
8683 • CMAKE_OBJCXX_STANDARD
8685 Default values for <LANG>_STANDARD target properties if set when a tar‐
8687 get is created.
8688 For supported CMake versions see the respective pages.
8690 See the cmake-compile-features(7) manual for information on compile
8692 features and a list of supported compilers.
8693 CMAKE_<LANG>_STANDARD_DEFAULT
8695 New in version 3.9.
8696 The compiler's default standard for the language <LANG>. Empty if the
8699 compiler has no conception of standard levels.
8700 CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES
8702 New in version 3.6.
8703 Include directories to be used for every source file compiled with the
8706 <LANG> compiler. This is meant for specification of system include di‐
8707 rectories needed by the language for the current platform. The direc‐
8708 tories always appear at the end of the include path passed to the com‐
8709 piler.
8710 This variable should not be set by project code. It is meant to be set
8712 by CMake's platform information modules for the current toolchain, or
8713 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8714 See also CMAKE_<LANG>_STANDARD_LIBRARIES.
8716 CMAKE_<LANG>_STANDARD_LIBRARIES
8718 New in version 3.6.
8719 Libraries linked into every executable and shared library linked for
8722 language <LANG>. This is meant for specification of system libraries
8723 needed by the language for the current platform.
8724 This variable should not be set by project code. It is meant to be set
8726 by CMake's platform information modules for the current toolchain, or
8727 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8728 See also CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES.
8730 CMAKE_<LANG>_STANDARD_REQUIRED
8732 The variations are:
8733 • CMAKE_C_STANDARD_REQUIRED
8735 • CMAKE_CXX_STANDARD_REQUIRED
8737 • CMAKE_CUDA_STANDARD_REQUIRED
8739 • CMAKE_HIP_STANDARD_REQUIRED
8741 • CMAKE_OBJC_STANDARD_REQUIRED
8743 • CMAKE_OBJCXX_STANDARD_REQUIRED
8745 Default values for <LANG>_STANDARD_REQUIRED target properties if set
8747 when a target is created.
8748 For supported CMake versions see the respective pages.
8750 See the cmake-compile-features(7) manual for information on compile
8752 features and a list of supported compilers.
8753 CMAKE_OBJC_EXTENSIONS
8755 New in version 3.16.
8756 Default value for OBJC_EXTENSIONS target property if set when a target
8759 is created.
8760 See the cmake-compile-features(7) manual for information on compile
8762 features and a list of supported compilers.
8763 CMAKE_OBJC_STANDARD
8765 New in version 3.16.
8766 Default value for OBJC_STANDARD target property if set when a target is
8769 created.
8770 See the cmake-compile-features(7) manual for information on compile
8772 features and a list of supported compilers.
8773 CMAKE_OBJC_STANDARD_REQUIRED
8775 New in version 3.16.
8776 Default value for OBJC_STANDARD_REQUIRED target property if set when a
8779 target is created.
8780 See the cmake-compile-features(7) manual for information on compile
8782 features and a list of supported compilers.
8783 CMAKE_OBJCXX_EXTENSIONS
8785 New in version 3.16.
8786 Default value for OBJCXX_EXTENSIONS target property if set when a tar‐
8789 get is created.
8790 See the cmake-compile-features(7) manual for information on compile
8792 features and a list of supported compilers.
8793 CMAKE_OBJCXX_STANDARD
8795 New in version 3.16.
8796 Default value for OBJCXX_STANDARD target property if set when a target
8799 is created.
8800 See the cmake-compile-features(7) manual for information on compile
8802 features and a list of supported compilers.
8803 CMAKE_OBJCXX_STANDARD_REQUIRED
8805 New in version 3.16.
8806 Default value for OBJCXX_STANDARD_REQUIRED target property if set when
8809 a target is created.
8810 See the cmake-compile-features(7) manual for information on compile
8812 features and a list of supported compilers.
8813 CMAKE_Swift_LANGUAGE_VERSION
8815 New in version 3.7.
8816 Set to the Swift language version number. If not set, the oldest
8819 legacy version known to be available in the host Xcode version is as‐
8820 sumed:
8821 • Swift 4.0 for Xcode 10.2 and above.
8823 • Swift 3.0 for Xcode 8.3 and above.
8825 • Swift 2.3 for Xcode 8.2 and below.
8827 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
8829 Specify a CMake file that overrides platform information for <LANG>.
8830 This is a language-specific version of CMAKE_USER_MAKE_RULES_OVERRIDE
8832 loaded only when enabling language <LANG>.
8833
8835 CTEST_BINARY_DIRECTORY
8836 New in version 3.1.
8837 Specify the CTest BuildDirectory setting in a ctest(1) dashboard client
8840 script.
8841 CTEST_BUILD_COMMAND
8843 New in version 3.1.
8844 Specify the CTest MakeCommand setting in a ctest(1) dashboard client
8847 script.
8848 CTEST_BUILD_NAME
8850 New in version 3.1.
8851 Specify the CTest BuildName setting in a ctest(1) dashboard client
8854 script.
8855 CTEST_BZR_COMMAND
8857 New in version 3.1.
8858 Specify the CTest BZRCommand setting in a ctest(1) dashboard client
8861 script.
8862 CTEST_BZR_UPDATE_OPTIONS
8864 New in version 3.1.
8865 Specify the CTest BZRUpdateOptions setting in a ctest(1) dashboard
8868 client script.
8869 CTEST_CHANGE_ID
8871 New in version 3.4.
8872 Specify the CTest ChangeId setting in a ctest(1) dashboard client
8875 script.
8876 This setting allows CTest to pass arbitrary information about this
8878 build up to CDash. One use of this feature is to allow CDash to post
8879 comments on your pull request if anything goes wrong with your build.
8880 CTEST_CHECKOUT_COMMAND
8882 New in version 3.1.
8883 Tell the ctest_start() command how to checkout or initialize the source
8886 directory in a ctest(1) dashboard client script.
8887 CTEST_CONFIGURATION_TYPE
8889 New in version 3.1.
8890 Specify the CTest DefaultCTestConfigurationType setting in a ctest(1)
8893 dashboard client script.
8894 If the configuration type is set via -C <cfg> from the command line
8896 then this variable is populated accordingly.
8897 CTEST_CONFIGURE_COMMAND
8899 New in version 3.1.
8900 Specify the CTest ConfigureCommand setting in a ctest(1) dashboard
8903 client script.
8904 CTEST_COVERAGE_COMMAND
8906 New in version 3.1.
8907 Specify the CTest CoverageCommand setting in a ctest(1) dashboard
8910 client script.
8911 Cobertura
8913 Using Cobertura as the coverage generation within your multi-module
8914 Java project can generate a series of XML files.
8915 The Cobertura Coverage parser expects to read the coverage data from a
8917 single XML file which contains the coverage data for all modules.
8918 Cobertura has a program with the ability to merge given cobertura.ser
8919 files and then another program to generate a combined XML file from the
8920 previous merged file. For command line testing, this can be done by
8921 hand prior to CTest looking for the coverage files. For script builds,
8922 set the CTEST_COVERAGE_COMMAND variable to point to a file which will
8923 perform these same steps, such as a .sh or .bat file.
8924 set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh)
8926 where the run-coverage-and-consolidate.sh script is perhaps created by
8928 the configure_file() command and might contain the following code:
8929 #!/usr/bin/env bash
8931 CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")"
8932 SourceDirs="$(find "/path/to/source" -name "java" -type d)"
8933 cobertura-merge --datafile coberturamerge.ser $CoberturaFiles
8934 cobertura-report --datafile coberturamerge.ser --destination . \
8935 --format xml $SourceDirs
8936 The script uses find to capture the paths to all of the cobertura.ser
8938 files found below the project's source directory. It keeps the list of
8939 files and supplies it as an argument to the cobertura-merge program.
8940 The --datafile argument signifies where the result of the merge will be
8941 kept.
8942 The combined coberturamerge.ser file is then used to generate the XML
8944 report using the cobertura-report program. The call to the cober‐
8945 tura-report program requires some named arguments.
8946 --datafila
8948 path to the merged .ser file
8949 --destination
8951 path to put the output files(s)
8952 --format
8954 file format to write output in: xml or html
8955 The rest of the supplied arguments consist of the full paths to the
8957 /src/main/java directories of each module within the source tree. These
8958 directories are needed and should not be forgotten.
8959 CTEST_COVERAGE_EXTRA_FLAGS
8961 New in version 3.1.
8962 Specify the CTest CoverageExtraFlags setting in a ctest(1) dashboard
8965 client script.
8966 CTEST_CURL_OPTIONS
8968 New in version 3.1.
8969 Specify the CTest CurlOptions setting in a ctest(1) dashboard client
8972 script.
8973 CTEST_CUSTOM_COVERAGE_EXCLUDE
8975 A list of regular expressions which will be used to exclude files by
8976 their path from coverage output by the ctest_coverage() command.
8977 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8979 See ctest_read_custom_files() documentation.
8980 CTEST_CUSTOM_ERROR_EXCEPTION
8982 A list of regular expressions which will be used to exclude when de‐
8983 tecting error messages in build outputs by the ctest_build() command.
8984 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8986 See ctest_read_custom_files() documentation.
8987 CTEST_CUSTOM_ERROR_MATCH
8989 A list of regular expressions which will be used to detect error mes‐
8990 sages in build outputs by the ctest_build() command.
8991 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8993 See ctest_read_custom_files() documentation.
8994 CTEST_CUSTOM_ERROR_POST_CONTEXT
8996 The number of lines to include as context which follow an error message
8997 by the ctest_build() command. The default is 10.
8998 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9000 See ctest_read_custom_files() documentation.
9001 CTEST_CUSTOM_ERROR_PRE_CONTEXT
9003 The number of lines to include as context which precede an error mes‐
9004 sage by the ctest_build() command. The default is 10.
9005 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9007 See ctest_read_custom_files() documentation.
9008 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
9010 When saving a failing test's output, this is the maximum size, in
9011 bytes, that will be collected by the ctest_test() command. Defaults to
9012 307200 (300 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
9013 truncation modes.
9014 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
9016 output will not be truncated and may exceed the maximum size.
9017 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9019 See ctest_read_custom_files() documentation.
9020 For controlling the output collection of passing tests, see
9022 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.
9023 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
9025 The maximum number of errors in a single build step which will be de‐
9026 tected. After this, the ctest_test() command will truncate the output.
9027 Defaults to 50.
9028 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9030 See ctest_read_custom_files() documentation.
9031 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
9033 The maximum number of warnings in a single build step which will be de‐
9034 tected. After this, the ctest_test() command will truncate the output.
9035 Defaults to 50.
9036 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9038 See ctest_read_custom_files() documentation.
9039 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
9041 When saving a passing test's output, this is the maximum size, in
9042 bytes, that will be collected by the ctest_test() command. Defaults to
9043 1024 (1 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
9044 truncation modes.
9045 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
9047 output will not be truncated and may exceed the maximum size.
9048 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9050 See ctest_read_custom_files() documentation.
9051 For controlling the output collection of failing tests, see
9053 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.
9054 CTEST_CUSTOM_MEMCHECK_IGNORE
9056 A list of regular expressions to use to exclude tests during the
9057 ctest_memcheck() command.
9058 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9060 See ctest_read_custom_files() documentation.
9061 CTEST_CUSTOM_POST_MEMCHECK
9063 A list of commands to run at the end of the ctest_memcheck() command.
9064 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9066 See ctest_read_custom_files() documentation.
9067 CTEST_CUSTOM_POST_TEST
9069 A list of commands to run at the end of the ctest_test() command.
9070 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9072 See ctest_read_custom_files() documentation.
9073 CTEST_CUSTOM_PRE_MEMCHECK
9075 A list of commands to run at the start of the ctest_memcheck() command.
9076 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9078 See ctest_read_custom_files() documentation.
9079 CTEST_CUSTOM_PRE_TEST
9081 A list of commands to run at the start of the ctest_test() command.
9082 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9084 See ctest_read_custom_files() documentation.
9085 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
9087 New in version 3.24.
9088 Set the test output truncation mode in case a maximum size is config‐
9091 ured via the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE or
9092 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables. By default the
9093 tail of the output will be truncated. Other possible values are middle
9094 and head.
9095 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9097 See ctest_read_custom_files() documentation.
9098 CTEST_CUSTOM_TESTS_IGNORE
9100 A list of test names to be excluded from the set of tests run by the
9101 ctest_test() command.
9102 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9104 See ctest_read_custom_files() documentation.
9105 CTEST_CUSTOM_WARNING_EXCEPTION
9107 A list of regular expressions which will be used to exclude when de‐
9108 tecting warning messages in build outputs by the ctest_build() command.
9109 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9111 See ctest_read_custom_files() documentation.
9112 CTEST_CUSTOM_WARNING_MATCH
9114 A list of regular expressions which will be used to detect warning mes‐
9115 sages in build outputs by the ctest_build() command.
9116 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9118 See ctest_read_custom_files() documentation.
9119 CTEST_CVS_CHECKOUT
9121 New in version 3.1.
9122 Deprecated. Use CTEST_CHECKOUT_COMMAND instead.
9125 CTEST_CVS_COMMAND
9127 New in version 3.1.
9128 Specify the CTest CVSCommand setting in a ctest(1) dashboard client
9131 script.
9132 CTEST_CVS_UPDATE_OPTIONS
9134 New in version 3.1.
9135 Specify the CTest CVSUpdateOptions setting in a ctest(1) dashboard
9138 client script.
9139 CTEST_DROP_LOCATION
9141 New in version 3.1.
9142 Specify the CTest DropLocation setting in a ctest(1) dashboard client
9145 script.
9146 CTEST_DROP_METHOD
9148 New in version 3.1.
9149 Specify the CTest DropMethod setting in a ctest(1) dashboard client
9152 script.
9153 CTEST_DROP_SITE
9155 New in version 3.1.
9156 Specify the CTest DropSite setting in a ctest(1) dashboard client
9159 script.
9160 CTEST_DROP_SITE_CDASH
9162 New in version 3.1.
9163 Specify the CTest IsCDash setting in a ctest(1) dashboard client
9166 script.
9167 CTEST_DROP_SITE_PASSWORD
9169 New in version 3.1.
9170 Specify the CTest DropSitePassword setting in a ctest(1) dashboard
9173 client script.
9174 CTEST_DROP_SITE_USER
9176 New in version 3.1.
9177 Specify the CTest DropSiteUser setting in a ctest(1) dashboard client
9180 script.
9181 CTEST_EXTRA_COVERAGE_GLOB
9183 New in version 3.4.
9184 A list of regular expressions which will be used to find files which
9187 should be covered by the ctest_coverage() command.
9188 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9190 See ctest_read_custom_files() documentation.
9191 CTEST_GIT_COMMAND
9193 New in version 3.1.
9194 Specify the CTest GITCommand setting in a ctest(1) dashboard client
9197 script.
9198 CTEST_GIT_INIT_SUBMODULES
9200 New in version 3.6.
9201 Specify the CTest GITInitSubmodules setting in a ctest(1) dashboard
9204 client script.
9205 CTEST_GIT_UPDATE_CUSTOM
9207 New in version 3.1.
9208 Specify the CTest GITUpdateCustom setting in a ctest(1) dashboard
9211 client script.
9212 CTEST_GIT_UPDATE_OPTIONS
9214 New in version 3.1.
9215 Specify the CTest GITUpdateOptions setting in a ctest(1) dashboard
9218 client script.
9219 CTEST_HG_COMMAND
9221 New in version 3.1.
9222 Specify the CTest HGCommand setting in a ctest(1) dashboard client
9225 script.
9226 CTEST_HG_UPDATE_OPTIONS
9228 New in version 3.1.
9229 Specify the CTest HGUpdateOptions setting in a ctest(1) dashboard
9232 client script.
9233 CTEST_LABELS_FOR_SUBPROJECTS
9235 New in version 3.10.
9236 Specify the CTest LabelsForSubprojects setting in a ctest(1) dashboard
9239 client script.
9240 CTEST_MEMORYCHECK_COMMAND
9242 New in version 3.1.
9243 Specify the CTest MemoryCheckCommand setting in a ctest(1) dashboard
9246 client script.
9247 CTEST_MEMORYCHECK_COMMAND_OPTIONS
9249 New in version 3.1.
9250 Specify the CTest MemoryCheckCommandOptions setting in a ctest(1) dash‐
9253 board client script.
9254 CTEST_MEMORYCHECK_SANITIZER_OPTIONS
9256 New in version 3.1.
9257 Specify the CTest MemoryCheckSanitizerOptions setting in a ctest(1)
9260 dashboard client script.
9261 CTest prepends correct sanitizer options *_OPTIONS environment variable
9263 to executed command. CTests adds its own log_path to sanitizer options,
9264 don't provide your own log_path.
9265 CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
9267 New in version 3.1.
9268 Specify the CTest MemoryCheckSuppressionFile setting in a ctest(1)
9271 dashboard client script.
9272 CTEST_MEMORYCHECK_TYPE
9274 New in version 3.1.
9275 Specify the CTest MemoryCheckType setting in a ctest(1) dashboard
9278 client script. Valid values are Valgrind, Purify, BoundsChecker,
9279 DrMemory, CudaSanitizer, ThreadSanitizer, AddressSanitizer, LeakSani‐
9280 tizer, MemorySanitizer and UndefinedBehaviorSanitizer.
9281 CTEST_NIGHTLY_START_TIME
9283 New in version 3.1.
9284 Specify the CTest NightlyStartTime setting in a ctest(1) dashboard
9287 client script.
9288 Note that this variable must always be set for a nightly build in a
9290 dashboard script. It is needed so that nightly builds can be properly
9291 grouped together in CDash.
9292 CTEST_P4_CLIENT
9294 New in version 3.1.
9295 Specify the CTest P4Client setting in a ctest(1) dashboard client
9298 script.
9299 CTEST_P4_COMMAND
9301 New in version 3.1.
9302 Specify the CTest P4Command setting in a ctest(1) dashboard client
9305 script.
9306 CTEST_P4_OPTIONS
9308 New in version 3.1.
9309 Specify the CTest P4Options setting in a ctest(1) dashboard client
9312 script.
9313 CTEST_P4_UPDATE_OPTIONS
9315 New in version 3.1.
9316 Specify the CTest P4UpdateOptions setting in a ctest(1) dashboard
9319 client script.
9320 CTEST_RESOURCE_SPEC_FILE
9322 New in version 3.18.
9323 Specify the CTest ResourceSpecFile setting in a ctest(1) dashboard
9326 client script.
9327 This can also be used to specify the resource spec file from a CMake
9329 build. If no RESOURCE_SPEC_FILE is passed to ctest_test(), and
9330 CTEST_RESOURCE_SPEC_FILE is not specified in the dashboard script, the
9331 value of this variable from the build is used.
9332 CTEST_RUN_CURRENT_SCRIPT
9334 New in version 3.11.
9335 Setting this to 0 prevents ctest(1) from being run again when it
9338 reaches the end of a script run by calling ctest -S.
9339 CTEST_SCP_COMMAND
9341 New in version 3.1.
9342 Legacy option. Not used.
9345 CTEST_SCRIPT_DIRECTORY
9347 The directory containing the top-level CTest script. The concept is
9348 similar to CMAKE_SOURCE_DIR.
9349 CTEST_SITE
9351 New in version 3.1.
9352 Specify the CTest Site setting in a ctest(1) dashboard client script.
9355 CTEST_SOURCE_DIRECTORY
9357 New in version 3.1.
9358 Specify the CTest SourceDirectory setting in a ctest(1) dashboard
9361 client script.
9362 CTEST_SUBMIT_INACTIVITY_TIMEOUT
9364 New in version 3.23.
9365 Specify the CTest SubmitInactivityTimeout setting in a ctest(1) dash‐
9368 board client script.
9369 CTEST_SUBMIT_URL
9371 New in version 3.14.
9372 Specify the CTest SubmitURL setting in a ctest(1) dashboard client
9375 script.
9376 CTEST_SVN_COMMAND
9378 New in version 3.1.
9379 Specify the CTest SVNCommand setting in a ctest(1) dashboard client
9382 script.
9383 CTEST_SVN_OPTIONS
9385 New in version 3.1.
9386 Specify the CTest SVNOptions setting in a ctest(1) dashboard client
9389 script.
9390 CTEST_SVN_UPDATE_OPTIONS
9392 New in version 3.1.
9393 Specify the CTest SVNUpdateOptions setting in a ctest(1) dashboard
9396 client script.
9397 CTEST_TEST_LOAD
9399 New in version 3.4.
9400 Specify the TestLoad setting in the CTest Test Step of a ctest(1) dash‐
9403 board client script. This sets the default value for the TEST_LOAD op‐
9404 tion of the ctest_test() command.
9405 CTEST_TEST_TIMEOUT
9407 New in version 3.1.
9408 Specify the CTest TimeOut setting in a ctest(1) dashboard client
9411 script.
9412 CTEST_TRIGGER_SITE
9414 New in version 3.1.
9415 Legacy option. Not used.
9418 CTEST_UPDATE_COMMAND
9420 New in version 3.1.
9421 Specify the CTest UpdateCommand setting in a ctest(1) dashboard client
9424 script.
9425 CTEST_UPDATE_OPTIONS
9427 New in version 3.1.
9428 Specify the CTest UpdateOptions setting in a ctest(1) dashboard client
9431 script.
9432 CTEST_UPDATE_VERSION_ONLY
9434 New in version 3.1.
9435 Specify the CTest UpdateVersionOnly setting in a ctest(1) dashboard
9438 client script.
9439 CTEST_UPDATE_VERSION_OVERRIDE
9441 New in version 3.15.
9442 Specify the CTest UpdateVersionOverride setting in a ctest(1) dashboard
9445 client script.
9446 CTEST_USE_LAUNCHERS
9448 New in version 3.1.
9449 Specify the CTest UseLaunchers setting in a ctest(1) dashboard client
9452 script.
9453
9455 CPACK_ABSOLUTE_DESTINATION_FILES
9456 List of files which have been installed using an ABSOLUTE DESTINATION
9457 path.
9458 This variable is a Read-Only variable which is set internally by CPack
9460 during installation and before packaging using
9461 CMAKE_ABSOLUTE_DESTINATION_FILES defined in cmake_install.cmake
9462 scripts. The value can be used within CPack project configuration file
9463 and/or CPack<GEN>.cmake file of <GEN> generator.
9464 CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9466 Boolean toggle to include/exclude top level directory (component case).
9467 Similar usage as CPACK_INCLUDE_TOPLEVEL_DIRECTORY but for the component
9469 case. See CPACK_INCLUDE_TOPLEVEL_DIRECTORY documentation for the de‐
9470 tail.
9471 CPACK_CUSTOM_INSTALL_VARIABLES
9473 New in version 3.21.
9474 CPack variables (set via e.g. cpack -D, CPackConfig.cmake or
9477 CPACK_PROJECT_CONFIG_FILE scripts) are not directly visible in instal‐
9478 lation scripts. Instead, one can pass a list of varName=value pairs in
9479 the CPACK_CUSTOM_INSTALL_VARIABLES variable. At install time, each
9480 list item will result in a variable of the specified name (varName) be‐
9481 ing set to the given value. The = can be omitted for an empty value.
9482 CPACK_CUSTOM_INSTALL_VARIABLES allows the packaging installation to be
9484 influenced by the user or driving script at CPack runtime without hav‐
9485 ing to regenerate the install scripts.
9486 Example
9488 install(FILES large.txt DESTINATION data)
9489 install(CODE [[
9491 if(ENABLE_COMPRESSION)
9492 # "run-compressor" is a fictional tool that produces
9493 # large.txt.xz from large.txt and then removes the input file
9494 execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt)
9495 endif()
9496 ]])
9497 With the above example snippet, cpack will by default run the installa‐
9499 tion script with ENABLE_COMPRESSION unset, resulting in a package con‐
9500 taining the uncompressed large.txt. This can be overridden when invok‐
9501 ing cpack like so:
9502 cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE"
9504 The installation script will then run with ENABLE_COMPRESSION set to
9506 TRUE, resulting in a package containing the compressed large.txt.xz in‐
9507 stead.
9508 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
9510 Ask CPack to error out as soon as a file with absolute INSTALL DESTINA‐
9511 TION is encountered.
9512 The fatal error is emitted before the installation of the offending
9514 file takes place. Some CPack generators, like NSIS, enforce this in‐
9515 ternally. This variable triggers the definition of
9516 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs.
9517 CPACK_INCLUDE_TOPLEVEL_DIRECTORY
9519 Boolean toggle to include/exclude top level directory.
9520 When preparing a package CPack installs the item under the so-called
9522 top level directory. The purpose of is to include (set to 1 or ON or
9523 TRUE) the top level directory in the package or not (set to 0 or OFF or
9524 FALSE).
9525 Each CPack generator has a built-in default value for this variable.
9527 E.g. Archive generators (ZIP, TGZ, ...) includes the top level whereas
9528 RPM or DEB don't. The user may override the default value by setting
9529 this variable.
9530 There is a similar variable CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9532 which may be used to override the behavior for the component packaging
9533 case which may have different default value for historical (now back‐
9534 ward compatibility) reason.
9535 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
9537 New in version 3.11.
9538 Default permissions for implicitly created directories during packag‐
9541 ing.
9542 This variable serves the same purpose during packaging as the
9544 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable serves during in‐
9545 stallation (e.g. make install).
9546 If include(CPack) is used then by default this variable is set to the
9548 content of CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.
9549 CPACK_PACKAGING_INSTALL_PREFIX
9551 The prefix used in the built package.
9552 Each CPack generator has a default value (like /usr). This default
9554 value may be overwritten from the CMakeLists.txt or the cpack(1) com‐
9555 mand line by setting an alternative value. Example:
9556 set(CPACK_PACKAGING_INSTALL_PREFIX "/opt")
9558 This is not the same purpose as CMAKE_INSTALL_PREFIX which is used when
9560 installing from the build tree without building a package.
9561 CPACK_SET_DESTDIR
9563 Boolean toggle to make CPack use DESTDIR mechanism when packaging.
9564 DESTDIR means DESTination DIRectory. It is commonly used by makefile
9566 users in order to install software at non-default location. It is a
9567 basic relocation mechanism that should not be used on Windows (see
9568 CMAKE_INSTALL_PREFIX documentation). It is usually invoked like this:
9569 make DESTDIR=/home/john install
9571 which will install the concerned software using the installation pre‐
9573 fix, e.g. /usr/local prepended with the DESTDIR value which finally
9574 gives /home/john/usr/local. When preparing a package, CPack first in‐
9575 stalls the items to be packaged in a local (to the build tree) direc‐
9576 tory by using the same DESTDIR mechanism. Nevertheless, if
9577 CPACK_SET_DESTDIR is set then CPack will set DESTDIR before doing the
9578 local install. The most noticeable difference is that without
9579 CPACK_SET_DESTDIR, CPack uses CPACK_PACKAGING_INSTALL_PREFIX as a pre‐
9580 fix whereas with CPACK_SET_DESTDIR set, CPack will use
9581 CMAKE_INSTALL_PREFIX as a prefix.
9582 Manually setting CPACK_SET_DESTDIR may help (or simply be necessary) if
9584 some install rules uses absolute DESTINATION (see CMake install() com‐
9585 mand). However, starting with CPack/CMake 2.8.3 RPM and DEB installers
9586 tries to handle DESTDIR automatically so that it is seldom necessary
9587 for the user to set it.
9588 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
9590 Ask CPack to warn each time a file with absolute INSTALL DESTINATION is
9591 encountered.
9592 This variable triggers the definition of
9594 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs cmake_in‐
9595 stall.cmake scripts.
9596
9598 CACHE
9599 New in version 3.13.
9600 Operator to read cache variables.
9603 Use the syntax $CACHE{VAR} to read cache entry VAR. See the
9605 cmake-language(7) variables documentation for more complete documenta‐
9606 tion of the interaction of normal variables and cache entries.
9607 When evaluating Variable References of the form ${VAR}, CMake first
9609 searches for a normal variable with that name, and if not found CMake
9610 will search for a cache entry with that name. The $CACHE{VAR} syntax
9611 can be used to do direct cache lookup and ignore any existing normal
9612 variable.
9613 See the set() and unset() commands to see how to write or remove cache
9615 variables.
9616 ENV
9618 Operator to read environment variables.
9619 Use the syntax $ENV{VAR} to read environment variable VAR.
9621 To test whether an environment variable is defined, use the signature
9623 if(DEFINED ENV{<name>}) of the if() command.
9624 For general information on environment variables, see the Environment
9626 Variables section in the cmake-language(7) manual.
9627
9629 CMake has many internal variables. Most of them are undocumented.
9630 Some of them, however, were at some point described as normal vari‐
9631 ables, and therefore may be encountered in legacy code. They are sub‐
9632 ject to change, and not recommended for use in project code.
9633 CMAKE_HOME_DIRECTORY
9635 Path to top of source tree. Same as CMAKE_SOURCE_DIR.
9636 This is an internal cache entry used to locate the source directory
9638 when loading a CMakeCache.txt from a build tree. It should not be used
9639 in project code. The variable CMAKE_SOURCE_DIR has the same value and
9640 should be preferred.
9641 CMAKE_INTERNAL_PLATFORM_ABI
9643 An internal variable subject to change.
9644 This is used in determining the compiler ABI and is subject to change.
9646 CMAKE_<LANG>_COMPILER_ABI
9648 An internal variable subject to change.
9649 This is used in determining the compiler ABI and is subject to change.
9651 CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID
9653 New in version 3.10.
9654 An internal variable subject to change.
9657 This is used to identify the variant of a compiler based on its target
9659 architecture. For some compilers this is needed to determine the cor‐
9660 rect usage.
9661 CMAKE_<LANG>_COMPILER_VERSION_INTERNAL
9663 New in version 3.10.
9664 An internal variable subject to change.
9667 This is used to identify the variant of a compiler based on an internal
9669 version number. For some compilers this is needed to determine the
9670 correct usage.
9671 CMAKE_<LANG>_LINKER_PREFERENCE
9673 An internal variable subject to change.
9674 Preference value for linker language selection.
9676 The "linker language" for executable, shared library, and module tar‐
9678 gets is the language whose compiler will invoke the linker. The
9679 LINKER_LANGUAGE target property sets the language explicitly. Other‐
9680 wise, the linker language is that whose linker preference value is
9681 highest among languages compiled and linked into the target. See also
9682 the CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES variable.
9683 CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
9685 An internal variable subject to change.
9686 True if CMAKE_<LANG>_LINKER_PREFERENCE propagates across targets.
9688 This is used when CMake selects a linker language for a target. Lan‐
9690 guages compiled directly into the target are always considered. A lan‐
9691 guage compiled into static libraries linked by the target is considered
9692 if this variable is true.
9693 CMAKE_<LANG>_PLATFORM_ID
9695 An internal variable subject to change.
9696 This is used in determining the platform and is subject to change.
9698 CMAKE_NOT_USING_CONFIG_FLAGS
9700 Skip _BUILD_TYPE flags if true.
9701 This is an internal flag used by the generators in CMake to tell CMake
9703 to skip the _BUILD_TYPE flags.
9704 CMAKE_VS_INTEL_Fortran_PROJECT_VERSION
9706 When generating for Visual Studio 9 2008 or greater with the Intel For‐
9707 tran plugin installed, this specifies the .vfproj project file format
9708 version. This is intended for internal use by CMake and should not be
9709 used by project code.
9710
9712 2000-2023 Kitware, Inc. and Contributors
97133.27.7 Oct 07, 2023 CMAKE-VARIABLES(7)