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
51 CMAKE_BINARY_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 Intended to indicate whether CMake is cross compiling, but note limita‐
148 tions 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 it will
154 otherwise be given the same value as CMAKE_HOST_SYSTEM_NAME if not man‐
155 ually set, which is correct for the non-cross-compiling case. In the
156 event that CMAKE_SYSTEM_NAME is manually set to the same value as
157 CMAKE_HOST_SYSTEM_NAME, then CMAKE_CROSSCOMPILING will still be set to
158 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 when not using an "extra" generator for an IDE.
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 The extra generator used to build the project. See
439 cmake-generators(7).
440 When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime genera‐
442 tors, CMake generates Makefiles (CMAKE_GENERATOR) and additionally
443 project files for the respective IDE. This IDE project file generator
444 is stored in CMAKE_EXTRA_GENERATOR (e.g. Eclipse CDT4).
445 CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
447 Additional suffixes for shared libraries.
448 Extensions for shared libraries other than that specified by
450 CMAKE_SHARED_LIBRARY_SUFFIX, if any. CMake uses this to recognize ex‐
451 ternal shared library files during analysis of libraries linked by a
452 target.
453 CMAKE_FIND_DEBUG_MODE
455 New in version 3.17.
456 Print extra find call information for the following commands to stan‐
459 dard error:
460 • find_program()
462 • find_library()
464 • find_file()
466 • find_path()
468 • find_package()
470 Output is designed for human consumption and not for parsing. Enabling
472 this variable is equivalent to using cmake --debug-find with the added
473 ability to enable debugging for a subset of find calls.
474 set(CMAKE_FIND_DEBUG_MODE TRUE)
476 find_program(...)
477 set(CMAKE_FIND_DEBUG_MODE FALSE)
478 Default is unset.
480 CMAKE_FIND_PACKAGE_NAME
482 New in version 3.1.1.
483 Defined by the find_package() command while loading a find module to
486 record the caller-specified package name. See command documentation
487 for details.
488 CMAKE_FIND_PACKAGE_REDIRECTS_DIR
490 New in version 3.24.
491 This read-only variable specifies a directory that the find_package()
494 command will check first before searching anywhere else for a module or
495 config package file. A config package file in this directory will al‐
496 ways be found in preference to any other Find module file or config
497 package file.
498 The primary purpose of this variable is to facilitate integration be‐
500 tween find_package() and FetchContent_MakeAvailable(). The latter com‐
501 mand may create files in the CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory
502 when it populates a dependency. This allows subsequent calls to
503 find_package() for the same dependency to re-use the populated contents
504 instead of trying to satisfy the dependency from somewhere external to
505 the build. Projects may also want to write files into this directory
506 in some situations (see Integrating With find_package() for examples).
507 The directory that CMAKE_FIND_PACKAGE_REDIRECTS_DIR points to will al‐
509 ways be erased and recreated empty at the start of every CMake run.
510 Any files written into this directory during the CMake run will be lost
511 the next time CMake configures the project.
512 CMAKE_FIND_PACKAGE_REDIRECTS_DIR is only set in CMake project mode. It
514 is not set when CMake is run in script mode (i.e. cmake -P).
515 CMAKE_FIND_PACKAGE_SORT_DIRECTION
517 New in version 3.7.
518 The sorting direction used by CMAKE_FIND_PACKAGE_SORT_ORDER. It can
521 assume one of the following values:
522 DEC Default. Ordering is done in descending mode. The highest
524 folder found will be tested first.
525 ASC Ordering is done in ascending mode. The lowest folder found
527 will be tested first.
528 If CMAKE_FIND_PACKAGE_SORT_ORDER is not set or is set to NONE this
530 variable has no effect.
531 CMAKE_FIND_PACKAGE_SORT_ORDER
533 New in version 3.7.
534 The default order for sorting packages found using find_package(). It
537 can assume one of the following values:
538 NONE Default. No attempt is done to sort packages. The first valid
540 package found will be selected.
541 NAME Sort packages lexicographically before selecting one.
543 NATURAL
545 Sort packages using natural order (see strverscmp(3) manual),
546 i.e. such that contiguous digits are compared as whole numbers.
547 Natural sorting can be employed to return the highest version when mul‐
549 tiple versions of the same library are found by find_package(). For
550 example suppose that the following libraries have been found:
551 • libX-1.1.0
553 • libX-1.2.9
555 • libX-1.2.10
557 By setting NATURAL order we can select the one with the highest version
559 number libX-1.2.10.
560 set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
562 find_package(libX CONFIG)
563 The sort direction can be controlled using the
565 CMAKE_FIND_PACKAGE_SORT_DIRECTION variable (by default decrescent, e.g.
566 lib-B will be tested before lib-A).
567 CMAKE_GENERATOR
569 The generator used to build the project. See cmake-generators(7).
570 The name of the generator that is being used to generate the build
572 files. (e.g. Unix Makefiles, Ninja, etc.)
573 The value of this variable should never be modified by project code. A
575 generator may be selected via the cmake -G option, interactively in
576 cmake-gui(1), or via the CMAKE_GENERATOR environment variable.
577 CMAKE_GENERATOR_INSTANCE
579 New in version 3.11.
580 Generator-specific instance specification provided by user.
583 Some CMake generators support selection of an instance of the native
585 build system when multiple instances are available. If the user speci‐
586 fies an instance (e.g. by setting this cache entry or via the
587 CMAKE_GENERATOR_INSTANCE environment variable), or after a default in‐
588 stance is chosen when a build tree is first configured, the value will
589 be available in this variable.
590 The value of this variable should never be modified by project code. A
592 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
593 tialize CMAKE_GENERATOR_INSTANCE as a cache entry. Once a given build
594 tree has been initialized with a particular value for this variable,
595 changing the value has undefined behavior.
596 Instance specification is supported only on specific generators.
598 Visual Studio Instance Selection
600 Visual Studio Generators support instance specification for Visual Stu‐
601 dio 2017 and above. The CMAKE_GENERATOR_INSTANCE variable may be set
602 as a cache entry selecting an instance of Visual Studio via one of the
603 following forms:
604 • location
606 • location[,key=value]*
608 • key=value[,key=value]*
610 The location specifies the absolute path to the top-level directory of
612 the VS installation.
613 The key=value pairs form a comma-separated list of options to specify
615 details of the instance selection. Supported pairs are:
616 version=<major>.<minor>.<date>.<build>
618 New in version 3.23.
619 Specify the 4-component VS Build Version, a.k.a. Build Number.
622 The components are:
623 <major>.<minor>
625 The VS major and minor version numbers. These are the same
626 as the release version numbers.
627 <date>
629 A build date in the format MMMDD, where MMM is a month index
630 since an epoch used by Microsoft, and DD is a day in that
631 month.
632 <build>
634 A build index on the day represented by <date>.
635 The build number is reported by vswhere as installationVersion.
637 For example, VS 16.11.10 has build number 16.11.32126.315.
638 New in version 3.23: A portable VS instance, which is not known to the
640 Visual Studio Installer, may be specified by providing both location
641 and version=.
642 If the value of CMAKE_GENERATOR_INSTANCE is not specified explicitly by
645 the user or a toolchain file, CMake queries the Visual Studio Installer
646 to locate VS instances, chooses one, and sets the variable as a cache
647 entry to hold the value persistently. If an environment variable of
648 the form VS##0COMNTOOLS, where ## the Visual Studio major version num‐
649 ber, is set and points to the Common7/Tools directory within one of the
650 VS instances, that instance will be used. Otherwise, if more than one
651 VS instance is installed we do not define which one is chosen by de‐
652 fault.
653 CMAKE_GENERATOR_PLATFORM
655 New in version 3.1.
656 Generator-specific target platform specification provided by user.
659 Some CMake generators support a target platform name to be given to the
661 native build system to choose a compiler toolchain. If the user speci‐
662 fies a platform name (e.g. via the cmake -A option or via the
663 CMAKE_GENERATOR_PLATFORM environment variable) the value will be avail‐
664 able in this variable.
665 The value of this variable should never be modified by project code. A
667 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
668 tialize CMAKE_GENERATOR_PLATFORM. Once a given build tree has been
669 initialized with a particular value for this variable, changing the
670 value has undefined behavior.
671 Platform specification is supported only on specific generators:
673 • For Visual Studio Generators with VS 2005 and above this specifies
675 the target architecture.
676 • For Green Hills MULTI this specifies the target architecture.
678 See native build system documentation for allowed platform names.
680 Visual Studio Platform Selection
682 On Visual Studio Generators the selected platform name is provided in
683 the CMAKE_VS_PLATFORM_NAME variable.
684 CMAKE_GENERATOR_TOOLSET
686 Native build system toolset specification provided by user.
687 Some CMake generators support a toolset specification to tell the na‐
689 tive build system how to choose a compiler. If the user specifies a
690 toolset (e.g. via the cmake -T option or via the
691 CMAKE_GENERATOR_TOOLSET environment variable) the value will be avail‐
692 able in this variable.
693 The value of this variable should never be modified by project code. A
695 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
696 tialize CMAKE_GENERATOR_TOOLSET. Once a given build tree has been ini‐
697 tialized with a particular value for this variable, changing the value
698 has undefined behavior.
699 Toolset specification is supported only on specific generators:
701 • Visual Studio Generators for VS 2010 and above
703 • The Xcode generator for Xcode 3.0 and above
705 • The Green Hills MULTI generator
707 See native build system documentation for allowed toolset names.
709 Visual Studio Toolset Selection
711 The Visual Studio Generators support toolset specification using one of
712 these forms:
713 • toolset
715 • toolset[,key=value]*
717 • key=value[,key=value]*
719 The toolset specifies the toolset name. The selected toolset name is
721 provided in the CMAKE_VS_PLATFORM_TOOLSET variable.
722 The key=value pairs form a comma-separated list of options to specify
724 generator-specific details of the toolset selection. Supported pairs
725 are:
726 cuda=<version>|<path>
728 Specify the CUDA toolkit version to use or the path to a stand‐
729 alone CUDA toolkit directory. Supported by VS 2010 and above.
730 The version can only be used with the CUDA toolkit VS integra‐
731 tion globally installed. See the CMAKE_VS_PLATFORM_TOOLSET_CUDA
732 and CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR variables.
733 host=<arch>
735 Specify the host tools architecture as x64 or x86. Supported by
736 VS 2013 and above. See the
737 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE variable.
738 version=<version>
740 Specify the toolset version to use. Supported by VS 2017 and
741 above with the specified toolset installed. See the
742 CMAKE_VS_PLATFORM_TOOLSET_VERSION variable.
743 VCTargetsPath=<path>
745 Specify an alternative VCTargetsPath value for Visual Studio
746 project files. This allows use of VS platform extension config‐
747 uration files (.props and .targets) that are not installed with
748 VS.
749 Visual Studio Toolset Customization
751 These are unstable interfaces with no compatibility guarantees because
752 they hook into undocumented internal CMake implementation details. In‐
753 stitutions may use these to internally maintain support for non-public
754 Visual Studio platforms and toolsets, but must accept responsibility to
755 make updates as changes are made to CMake.
756 Additional key=value pairs are available:
758 customFlagTableDir=<path>
760 New in version 3.21.
761 Specify the absolute path to a directory from which to load cus‐
764 tom flag tables stored as JSON documents with file names of the
765 form <platform>_<toolset>_<tool>.json or <platform>_<tool>.json,
766 where <platform> is the CMAKE_VS_PLATFORM_NAME, <toolset> is the
767 CMAKE_VS_PLATFORM_TOOLSET, and <tool> is the tool for which the
768 flag table is meant. This naming pattern is an internal CMake
769 implementation detail. The <tool> names are undocumented. The
770 format of the .json flag table files is undocumented.
771 CMAKE_IMPORT_LIBRARY_PREFIX
773 The prefix for import libraries that you link to.
774 The prefix to use for the name of an import library if used on this
776 platform.
777 CMAKE_IMPORT_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
779 CMAKE_IMPORT_LIBRARY_SUFFIX
781 The suffix for import libraries that you link to.
782 The suffix to use for the end of an import library filename if used on
784 this platform.
785 CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
787 CMAKE_JOB_POOL_COMPILE
789 This variable is used to initialize the JOB_POOL_COMPILE property on
790 all the targets. See JOB_POOL_COMPILE for additional information.
791 CMAKE_JOB_POOL_LINK
793 This variable is used to initialize the JOB_POOL_LINK property on all
794 the targets. See JOB_POOL_LINK for additional information.
795 CMAKE_JOB_POOL_PRECOMPILE_HEADER
797 New in version 3.17.
798 This variable is used to initialize the JOB_POOL_PRECOMPILE_HEADER
801 property on all the targets. See JOB_POOL_PRECOMPILE_HEADER for addi‐
802 tional information.
803 CMAKE_JOB_POOLS
805 New in version 3.11.
806 If the JOB_POOLS global property is not set, the value of this variable
809 is used in its place. See JOB_POOLS for additional information.
810 CMAKE_<LANG>_COMPILER_AR
812 New in version 3.9.
813 A wrapper around ar adding the appropriate --plugin option for the com‐
816 piler.
817 See also CMAKE_AR.
819 CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT
821 New in version 3.14.
822 Identification string of the compiler frontend variant.
825 Some compilers have multiple, different frontends for accepting command
827 line options. (For example Clang originally only had a frontend com‐
828 patible with the GNU compiler but since its port to Windows (Clang-Cl)
829 it now also supports a frontend compatible with MSVC.) When CMake de‐
830 tects such a compiler it sets this variable to what would have been the
831 CMAKE_<LANG>_COMPILER_ID for the compiler whose frontend it resembles.
832 NOTE:
834 In other words, this variable describes what command line options
835 and language extensions the compiler frontend expects.
836 CMAKE_<LANG>_COMPILER_RANLIB
838 New in version 3.9.
839 A wrapper around ranlib adding the appropriate --plugin option for the
842 compiler.
843 See also CMAKE_RANLIB.
845 CMAKE_<LANG>_LINK_LIBRARY_SUFFIX
847 New in version 3.16.
848 Language-specific suffix for libraries that you link to.
851 The suffix to use for the end of a library filename, .lib on Windows.
853 CMAKE_LINK_LIBRARY_SUFFIX
855 The suffix for libraries that you link to.
856 The suffix to use for the end of a library filename, .lib on Windows.
858 CMAKE_LINK_SEARCH_END_STATIC
860 New in version 3.4.
861 End a link line such that static system libraries are used.
864 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
866 mine whether to use static or shared libraries for -lXXX options.
867 CMake uses these options to set the link type for libraries whose full
868 paths are not known or (in some cases) are in implicit link directories
869 for the platform. By default CMake adds an option at the end of the
870 library list (if necessary) to set the linker search type back to its
871 starting type. This property switches the final linker search type to
872 -Bstatic regardless of how it started.
873 This variable is used to initialize the target property
875 LINK_SEARCH_END_STATIC for all targets. If set, its value is also used
876 by the try_compile() command.
877 See also CMAKE_LINK_SEARCH_START_STATIC.
879 CMAKE_LINK_SEARCH_START_STATIC
881 New in version 3.4.
882 Assume the linker looks for static libraries by default.
885 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
887 mine whether to use static or shared libraries for -lXXX options.
888 CMake uses these options to set the link type for libraries whose full
889 paths are not known or (in some cases) are in implicit link directories
890 for the platform. By default the linker search type is assumed to be
891 -Bdynamic at the beginning of the library list. This property switches
892 the assumption to -Bstatic. It is intended for use when linking an ex‐
893 ecutable statically (e.g. with the GNU -static option).
894 This variable is used to initialize the target property
896 LINK_SEARCH_START_STATIC for all targets. If set, its value is also
897 used by the try_compile() command.
898 See also CMAKE_LINK_SEARCH_END_STATIC.
900 CMAKE_MAJOR_VERSION
902 First version number component of the CMAKE_VERSION variable.
903 CMAKE_MAKE_PROGRAM
905 Tool that can launch the native build system. The value may be the
906 full path to an executable or just the tool name if it is expected to
907 be in the PATH.
908 The tool selected depends on the CMAKE_GENERATOR used to configure the
910 project:
911 • The Makefile Generators set this to make, gmake, or a generator-spe‐
913 cific tool (e.g. nmake for NMake Makefiles).
914 These generators store CMAKE_MAKE_PROGRAM in the CMake cache so that
916 it may be edited by the user.
917 • The Ninja generator sets this to ninja.
919 This generator stores CMAKE_MAKE_PROGRAM in the CMake cache so that
921 it may be edited by the user.
922 • The Xcode generator sets this to xcodebuild.
924 This generator prefers to lookup the build tool at build time rather
926 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
927 This is because xcodebuild is easy to find.
928 For compatibility with versions of CMake prior to 3.2, if a user or
930 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
931 CMake will use the specified value.
932 • The Visual Studio Generators set this to the full path to MSBuild.exe
934 (VS >= 10), devenv.com (VS 7,8,9), or VCExpress.exe (VS Express 8,9).
935 (See also variables CMAKE_VS_MSBUILD_COMMAND and
936 CMAKE_VS_DEVENV_COMMAND.
937 These generators prefer to lookup the build tool at build time rather
939 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
940 This is because the tools are version-specific and can be located us‐
941 ing the Windows Registry. It is also necessary because the proper
942 build tool may depend on the project content (e.g. the Intel Fortran
943 plugin to VS 10 and 11 requires devenv.com to build its .vfproj
944 project files even though MSBuild.exe is normally preferred to sup‐
945 port the CMAKE_GENERATOR_TOOLSET).
946 For compatibility with versions of CMake prior to 3.0, if a user or
948 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
949 CMake will use the specified value if possible.
950 • The Green Hills MULTI generator sets this to the full path to
952 gbuild.exe(Windows) or gbuild(Linux) based upon the toolset being
953 used.
954 Once the generator has initialized a particular value for this vari‐
956 able, changing the value has undefined behavior.
957 The CMAKE_MAKE_PROGRAM variable is set for use by project code. The
959 value is also used by the cmake --build and ctest --build-and-test
960 tools to launch the native build process.
961 CMAKE_MATCH_COUNT
963 New in version 3.2.
964 The number of matches with the last regular expression.
967 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
969 variables with the match contents. The CMAKE_MATCH_COUNT variable
970 holds the number of match expressions when these are filled.
971 CMAKE_MATCH_<n>
973 New in version 3.9.
974 Capture group <n> matched by the last regular expression, for groups 0
977 through 9. Group 0 is the entire match. Groups 1 through 9 are the
978 subexpressions captured by () syntax.
979 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
981 variables with the match contents. The CMAKE_MATCH_COUNT variable
982 holds the number of match expressions when these are filled.
983 CMAKE_MINIMUM_REQUIRED_VERSION
985 The <min> version of CMake given to the most recent call to the
986 cmake_minimum_required(VERSION) command in the current variable scope
987 or any parent variable scope.
988 CMAKE_MINOR_VERSION
990 Second version number component of the CMAKE_VERSION variable.
991 CMAKE_NETRC
993 New in version 3.11.
994 This variable is used to initialize the NETRC option for the
997 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
998 tional information.
999 This variable is also used by the ExternalProject and FetchContent mod‐
1001 ules for internal calls to file(DOWNLOAD).
1002 The local option takes precedence over this variable.
1004 CMAKE_NETRC_FILE
1006 New in version 3.11.
1007 This variable is used to initialize the NETRC_FILE option for the
1010 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
1011 tional information.
1012 This variable is also used by the ExternalProject and FetchContent mod‐
1014 ules for internal calls to file(DOWNLOAD).
1015 The local option takes precedence over this variable.
1017 CMAKE_PARENT_LIST_FILE
1019 Full path to the CMake file that included the current one.
1020 While processing a CMake file loaded by include() or find_package()
1022 this variable contains the full path to the file including it. The top
1023 of the include stack is always the CMakeLists.txt for the current di‐
1024 rectory. See also CMAKE_CURRENT_LIST_FILE.
1025 CMAKE_PATCH_VERSION
1027 Third version number component of the CMAKE_VERSION variable.
1028 CMAKE_PROJECT_DESCRIPTION
1030 New in version 3.9.
1031 The description of the top level project.
1034 This variable holds the description of the project as specified in the
1036 top level CMakeLists.txt file by a project() command. In the event
1037 that the top level CMakeLists.txt contains multiple project() calls,
1038 the most recently called one from that top level CMakeLists.txt will
1039 determine the value that CMAKE_PROJECT_DESCRIPTION contains. For exam‐
1040 ple, consider the following top level CMakeLists.txt:
1041 cmake_minimum_required(VERSION 3.0)
1043 project(First DESCRIPTION "I am First")
1044 project(Second DESCRIPTION "I am Second")
1045 add_subdirectory(sub)
1046 project(Third DESCRIPTION "I am Third")
1047 And sub/CMakeLists.txt with the following contents:
1049 project(SubProj DESCRIPTION "I am SubProj")
1051 message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")
1052 The most recently seen project() command from the top level CMake‐
1054 Lists.txt would be project(Second ...), so this will print:
1055 CMAKE_PROJECT_DESCRIPTION = I am Second
1057 To obtain the description from the most recent call to project() in the
1059 current directory scope or above, see the PROJECT_DESCRIPTION variable.
1060 CMAKE_PROJECT_HOMEPAGE_URL
1062 New in version 3.12.
1063 The homepage URL of the top level project.
1066 This variable holds the homepage URL of the project as specified in the
1068 top level CMakeLists.txt file by a project() command. In the event
1069 that the top level CMakeLists.txt contains multiple project() calls,
1070 the most recently called one from that top level CMakeLists.txt will
1071 determine the value that CMAKE_PROJECT_HOMEPAGE_URL contains. For ex‐
1072 ample, consider the following top level CMakeLists.txt:
1073 cmake_minimum_required(VERSION 3.0)
1075 project(First HOMEPAGE_URL "http://first.example.com")
1076 project(Second HOMEPAGE_URL "http://second.example.com")
1077 add_subdirectory(sub)
1078 project(Third HOMEPAGE_URL "http://third.example.com")
1079 And sub/CMakeLists.txt with the following contents:
1081 project(SubProj HOMEPAGE_URL "http://subproj.example.com")
1083 message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}")
1084 The most recently seen project() command from the top level CMake‐
1086 Lists.txt would be project(Second ...), so this will print:
1087 CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com
1089 To obtain the homepage URL from the most recent call to project() in
1091 the current directory scope or above, see the PROJECT_HOMEPAGE_URL
1092 variable.
1093 CMAKE_PROJECT_NAME
1095 The name of the top level project.
1096 This variable holds the name of the project as specified in the top
1098 level CMakeLists.txt file by a project() command. In the event that
1099 the top level CMakeLists.txt contains multiple project() calls, the
1100 most recently called one from that top level CMakeLists.txt will deter‐
1101 mine the name that CMAKE_PROJECT_NAME contains. For example, consider
1102 the following top level CMakeLists.txt:
1103 cmake_minimum_required(VERSION 3.0)
1105 project(First)
1106 project(Second)
1107 add_subdirectory(sub)
1108 project(Third)
1109 And sub/CMakeLists.txt with the following contents:
1111 project(SubProj)
1113 message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")
1114 The most recently seen project() command from the top level CMake‐
1116 Lists.txt would be project(Second), so this will print:
1117 CMAKE_PROJECT_NAME = Second
1119 To obtain the name from the most recent call to project() in the cur‐
1121 rent directory scope or above, see the PROJECT_NAME variable.
1122 CMAKE_PROJECT_VERSION
1124 New in version 3.12.
1125 The version of the top level project.
1128 This variable holds the version of the project as specified in the top
1130 level CMakeLists.txt file by a project() command. In the event that
1131 the top level CMakeLists.txt contains multiple project() calls, the
1132 most recently called one from that top level CMakeLists.txt will deter‐
1133 mine the value that CMAKE_PROJECT_VERSION contains. For example, con‐
1134 sider the following top level CMakeLists.txt:
1135 cmake_minimum_required(VERSION 3.0)
1137 project(First VERSION 1.2.3)
1138 project(Second VERSION 3.4.5)
1139 add_subdirectory(sub)
1140 project(Third VERSION 6.7.8)
1141 And sub/CMakeLists.txt with the following contents:
1143 project(SubProj VERSION 1)
1145 message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")
1146 The most recently seen project() command from the top level CMake‐
1148 Lists.txt would be project(Second ...), so this will print:
1149 CMAKE_PROJECT_VERSION = 3.4.5
1151 To obtain the version from the most recent call to project() in the
1153 current directory scope or above, see the PROJECT_VERSION variable.
1154 CMAKE_PROJECT_VERSION_MAJOR
1156 New in version 3.12.
1157 The major version of the top level project.
1160 This variable holds the major version of the project as specified in
1162 the top level CMakeLists.txt file by a project() command. Please see
1163 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1164 project() commands are used in the sources.
1165 CMAKE_PROJECT_VERSION_MINOR
1167 New in version 3.12.
1168 The minor version of the top level project.
1171 This variable holds the minor version of the project as specified in
1173 the top level CMakeLists.txt file by a project() command. Please see
1174 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1175 project() commands are used in the sources.
1176 CMAKE_PROJECT_VERSION_PATCH
1178 New in version 3.12.
1179 The patch version of the top level project.
1182 This variable holds the patch version of the project as specified in
1184 the top level CMakeLists.txt file by a project() command. Please see
1185 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1186 project() commands are used in the sources.
1187 CMAKE_PROJECT_VERSION_TWEAK
1189 New in version 3.12.
1190 The tweak version of the top level project.
1193 This variable holds the tweak version of the project as specified in
1195 the top level CMakeLists.txt file by a project() command. Please see
1196 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1197 project() commands are used in the sources.
1198 CMAKE_RANLIB
1200 Name of randomizing tool for static libraries.
1201 This specifies name of the program that randomizes libraries on UNIX,
1203 not used on Windows, but may be present.
1204 CMAKE_ROOT
1206 Install directory for running cmake.
1207 This is the install root for the running CMake and the Modules direc‐
1209 tory can be found here. This is commonly used in this format:
1210 ${CMAKE_ROOT}/Modules
1211 CMAKE_RULE_MESSAGES
1213 New in version 3.13.
1214 Specify whether to report a message for each make rule.
1217 If set in the cache it is used to initialize the value of the
1219 RULE_MESSAGES property. Users may disable the option in their local
1220 build tree to disable granular messages and report only as each target
1221 completes in Makefile builds.
1222 CMAKE_SCRIPT_MODE_FILE
1224 Full path to the cmake -P script file currently being processed.
1225 When run in cmake -P script mode, CMake sets this variable to the full
1227 path of the script file. When run to configure a CMakeLists.txt file,
1228 this variable is not set.
1229 CMAKE_SHARED_LIBRARY_PREFIX
1231 The prefix for shared libraries that you link to.
1232 The prefix to use for the name of a shared library, lib on UNIX.
1234 CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1236 CMAKE_SHARED_LIBRARY_SUFFIX
1238 The suffix for shared libraries that you link to.
1239 The suffix to use for the end of a shared library filename, .dll on
1241 Windows.
1242 CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1244 CMAKE_SHARED_MODULE_PREFIX
1246 The prefix for loadable modules that you link to.
1247 The prefix to use for the name of a loadable module on this platform.
1249 CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides this for language <LANG>.
1251 CMAKE_SHARED_MODULE_SUFFIX
1253 The suffix for shared libraries that you link to.
1254 The suffix to use for the end of a loadable module filename on this
1256 platform
1257 CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides this for language <LANG>.
1259 CMAKE_SIZEOF_VOID_P
1261 Size of a void pointer.
1262 This is set to the size of a pointer on the target machine, and is de‐
1264 termined by a try compile. If a 64-bit size is found, then the library
1265 search path is modified to look for 64-bit libraries first.
1266 CMAKE_SKIP_INSTALL_RULES
1268 Whether to disable generation of installation rules.
1269 If TRUE, CMake will neither generate installation rules nor will it
1271 generate cmake_install.cmake files. This variable is FALSE by default.
1272 CMAKE_SKIP_RPATH
1274 If true, do not add run time path information.
1275 If this is set to TRUE, then the rpath information is not added to com‐
1277 piled executables. The default is to add rpath information if the
1278 platform supports it. This allows for easy running from the build
1279 tree. To omit RPATH in the install step, but not the build step, use
1280 CMAKE_SKIP_INSTALL_RPATH instead.
1281 CMAKE_SOURCE_DIR
1283 The path to the top level of the source tree.
1284 This is the full path to the top level of the current CMake source
1286 tree. For an in-source build, this would be the same as
1287 CMAKE_BINARY_DIR.
1288 When run in cmake -P script mode, CMake sets the variables
1290 CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
1291 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
1292 CMAKE_STATIC_LIBRARY_PREFIX
1294 The prefix for static libraries that you link to.
1295 The prefix to use for the name of a static library, lib on UNIX.
1297 CMAKE_STATIC_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1299 CMAKE_STATIC_LIBRARY_SUFFIX
1301 The suffix for static libraries that you link to.
1302 The suffix to use for the end of a static library filename, .lib on
1304 Windows.
1305 CMAKE_STATIC_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1307 CMAKE_Swift_MODULE_DIRECTORY
1309 New in version 3.15.
1310 Swift module output directory.
1313 This variable is used to initialize the Swift_MODULE_DIRECTORY property
1315 on all the targets. See the target property for additional informa‐
1316 tion.
1317 CMAKE_Swift_NUM_THREADS
1319 New in version 3.15.1.
1320 Number of threads for parallel compilation for Swift targets.
1323 This variable controls the number of parallel jobs that the swift
1325 driver creates for building targets. If not specified, it will default
1326 to the number of logical CPUs on the host.
1327 CMAKE_TOOLCHAIN_FILE
1329 Path to toolchain file supplied to cmake(1).
1330 This variable is specified on the command line when cross-compiling
1332 with CMake. It is the path to a file which is read early in the CMake
1333 run and which specifies locations for compilers and toolchain utili‐
1334 ties, and other target platform and compiler related information.
1335 Relative paths are allowed and are interpreted first as relative to the
1337 build directory, and if not found, relative to the source directory.
1338 This is initialized by the CMAKE_TOOLCHAIN_FILE environment variable if
1340 it is set when a new build tree is first created.
1341 See the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable for setting other
1343 things not directly related to the toolchain.
1344 CMAKE_TWEAK_VERSION
1346 Defined to 0 for compatibility with code written for older CMake ver‐
1347 sions that may have defined higher values.
1348 NOTE:
1350 In CMake versions 2.8.2 through 2.8.12, this variable holds the
1351 fourth version number component of the CMAKE_VERSION variable.
1352 CMAKE_VERBOSE_MAKEFILE
1354 Enable verbose output from Makefile builds.
1355 This variable is a cache entry initialized (to FALSE) by the project()
1357 command. Users may enable the option in their local build tree to get
1358 more verbose output from Makefile builds and show each command line as
1359 it is launched.
1360 CMAKE_VERSION
1362 The CMake version string as three non-negative integer components sepa‐
1363 rated by . and possibly followed by - and other information. The first
1364 two components represent the feature level and the third component rep‐
1365 resents either a bug-fix level or development date.
1366 Release versions and release candidate versions of CMake use the for‐
1368 mat:
1369 <major>.<minor>.<patch>[-rc<n>]
1371 where the <patch> component is less than 20000000. Development ver‐
1373 sions of CMake use the format:
1374 <major>.<minor>.<date>[-<id>]
1376 where the <date> component is of format CCYYMMDD and <id> may contain
1378 arbitrary text. This represents development as of a particular date
1379 following the <major>.<minor> feature release.
1380 Individual component values are also available in variables:
1382 • CMAKE_MAJOR_VERSION
1384 • CMAKE_MINOR_VERSION
1386 • CMAKE_PATCH_VERSION
1388 • CMAKE_TWEAK_VERSION
1390 Use the if() command VERSION_LESS, VERSION_GREATER, VERSION_EQUAL, VER‐
1392 SION_LESS_EQUAL, or VERSION_GREATER_EQUAL operators to compare version
1393 string values against CMAKE_VERSION using a component-wise test. Ver‐
1394 sion component values may be 10 or larger so do not attempt to compare
1395 version strings as floating-point numbers.
1396 NOTE:
1398 CMake versions 2.8.2 through 2.8.12 used three components for the
1399 feature level. Release versions represented the bug-fix level in a
1400 fourth component, i.e. <major>.<minor>.<patch>[.<tweak>][-rc<n>].
1401 Development versions represented the development date in the fourth
1402 component, i.e. <major>.<minor>.<patch>.<date>[-<id>].
1403 CMake versions prior to 2.8.2 used three components for the feature
1405 level and had no bug-fix component. Release versions used an
1406 even-valued second component, i.e. <major>.<even-mi‐
1407 nor>.<patch>[-rc<n>]. Development versions used an odd-valued sec‐
1408 ond component with the development date as the third component, i.e.
1409 <major>.<odd-minor>.<date>.
1410 The CMAKE_VERSION variable is defined by CMake 2.6.3 and higher.
1412 Earlier versions defined only the individual component variables.
1413 CMAKE_VS_DEVENV_COMMAND
1415 The generators for Visual Studio 9 2008 and above set this variable to
1416 the devenv.com command installed with the corresponding Visual Studio
1417 version. Note that this variable may be empty on Visual Studio Express
1418 editions because they do not provide this tool.
1419 This variable is not defined by other generators even if devenv.com is
1421 installed on the computer.
1422 The CMAKE_VS_MSBUILD_COMMAND is also provided for Visual Studio 11 2012
1424 and above. See also the CMAKE_MAKE_PROGRAM variable.
1425 CMAKE_VS_MSBUILD_COMMAND
1427 The generators for Visual Studio 11 2012 and above set this variable to
1428 the MSBuild.exe command installed with the corresponding Visual Studio
1429 version.
1430 This variable is not defined by other generators even if MSBuild.exe is
1432 installed on the computer.
1433 The CMAKE_VS_DEVENV_COMMAND is also provided for the non-Express edi‐
1435 tions of Visual Studio. See also the CMAKE_MAKE_PROGRAM variable.
1436 CMAKE_VS_NsightTegra_VERSION
1438 New in version 3.1.
1439 When using a Visual Studio generator with the CMAKE_SYSTEM_NAME vari‐
1442 able set to Android, this variable contains the version number of the
1443 installed NVIDIA Nsight Tegra Visual Studio Edition.
1444 CMAKE_VS_NUGET_PACKAGE_RESTORE
1446 New in version 3.23.
1447 When using a Visual Studio generator, this cache variable controls if
1450 msbuild should automatically attempt to restore NuGet packages prior to
1451 a build. NuGet packages can be defined using the VS_PACKAGE_REFERENCES
1452 property on a target. If no package references are defined, this set‐
1453 ting will do nothing.
1454 The command line option --resolve-package-references can be used alter‐
1456 natively to control the resolve behavior globally. This option will
1457 take precedence over the cache variable.
1458 Targets that use the DOTNET_SDK are required to run a restore before
1460 building. Disabling this option may cause the build to fail in such
1461 projects.
1462 This setting is stored as a cache entry. Default value is ON.
1464 See also the VS_PACKAGE_REFERENCES property.
1466 CMAKE_VS_PLATFORM_NAME
1468 New in version 3.1.
1469 Visual Studio target platform name used by the current generator.
1472 VS 8 and above allow project files to specify a target platform. CMake
1474 provides the name of the chosen platform in this variable. See the
1475 CMAKE_GENERATOR_PLATFORM variable for details.
1476 See also the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.
1478 CMAKE_VS_PLATFORM_NAME_DEFAULT
1480 New in version 3.14.3.
1481 Default for the Visual Studio target platform name for the current gen‐
1484 erator without considering the value of the CMAKE_GENERATOR_PLATFORM
1485 variable. For Visual Studio Generators for VS 2017 and below this is
1486 always Win32. For VS 2019 and above this is based on the host plat‐
1487 form.
1488 See also the CMAKE_VS_PLATFORM_NAME variable.
1490 CMAKE_VS_PLATFORM_TOOLSET
1492 Visual Studio Platform Toolset name.
1493 VS 10 and above use MSBuild under the hood and support multiple com‐
1495 piler toolchains. CMake may specify a toolset explicitly, such as v110
1496 for VS 11 or Windows7.1SDK for 64-bit support in VS 10 Express. CMake
1497 provides the name of the chosen toolset in this variable.
1498 See the CMAKE_GENERATOR_TOOLSET variable for details.
1500 CMAKE_VS_PLATFORM_TOOLSET_CUDA
1502 New in version 3.9.
1503 NVIDIA CUDA Toolkit version whose Visual Studio toolset to use.
1506 The Visual Studio Generators for VS 2010 and above support using a CUDA
1508 toolset provided by a CUDA Toolkit. The toolset version number may be
1509 specified by a field in CMAKE_GENERATOR_TOOLSET of the form cuda=8.0.
1510 Or it is automatically detected if a path to a standalone CUDA direc‐
1511 tory is specified in the form cuda=C:\path\to\cuda. If none is speci‐
1512 fied CMake will choose a default version. CMake provides the selected
1513 CUDA toolset version in this variable. The value may be empty if no
1514 CUDA Toolkit with Visual Studio integration is installed.
1515 CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
1517 New in version 3.16.
1518 Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer).
1521 The Visual Studio Generators for VS 2010 and above support using a
1523 standalone (non-installed) NVIDIA CUDA toolkit. The path may be speci‐
1524 fied by a field in CMAKE_GENERATOR_TOOLSET of the form
1525 cuda=C:\path\to\cuda. The given directory must at least contain the
1526 nvcc compiler in path .\bin and must provide Visual Studio integration
1527 files in path .\extras\visual_studio_integration\ MSBuildExtensions\.
1528 One can create a standalone CUDA toolkit directory by either opening a
1529 installer with 7zip or copying the files that are extracted by the run‐
1530 ning installer. The value may be empty if no path to a standalone CUDA
1531 Toolkit was specified.
1532 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
1534 New in version 3.8.
1535 Visual Studio preferred tool architecture.
1538 The Visual Studio Generators for VS 2013 and above support using either
1540 the 32-bit or 64-bit host toolchains by specifying a host=x86 or
1541 host=x64 value in the CMAKE_GENERATOR_TOOLSET option. CMake provides
1542 the selected toolchain architecture preference in this variable (x86,
1543 x64, ARM64 or empty).
1544 CMAKE_VS_PLATFORM_TOOLSET_VERSION
1546 New in version 3.12.
1547 Visual Studio Platform Toolset version.
1550 The Visual Studio Generators for VS 2017 and above allow to select mi‐
1552 nor versions of the same toolset. The toolset version number may be
1553 specified by a field in CMAKE_GENERATOR_TOOLSET of the form ver‐
1554 sion=14.11. If none is specified CMake will choose a default toolset.
1555 The value may be empty if no minor version was selected and the default
1556 is used.
1557 If the value is not empty, it is the version number that MSBuild uses
1559 in its Microsoft.VCToolsVersion.*.props file names.
1560 New in version 3.19.7: VS 16.9's toolset may also be specified as
1562 14.28.16.9 because VS 16.10 uses the file name Microsoft.VCToolsVer‐
1563 sion.14.28.16.9.props.
1564 Three-Component MSVC Toolset Versions
1567 New in version 3.19.7.
1568 The version= field may be given a three-component toolset version such
1571 as 14.28.29910, and CMake will convert it to the name used by MSBuild
1572 Microsoft.VCToolsVersion.*.props files. This is useful to distinguish
1573 between VS 16.8's 14.28.29333 toolset and VS 16.9's 14.28.29910
1574 toolset. It also matches vcvarsall's -vcvars_ver= behavior.
1575 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
1577 New in version 3.22.
1578 Visual Studio target framework identifier.
1581 In some cases, the Visual Studio Generators may use an explicit value
1583 for the MSBuild TargetFrameworkIdentifier setting in .csproj files.
1584 CMake provides the chosen value in this variable.
1585 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1587 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1588 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
1590 New in version 3.22.
1591 Visual Studio target framework targets version.
1594 In some cases, the Visual Studio Generators may use an explicit value
1596 for the MSBuild TargetFrameworkTargetsVersion setting in .csproj files.
1597 CMake provides the chosen value in this variable.
1598 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1600 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.
1601 CMAKE_VS_TARGET_FRAMEWORK_VERSION
1603 New in version 3.22.
1604 Visual Studio target framework version.
1607 In some cases, the Visual Studio Generators may use an explicit value
1609 for the MSBuild TargetFrameworkVersion setting in .csproj files. CMake
1610 provides the chosen value in this variable.
1611 See the CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION variable and
1613 DOTNET_TARGET_FRAMEWORK_VERSION target property to specify custom Tar‐
1614 getFrameworkVersion values for project targets.
1615 See also CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER and
1617 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1618 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
1620 New in version 3.4.
1621 Visual Studio Windows Target Platform Version.
1624 When targeting Windows 10 and above Visual Studio 2015 and above sup‐
1626 port specification of a target Windows version to select a correspond‐
1627 ing SDK. The CMAKE_SYSTEM_VERSION variable may be set to specify a
1628 version. Otherwise CMake computes a default version based on the Win‐
1629 dows SDK versions available. The chosen Windows target version number
1630 is provided in CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION. If no Windows
1631 10 SDK is available this value will be empty.
1632 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to an ab‐
1634 solute path to tell CMake to look for Windows 10 SDKs in a custom loca‐
1635 tion. The specified directory is expected to contain Include/10.0.*
1636 directories.
1637 See also CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.
1639 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
1641 New in version 3.19.
1642 Override the Windows 10 SDK Maximum Version for VS 2015 and beyond.
1645 The CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM variable may be
1647 set to a false value (e.g. OFF, FALSE, or 0) or the SDK version to use
1648 as the maximum (e.g. 10.0.14393.0). If unset, the default depends on
1649 which version of Visual Studio is targeted by the current generator.
1650 This can be used in conjunction with CMAKE_SYSTEM_VERSION, which CMake
1652 uses to select CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.
1653 CMAKE_XCODE_BUILD_SYSTEM
1655 New in version 3.19.
1656 Xcode build system selection.
1659 The Xcode generator defines this variable to indicate which variant of
1661 the Xcode build system will be used. The value is the version of Xcode
1662 in which the corresponding build system first became mature enough for
1663 use by CMake. The possible values are:
1664 1 The original Xcode build system. This is the default when using
1666 Xcode 11.x or below.
1667 12 The Xcode "new build system" introduced by Xcode 10. It became
1669 mature enough for use by CMake in Xcode 12. This is the default
1670 when using Xcode 12.x or above.
1671 The CMAKE_XCODE_BUILD_SYSTEM variable is informational and should not
1673 be modified by project code. See the Toolset and Build System Selec‐
1674 tion documentation section to select the Xcode build system.
1675 CMAKE_XCODE_PLATFORM_TOOLSET
1677 Xcode compiler selection.
1678 Xcode supports selection of a compiler from one of the installed
1680 toolsets. CMake provides the name of the chosen toolset in this vari‐
1681 able, if any is explicitly selected (e.g. via the cmake -T option).
1682 <PROJECT-NAME>_BINARY_DIR
1684 Top level binary directory for the named project.
1685 A variable is created with the name used in the project() command, and
1687 is the binary directory for the project. This can be useful when
1688 add_subdirectory() is used to connect several projects.
1689 <PROJECT-NAME>_DESCRIPTION
1691 New in version 3.12.
1692 Value given to the DESCRIPTION option of the most recent call to the
1695 project() command with project name <PROJECT-NAME>, if any.
1696 <PROJECT-NAME>_HOMEPAGE_URL
1698 New in version 3.12.
1699 Value given to the HOMEPAGE_URL option of the most recent call to the
1702 project() command with project name <PROJECT-NAME>, if any.
1703 <PROJECT-NAME>_IS_TOP_LEVEL
1705 New in version 3.21.
1706 A boolean variable indicating whether the named project was called in a
1709 top level CMakeLists.txt file.
1710 To obtain the value from the most recent call to project() in the cur‐
1712 rent directory scope or above, see the PROJECT_IS_TOP_LEVEL variable.
1713 The variable value will be true in:
1715 • the top-level directory of the project
1717 • the top-level directory of an external project added by
1719 ExternalProject
1720 • a directory added by add_subdirectory() that does not also contain a
1722 project() call
1723 • a directory added by FetchContent_MakeAvailable(), if the fetched
1725 content does not contain a project() call
1726 The variable value will be false in:
1728 • a directory added by add_subdirectory() that also contains a
1730 project() call
1731 • a directory added by FetchContent_MakeAvailable(), if the fetched
1733 content contains a project() call
1734 <PROJECT-NAME>_SOURCE_DIR
1736 Top level source directory for the named project.
1737 A variable is created with the name used in the project() command, and
1739 is the source directory for the project. This can be useful when
1740 add_subdirectory() is used to connect several projects.
1741 <PROJECT-NAME>_VERSION
1743 Value given to the VERSION option of the most recent call to the
1744 project() command with project name <PROJECT-NAME>, if any.
1745 See also the component-wise version variables
1747 <PROJECT-NAME>_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MINOR,
1748 <PROJECT-NAME>_VERSION_PATCH, and <PROJECT-NAME>_VERSION_TWEAK.
1749 <PROJECT-NAME>_VERSION_MAJOR
1751 First version number component of the <PROJECT-NAME>_VERSION variable
1752 as set by the project() command.
1753 <PROJECT-NAME>_VERSION_MINOR
1755 Second version number component of the <PROJECT-NAME>_VERSION variable
1756 as set by the project() command.
1757 <PROJECT-NAME>_VERSION_PATCH
1759 Third version number component of the <PROJECT-NAME>_VERSION variable
1760 as set by the project() command.
1761 <PROJECT-NAME>_VERSION_TWEAK
1763 Fourth version number component of the <PROJECT-NAME>_VERSION variable
1764 as set by the project() command.
1765 PROJECT_BINARY_DIR
1767 Full path to build directory for project.
1768 This is the binary directory of the most recent project() command.
1770 PROJECT_DESCRIPTION
1772 New in version 3.9.
1773 Short project description given to the project command.
1776 This is the description given to the most recently called project()
1778 command in the current directory scope or above. To obtain the de‐
1779 scription of the top level project, see the CMAKE_PROJECT_DESCRIPTION
1780 variable.
1781 PROJECT_HOMEPAGE_URL
1783 New in version 3.12.
1784 The homepage URL of the project.
1787 This is the homepage URL given to the most recently called project()
1789 command in the current directory scope or above. To obtain the home‐
1790 page URL of the top level project, see the CMAKE_PROJECT_HOMEPAGE_URL
1791 variable.
1792 PROJECT_IS_TOP_LEVEL
1794 New in version 3.21.
1795 A boolean variable indicating whether the most recently called
1798 project() command in the current scope or above was in the top level
1799 CMakeLists.txt file.
1800 Some modules should only be included as part of the top level CMake‐
1802 Lists.txt file to not cause unintended side effects in the build tree,
1803 and this variable can be used to conditionally execute such code. For
1804 example, consider the CTest module, which creates targets and options:
1805 project(MyProject)
1807 ...
1808 if(PROJECT_IS_TOP_LEVEL)
1809 include(CTest)
1810 endif()
1811 The variable value will be true in:
1813 • the top-level directory of the project
1815 • the top-level directory of an external project added by
1817 ExternalProject
1818 • a directory added by add_subdirectory() that does not also contain a
1820 project() call
1821 • a directory added by FetchContent_MakeAvailable(), if the fetched
1823 content does not contain a project() call
1824 The variable value will be false in:
1826 • a directory added by add_subdirectory() that also contains a
1828 project() call
1829 • a directory added by FetchContent_MakeAvailable(), if the fetched
1831 content contains a project() call
1832 PROJECT_NAME
1834 Name of the project given to the project command.
1835 This is the name given to the most recently called project() command in
1837 the current directory scope or above. To obtain the name of the top
1838 level project, see the CMAKE_PROJECT_NAME variable.
1839 PROJECT_SOURCE_DIR
1841 This is the source directory of the last call to the project() command
1842 made in the current directory scope or one of its parents. Note, it is
1843 not affected by calls to project() made within a child directory scope
1844 (i.e. from within a call to add_subdirectory() from the current scope).
1845 PROJECT_VERSION
1847 Value given to the VERSION option of the most recent call to the
1848 project() command, if any.
1849 See also the component-wise version variables PROJECT_VERSION_MAJOR,
1851 PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH, and
1852 PROJECT_VERSION_TWEAK.
1853 PROJECT_VERSION_MAJOR
1855 First version number component of the PROJECT_VERSION variable as set
1856 by the project() command.
1857 PROJECT_VERSION_MINOR
1859 Second version number component of the PROJECT_VERSION variable as set
1860 by the project() command.
1861 PROJECT_VERSION_PATCH
1863 Third version number component of the PROJECT_VERSION variable as set
1864 by the project() command.
1865 PROJECT_VERSION_TWEAK
1867 Fourth version number component of the PROJECT_VERSION variable as set
1868 by the project() command.
1869
1871 BUILD_SHARED_LIBS
1872 Global flag to cause add_library() to create shared libraries if on.
1873 If present and true, this will cause all libraries to be built shared
1875 unless the library was explicitly added as a static library. This
1876 variable is often added to projects as an option() so that each user of
1877 a project can decide if they want to build the project using shared or
1878 static libraries.
1879 CMAKE_ABSOLUTE_DESTINATION_FILES
1881 List of files which have been installed using an ABSOLUTE DESTINATION
1882 path.
1883 This variable is defined by CMake-generated cmake_install.cmake
1885 scripts. It can be used (read-only) by programs or scripts that source
1886 those install scripts. This is used by some CPack generators (e.g.
1887 RPM).
1888 CMAKE_APPBUNDLE_PATH
1890 Semicolon-separated list of directories specifying a search path for
1891 macOS application bundles used by the find_program(), and
1892 find_package() commands.
1893 CMAKE_AUTOMOC_RELAXED_MODE
1895 Deprecated since version 3.15.
1896 Switch between strict and relaxed automoc mode.
1899 By default, AUTOMOC behaves exactly as described in the documentation
1901 of the AUTOMOC target property. When set to TRUE, it accepts more in‐
1902 put and tries to find the correct input file for moc even if it differs
1903 from the documented behavior. In this mode it e.g. also checks
1904 whether a header file is intended to be processed by moc when a
1905 "foo.moc" file has been included.
1906 Relaxed mode has to be enabled for KDE4 compatibility.
1908 CMAKE_BACKWARDS_COMPATIBILITY
1910 Deprecated. See CMake Policy CMP0001 documentation.
1911 CMAKE_BUILD_TYPE
1913 Specifies the build type on single-configuration generators (e.g.
1914 Makefile Generators or Ninja). Typical values include Debug, Release,
1915 RelWithDebInfo and MinSizeRel, but custom build types can also be de‐
1916 fined.
1917 This variable is initialized by the first project() or
1919 enable_language() command called in a project when a new build tree is
1920 first created. If the CMAKE_BUILD_TYPE environment variable is set,
1921 its value is used. Otherwise, a toolchain-specific default is chosen
1922 when a language is enabled. The default value is often an empty
1923 string, but this is usually not desirable and one of the other standard
1924 build types is usually more appropriate.
1925 Depending on the situation, the value of this variable may be treated
1927 case-sensitively or case-insensitively. See Build Configurations for
1928 discussion of this and other related topics.
1929 For multi-config generators, see CMAKE_CONFIGURATION_TYPES.
1931 CMAKE_CLANG_VFS_OVERLAY
1933 New in version 3.19.
1934 When cross compiling for windows with clang-cl, this variable can be an
1937 absolute path pointing to a clang virtual file system yaml file, which
1938 will enable clang-cl to resolve windows header names on a case sensi‐
1939 tive file system.
1940 CMAKE_CODEBLOCKS_COMPILER_ID
1942 New in version 3.11.
1943 Change the compiler id in the generated CodeBlocks project files.
1946 CodeBlocks uses its own compiler id string which differs from
1948 CMAKE_<LANG>_COMPILER_ID. If this variable is left empty, CMake tries
1949 to recognize the CodeBlocks compiler id automatically. Otherwise the
1950 specified string is used in the CodeBlocks project file. See the Code‐
1951 Blocks documentation for valid compiler id strings.
1952 Other IDEs like QtCreator that also use the CodeBlocks generator may
1954 ignore this setting.
1955 CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
1957 New in version 3.10.
1958 Change the way the CodeBlocks generator creates project files.
1961 If this variable evaluates to ON the generator excludes from the
1963 project file any files that are located outside the project root.
1964 CMAKE_CODELITE_USE_TARGETS
1966 New in version 3.7.
1967 Change the way the CodeLite generator creates projectfiles.
1970 If this variable evaluates to ON at the end of the top-level CMake‐
1972 Lists.txt file, the generator creates projectfiles based on targets
1973 rather than projects.
1974 CMAKE_COLOR_DIAGNOSTICS
1976 New in version 3.24.
1977 Enable color diagnostics throughout.
1980 This variable uses three states: ON, OFF and not defined.
1982 When not defined:
1984 • Makefile Generators initialize the CMAKE_COLOR_MAKEFILE variable to
1986 ON. It controls color buildsystem messages.
1987 • GNU/Clang compilers are not invoked with any color diagnostics flag.
1989 When ON:
1991 • Makefile Generators produce color buildsystem messages by default.
1993 CMAKE_COLOR_MAKEFILE is not initialized, but may be explicitly set to
1994 OFF to disable color buildsystem messages.
1995 • GNU/Clang compilers are invoked with a flag enabling color diagnos‐
1997 tics (-fcolor-diagnostics).
1998 When OFF:
2000 • Makefile Generators do not produce color buildsystem messages by de‐
2002 fault. CMAKE_COLOR_MAKEFILE is not initialized, but may be explic‐
2003 itly set to ON to enable color buildsystem messages.
2004 • GNU/Clang compilers are invoked with a flag disabling color diagnos‐
2006 tics (-fno-color-diagnostics).
2007 If the CMAKE_COLOR_DIAGNOSTICS environment variable is set, its value
2009 is used. Otherwise, CMAKE_COLOR_DIAGNOSTICS is not defined by default.
2010 CMAKE_COLOR_MAKEFILE
2012 Enables color output when using the Makefile Generators.
2013 When enabled, the generated Makefiles will produce colored output. De‐
2015 fault is ON.
2016 CMAKE_CONFIGURATION_TYPES
2018 Specifies the available build types (configurations) on multi-config
2019 generators (e.g. Visual Studio, Xcode, or Ninja Multi-Config). Typical
2020 values include Debug, Release, RelWithDebInfo and MinSizeRel, but cus‐
2021 tom build types can also be defined.
2022 This variable is initialized by the first project() or
2024 enable_language() command called in a project when a new build tree is
2025 first created. If the CMAKE_CONFIGURATION_TYPES environment variable
2026 is set, its value is used. Otherwise, the default value is genera‐
2027 tor-specific.
2028 Depending on the situation, the values in this variable may be treated
2030 case-sensitively or case-insensitively. See Build Configurations for
2031 discussion of this and other related topics.
2032 For single-config generators, see CMAKE_BUILD_TYPE.
2034 CMAKE_DEPENDS_IN_PROJECT_ONLY
2036 New in version 3.6.
2037 When set to TRUE in a directory, the build system produced by the
2040 Makefile Generators is set up to only consider dependencies on source
2041 files that appear either in the source or in the binary directories.
2042 Changes to source files outside of these directories will not cause re‐
2043 builds.
2044 This should be used carefully in cases where some source files are
2046 picked up through external headers during the build.
2047 CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
2049 Variable for disabling find_package() calls.
2050 Every non-REQUIRED find_package() call in a project can be disabled by
2052 setting the variable CMAKE_DISABLE_FIND_PACKAGE_<PackageName> to TRUE.
2053 This can be used to build a project without an optional package, al‐
2054 though that package is installed.
2055 This switch should be used during the initial CMake run. Otherwise if
2057 the package has already been found in a previous CMake run, the vari‐
2058 ables which have been stored in the cache will still be there. In that
2059 case it is recommended to remove the cache variables for this package
2060 from the cache using the cache editor or cmake -U.
2061 See also the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable.
2063 CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
2065 New in version 3.6.
2066 This cache variable is used by the Eclipse project generator. See
2069 cmake-generators(7).
2070 The Eclipse project generator generates so-called linked resources e.g.
2072 to the subproject root dirs in the source tree or to the source files
2073 of targets. This can be disabled by setting this variable to FALSE.
2074 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
2076 New in version 3.6.
2077 This cache variable is used by the Eclipse project generator. See
2080 cmake-generators(7).
2081 If this variable is set to TRUE, the Eclipse project generator will
2083 generate an Eclipse project in CMAKE_SOURCE_DIR . This project can then
2084 be used in Eclipse e.g. for the version control functionality.
2085 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT defaults to FALSE; so nothing is
2086 written into the source directory.
2087 CMAKE_ECLIPSE_MAKE_ARGUMENTS
2089 New in version 3.6.
2090 This cache variable is used by the Eclipse project generator. See
2093 cmake-generators(7).
2094 This variable holds arguments which are used when Eclipse invokes the
2096 make tool. By default it is initialized to hold flags to enable paral‐
2097 lel builds (using -j typically).
2098 CMAKE_ECLIPSE_RESOURCE_ENCODING
2100 New in version 3.16.
2101 This cache variable tells the Eclipse CDT4 project generator to set the
2104 resource encoding to the given value in generated project files. If no
2105 value is given, no encoding will be set.
2106 CMAKE_ECLIPSE_VERSION
2108 New in version 3.6.
2109 This cache variable is used by the Eclipse project generator. See
2112 cmake-generators(7).
2113 When using the Eclipse project generator, CMake tries to find the
2115 Eclipse executable and detect the version of it. Depending on the ver‐
2116 sion it finds, some features are enabled or disabled. If CMake doesn't
2117 find Eclipse, it assumes the oldest supported version, Eclipse Callisto
2118 (3.2).
2119 CMAKE_ERROR_DEPRECATED
2121 Whether to issue errors for deprecated functionality.
2122 If TRUE, use of deprecated functionality will issue fatal errors. If
2124 this variable is not set, CMake behaves as if it were set to FALSE.
2125 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
2127 Ask cmake_install.cmake script to error out as soon as a file with ab‐
2128 solute INSTALL DESTINATION is encountered.
2129 The fatal error is emitted before the installation of the offending
2131 file takes place. This variable is used by CMake-generated cmake_in‐
2132 stall.cmake scripts. If one sets this variable to ON while running the
2133 script, it may get fatal error messages from the script.
2134 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
2136 New in version 3.15.
2137 If this variable is set to STDERR, STDOUT or NONE then commands in
2140 execute_process() calls will be printed to either stderr or stdout or
2141 not at all.
2142 CMAKE_EXPORT_COMPILE_COMMANDS
2144 New in version 3.5.
2145 Enable/Disable output of compile commands during generation.
2148 If enabled, generates a compile_commands.json file containing the exact
2150 compiler calls for all translation units of the project in ma‐
2151 chine-readable form. The format of the JSON file looks like:
2152 [
2154 {
2155 "directory": "/home/user/development/project",
2156 "command": "/usr/bin/c++ ... -c ../foo/foo.cc",
2157 "file": "../foo/foo.cc"
2158 },
2159 ...
2161 {
2163 "directory": "/home/user/development/project",
2164 "command": "/usr/bin/c++ ... -c ../foo/bar.cc",
2165 "file": "../foo/bar.cc"
2166 }
2167 ]
2168 This is initialized by the CMAKE_EXPORT_COMPILE_COMMANDS environment
2170 variable, and initializes the EXPORT_COMPILE_COMMANDS target property
2171 for all targets.
2172 NOTE:
2174 This option is implemented only by Makefile Generators and Ninja
2175 Generators. It is ignored on other generators.
2176 This option currently does not work well in combination with the
2178 UNITY_BUILD target property or the CMAKE_UNITY_BUILD variable.
2179 CMAKE_EXPORT_PACKAGE_REGISTRY
2181 New in version 3.15.
2182 Enables the export(PACKAGE) command when CMP0090 is set to NEW.
2185 The export(PACKAGE) command does nothing by default. In some cases it
2187 is desirable to write to the user package registry, so the CMAKE_EX‐
2188 PORT_PACKAGE_REGISTRY variable may be set to enable it.
2189 If CMP0090 is not set to NEW this variable does nothing, and the
2191 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable controls the behavior in‐
2192 stead.
2193 See also Disabling the Package Registry.
2195 CMAKE_EXPORT_NO_PACKAGE_REGISTRY
2197 New in version 3.1.
2198 Disable the export(PACKAGE) command when CMP0090 is not set to NEW.
2201 In some cases, for example for packaging and for system wide installa‐
2203 tions, it is not desirable to write the user package registry. If the
2204 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the
2205 export(PACKAGE) command will do nothing.
2206 If CMP0090 is set to NEW this variable does nothing, and the
2208 CMAKE_EXPORT_PACKAGE_REGISTRY variable controls the behavior instead.
2209 See also Disabling the Package Registry.
2211 CMAKE_FIND_APPBUNDLE
2213 New in version 3.4.
2214 This variable affects how find_* commands choose between macOS Applica‐
2217 tion Bundles and unix-style package components.
2218 On Darwin or systems supporting macOS Application Bundles, the
2220 CMAKE_FIND_APPBUNDLE variable can be set to empty or one of the follow‐
2221 ing:
2222 FIRST Try to find application bundles before standard programs. This
2224 is the default on Darwin.
2225 LAST Try to find application bundles after standard programs.
2227 ONLY Only try to find application bundles.
2229 NEVER Never try to find application bundles.
2231 CMAKE_FIND_FRAMEWORK
2233 New in version 3.4.
2234 This variable affects how find_* commands choose between macOS Frame‐
2237 works and unix-style package components.
2238 On Darwin or systems supporting macOS Frameworks, the CMAKE_FIND_FRAME‐
2240 WORK variable can be set to empty or one of the following:
2241 FIRST Try to find frameworks before standard libraries or headers.
2243 This is the default on Darwin.
2244 LAST Try to find frameworks after standard libraries or headers.
2246 ONLY Only try to find frameworks.
2248 NEVER Never try to find frameworks.
2250 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
2252 New in version 3.9.
2253 Specify a <suffix> to tell the find_library() command to search in a
2256 lib<suffix> directory before each lib directory that would normally be
2257 searched.
2258 This overrides the behavior of related global properties:
2260 • FIND_LIBRARY_USE_LIB32_PATHS
2262 • FIND_LIBRARY_USE_LIB64_PATHS
2264 • FIND_LIBRARY_USE_LIBX32_PATHS
2266 CMAKE_FIND_LIBRARY_PREFIXES
2268 Prefixes to prepend when looking for libraries.
2269 This specifies what prefixes to add to library names when the
2271 find_library() command looks for libraries. On UNIX systems this is
2272 typically lib, meaning that when trying to find the foo library it will
2273 look for libfoo.
2274 CMAKE_FIND_LIBRARY_SUFFIXES
2276 Suffixes to append when looking for libraries.
2277 This specifies what suffixes to add to library names when the
2279 find_library() command looks for libraries. On Windows systems this is
2280 typically .lib and, depending on the compiler, .dll.a, .a (e.g. GCC and
2281 Clang), so when it tries to find the foo library, it will look for
2282 [<prefix>]foo.lib and/or [<prefix>]foo[.dll].a, depending on the com‐
2283 piler used and the <prefix> specified in the
2284 CMAKE_FIND_LIBRARY_PREFIXES.
2285 CMAKE_FIND_NO_INSTALL_PREFIX
2287 Exclude the values of the CMAKE_INSTALL_PREFIX and CMAKE_STAGING_PREFIX
2288 variables from CMAKE_SYSTEM_PREFIX_PATH. CMake adds these project-des‐
2289 tination prefixes to CMAKE_SYSTEM_PREFIX_PATH by default in order to
2290 support building a series of dependent packages and installing them
2291 into a common prefix. Set CMAKE_FIND_NO_INSTALL_PREFIX to TRUE to sup‐
2292 press this behavior.
2293 The CMAKE_SYSTEM_PREFIX_PATH is initialized on the first call to a
2295 project() or enable_language() command. Therefore one must set
2296 CMAKE_FIND_NO_INSTALL_PREFIX before this in order to take effect. A
2297 user may set the variable as a cache entry on the command line to
2298 achieve this.
2299 Note that the prefix(es) may still be searched for other reasons, such
2301 as being the same prefix as the CMake installation, or for being a
2302 built-in system prefix.
2303 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
2305 New in version 3.1.
2306 Deprecated since version 3.16: Use the CMAKE_FIND_USE_PACKAGE_REGISTRY
2309 variable instead.
2310 By default this variable is not set. If neither
2313 CMAKE_FIND_USE_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_PACKAGE_REG‐
2314 ISTRY is set, then find_package() will use the User Package Registry
2315 unless the NO_CMAKE_PACKAGE_REGISTRY option is provided.
2316 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY is ignored if
2318 CMAKE_FIND_USE_PACKAGE_REGISTRY is set.
2319 In some cases, for example to locate only system wide installations, it
2321 is not desirable to use the User Package Registry when searching for
2322 packages. If the CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable is
2323 TRUE, all the find_package() commands will skip the User Package Reg‐
2324 istry as if they were called with the NO_CMAKE_PACKAGE_REGISTRY argu‐
2325 ment.
2326 See also Disabling the Package Registry.
2328 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
2330 New in version 3.1.
2331 Deprecated since version 3.16: Use the
2334 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable instead.
2335 By default this variable is not set. If neither
2338 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_SYS‐
2339 TEM_PACKAGE_REGISTRY is set, then find_package() will use the System
2340 Package Registry unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is
2341 provided.
2342 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY is ignored if
2344 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY is set.
2345 In some cases, it is not desirable to use the System Package Registry
2347 when searching for packages. If the
2348 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable is TRUE, all the
2349 find_package() commands will skip the System Package Registry as if
2350 they were called with the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY argument.
2351 See also Disabling the Package Registry.
2353 CMAKE_FIND_PACKAGE_PREFER_CONFIG
2355 New in version 3.15.
2356 Tell find_package() to try "Config" mode before "Module" mode if no
2359 mode was specified.
2360 The command find_package() operates without an explicit mode when the
2362 reduced signature is used without the MODULE option. In this case, by
2363 default, CMake first tries Module mode by searching for a
2364 Find<pkg>.cmake module. If it fails, CMake then searches for the pack‐
2365 age using Config mode.
2366 Set CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to tell find_package() to
2368 first search using Config mode before falling back to Module mode.
2369 This variable may be useful when a developer has compiled a custom ver‐
2371 sion of a common library and wishes to link it to a dependent project.
2372 If this variable is set to TRUE, it would prevent a dependent project's
2373 call to find_package() from selecting the default library located by
2374 the system's Find<pkg>.cmake module before finding the developer's cus‐
2375 tom built library.
2376 Once this variable is set, it is the responsibility of the exported
2378 <pkg>Config.cmake files to provide the same result variables as the
2379 Find<pkg>.cmake modules so that dependent projects can use them inter‐
2380 changeably.
2381 CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
2383 New in version 3.14.
2384 Set to TRUE to tell find_package() calls to resolve symbolic links in
2387 the value of <PackageName>_DIR.
2388 This is helpful in use cases where the package search path points at a
2390 proxy directory in which symlinks to the real package locations appear.
2391 This is not enabled by default because there are also common use cases
2392 in which the symlinks should be preserved.
2393 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
2395 New in version 3.24.
2396 Setting to TRUE promotes all IMPORTED targets discoverd by
2399 find_package() to a GLOBAL scope.
2400 Setting this to TRUE is akin to specifying GLOBAL as an argument to
2402 find_package(). Default value is OFF.
2403 CMAKE_FIND_PACKAGE_WARN_NO_MODULE
2405 Tell find_package() to warn if called without an explicit mode.
2406 If find_package() is called without an explicit mode option (MODULE,
2408 CONFIG, or NO_MODULE) and no Find<pkg>.cmake module is in
2409 CMAKE_MODULE_PATH then CMake implicitly assumes that the caller intends
2410 to search for a package configuration file. If no package configura‐
2411 tion file is found then the wording of the failure message must account
2412 for both the case that the package is really missing and the case that
2413 the project has a bug and failed to provide the intended Find module.
2414 If instead the caller specifies an explicit mode option then the fail‐
2415 ure message can be more specific.
2416 Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_package() to
2418 warn when it implicitly assumes Config mode. This helps developers en‐
2419 force use of an explicit mode in all calls to find_package() within a
2420 project.
2421 This variable has no effect if CMAKE_FIND_PACKAGE_PREFER_CONFIG is set
2423 to TRUE.
2424 CMAKE_FIND_ROOT_PATH
2426 Semicolon-separated list of root paths to search on the filesystem.
2427 This variable is most useful when cross-compiling. CMake uses the paths
2429 in this list as alternative roots to find filesystem items with
2430 find_package(), find_library() etc.
2431 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
2433 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2434 CMAKE_SYSROOT are used by find_file() and find_path().
2435 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2437 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2438 be ignored and only the host system root will be used. If set to BOTH,
2439 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2440 be searched.
2441 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
2443 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2444 CMAKE_SYSROOT are used by find_library().
2445 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2447 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2448 be ignored and only the host system root will be used. If set to BOTH,
2449 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2450 be searched.
2451 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
2453 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2454 CMAKE_SYSROOT are used by find_package().
2455 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2457 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2458 be ignored and only the host system root will be used. If set to BOTH,
2459 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2460 be searched.
2461 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
2463 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2464 CMAKE_SYSROOT are used by find_program().
2465 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2467 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2468 be ignored and only the host system root will be used. If set to BOTH,
2469 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2470 be searched.
2471 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
2473 New in version 3.16.
2474 Controls the default behavior of the following commands for whether or
2477 not to search paths provided by cmake-specific environment variables:
2478 • find_program()
2480 • find_library()
2482 • find_file()
2484 • find_path()
2486 • find_package()
2488 This is useful in cross-compiling environments.
2490 By default this variable is not set, which is equivalent to it having a
2492 value of TRUE. Explicit options given to the above commands take
2493 precedence over this variable.
2494 See also the CMAKE_FIND_USE_CMAKE_PATH,
2496 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2497 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2498 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2499 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2500 variables.
2501 CMAKE_FIND_USE_CMAKE_PATH
2503 New in version 3.16.
2504 Controls the default behavior of the following commands for whether or
2507 not to search paths provided by cmake-specific cache variables:
2508 • find_program()
2510 • find_library()
2512 • find_file()
2514 • find_path()
2516 • find_package()
2518 This is useful in cross-compiling environments.
2520 By default this variable is not set, which is equivalent to it having a
2522 value of TRUE. Explicit options given to the above commands take
2523 precedence over this variable.
2524 See also the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2526 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2527 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2528 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2529 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2530 variables.
2531 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
2533 New in version 3.16.
2534 Controls the default behavior of the following commands for whether or
2537 not to search paths provided by platform-specific cmake variables:
2538 • find_program()
2540 • find_library()
2542 • find_file()
2544 • find_path()
2546 • find_package()
2548 This is useful in cross-compiling environments.
2550 By default this variable is not set, which is equivalent to it having a
2552 value of TRUE. Explicit options given to the above commands take
2553 precedence over this variable.
2554 See also the CMAKE_FIND_USE_CMAKE_PATH,
2556 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2557 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2558 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2559 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2560 variables.
2561 CMAKE_FIND_USE_INSTALL_PREFIX
2563 New in version 3.24.
2564 Controls the default behavior of the following commands for whether or
2567 not to search the locations in the CMAKE_INSTALL_PREFIX and
2568 CMAKE_STAGING_PREFIX variables.
2569 • find_program()
2571 • find_library()
2573 • find_file()
2575 • find_path()
2577 • find_package()
2579 This is useful in cross-compiling environments.
2581 Due to backwards compatibility with CMAKE_FIND_NO_INSTALL_PREFIX, the
2583 behavior of the find command change based on if this variable exists.
2584 ┌───────────────────┬────────────────────┬────────┐
2586 │CMAKE_FIND_USE_IN‐ │ CMAKE_FIND_NO_IN‐ │ Search │
2587 │STALL_PREFIX │ STALL_PREFIX │ │
2588 ├───────────────────┼────────────────────┼────────┤
2589 │Not Defined │ On │ NO │
2590 ├───────────────────┼────────────────────┼────────┤
2591 │Not Defined │ Off || Not Defined │ YES │
2592 └───────────────────┴────────────────────┴────────┘
2593 │Off │ On │ NO │
2595 ├───────────────────┼────────────────────┼────────┤
2596 │Off │ Off || Not Defined │ NO │
2597 ├───────────────────┼────────────────────┼────────┤
2598 │On │ On │ YES │
2599 ├───────────────────┼────────────────────┼────────┤
2600 │On │ Off || Not Defined │ YES │
2601 └───────────────────┴────────────────────┴────────┘
2602 By default this variable is not defined. Explicit options given to the
2604 above commands take precedence over this variable.
2605 See also the CMAKE_FIND_USE_CMAKE_PATH,
2607 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2608 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2609 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2610 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2611 variables.
2612 CMAKE_FIND_USE_PACKAGE_REGISTRY
2614 New in version 3.16.
2615 Controls the default behavior of the find_package() command for whether
2618 or not to search paths provided by the User Package Registry.
2619 By default this variable is not set and the behavior will fall back to
2621 that determined by the deprecated
2622 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable. If that is also not
2623 set, then find_package() will use the User Package Registry unless the
2624 NO_CMAKE_PACKAGE_REGISTRY option is provided.
2625 This variable takes precedence over
2627 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY when both are set.
2628 In some cases, for example to locate only system wide installations, it
2630 is not desirable to use the User Package Registry when searching for
2631 packages. If the CMAKE_FIND_USE_PACKAGE_REGISTRY variable is FALSE,
2632 all the find_package() commands will skip the User Package Registry as
2633 if they were called with the NO_CMAKE_PACKAGE_REGISTRY argument.
2634 See also Disabling the Package Registry and the
2636 CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2637 CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2638 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2639 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2640 CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.
2641 CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2643 New in version 3.16.
2644 Controls the default behavior of the following commands for whether or
2647 not to search paths provided by <PackageName>_ROOT variables:
2648 • find_program()
2650 • find_library()
2652 • find_file()
2654 • find_path()
2656 • find_package()
2658 By default this variable is not set, which is equivalent to it having a
2660 value of TRUE. Explicit options given to the above commands take
2661 precedence over this variable.
2662 See also the CMAKE_FIND_USE_CMAKE_PATH,
2664 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2665 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2666 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2667 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2668 CMAKE_FIND_USE_PACKAGE_REGISTRY variables.
2669 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
2671 New in version 3.16.
2672 Controls the default behavior of the following commands for whether or
2675 not to search paths provided by standard system environment variables:
2676 • find_program()
2678 • find_library()
2680 • find_file()
2682 • find_path()
2684 • find_package()
2686 This is useful in cross-compiling environments.
2688 By default this variable is not set, which is equivalent to it having a
2690 value of TRUE. Explicit options given to the above commands take
2691 precedence over this variable.
2692 See also the CMAKE_FIND_USE_CMAKE_PATH,
2694 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2695 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_PACKAGE_REGISTRY,
2696 CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and
2697 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variables.
2698 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
2700 New in version 3.16.
2701 Controls searching the System Package Registry by the find_package()
2704 command.
2705 By default this variable is not set and the behavior will fall back to
2707 that determined by the deprecated
2708 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable. If that is
2709 also not set, then find_package() will use the System Package Registry
2710 unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is provided.
2711 This variable takes precedence over
2713 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY when both are set.
2714 In some cases, for example to locate only user specific installations,
2716 it is not desirable to use the System Package Registry when searching
2717 for packages. If the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable is
2718 FALSE, all the find_package() commands will skip the System Package
2719 Registry as if they were called with the NO_CMAKE_SYSTEM_PACKAGE_REG‐
2720 ISTRY argument.
2721 See also Disabling the Package Registry.
2723 See also the CMAKE_FIND_USE_CMAKE_PATH,
2725 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2726 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2727 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2728 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2729 variables.
2730 CMAKE_FRAMEWORK_PATH
2732 Semicolon-separated list of directories specifying a search path for
2733 macOS frameworks used by the find_library(), find_package(),
2734 find_path(), and find_file() commands.
2735 CMAKE_IGNORE_PATH
2737 Semicolon-separated list of directories to be ignored by the various
2738 find...() commands.
2739 For find_program(), find_library(), find_file(), and find_path(), any
2741 file found in one of the listed directories will be ignored. The listed
2742 directories do not apply recursively, so any subdirectories to be ig‐
2743 nored must also be explicitly listed. CMAKE_IGNORE_PATH does not af‐
2744 fect the search prefixes used by these four commands. To ignore indi‐
2745 vidual paths under a search prefix (e.g. bin, include, lib, etc.), each
2746 path must be listed in CMAKE_IGNORE_PATH as a full absolute path.
2747 CMAKE_IGNORE_PREFIX_PATH provides a more appropriate way to ignore a
2748 whole search prefix.
2749 find_package() is also affected by CMAKE_IGNORE_PATH, but only for Con‐
2751 fig mode searches. Any <Name>Config.cmake or <name>-config.cmake file
2752 found in one of the specified directories will be ignored. In addition,
2753 any search prefix found in CMAKE_IGNORE_PATH will be skipped for back‐
2754 ward compatibility reasons, but new code should prefer to use
2755 CMAKE_IGNORE_PREFIX_PATH to ignore prefixes instead.
2756 Ignoring search locations can be useful in cross-compiling environments
2758 where some system directories contain incompatible but possibly link‐
2759 able libraries. For example, on cross-compiled cluster environments,
2760 this allows a user to ignore directories containing libraries meant for
2761 the front-end machine.
2762 By default, CMAKE_IGNORE_PATH is empty. It is intended to be set by the
2764 project or the end user.
2765 See also the following variables:
2767 • CMAKE_IGNORE_PREFIX_PATH
2769 • CMAKE_SYSTEM_IGNORE_PATH
2771 • CMAKE_PREFIX_PATH
2773 • CMAKE_LIBRARY_PATH
2775 • CMAKE_INCLUDE_PATH
2777 • CMAKE_PROGRAM_PATH
2779 CMAKE_IGNORE_PREFIX_PATH
2781 New in version 3.23.
2782 Semicolon-separated list of search prefixes to be ignored by the
2785 find_program(), find_library(), find_file(), and find_path() commands.
2786 The prefixes are also ignored by the Config mode of the find_package()
2787 command (Module mode is unaffected). To ignore specific directories
2788 instead, see CMAKE_IGNORE_PATH.
2789 Ignoring search locations can be useful in cross-compiling environments
2791 where some system directories contain incompatible but possibly link‐
2792 able libraries. For example, on cross-compiled cluster environments,
2793 this allows a user to ignore directories containing libraries meant for
2794 the front-end machine.
2795 By default, CMAKE_IGNORE_PREFIX_PATH is empty. It is intended to be set
2797 by the project or the end user.
2798 See also the following variables:
2800 • CMAKE_IGNORE_PATH
2802 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
2804 • CMAKE_PREFIX_PATH
2806 • CMAKE_LIBRARY_PATH
2808 • CMAKE_INCLUDE_PATH
2810 • CMAKE_PROGRAM_PATH
2812 CMAKE_INCLUDE_DIRECTORIES_BEFORE
2814 Whether to append or prepend directories by default in
2815 include_directories().
2816 This variable affects the default behavior of the include_directories()
2818 command. Setting this variable to ON is equivalent to using the BEFORE
2819 option in all uses of that command.
2820 CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
2822 Whether to force prepending of project include directories.
2823 This variable affects the order of include directories generated in
2825 compiler command lines. If set to ON, it causes the CMAKE_SOURCE_DIR
2826 and the CMAKE_BINARY_DIR to appear first.
2827 CMAKE_INCLUDE_PATH
2829 Semicolon-separated list of directories specifying a search path for
2830 the find_file() and find_path() commands. By default it is empty, it
2831 is intended to be set by the project. See also
2832 CMAKE_SYSTEM_INCLUDE_PATH and CMAKE_PREFIX_PATH.
2833 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
2835 Default component used in install() commands.
2836 If an install() command is used without the COMPONENT argument, these
2838 files will be grouped into a default component. The name of this de‐
2839 fault install component will be taken from this variable. It defaults
2840 to Unspecified.
2841 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2843 New in version 3.11.
2844 Default permissions for directories created implicitly during installa‐
2847 tion of files by install() and file(INSTALL).
2848 If make install is invoked and directories are implicitly created they
2850 get permissions set by CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2851 variable or platform specific default permissions if the variable is
2852 not set.
2853 Implicitly created directories are created if they are not explicitly
2855 installed by install() command but are needed to install a file on a
2856 certain path. Example of such locations are directories created due to
2857 the setting of CMAKE_INSTALL_PREFIX.
2858 Expected content of the CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2860 variable is a list of permissions that can be used by install() command
2861 PERMISSIONS section.
2862 Example usage:
2864 set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2866 OWNER_READ
2867 OWNER_WRITE
2868 OWNER_EXECUTE
2869 GROUP_READ
2870 )
2871 CMAKE_INSTALL_MESSAGE
2873 New in version 3.1.
2874 Specify verbosity of installation script code generated by the
2877 install() command (using the file(INSTALL) command). For paths that
2878 are newly installed or updated, installation may print lines like:
2879 -- Installing: /some/destination/path
2881 For paths that are already up to date, installation may print lines
2883 like:
2884 -- Up-to-date: /some/destination/path
2886 The CMAKE_INSTALL_MESSAGE variable may be set to control which messages
2888 are printed:
2889 ALWAYS Print both Installing and Up-to-date messages.
2891 LAZY Print Installing but not Up-to-date messages.
2893 NEVER Print neither Installing nor Up-to-date messages.
2895 Other values have undefined behavior and may not be diagnosed.
2897 If this variable is not set, the default behavior is ALWAYS.
2899 CMAKE_INSTALL_PREFIX
2901 Install directory used by install().
2902 If make install is invoked or INSTALL is built, this directory is
2904 prepended onto all install directories. This variable defaults to
2905 /usr/local on UNIX and c:/Program Files/${PROJECT_NAME} on Windows.
2906 See CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT for how a project might
2907 choose its own default.
2908 On UNIX one can use the DESTDIR mechanism in order to relocate the
2910 whole installation to a staging area. See the DESTDIR environment
2911 variable for more information.
2912 The installation prefix is also added to CMAKE_SYSTEM_PREFIX_PATH so
2914 that find_package(), find_program(), find_library(), find_path(), and
2915 find_file() will search the prefix for other software. This behavior
2916 can be disabled by setting the CMAKE_FIND_NO_INSTALL_PREFIX to TRUE be‐
2917 fore the first project() invocation.
2918 NOTE:
2920 Use the GNUInstallDirs module to provide GNU-style options for the
2921 layout of directories within the installation.
2922 The CMAKE_INSTALL_PREFIX may be defined when configuring a build tree
2924 to set its installation prefix. Or, when using the cmake(1) com‐
2925 mand-line tool's --install mode, one may specify a different prefix us‐
2926 ing the --prefix option:
2927 cmake --install . --prefix /my/install/prefix
2929 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
2931 New in version 3.7.1.
2932 CMake sets this variable to a TRUE value when the CMAKE_INSTALL_PREFIX
2935 has just been initialized to its default value, typically on the first
2936 run of CMake within a new build tree. This can be used by project code
2937 to change the default without overriding a user-provided value:
2938 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
2940 set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
2941 endif()
2942 CMAKE_LIBRARY_PATH
2944 Semicolon-separated list of directories specifying a search path for
2945 the find_library() command. By default it is empty, it is intended to
2946 be set by the project. See also CMAKE_SYSTEM_LIBRARY_PATH and
2947 CMAKE_PREFIX_PATH.
2948 CMAKE_LINK_DIRECTORIES_BEFORE
2950 New in version 3.13.
2951 Whether to append or prepend directories by default in
2954 link_directories().
2955 This variable affects the default behavior of the link_directories()
2957 command. Setting this variable to ON is equivalent to using the BEFORE
2958 option in all uses of that command.
2959 CMAKE_LINK_LIBRARIES_ONLY_TARGETS
2961 New in version 3.23.
2962 Set this variable to initialize the LINK_LIBRARIES_ONLY_TARGETS prop‐
2965 erty of non-imported targets when they are created. Setting it to true
2966 enables an additional check that all items named by
2967 target_link_libraries() that can be target names are actually names of
2968 existing targets. See the target property documentation for details.
2969 CMAKE_MAXIMUM_RECURSION_DEPTH
2971 New in version 3.14.
2972 Maximum recursion depth for CMake scripts. It is intended to be set on
2975 the command line with -DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>, or within
2976 CMakeLists.txt by projects that require a large recursion depth.
2977 Projects that set this variable should provide the user with a way to
2978 override it. For example:
2979 # About to perform deeply recursive actions
2981 if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
2982 set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
2983 endif()
2984 If it is not set, or is set to a non-integer value, a sensible default
2986 limit is used. If the recursion limit is reached, the script terminates
2987 immediately with a fatal error.
2988 Calling any of the following commands increases the recursion depth:
2990 • include()
2992 • find_package()
2994 • add_subdirectory()
2996 • try_compile()
2998 • ctest_read_custom_files()
3000 • ctest_run_script() (unless NEW_PROCESS is specified)
3002 • User-defined function()'s and macro()'s (note that function() and
3004 macro() themselves don't increase recursion depth)
3005 • Reading or writing variables that are being watched by a
3007 variable_watch()
3008 CMAKE_MESSAGE_CONTEXT
3010 New in version 3.17.
3011 When enabled by the cmake --log-context command line option or the
3014 CMAKE_MESSAGE_CONTEXT_SHOW variable, the message() command converts the
3015 CMAKE_MESSAGE_CONTEXT list into a dot-separated string surrounded by
3016 square brackets and prepends it to each line for messages of log levels
3017 NOTICE and below.
3018 For logging contexts to work effectively, projects should generally AP‐
3020 PEND and POP_BACK an item to the current value of CMAKE_MESSAGE_CONTEXT
3021 rather than replace it. Projects should not assume the message context
3022 at the top of the source tree is empty, as there are scenarios where
3023 the context might have already been set (e.g. hierarchical projects).
3024 WARNING:
3026 Valid context names are restricted to anything that could be used as
3027 a CMake variable name. All names that begin with an underscore or
3028 the string cmake_ are also reserved for use by CMake and should not
3029 be used by projects.
3030 Example:
3032 function(bar)
3034 list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
3035 message(VERBOSE "bar VERBOSE message")
3036 endfunction()
3037 function(baz)
3039 list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
3040 message(DEBUG "baz DEBUG message")
3041 endfunction()
3042 function(foo)
3044 list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
3045 bar()
3046 message(TRACE "foo TRACE message")
3047 baz()
3048 endfunction()
3049 list(APPEND CMAKE_MESSAGE_CONTEXT "top")
3051 message(VERBOSE "Before `foo`")
3053 foo()
3054 message(VERBOSE "After `foo`")
3055 list(POP_BACK CMAKE_MESSAGE_CONTEXT)
3057 Which results in the following output:
3059 -- [top] Before `foo`
3061 -- [top.foo.bar] bar VERBOSE message
3062 -- [top.foo] foo TRACE message
3063 -- [top.foo.baz] baz DEBUG message
3064 -- [top] After `foo`
3065 CMAKE_MESSAGE_CONTEXT_SHOW
3067 New in version 3.17.
3068 Setting this variable to true enables showing a context with each line
3071 logged by the message() command (see CMAKE_MESSAGE_CONTEXT for how the
3072 context itself is specified).
3073 This variable is an alternative to providing the --log-context option
3075 on the cmake command line. Whereas the command line option will apply
3076 only to that one CMake run, setting CMAKE_MESSAGE_CONTEXT_SHOW to true
3077 as a cache variable will ensure that subsequent CMake runs will con‐
3078 tinue to show the message context.
3079 Projects should not set CMAKE_MESSAGE_CONTEXT_SHOW. It is intended for
3081 users so that they may control whether or not to include context with
3082 messages.
3083 CMAKE_MESSAGE_INDENT
3085 New in version 3.16.
3086 The message() command joins the strings from this list and for log lev‐
3089 els of NOTICE and below, it prepends the resultant string to each line
3090 of the message.
3091 Example:
3093 list(APPEND listVar one two three)
3095 message(VERBOSE [[Collected items in the "listVar":]])
3097 list(APPEND CMAKE_MESSAGE_INDENT " ")
3098 foreach(item IN LISTS listVar)
3100 message(VERBOSE ${item})
3101 endforeach()
3102 list(POP_BACK CMAKE_MESSAGE_INDENT)
3104 message(VERBOSE "No more indent")
3105 Which results in the following output:
3107 -- Collected items in the "listVar":
3109 -- one
3110 -- two
3111 -- three
3112 -- No more indent
3113 CMAKE_MESSAGE_LOG_LEVEL
3115 New in version 3.17.
3116 When set, this variable specifies the logging level used by the
3119 message() command. Valid values are the same as those for the
3120 --log-level command line option of the cmake(1) program. If this vari‐
3121 able is set and the --log-level command line option is given, the com‐
3122 mand line option takes precedence.
3123 The main advantage to using this variable is to make a log level per‐
3125 sist between CMake runs. Setting it as a cache variable will ensure
3126 that subsequent CMake runs will continue to use the chosen log level.
3127 Projects should not set this variable, it is intended for users so that
3129 they may control the log level according to their own needs.
3130 New in version 3.25: See the cmake_language() cmake_language command
3132 for a way to query the current message logging level.
3133 CMAKE_MFC_FLAG
3136 Use the MFC library for an executable or dll.
3137 Enables the use of the Microsoft Foundation Classes (MFC). It should
3139 be set to 1 for the static MFC library, and 2 for the shared MFC li‐
3140 brary. This is used in Visual Studio project files.
3141 Usage example:
3143 add_definitions(-D_AFXDLL)
3145 set(CMAKE_MFC_FLAG 2)
3146 add_executable(CMakeSetup WIN32 ${SRCS})
3147 Contents of CMAKE_MFC_FLAG may use generator expressions.
3149 CMAKE_MODULE_PATH
3151 Semicolon-separated list of directories specifying a search path for
3152 CMake modules to be loaded by the include() or find_package() commands
3153 before checking the default modules that come with CMake. By default
3154 it is empty, it is intended to be set by the project.
3155 CMAKE_POLICY_DEFAULT_CMP<NNNN>
3157 Default for CMake Policy CMP<NNNN> when it is otherwise left unset.
3158 Commands cmake_minimum_required(VERSION) and cmake_policy(VERSION) by
3160 default leave policies introduced after the given version unset. Set
3161 CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to specify the default for
3162 policy CMP<NNNN>, where <NNNN> is the policy number.
3163 This variable should not be set by a project in CMake code as a way to
3165 set its own policies; use cmake_policy(SET) instead. This variable is
3166 meant to externally set policies for which a project has not itself
3167 been updated:
3168 • Users running CMake may set this variable in the cache (e.g. -DC‐
3170 MAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>). Set it to OLD to quiet a
3171 policy warning while using old behavior or to NEW to try building the
3172 project with new behavior.
3173 • Projects may set this variable before a call to add_subdirectory()
3175 that adds a third-party project in order to set its policies without
3176 modifying third-party code.
3177 CMAKE_POLICY_WARNING_CMP<NNNN>
3179 Explicitly enable or disable the warning when CMake Policy CMP<NNNN>
3180 has not been set explicitly by cmake_policy() or implicitly by
3181 cmake_minimum_required(). This is meaningful only for the policies that
3182 do not warn by default:
3183 • CMAKE_POLICY_WARNING_CMP0025 controls the warning for policy CMP0025.
3185 • CMAKE_POLICY_WARNING_CMP0047 controls the warning for policy CMP0047.
3187 • CMAKE_POLICY_WARNING_CMP0056 controls the warning for policy CMP0056.
3189 • CMAKE_POLICY_WARNING_CMP0060 controls the warning for policy CMP0060.
3191 • CMAKE_POLICY_WARNING_CMP0065 controls the warning for policy CMP0065.
3193 • CMAKE_POLICY_WARNING_CMP0066 controls the warning for policy CMP0066.
3195 • CMAKE_POLICY_WARNING_CMP0067 controls the warning for policy CMP0067.
3197 • CMAKE_POLICY_WARNING_CMP0082 controls the warning for policy CMP0082.
3199 • CMAKE_POLICY_WARNING_CMP0089 controls the warning for policy CMP0089.
3201 • CMAKE_POLICY_WARNING_CMP0102 controls the warning for policy CMP0102.
3203 • CMAKE_POLICY_WARNING_CMP0112 controls the warning for policy CMP0112.
3205 • CMAKE_POLICY_WARNING_CMP0116 controls the warning for policy CMP0116.
3207 • CMAKE_POLICY_WARNING_CMP0126 controls the warning for policy CMP0126.
3209 • CMAKE_POLICY_WARNING_CMP0128 controls the warning for policy CMP0128.
3211 • CMAKE_POLICY_WARNING_CMP0129 controls the warning for policy CMP0129.
3213 • CMAKE_POLICY_WARNING_CMP0133 controls the warning for policy CMP0133.
3215 This variable should not be set by a project in CMake code. Project
3217 developers running CMake may set this variable in their cache to enable
3218 the warning (e.g. -DCMAKE_POLICY_WARNING_CMP<NNNN>=ON). Alternatively,
3219 running cmake(1) with the --debug-output, --trace, or --trace-expand
3220 option will also enable the warning.
3221 CMAKE_PREFIX_PATH
3223 Semicolon-separated list of directories specifying installation pre‐
3224 fixes to be searched by the find_package(), find_program(),
3225 find_library(), find_file(), and find_path() commands. Each command
3226 will add appropriate subdirectories (like bin, lib, or include) as
3227 specified in its own documentation.
3228 By default this is empty. It is intended to be set by the project.
3230 See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH,
3232 CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH, and CMAKE_IGNORE_PATH.
3233 CMAKE_PROGRAM_PATH
3235 Semicolon-separated list of directories specifying a search path for
3236 the find_program() command. By default it is empty, it is intended to
3237 be set by the project. See also CMAKE_SYSTEM_PROGRAM_PATH and
3238 CMAKE_PREFIX_PATH.
3239 CMAKE_PROJECT_INCLUDE
3241 New in version 3.15.
3242 A CMake language file or module to be included as the last step of all
3245 project() command calls. This is intended for injecting custom code
3246 into project builds without modifying their source. See Code Injection
3247 for a more detailed discussion of files potentially included during a
3248 project() call.
3249 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3251 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3252 CMAKE_PROJECT_INCLUDE_BEFORE, and CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3253 variables.
3254 CMAKE_PROJECT_INCLUDE_BEFORE
3256 New in version 3.15.
3257 A CMake language file or module to be included as the first step of all
3260 project() command calls. This is intended for injecting custom code
3261 into project builds without modifying their source. See Code Injection
3262 for a more detailed discussion of files potentially included during a
3263 project() call.
3264 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3266 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, CMAKE_PROJECT_INCLUDE, and
3267 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3268 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
3270 A CMake language file or module to be included as the last step of any
3271 project() command calls that specify <PROJECT-NAME> as the project
3272 name. This is intended for injecting custom code into project builds
3273 without modifying their source. See Code Injection for a more detailed
3274 discussion of files potentially included during a project() call.
3275 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3277 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3278 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3279 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
3281 New in version 3.17.
3282 A CMake language file or module to be included as the first step of any
3285 project() command calls that specify <PROJECT-NAME> as the project
3286 name. This is intended for injecting custom code into project builds
3287 without modifying their source. See Code Injection for a more detailed
3288 discussion of files potentially included during a project() call.
3289 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3291 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3292 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3293 CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3295 New in version 3.24.
3296 Semicolon-separated list of CMake language files to include as part of
3299 the very first project() call. The files will be included immediately
3300 after the toolchain file has been read (if one is specified) and plat‐
3301 form variables have been set, but before any languages have been en‐
3302 abled. Therefore, language-specific variables, including things like
3303 CMAKE_<LANG>_COMPILER, might not be set. See Code Injection for a more
3304 detailed discussion of files potentially included during a project()
3305 call.
3306 This variable is intended for specifying files that perform one-time
3308 setup for the build. It provides an injection point for things like
3309 configuring package managers, adding logic the user shares between
3310 projects (e.g. defining their own custom build types), and so on. It is
3311 primarily for users to add things specific to their environment, but
3312 not for specifying the toolchain details (use CMAKE_TOOLCHAIN_FILE for
3313 that).
3314 By default, this variable is empty. It is intended to be set by the
3316 user.
3317 See also the CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE,
3319 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, and
3320 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables.
3321 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>
3323 New in version 3.22.
3324 Variable for making find_package() call REQUIRED.
3327 Every non-REQUIRED find_package() call in a project can be turned into
3329 REQUIRED by setting the variable CMAKE_REQUIRE_FIND_PACKAGE_<Package‐
3330 Name> to TRUE. This can be used to assert assumptions about build en‐
3331 vironment and to ensure the build will fail early if they do not hold.
3332 See also the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable.
3334 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
3336 Don't make the install target depend on the all target.
3337 By default, the install target depends on the all target. This has the
3339 effect, that when make install is invoked or INSTALL is built, first
3340 the all target is built, then the installation starts. If
3341 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is set to TRUE, this dependency is
3342 not created, so the installation process will start immediately, inde‐
3343 pendent from whether the project has been completely built or not.
3344 CMAKE_STAGING_PREFIX
3346 This variable may be set to a path to install to when cross-compiling.
3347 This can be useful if the path in CMAKE_SYSROOT is read-only, or other‐
3348 wise should remain pristine.
3349 The CMAKE_STAGING_PREFIX location is also used as a search prefix by
3351 the find_* commands. This can be controlled by setting the
3352 CMAKE_FIND_NO_INSTALL_PREFIX variable.
3353 If any RPATH/RUNPATH entries passed to the linker contain the
3355 CMAKE_STAGING_PREFIX, the matching path fragments are replaced with the
3356 CMAKE_INSTALL_PREFIX.
3357 CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3359 New in version 3.8.
3360 This variable contains a list of env vars as a list of tokens with the
3363 syntax var=value.
3364 Example:
3366 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3368 "FOO=FOO1\;FOO2\;FOON"
3369 "BAR=BAR1\;BAR2\;BARN"
3370 "BAZ=BAZ1\;BAZ2\;BAZN"
3371 "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN"
3372 "VALID="
3373 )
3374 In case of malformed variables CMake will fail:
3376 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3378 "THIS_IS_NOT_VALID"
3379 )
3380 CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
3382 New in version 3.8.
3383 If this variable evaluates to ON at the end of the top-level CMake‐
3386 Lists.txt file, the Sublime Text 2 extra generator excludes the build
3387 tree from the .sublime-project if it is inside the source tree.
3388 CMAKE_SUPPRESS_REGENERATION
3390 New in version 3.12.
3391 If CMAKE_SUPPRESS_REGENERATION is OFF, which is default, then CMake
3394 adds a special target on which all other targets depend that checks the
3395 build system and optionally re-runs CMake to regenerate the build sys‐
3396 tem when the target specification source changes.
3397 If this variable evaluates to ON at the end of the top-level CMake‐
3399 Lists.txt file, CMake will not add the regeneration target to the build
3400 system or perform any build system checks.
3401 CMAKE_SYSROOT
3403 Path to pass to the compiler in the --sysroot flag.
3404 The CMAKE_SYSROOT content is passed to the compiler in the --sysroot
3406 flag, if supported. The path is also stripped from the RPATH/RUNPATH
3407 if necessary on installation. The CMAKE_SYSROOT is also used to prefix
3408 paths searched by the find_* commands.
3409 This variable may only be set in a toolchain file specified by the
3411 CMAKE_TOOLCHAIN_FILE variable.
3412 See also the CMAKE_SYSROOT_COMPILE and CMAKE_SYSROOT_LINK variables.
3414 CMAKE_SYSROOT_COMPILE
3416 New in version 3.9.
3417 Path to pass to the compiler in the --sysroot flag when compiling
3420 source files. This is the same as CMAKE_SYSROOT but is used only for
3421 compiling sources and not linking.
3422 This variable may only be set in a toolchain file specified by the
3424 CMAKE_TOOLCHAIN_FILE variable.
3425 CMAKE_SYSROOT_LINK
3427 New in version 3.9.
3428 Path to pass to the compiler in the --sysroot flag when linking. This
3431 is the same as CMAKE_SYSROOT but is used only for linking and not com‐
3432 piling sources.
3433 This variable may only be set in a toolchain file specified by the
3435 CMAKE_TOOLCHAIN_FILE variable.
3436 CMAKE_SYSTEM_APPBUNDLE_PATH
3438 New in version 3.4.
3439 Search path for macOS application bundles used by the find_program(),
3442 and find_package() commands. By default it contains the standard di‐
3443 rectories for the current system. It is not intended to be modified by
3444 the project, use CMAKE_APPBUNDLE_PATH for this.
3445 CMAKE_SYSTEM_FRAMEWORK_PATH
3447 New in version 3.4.
3448 Search path for macOS frameworks used by the find_library(),
3451 find_package(), find_path(), and find_file() commands. By default it
3452 contains the standard directories for the current system. It is not
3453 intended to be modified by the project, use CMAKE_FRAMEWORK_PATH for
3454 this.
3455 CMAKE_SYSTEM_IGNORE_PATH
3457 Semicolon-separated list of directories to be ignored by the various
3458 find...() commands.
3459 For find_program(), find_library(), find_file(), and find_path(), any
3461 file found in one of the listed directories will be ignored. The listed
3462 directories do not apply recursively, so any subdirectories to be ig‐
3463 nored must also be explicitly listed. CMAKE_SYSTEM_IGNORE_PATH does
3464 not affect the search prefixes used by these four commands. To ignore
3465 individual paths under a search prefix (e.g. bin, include, lib, etc.),
3466 each path must be listed in CMAKE_SYSTEM_IGNORE_PATH as a full absolute
3467 path. CMAKE_SYSTEM_IGNORE_PREFIX_PATH provides a more appropriate way
3468 to ignore a whole search prefix.
3469 find_package() is also affected by CMAKE_SYSTEM_IGNORE_PATH, but only
3471 for Config mode searches. Any <Name>Config.cmake or <name>-config.cmake
3472 file found in one of the specified directories will be ignored. In ad‐
3473 dition, any search prefix found in CMAKE_SYSTEM_IGNORE_PATH will be
3474 skipped for backward compatibility reasons, but new code should prefer
3475 to use CMAKE_SYSTEM_IGNORE_PREFIX_PATH to ignore prefixes instead.
3476 Ignoring search locations can be useful in cross-compiling environments
3478 where some system directories contain incompatible but possibly link‐
3479 able libraries. For example, on cross-compiled cluster environments,
3480 this allows a user to ignore directories containing libraries meant for
3481 the front-end machine.
3482 CMAKE_SYSTEM_IGNORE_PATH is populated by CMake as part of its platform
3484 and toolchain setup. Its purpose is to ignore locations containing in‐
3485 compatible binaries meant for the host rather than the target platform.
3486 The project or end user should not modify this variable, they should
3487 use CMAKE_IGNORE_PATH instead.
3488 See also the following variables:
3490 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3492 • CMAKE_SYSTEM_PREFIX_PATH
3494 • CMAKE_SYSTEM_LIBRARY_PATH
3496 • CMAKE_SYSTEM_INCLUDE_PATH
3498 • CMAKE_SYSTEM_PROGRAM_PATH
3500 CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3502 New in version 3.23.
3503 Semicolon-separated list of search prefixes to be ignored by the
3506 find_program(), find_library(), find_file(), and find_path() commands.
3507 The prefixes are also ignored by the Config mode of the find_package()
3508 command (Module mode is unaffected). To ignore specific directories
3509 instead, see CMAKE_SYSTEM_IGNORE_PATH.
3510 Ignoring search locations can be useful in cross-compiling environments
3512 where some system directories contain incompatible but possibly link‐
3513 able libraries. For example, on cross-compiled cluster environments,
3514 this allows a user to ignore directories containing libraries meant for
3515 the front-end machine.
3516 CMAKE_SYSTEM_IGNORE_PREFIX_PATH is populated by CMake as part of its
3518 platform and toolchain setup. Its purpose is to ignore locations con‐
3519 taining incompatible binaries meant for the host rather than the target
3520 platform. The project or end user should not modify this variable,
3521 they should use CMAKE_IGNORE_PREFIX_PATH instead.
3522 See also the following variables:
3524 • CMAKE_SYSTEM_IGNORE_PATH
3526 • CMAKE_SYSTEM_PREFIX_PATH
3528 • CMAKE_SYSTEM_LIBRARY_PATH
3530 • CMAKE_SYSTEM_INCLUDE_PATH
3532 • CMAKE_SYSTEM_PROGRAM_PATH
3534 CMAKE_SYSTEM_INCLUDE_PATH
3536 Semicolon-separated list of directories specifying a search path for
3537 the find_file() and find_path() commands. By default this contains the
3538 standard directories for the current system. It is not intended to be
3539 modified by the project; use CMAKE_INCLUDE_PATH for this. See also
3540 CMAKE_SYSTEM_PREFIX_PATH.
3541 CMAKE_SYSTEM_LIBRARY_PATH
3543 Semicolon-separated list of directories specifying a search path for
3544 the find_library() command. By default this contains the standard di‐
3545 rectories for the current system. It is not intended to be modified by
3546 the project; use CMAKE_LIBRARY_PATH for this. See also
3547 CMAKE_SYSTEM_PREFIX_PATH.
3548 CMAKE_SYSTEM_PREFIX_PATH
3550 Semicolon-separated list of directories specifying installation pre‐
3551 fixes to be searched by the find_package(), find_program(),
3552 find_library(), find_file(), and find_path() commands. Each command
3553 will add appropriate subdirectories (like bin, lib, or include) as
3554 specified in its own documentation.
3555 By default this contains the system directories for the current system,
3557 the CMAKE_INSTALL_PREFIX, and the CMAKE_STAGING_PREFIX. The installa‐
3558 tion and staging prefixes may be excluded by setting the
3559 CMAKE_FIND_NO_INSTALL_PREFIX variable before the first project() invo‐
3560 cation.
3561 The system directories that are contained in CMAKE_SYSTEM_PREFIX_PATH
3563 are locations that typically include installed software. An example be‐
3564 ing /usr/local for UNIX based platforms. In addition to standard plat‐
3565 form locations, CMake will also add values to CMAKE_SYSTEM_PREFIX_PATH
3566 based on environment variables. The environment variables and search
3567 locations that CMake uses may evolve over time, as platforms and their
3568 conventions also evolve. The following provides an indicative list of
3569 environment variables and locations that CMake searches, but they are
3570 subject to change:
3571 CrayLinuxEnvironment:
3573 • ENV{SYSROOT_DIR}/
3575 • ENV{SYSROOT_DIR}/usr
3577 • ENV{SYSROOT_DIR}/usr/local
3579 Darwin:
3581 • ENV{SDKROOT}/usr When CMAKE_OSX_SYSROOT is not explicitly
3583 specified.
3584 OpenBSD:
3586 • ENV{LOCALBASE}
3588 Unix:
3590 • ENV{CONDA_PREFIX} when using a conda compiler
3592 Windows:
3594 • ENV{ProgramW6432}
3596 • ENV{ProgramFiles}
3598 • ENV{ProgramFiles(x86)}
3600 • ENV{SystemDrive}/Program Files
3602 • ENV{SystemDrive}/Program Files (x86)
3604 CMAKE_SYSTEM_PREFIX_PATH is not intended to be modified by the project;
3606 use CMAKE_PREFIX_PATH for this.
3607 See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
3609 CMAKE_SYSTEM_PROGRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.
3610 CMAKE_SYSTEM_PROGRAM_PATH
3612 Semicolon-separated list of directories specifying a search path for
3613 the find_program() command. By default this contains the standard di‐
3614 rectories for the current system. It is not intended to be modified by
3615 the project; use CMAKE_PROGRAM_PATH for this. See also
3616 CMAKE_SYSTEM_PREFIX_PATH.
3617 CMAKE_TLS_CAINFO
3619 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3620 mands' TLS_CAINFO options. It is unset by default.
3621 This variable is also used by the ExternalProject and FetchContent mod‐
3623 ules for internal calls to file(DOWNLOAD).
3624 CMAKE_TLS_VERIFY
3626 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3627 mands' TLS_VERIFY options. If not set, the default is off.
3628 This variable is also used by the ExternalProject and FetchContent mod‐
3630 ules for internal calls to file(DOWNLOAD).
3631 TLS verification can help provide confidence that one is connecting to
3633 the desired server. When downloading known content, one should also
3634 use file hashes to verify it.
3635 set(CMAKE_TLS_VERIFY TRUE)
3637 CMAKE_USER_MAKE_RULES_OVERRIDE
3639 Specify a CMake file that overrides platform information.
3640 CMake loads the specified file while enabling support for each language
3642 from either the project() or enable_language() commands. It is loaded
3643 after CMake's builtin compiler and platform information modules have
3644 been loaded but before the information is used. The file may set plat‐
3645 form information variables to override CMake's defaults. See
3646 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> for the language-specific version
3647 of this variable.
3648 This feature is intended for use only in overriding information vari‐
3650 ables that must be set before CMake builds its first test project to
3651 check that the compiler for a language works. It should not be used to
3652 load a file in cases that a normal include() will work. Use it only as
3653 a last resort for behavior that cannot be achieved any other way. For
3654 example, one may set the CMAKE_C_FLAGS_INIT variable to change the de‐
3655 fault value used to initialize the CMAKE_C_FLAGS variable before it is
3656 cached. The override file should NOT be used to set anything that
3657 could be set after languages are enabled, such as variables like
3658 CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries.
3659 Information set in the file will be used for try_compile() and
3660 try_run() builds too.
3661 CMAKE_WARN_DEPRECATED
3663 Whether to issue warnings for deprecated functionality.
3664 If not FALSE, use of deprecated functionality will issue warnings. If
3666 this variable is not set, CMake behaves as if it were set to TRUE.
3667 When running cmake(1), this option can be enabled with the -Wdeprecated
3669 option, or disabled with the -Wno-deprecated option.
3670 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
3672 Ask cmake_install.cmake script to warn each time a file with absolute
3673 INSTALL DESTINATION is encountered.
3674 This variable is used by CMake-generated cmake_install.cmake scripts.
3676 If one sets this variable to ON while running the script, it may get
3677 warning messages from the script.
3678 CMAKE_XCODE_GENERATE_SCHEME
3680 New in version 3.9.
3681 If enabled, the Xcode generator will generate schema files. These are
3684 useful to invoke analyze, archive, build-for-testing and test actions
3685 from the command line.
3686 This variable initializes the XCODE_GENERATE_SCHEME target property on
3688 all targets.
3689 CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
3691 New in version 3.11.
3692 If enabled, the Xcode generator will generate only a single Xcode
3695 project file for the topmost project() command instead of generating
3696 one for every project() command.
3697 This could be useful to speed up the CMake generation step for large
3699 projects and to work-around a bug in the ZERO_CHECK logic.
3700 CMAKE_XCODE_LINK_BUILD_PHASE_MODE
3702 New in version 3.19.
3703 This variable is used to initialize the XCODE_LINK_BUILD_PHASE_MODE
3706 property on targets. It affects the methods that the Xcode generator
3707 uses to link different kinds of libraries. Its default value is NONE.
3708 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
3710 New in version 3.13.
3711 Whether to enable Address Sanitizer in the Diagnostics section of the
3714 generated Xcode scheme.
3715 This variable initializes the XCODE_SCHEME_ADDRESS_SANITIZER property
3717 on all targets.
3718 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3720 to see all Xcode schema related properties.
3721 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
3723 New in version 3.13.
3724 Whether to enable Detect use of stack after return in the Diagnostics
3727 section of the generated Xcode scheme.
3728 This variable initializes the
3730 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN property on all tar‐
3731 gets.
3732 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3734 to see all Xcode schema related properties.
3735 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3737 New in version 3.16.
3738 Whether to enable Allow debugging when using document Versions Browser
3741 in the Options section of the generated Xcode scheme.
3742 This variable initializes the XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3744 property on all targets.
3745 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3747 to see all Xcode schema related properties.
3748 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3750 New in version 3.13.
3751 Whether to disable the Main Thread Checker in the Diagnostics section
3754 of the generated Xcode scheme.
3755 This variable initializes the XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3757 property on all targets.
3758 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3760 to see all Xcode schema related properties.
3761 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
3763 New in version 3.13.
3764 Whether to enable Dynamic Library Loads in the Diagnostics section of
3767 the generated Xcode scheme.
3768 This variable initializes the XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS prop‐
3770 erty on all targets.
3771 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3773 to see all Xcode schema related properties.
3774 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3776 New in version 3.13.
3777 Whether to enable Dynamic Linker API usage in the Diagnostics section
3780 of the generated Xcode scheme.
3781 This variable initializes the XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3783 property on all targets.
3784 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3786 to see all Xcode schema related properties.
3787 CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3789 New in version 3.25.
3790 Property value for Metal: API Validation in the Options section of the
3793 generated Xcode scheme.
3794 This variable initializes the XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3796 property on all targets.
3797 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3799 to see all Xcode schema related properties.
3800 CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
3802 New in version 3.23.
3803 Property value for GPU Frame Capture in the Options section of the gen‐
3806 erated Xcode scheme. Example values are Metal and Disabled.
3807 This variable initializes the
3809 XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE property on all targets.
3810 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3812 to see all Xcode schema related properties.
3813 CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
3815 New in version 3.25.
3816 Property value for Metal: Shader Validation in the Options section of
3819 the generated Xcode scheme.
3820 This variable initializes the XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
3822 property on all targets.
3823 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3825 to see all Xcode schema related properties.
3826 CMAKE_XCODE_SCHEME_ENVIRONMENT
3828 New in version 3.17.
3829 Specify environment variables that should be added to the Arguments
3832 section of the generated Xcode scheme.
3833 If set to a list of environment variables and values of the form MY‐
3835 VAR=value those environment variables will be added to the scheme.
3836 This variable initializes the XCODE_SCHEME_ENVIRONMENT property on all
3838 targets.
3839 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3841 to see all Xcode schema related properties.
3842 CMAKE_XCODE_SCHEME_GUARD_MALLOC
3844 New in version 3.13.
3845 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
3848 ated Xcode scheme.
3849 This variable initializes the XCODE_SCHEME_GUARD_MALLOC property on all
3851 targets.
3852 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3854 to see all Xcode schema related properties.
3855 CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION
3857 New in version 3.25.
3858 Set the build configuration to run the target.
3861 This variable initializes the XCODE_SCHEME_LAUNCH_CONFIGURATION prop‐
3863 erty on all targets.
3864 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3866 to see all Xcode schema related properties.
3867 CMAKE_XCODE_SCHEME_LAUNCH_MODE
3869 New in version 3.25.
3870 Property value for Launch in the Info section of the generated Xcode
3873 scheme.
3874 This variable initializes the XCODE_SCHEME_LAUNCH_MODE property on all
3876 targets.
3877 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3879 to see all Xcode schema related properties.
3880 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
3882 New in version 3.13.
3883 Whether to enable the Main Thread Checker option Pause on issues in the
3886 Diagnostics section of the generated Xcode scheme.
3887 This variable initializes the XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
3889 property on all targets.
3890 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3892 to see all Xcode schema related properties.
3893 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
3895 New in version 3.13.
3896 Whether to enable Malloc Guard Edges in the Diagnostics section of the
3899 generated Xcode scheme.
3900 This variable initializes the XCODE_SCHEME_MALLOC_GUARD_EDGES property
3902 on all targets.
3903 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3905 to see all Xcode schema related properties.
3906 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
3908 New in version 3.13.
3909 Whether to enable Malloc Scribble in the Diagnostics section of the
3912 generated Xcode scheme.
3913 This variable initializes the XCODE_SCHEME_MALLOC_SCRIBBLE property on
3915 all targets.
3916 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3918 to see all Xcode schema related properties.
3919 CMAKE_XCODE_SCHEME_MALLOC_STACK
3921 New in version 3.13.
3922 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
3925 ated Xcode scheme.
3926 This variable initializes the XCODE_SCHEME_MALLOC_STACK property on all
3928 targets.
3929 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3931 to see all Xcode schema related properties.
3932 CMAKE_XCODE_SCHEME_THREAD_SANITIZER
3934 New in version 3.13.
3935 Whether to enable Thread Sanitizer in the Diagnostics section of the
3938 generated Xcode scheme.
3939 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER property on
3941 all targets.
3942 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3944 to see all Xcode schema related properties.
3945 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
3947 New in version 3.13.
3948 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
3951 section of the generated Xcode scheme.
3952 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER_STOP prop‐
3954 erty on all targets.
3955 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3957 to see all Xcode schema related properties.
3958 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
3960 New in version 3.13.
3961 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
3964 tion of the generated Xcode scheme.
3965 This variable initializes the
3967 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER property on all targets.
3968 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3970 to see all Xcode schema related properties.
3971 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
3973 New in version 3.13.
3974 Whether to enable Undefined Behavior Sanitizer option Pause on issues
3977 in the Diagnostics section of the generated Xcode scheme.
3978 This variable initializes the
3980 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP property on all tar‐
3981 gets.
3982 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3984 to see all Xcode schema related properties.
3985 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
3987 New in version 3.17.
3988 Specify the Working Directory of the Run and Profile actions in the
3991 generated Xcode scheme.
3992 This variable initializes the XCODE_SCHEME_WORKING_DIRECTORY property
3994 on all targets.
3995 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3997 to see all Xcode schema related properties.
3998 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
4000 New in version 3.13.
4001 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
4004 erated Xcode scheme.
4005 This variable initializes the XCODE_SCHEME_ZOMBIE_OBJECTS property on
4007 all targets.
4008 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4010 to see all Xcode schema related properties.
4011 CMAKE_XCODE_XCCONFIG
4013 New in version 3.24.
4014 If set, the Xcode generator will register the specified file as a
4017 global XCConfig file. For target-level XCConfig files see the
4018 XCODE_XCCONFIG target property.
4019 This feature is intended to ease migration from native Xcode projects
4021 to CMake projects.
4022 Contents of CMAKE_XCODE_XCCONFIG may use generator expressions.
4024 <PackageName>_ROOT
4026 New in version 3.12.
4027 Calls to find_package(<PackageName>) will search in prefixes specified
4030 by the <PackageName>_ROOT CMake variable, where <PackageName> is the
4031 name given to the find_package() call and _ROOT is literal. For exam‐
4032 ple, find_package(Foo) will search prefixes specified in the Foo_ROOT
4033 CMake variable (if set). See policy CMP0074.
4034 This variable may hold a single prefix or a semicolon-separated list of
4036 multiple prefixes.
4037 See also the <PackageName>_ROOT environment variable.
4039
4041 ANDROID
4042 New in version 3.7.
4043 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is Android.
4046 APPLE
4048 Set to True when the target system is an Apple platform (macOS, iOS,
4049 tvOS or watchOS).
4050 BORLAND
4052 True if the Borland compiler is being used.
4053 This is set to true if the Borland compiler is being used.
4055 BSD
4057 New in version 3.25.
4058 Set to a string value when the target system is BSD. This value can be
4061 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4062 CMAKE_ANDROID_NDK_VERSION
4064 New in version 3.20.
4065 When Cross Compiling for Android with the NDK and using an Android NDK
4068 version 11 or higher, this variable is provided by CMake to report the
4069 NDK version number.
4070 CMAKE_CL_64
4072 Discouraged. Use CMAKE_SIZEOF_VOID_P instead.
4073 Set to a true value when using a Microsoft Visual Studio cl compiler
4075 that targets a 64-bit architecture.
4076 CMAKE_COMPILER_2005
4078 Using the Visual Studio 2005 compiler from Microsoft
4079 Set to true when using the Visual Studio 2005 compiler from Microsoft.
4081 CMAKE_HOST_APPLE
4083 True for Apple macOS operating systems.
4084 Set to true when the host system is Apple macOS.
4086 CMAKE_HOST_BSD
4088 New in version 3.25.
4089 Set to a string value when the host system is BSD. This value can be
4092 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4093 CMAKE_HOST_LINUX
4095 New in version 3.25.
4096 Set to true when the host system is Linux.
4099 CMAKE_HOST_SOLARIS
4101 New in version 3.6.
4102 True for Oracle Solaris operating systems.
4105 Set to true when the host system is Oracle Solaris.
4107 CMAKE_HOST_SYSTEM
4109 Composite Name of OS CMake is being run on.
4110 This variable is the composite of CMAKE_HOST_SYSTEM_NAME and
4112 CMAKE_HOST_SYSTEM_VERSION, e.g. ${CMAKE_HOST_SYS‐
4113 TEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}. If CMAKE_HOST_SYSTEM_VERSION
4114 is not set, then this variable is the same as CMAKE_HOST_SYSTEM_NAME.
4115 CMAKE_HOST_SYSTEM_NAME
4117 Name of the OS CMake is running on.
4118 On systems that have the uname command, this variable is set to the
4120 output of uname -s. Linux, Windows, and Darwin for macOS are the val‐
4121 ues found on the big three operating systems.
4122 CMAKE_HOST_SYSTEM_PROCESSOR
4124 The name of the CPU CMake is running on.
4125 Windows Platforms
4127 On Windows, this variable is set to the value of the environment vari‐
4128 able PROCESSOR_ARCHITECTURE.
4129 Unix Platforms
4131 On systems that support uname, this variable is set to the output of:
4132 • uname -m on GNU, Linux, Cygwin, Android, or
4134 • arch on OpenBSD, or
4136 • on other systems,
4138 • uname -p if its exit code is nonzero, or
4140 • uname -m otherwise.
4142 macOS Platforms
4144 The value of uname -m is used by default.
4145 On Apple Silicon hosts, the architecture printed by uname -m may vary
4147 based on CMake's own architecture and that of the invoking process
4148 tree.
4149 New in version 3.19.2: On Apple Silicon hosts:
4151 • The CMAKE_APPLE_SILICON_PROCESSOR variable or the
4153 CMAKE_APPLE_SILICON_PROCESSOR environment variable may be set to
4154 specify the host architecture explicitly.
4155 • If CMAKE_OSX_ARCHITECTURES is not set, CMake adds explicit flags to
4157 tell the compiler to build for the host architecture so the toolchain
4158 does not have to guess based on the process tree's architecture.
4159 CMAKE_HOST_SYSTEM_VERSION
4162 The OS version CMake is running on.
4163 A numeric version string for the system. On systems that support un‐
4165 ame, this variable is set to the output of uname -r. On other systems
4166 this is set to major-minor version numbers.
4167 CMAKE_HOST_UNIX
4169 True for UNIX and UNIX like operating systems.
4170 Set to true when the host system is UNIX or UNIX like (i.e. APPLE and
4172 CYGWIN).
4173 CMAKE_HOST_WIN32
4175 True if the host system is running Windows, including Windows 64-bit
4176 and MSYS.
4177 Set to false on Cygwin.
4179 CMAKE_LIBRARY_ARCHITECTURE
4181 Target architecture library directory name, if detected.
4182 This is the value of CMAKE_<LANG>_LIBRARY_ARCHITECTURE as detected for
4184 one of the enabled languages.
4185 CMAKE_LIBRARY_ARCHITECTURE_REGEX
4187 Regex matching possible target architecture library directory names.
4188 This is used to detect CMAKE_<LANG>_LIBRARY_ARCHITECTURE from the im‐
4190 plicit linker search path by matching the <arch> name.
4191 CMAKE_OBJECT_PATH_MAX
4193 Maximum object file full-path length allowed by native build tools.
4194 CMake computes for every source file an object file name that is unique
4196 to the source file and deterministic with respect to the full path to
4197 the source file. This allows multiple source files in a target to
4198 share the same name if they lie in different directories without re‐
4199 building when one is added or removed. However, it can produce long
4200 full paths in a few cases, so CMake shortens the path using a hashing
4201 scheme when the full path to an object file exceeds a limit. CMake has
4202 a built-in limit for each platform that is sufficient for common tools,
4203 but some native tools may have a lower limit. This variable may be set
4204 to specify the limit explicitly. The value must be an integer no less
4205 than 128.
4206 CMAKE_SYSTEM
4208 Composite name of operating system CMake is compiling for.
4209 This variable is the composite of CMAKE_SYSTEM_NAME and
4211 CMAKE_SYSTEM_VERSION, e.g. ${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VER‐
4212 SION}. If CMAKE_SYSTEM_VERSION is not set, then this variable is the
4213 same as CMAKE_SYSTEM_NAME.
4214 CMAKE_SYSTEM_NAME
4216 The name of the operating system for which CMake is to build. See the
4217 CMAKE_SYSTEM_VERSION variable for the OS version.
4218 Note that CMAKE_SYSTEM_NAME is not set to anything by default when run‐
4220 ning in script mode, since it's not building anything.
4221 System Name for Host Builds
4223 CMAKE_SYSTEM_NAME is by default set to the same value as the
4224 CMAKE_HOST_SYSTEM_NAME variable so that the build targets the host sys‐
4225 tem.
4226 System Name for Cross Compiling
4228 CMAKE_SYSTEM_NAME may be set explicitly when first configuring a new
4229 build tree in order to enable cross compiling. In this case the
4230 CMAKE_SYSTEM_VERSION variable must also be set explicitly.
4231 CMAKE_SYSTEM_PROCESSOR
4233 When not cross-compiling, this variable has the same value as the
4234 CMAKE_HOST_SYSTEM_PROCESSOR variable. In many cases, this will corre‐
4235 spond to the target architecture for the build, but this is not guaran‐
4236 teed. (E.g. on Windows, the host may be AMD64 even when using a MSVC
4237 cl compiler with a 32-bit target.)
4238 When cross-compiling, a CMAKE_TOOLCHAIN_FILE should set the CMAKE_SYS‐
4240 TEM_PROCESSOR variable to match target architecture that it specifies
4241 (via CMAKE_<LANG>_COMPILER and perhaps CMAKE_<LANG>_COMPILER_TARGET).
4242 CMAKE_SYSTEM_VERSION
4244 The version of the operating system for which CMake is to build. See
4245 the CMAKE_SYSTEM_NAME variable for the OS name.
4246 System Version for Host Builds
4248 When the CMAKE_SYSTEM_NAME variable takes its default value then
4249 CMAKE_SYSTEM_VERSION is by default set to the same value as the
4250 CMAKE_HOST_SYSTEM_VERSION variable so that the build targets the host
4251 system version.
4252 In the case of a host build then CMAKE_SYSTEM_VERSION may be set ex‐
4254 plicitly when first configuring a new build tree in order to enable
4255 targeting the build for a different version of the host operating sys‐
4256 tem than is actually running on the host. This is allowed and not con‐
4257 sidered cross compiling so long as the binaries built for the specified
4258 OS version can still run on the host.
4259 System Version for Cross Compiling
4261 When the CMAKE_SYSTEM_NAME variable is set explicitly to enable cross
4262 compiling then the value of CMAKE_SYSTEM_VERSION must also be set ex‐
4263 plicitly to specify the target system version.
4264 CYGWIN
4266 True for Cygwin.
4267 Set to true when using Cygwin.
4269 GHSMULTI
4271 New in version 3.3.
4272 1 when using Green Hills MULTI generator.
4275 Also, Set to 1 when the target system is a Green Hills platform (i.e.
4277 When CMAKE_SYSTEM_NAME is GHS-MULTI).
4278 IOS
4280 New in version 3.14.
4281 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is iOS.
4284 LINUX
4286 New in version 3.25.
4287 Set to true when the target system is Linux.
4290 MINGW
4292 New in version 3.2.
4293 True when using MinGW
4296 Set to true when the compiler is some version of MinGW.
4298 MSVC
4300 Set to true when the compiler is some version of Microsoft Visual C++
4301 or another compiler simulating the Visual C++ cl command-line syntax.
4302 See also the MSVC_VERSION variable.
4304 MSVC10
4306 Discouraged. Use the MSVC_VERSION variable instead.
4307 True when using the Microsoft Visual Studio v100 toolset (cl version
4309 16) or another compiler that simulates it.
4310 MSVC11
4312 Discouraged. Use the MSVC_VERSION variable instead.
4313 True when using the Microsoft Visual Studio v110 toolset (cl version
4315 17) or another compiler that simulates it.
4316 MSVC12
4318 Discouraged. Use the MSVC_VERSION variable instead.
4319 True when using the Microsoft Visual Studio v120 toolset (cl version
4321 18) or another compiler that simulates it.
4322 MSVC14
4324 New in version 3.1.
4325 Discouraged. Use the MSVC_VERSION variable instead.
4328 True when using the Microsoft Visual Studio v140 or v141 toolset (cl
4330 version 19) or another compiler that simulates it.
4331 MSVC60
4333 Discouraged. Use the MSVC_VERSION variable instead.
4334 True when using Microsoft Visual C++ 6.0.
4336 Set to true when the compiler is version 6.0 of Microsoft Visual C++.
4338 MSVC70
4340 Discouraged. Use the MSVC_VERSION variable instead.
4341 True when using Microsoft Visual C++ 7.0.
4343 Set to true when the compiler is version 7.0 of Microsoft Visual C++.
4345 MSVC71
4347 Discouraged. Use the MSVC_VERSION variable instead.
4348 True when using Microsoft Visual C++ 7.1.
4350 Set to true when the compiler is version 7.1 of Microsoft Visual C++.
4352 MSVC80
4354 Discouraged. Use the MSVC_VERSION variable instead.
4355 True when using the Microsoft Visual Studio v80 toolset (cl version 14)
4357 or another compiler that simulates it.
4358 MSVC90
4360 Discouraged. Use the MSVC_VERSION variable instead.
4361 True when using the Microsoft Visual Studio v90 toolset (cl version 15)
4363 or another compiler that simulates it.
4364 MSVC_IDE
4366 True when using the Microsoft Visual C++ IDE.
4367 Set to true when the target platform is the Microsoft Visual C++ IDE,
4369 as opposed to the command line compiler.
4370 NOTE:
4372 This variable is only available after compiler detection has been
4373 performed, so it is not available to toolchain files or before the
4374 first project() or enable_language() call which uses an MSVC-like
4375 compiler.
4376 MSVC_TOOLSET_VERSION
4378 New in version 3.12.
4379 The toolset version of Microsoft Visual C/C++ being used if any. If
4382 MSVC-like is being used, this variable is set based on the version of
4383 the compiler as given by the MSVC_VERSION variable.
4384 Known toolset version numbers are:
4386 80 = VS 2005 (8.0)
4388 90 = VS 2008 (9.0)
4389 100 = VS 2010 (10.0)
4390 110 = VS 2012 (11.0)
4391 120 = VS 2013 (12.0)
4392 140 = VS 2015 (14.0)
4393 141 = VS 2017 (15.0)
4394 142 = VS 2019 (16.0)
4395 143 = VS 2022 (17.0)
4396 Compiler versions newer than those known to CMake will be reported as
4398 the latest known toolset version.
4399 See also the MSVC_VERSION variable.
4401 MSVC_VERSION
4403 The version of Microsoft Visual C/C++ being used if any. If a compiler
4404 simulating Visual C++ is being used, this variable is set to the
4405 toolset version simulated as given by the _MSC_VER preprocessor defini‐
4406 tion.
4407 Known version numbers are:
4409 1200 = VS 6.0
4411 1300 = VS 7.0
4412 1310 = VS 7.1
4413 1400 = VS 8.0 (v80 toolset)
4414 1500 = VS 9.0 (v90 toolset)
4415 1600 = VS 10.0 (v100 toolset)
4416 1700 = VS 11.0 (v110 toolset)
4417 1800 = VS 12.0 (v120 toolset)
4418 1900 = VS 14.0 (v140 toolset)
4419 1910-1919 = VS 15.0 (v141 toolset)
4420 1920-1929 = VS 16.0 (v142 toolset)
4421 1930-1939 = VS 17.0 (v143 toolset)
4422 See also the CMAKE_<LANG>_COMPILER_VERSION and MSVC_TOOLSET_VERSION
4424 variable.
4425 MSYS
4427 New in version 3.14.
4428 True when using the MSYS Makefiles generator.
4431 UNIX
4433 Set to True when the target system is UNIX or UNIX-like (e.g. APPLE and
4434 CYGWIN). The CMAKE_SYSTEM_NAME variable should be queried if a more
4435 specific understanding of the target system is required.
4436 WIN32
4438 Set to True when the target system is Windows, including Win64.
4439 WINCE
4441 New in version 3.1.
4442 True when the CMAKE_SYSTEM_NAME variable is set to WindowsCE.
4445 WINDOWS_PHONE
4447 New in version 3.1.
4448 True when the CMAKE_SYSTEM_NAME variable is set to WindowsPhone.
4451 WINDOWS_STORE
4453 New in version 3.1.
4454 True when the CMAKE_SYSTEM_NAME variable is set to WindowsStore.
4457 XCODE
4459 New in version 3.7.
4460 True when using Xcode generator.
4463 XCODE_VERSION
4465 Version of Xcode (Xcode generator only).
4466 Under the Xcode generator, this is the version of Xcode as specified in
4468 Xcode.app/Contents/version.plist (such as 3.1.2).
4469
4471 CMAKE_ADSP_ROOT
4472 New in version 3.24.
4473 When Cross Compiling for ADSP SHARC/Blackfin, this variable holds the
4476 absolute path to the latest CCES or VDSP++ install. The directory is
4477 expected to contain the cc21k.exe and ccblkfn.exe compilers. This will
4478 be set automatically if a default install of CCES or VDSP++ can be
4479 found.
4480 See also the ADSP_ROOT environment variable.
4482 CMAKE_AIX_EXPORT_ALL_SYMBOLS
4484 New in version 3.17.
4485 Default value for AIX_EXPORT_ALL_SYMBOLS target property. This vari‐
4488 able is used to initialize the property on each target as it is cre‐
4489 ated.
4490 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
4492 New in version 3.4.
4493 Default value for the ANDROID_ANT_ADDITIONAL_OPTIONS target property.
4496 See that target property for additional information.
4497 CMAKE_ANDROID_API
4499 New in version 3.1.
4500 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4503 Edition, this variable may be set to specify the default value for the
4504 ANDROID_API target property. See that target property for additional
4505 information.
4506 When Cross Compiling for Android, the CMAKE_SYSTEM_VERSION variable
4508 represents the Android API version number targeted. For historical
4509 reasons, if a toolchain file sets CMAKE_ANDROID_API, but not CMAKE_SYS‐
4510 TEM_VERSION, the latter will be initialized using the former.
4511 CMAKE_ANDROID_API_MIN
4513 New in version 3.2.
4514 Default value for the ANDROID_API_MIN target property. See that target
4517 property for additional information.
4518 CMAKE_ANDROID_ARCH
4520 New in version 3.4.
4521 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4524 Edition, this variable may be set to specify the default value for the
4525 ANDROID_ARCH target property. See that target property for additional
4526 information.
4527 Otherwise, when Cross Compiling for Android, this variable provides the
4529 name of the Android architecture corresponding to the value of the
4530 CMAKE_ANDROID_ARCH_ABI variable. The architecture name may be one of:
4531 • arm
4533 • arm64
4535 • mips
4537 • mips64
4539 • x86
4541 • x86_64
4543 CMAKE_ANDROID_ARCH_ABI
4545 New in version 3.7.
4546 When Cross Compiling for Android, this variable specifies the target
4549 architecture and ABI to be used. Valid values are:
4550 • arm64-v8a
4552 • armeabi-v7a
4554 • armeabi-v6
4556 • armeabi
4558 • mips
4560 • mips64
4562 • x86
4564 • x86_64
4566 See also the CMAKE_ANDROID_ARM_MODE and CMAKE_ANDROID_ARM_NEON vari‐
4568 ables.
4569 CMAKE_ANDROID_ARM_MODE
4571 New in version 3.7.
4572 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4575 one of the armeabi architectures, set CMAKE_ANDROID_ARM_MODE to ON to
4576 target 32-bit ARM processors (-marm). Otherwise, the default is to
4577 target the 16-bit Thumb processors (-mthumb).
4578 CMAKE_ANDROID_ARM_NEON
4580 New in version 3.7.
4581 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4584 armeabi-v7a set CMAKE_ANDROID_ARM_NEON to ON to target ARM NEON de‐
4585 vices.
4586 CMAKE_ANDROID_ASSETS_DIRECTORIES
4588 New in version 3.4.
4589 Default value for the ANDROID_ASSETS_DIRECTORIES target property. See
4592 that target property for additional information.
4593 CMAKE_ANDROID_EXCEPTIONS
4595 New in version 3.20.
4596 When Cross Compiling for Android with the NDK, this variable may be set
4599 to specify whether exceptions are enabled.
4600 CMAKE_ANDROID_GUI
4602 New in version 3.1.
4603 Default value for the ANDROID_GUI target property of executables. See
4606 that target property for additional information.
4607 CMAKE_ANDROID_JAR_DEPENDENCIES
4609 New in version 3.4.
4610 Default value for the ANDROID_JAR_DEPENDENCIES target property. See
4613 that target property for additional information.
4614 CMAKE_ANDROID_JAR_DIRECTORIES
4616 New in version 3.4.
4617 Default value for the ANDROID_JAR_DIRECTORIES target property. See
4620 that target property for additional information.
4621 CMAKE_ANDROID_JAVA_SOURCE_DIR
4623 New in version 3.4.
4624 Default value for the ANDROID_JAVA_SOURCE_DIR target property. See
4627 that target property for additional information.
4628 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
4630 New in version 3.4.
4631 Default value for the ANDROID_NATIVE_LIB_DEPENDENCIES target property.
4634 See that target property for additional information.
4635 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
4637 New in version 3.4.
4638 Default value for the ANDROID_NATIVE_LIB_DIRECTORIES target property.
4641 See that target property for additional information.
4642 CMAKE_ANDROID_NDK
4644 New in version 3.7.
4645 When Cross Compiling for Android with the NDK, this variable holds the
4648 absolute path to the root directory of the NDK. The directory must
4649 contain a platforms subdirectory holding the android-<api> directories.
4650 CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
4652 New in version 3.9.
4653 When Cross Compiling for Android with the NDK, this variable may be set
4656 to specify whether to use the deprecated per-api-level headers instead
4657 of the unified headers.
4658 If not specified, the default will be false if using a NDK version that
4660 provides the unified headers and true otherwise.
4661 CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
4663 New in version 3.7.1.
4664 When Cross Compiling for Android with the NDK, this variable provides
4667 the NDK's "host tag" used to construct the path to prebuilt toolchains
4668 that run on the host.
4669 CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
4671 New in version 3.7.
4672 When Cross Compiling for Android with the NDK, this variable may be set
4675 to specify the version of the toolchain to be used as the compiler.
4676 On NDK r19 or above, this variable must be unset or set to clang.
4678 On NDK r18 or below, this variable must be set to one of these forms:
4680 • <major>.<minor>: GCC of specified version
4682 • clang<major>.<minor>: Clang of specified version
4684 • clang: Clang of most recent available version
4686 A toolchain of the requested version will be selected automatically to
4688 match the ABI named in the CMAKE_ANDROID_ARCH_ABI variable.
4689 If not specified, the default will be a value that selects the latest
4691 available GCC toolchain.
4692 CMAKE_ANDROID_PROCESS_MAX
4694 New in version 3.4.
4695 Default value for the ANDROID_PROCESS_MAX target property. See that
4698 target property for additional information.
4699 CMAKE_ANDROID_PROGUARD
4701 New in version 3.4.
4702 Default value for the ANDROID_PROGUARD target property. See that tar‐
4705 get property for additional information.
4706 CMAKE_ANDROID_PROGUARD_CONFIG_PATH
4708 New in version 3.4.
4709 Default value for the ANDROID_PROGUARD_CONFIG_PATH target property.
4712 See that target property for additional information.
4713 CMAKE_ANDROID_RTTI
4715 New in version 3.20.
4716 When Cross Compiling for Android with the NDK, this variable may be set
4719 to specify whether RTTI is enabled.
4720 CMAKE_ANDROID_SECURE_PROPS_PATH
4722 New in version 3.4.
4723 Default value for the ANDROID_SECURE_PROPS_PATH target property. See
4726 that target property for additional information.
4727 CMAKE_ANDROID_SKIP_ANT_STEP
4729 New in version 3.4.
4730 Default value for the ANDROID_SKIP_ANT_STEP target property. See that
4733 target property for additional information.
4734 CMAKE_ANDROID_STANDALONE_TOOLCHAIN
4736 New in version 3.7.
4737 When Cross Compiling for Android with a Standalone Toolchain, this
4740 variable holds the absolute path to the root directory of the
4741 toolchain. The specified directory must contain a sysroot subdirec‐
4742 tory.
4743 CMAKE_ANDROID_STL_TYPE
4745 New in version 3.4.
4746 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4749 Edition, this variable may be set to specify the default value for the
4750 ANDROID_STL_TYPE target property. See that target property for addi‐
4751 tional information.
4752 When Cross Compiling for Android with the NDK, this variable may be set
4754 to specify the STL variant to be used. The value may be one of:
4755 none No C++ Support
4757 system Minimal C++ without STL
4759 gabi++_static
4761 GAbi++ Static
4762 gabi++_shared
4764 GAbi++ Shared
4765 gnustl_static
4767 GNU libstdc++ Static
4768 gnustl_shared
4770 GNU libstdc++ Shared
4771 c++_static
4773 LLVM libc++ Static
4774 c++_shared
4776 LLVM libc++ Shared
4777 stlport_static
4779 STLport Static
4780 stlport_shared
4782 STLport Shared
4783 The default value is gnustl_static on NDK versions that provide it and
4785 otherwise c++_static. Note that this default differs from the native
4786 NDK build system because CMake may be used to build projects for An‐
4787 droid that are not natively implemented for it and use the C++ standard
4788 library.
4789 CMAKE_APPLE_SILICON_PROCESSOR
4791 New in version 3.19.2.
4792 On Apple Silicon hosts running macOS, set this variable to tell CMake
4795 what architecture to use for CMAKE_HOST_SYSTEM_PROCESSOR. The value
4796 must be either arm64 or x86_64.
4797 The value of this variable should never be modified by project code.
4799 It is meant to be set as a cache entry provided by the user, e.g. via
4800 -DCMAKE_APPLE_SILICON_PROCESSOR=....
4801 See also the CMAKE_APPLE_SILICON_PROCESSOR environment variable.
4803 CMAKE_ARCHIVE_OUTPUT_DIRECTORY
4805 Where to put all the ARCHIVE target files when built.
4806 This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY prop‐
4808 erty on all the targets. See that target property for additional in‐
4809 formation.
4810 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
4812 New in version 3.3.
4813 Where to put all the ARCHIVE target files when built for a specific
4816 configuration.
4817 This variable is used to initialize the
4819 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
4820 that target property for additional information.
4821 CMAKE_AUTOGEN_ORIGIN_DEPENDS
4823 New in version 3.14.
4824 Switch for forwarding origin target dependencies to the corresponding
4827 _autogen targets.
4828 This variable is used to initialize the AUTOGEN_ORIGIN_DEPENDS property
4830 on all the targets. See that target property for additional informa‐
4831 tion.
4832 By default CMAKE_AUTOGEN_ORIGIN_DEPENDS is ON.
4834 CMAKE_AUTOGEN_PARALLEL
4836 New in version 3.11.
4837 Number of parallel moc or uic processes to start when using AUTOMOC and
4840 AUTOUIC.
4841 This variable is used to initialize the AUTOGEN_PARALLEL property on
4843 all the targets. See that target property for additional information.
4844 By default CMAKE_AUTOGEN_PARALLEL is unset.
4846 CMAKE_AUTOGEN_VERBOSE
4848 New in version 3.13.
4849 Sets the verbosity of AUTOMOC, AUTOUIC and AUTORCC. A positive integer
4852 value or a true boolean value lets the AUTO* generators output addi‐
4853 tional processing information.
4854 Setting CMAKE_AUTOGEN_VERBOSE has the same effect as setting the VER‐
4856 BOSE environment variable during generation (e.g. by calling make VER‐
4857 BOSE=1). The extra verbosity is limited to the AUTO* generators
4858 though.
4859 By default CMAKE_AUTOGEN_VERBOSE is unset.
4861 CMAKE_AUTOMOC
4863 Whether to handle moc automatically for Qt targets.
4864 This variable is used to initialize the AUTOMOC property on all the
4866 targets. See that target property for additional information.
4867 CMAKE_AUTOMOC_COMPILER_PREDEFINES
4869 New in version 3.10.
4870 This variable is used to initialize the AUTOMOC_COMPILER_PREDEFINES
4873 property on all the targets. See that target property for additional
4874 information.
4875 By default it is ON.
4877 CMAKE_AUTOMOC_DEPEND_FILTERS
4879 New in version 3.9.
4880 Filter definitions used by CMAKE_AUTOMOC to extract file names from
4883 source code as additional dependencies for the moc file.
4884 This variable is used to initialize the AUTOMOC_DEPEND_FILTERS property
4886 on all the targets. See that target property for additional informa‐
4887 tion.
4888 By default it is empty.
4890 CMAKE_AUTOMOC_MACRO_NAMES
4892 New in version 3.10.
4893 Semicolon-separated list list of macro names used by CMAKE_AUTOMOC to
4896 determine if a C++ file needs to be processed by moc.
4897 This variable is used to initialize the AUTOMOC_MACRO_NAMES property on
4899 all the targets. See that target property for additional information.
4900 The default value is Q_OBJECT;Q_GADGET;Q_NAMESPACE;Q_NAMESPACE_EXPORT.
4902 Example
4904 Let CMake know that source files that contain CUSTOM_MACRO must be moc
4905 processed as well:
4906 set(CMAKE_AUTOMOC ON)
4908 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
4909 CMAKE_AUTOMOC_MOC_OPTIONS
4911 Additional options for moc when using CMAKE_AUTOMOC.
4912 This variable is used to initialize the AUTOMOC_MOC_OPTIONS property on
4914 all the targets. See that target property for additional information.
4915 CMAKE_AUTOMOC_PATH_PREFIX
4917 New in version 3.16.
4918 Whether to generate the -p path prefix option for moc on AUTOMOC en‐
4921 abled Qt targets.
4922 This variable is used to initialize the AUTOMOC_PATH_PREFIX property on
4924 all the targets. See that target property for additional information.
4925 The default value is OFF.
4927 CMAKE_AUTORCC
4929 Whether to handle rcc automatically for Qt targets.
4930 This variable is used to initialize the AUTORCC property on all the
4932 targets. See that target property for additional information.
4933 CMAKE_AUTORCC_OPTIONS
4935 Additional options for rcc when using CMAKE_AUTORCC.
4936 This variable is used to initialize the AUTORCC_OPTIONS property on all
4938 the targets. See that target property for additional information.
4939 EXAMPLE
4941 # ...
4942 set(CMAKE_AUTORCC_OPTIONS "--compress;9")
4943 # ...
4944 CMAKE_AUTOUIC
4946 Whether to handle uic automatically for Qt targets.
4947 This variable is used to initialize the AUTOUIC property on all the
4949 targets. See that target property for additional information.
4950 CMAKE_AUTOUIC_OPTIONS
4952 Additional options for uic when using CMAKE_AUTOUIC.
4953 This variable is used to initialize the AUTOUIC_OPTIONS property on all
4955 the targets. See that target property for additional information.
4956 EXAMPLE
4958 # ...
4959 set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection")
4960 # ...
4961 CMAKE_AUTOUIC_SEARCH_PATHS
4963 New in version 3.9.
4964 Search path list used by CMAKE_AUTOUIC to find included .ui files.
4967 This variable is used to initialize the AUTOUIC_SEARCH_PATHS property
4969 on all the targets. See that target property for additional informa‐
4970 tion.
4971 By default it is empty.
4973 CMAKE_BUILD_RPATH
4975 New in version 3.8.
4976 Semicolon-separated list specifying runtime path (RPATH) entries to add
4979 to binaries linked in the build tree (for platforms that support it).
4980 The entries will not be used for binaries in the install tree. See
4981 also the CMAKE_INSTALL_RPATH variable.
4982 This is used to initialize the BUILD_RPATH target property for all tar‐
4984 gets.
4985 CMAKE_BUILD_RPATH_USE_ORIGIN
4987 New in version 3.14.
4988 Whether to use relative paths for the build RPATH.
4991 This is used to initialize the BUILD_RPATH_USE_ORIGIN target property
4993 for all targets, see that property for more details.
4994 CMAKE_BUILD_WITH_INSTALL_NAME_DIR
4996 New in version 3.9.
4997 Whether to use INSTALL_NAME_DIR on targets in the build tree.
5000 This variable is used to initialize the BUILD_WITH_INSTALL_NAME_DIR
5002 property on all targets.
5003 CMAKE_BUILD_WITH_INSTALL_RPATH
5005 Use the install path for the RPATH.
5006 Normally CMake uses the build tree for the RPATH when building executa‐
5008 bles etc on systems that use RPATH. When the software is installed the
5009 executables etc are relinked by CMake to have the install RPATH. If
5010 this variable is set to true then the software is always built with the
5011 install path for the RPATH and does not need to be relinked when in‐
5012 stalled.
5013 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
5015 New in version 3.1.
5016 Output directory for MS debug symbol .pdb files generated by the com‐
5019 piler while building source files.
5020 This variable is used to initialize the COMPILE_PDB_OUTPUT_DIRECTORY
5022 property on all the targets.
5023 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
5025 New in version 3.1.
5026 Per-configuration output directory for MS debug symbol .pdb files gen‐
5029 erated by the compiler while building source files.
5030 This is a per-configuration version of
5032 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY. This variable is used to initial‐
5033 ize the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property on all the tar‐
5034 gets.
5035 CMAKE_COMPILE_WARNING_AS_ERROR
5037 New in version 3.24.
5038 Specify whether to treat warnings on compile as errors.
5041 This variable is used to initialize the COMPILE_WARNING_AS_ERROR prop‐
5043 erty on all the targets.
5044 CMAKE_<CONFIG>_POSTFIX
5046 Default filename postfix for libraries under configuration <CONFIG>.
5047 When a non-executable target is created its <CONFIG>_POSTFIX target
5049 property is initialized with the value of this variable if it is set.
5050 CMAKE_CROSS_CONFIGS
5052 New in version 3.17.
5053 Specifies a semicolon-separated list of configurations available from
5056 all build-<Config>.ninja files in the Ninja Multi-Config generator.
5057 This variable activates cross-config mode. Targets from each config
5058 specified in this variable can be built from any build-<Config>.ninja
5059 file. Custom commands will use the configuration native to build-<Con‐
5060 fig>.ninja. If it is set to all, all configurations from
5061 CMAKE_CONFIGURATION_TYPES are cross-configs. If it is not specified, or
5062 empty, each build-<Config>.ninja file will only contain build rules for
5063 its own configuration.
5064 The value of this variable must be a subset of
5066 CMAKE_CONFIGURATION_TYPES.
5067 CMAKE_CTEST_ARGUMENTS
5069 New in version 3.17.
5070 Set this to a semicolon-separated list of command-line arguments to
5073 pass to ctest(1) when running tests through the test (or RUN_TESTS)
5074 target of the generated build system.
5075 CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
5077 New in version 3.16.
5078 Default value for CUDA_RESOLVE_DEVICE_SYMBOLS target property. This
5081 variable is used to initialize the property on each target as it is
5082 created.
5083 CMAKE_CUDA_RUNTIME_LIBRARY
5085 New in version 3.17.
5086 Select the CUDA runtime library for use when compiling and linking
5089 CUDA. This variable is used to initialize the CUDA_RUNTIME_LIBRARY
5090 property on all targets as they are created.
5091 The allowed case insensitive values are:
5093 None Link with -cudart=none or equivalent flag(s) to use no CUDA run‐
5095 time library.
5096 Shared Link with -cudart=shared or equivalent flag(s) to use a dynami‐
5098 cally-linked CUDA runtime library.
5099 Static Link with -cudart=static or equivalent flag(s) to use a stati‐
5101 cally-linked CUDA runtime library.
5102 Contents of CMAKE_CUDA_RUNTIME_LIBRARY may use generator expressions.
5104 If this variable is not set then the CUDA_RUNTIME_LIBRARY target prop‐
5106 erty will not be set automatically. If that property is not set then
5107 CMake uses an appropriate default value based on the compiler to select
5108 the CUDA runtime library.
5109 NOTE:
5111 This property has effect only when the CUDA language is enabled. To
5112 control the CUDA runtime linking when only using the CUDA SDK with
5113 the C or C++ language we recommend using the FindCUDAToolkit module.
5114 CMAKE_CUDA_SEPARABLE_COMPILATION
5116 New in version 3.11.
5117 Default value for CUDA_SEPARABLE_COMPILATION target property. This
5120 variable is used to initialize the property on each target as it is
5121 created.
5122 CMAKE_DEBUG_POSTFIX
5124 See variable CMAKE_<CONFIG>_POSTFIX.
5125 This variable is a special case of the more-general
5127 CMAKE_<CONFIG>_POSTFIX variable for the DEBUG configuration.
5128 CMAKE_DEFAULT_BUILD_TYPE
5130 New in version 3.17.
5131 Specifies the configuration to use by default in a build.ninja file in
5134 the Ninja Multi-Config generator. If this variable is specified,
5135 build.ninja uses build rules from build-<Config>.ninja by default. All
5136 custom commands are executed with this configuration. If the variable
5137 is not specified, the first item from CMAKE_CONFIGURATION_TYPES is used
5138 instead.
5139 The value of this variable must be one of the items from
5141 CMAKE_CONFIGURATION_TYPES.
5142 CMAKE_DEFAULT_CONFIGS
5144 New in version 3.17.
5145 Specifies a semicolon-separated list of configurations to build for a
5148 target in build.ninja if no :<Config> suffix is specified in the Ninja
5149 Multi-Config generator. If it is set to all, all configurations from
5150 CMAKE_CROSS_CONFIGS are used. If it is not specified, it defaults to
5151 CMAKE_DEFAULT_BUILD_TYPE.
5152 For example, if you set CMAKE_DEFAULT_BUILD_TYPE to Release, but set
5154 CMAKE_DEFAULT_CONFIGS to Debug or all, all <target> aliases in
5155 build.ninja will resolve to <target>:Debug or <target>:all, but custom
5156 commands will still use the Release configuration.
5157 The value of this variable must be a subset of CMAKE_CROSS_CONFIGS or
5159 be the same as CMAKE_DEFAULT_BUILD_TYPE. It must not be specified if
5160 CMAKE_DEFAULT_BUILD_TYPE or CMAKE_CROSS_CONFIGS is not used.
5161 CMAKE_DEPENDS_USE_COMPILER
5163 New in version 3.20.
5164 For the Makefile Generators, source dependencies are now, for a selec‐
5167 tion of compilers, generated by the compiler itself. By defining this
5168 variable with value FALSE, you can restore the legacy behavior (i.e.
5169 using CMake for dependencies discovery).
5170 CMAKE_DISABLE_PRECOMPILE_HEADERS
5172 New in version 3.16.
5173 Default value for DISABLE_PRECOMPILE_HEADERS of targets.
5176 By default CMAKE_DISABLE_PRECOMPILE_HEADERS is OFF.
5178 CMAKE_ENABLE_EXPORTS
5180 New in version 3.4.
5181 Specify whether executables export symbols for loadable modules.
5184 This variable is used to initialize the ENABLE_EXPORTS target property
5186 for executable targets when they are created by calls to the
5187 add_executable() command. See the property documentation for details.
5188 CMAKE_EXE_LINKER_FLAGS
5190 Linker flags to be used to create executables.
5191 These flags will be used by the linker when creating an executable.
5193 CMAKE_EXE_LINKER_FLAGS_<CONFIG>
5195 Flags to be used when linking an executable.
5196 Same as CMAKE_C_FLAGS_* but used by the linker when creating executa‐
5198 bles.
5199 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT
5201 New in version 3.7.
5202 Value used to initialize the CMAKE_EXE_LINKER_FLAGS_<CONFIG> cache en‐
5205 try the first time a build tree is configured. This variable is meant
5206 to be set by a toolchain file. CMake may prepend or append content to
5207 the value based on the environment and target platform.
5208 See also CMAKE_EXE_LINKER_FLAGS_INIT.
5210 CMAKE_EXE_LINKER_FLAGS_INIT
5212 New in version 3.7.
5213 Value used to initialize the CMAKE_EXE_LINKER_FLAGS cache entry the
5216 first time a build tree is configured. This variable is meant to be
5217 set by a toolchain file. CMake may prepend or append content to the
5218 value based on the environment and target platform.
5219 See also the configuration-specific variable
5221 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT.
5222 CMAKE_FOLDER
5224 New in version 3.12.
5225 Set the folder name. Use to organize targets in an IDE.
5228 This variable is used to initialize the FOLDER property on all the tar‐
5230 gets. See that target property for additional information.
5231 CMAKE_Fortran_FORMAT
5233 Set to FIXED or FREE to indicate the Fortran source layout.
5234 This variable is used to initialize the Fortran_FORMAT property on all
5236 the targets. See that target property for additional information.
5237 CMAKE_Fortran_MODULE_DIRECTORY
5239 Fortran module output directory.
5240 This variable is used to initialize the Fortran_MODULE_DIRECTORY prop‐
5242 erty on all the targets. See that target property for additional in‐
5243 formation.
5244 CMAKE_Fortran_PREPROCESS
5246 New in version 3.18.
5247 Default value for Fortran_PREPROCESS of targets.
5250 This variable is used to initialize the Fortran_PREPROCESS property on
5252 all the targets. See that target property for additional information.
5253 CMAKE_FRAMEWORK
5255 New in version 3.15.
5256 Default value for FRAMEWORK of targets.
5259 This variable is used to initialize the FRAMEWORK property on all the
5261 targets. See that target property for additional information.
5262 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
5264 New in version 3.18.
5265 Default framework filename postfix under configuration <CONFIG> when
5268 using a multi-config generator.
5269 When a framework target is created its
5271 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property is initialized
5272 with the value of this variable if it is set.
5273 CMAKE_GHS_NO_SOURCE_GROUP_FILE
5275 New in version 3.14.
5276 ON / OFF boolean to control if the project file for a target should be
5279 one single file or multiple files. Refer to GHS_NO_SOURCE_GROUP_FILE
5280 for further details.
5281 CMAKE_GLOBAL_AUTOGEN_TARGET
5283 New in version 3.14.
5284 Switch to enable generation of a global autogen target.
5287 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a custom target autogen is
5289 generated. This target depends on all AUTOMOC and AUTOUIC generated
5290 <ORIGIN>_autogen targets in the project. By building the global auto‐
5291 gen target, all AUTOMOC and AUTOUIC files in the project will be gener‐
5292 ated.
5293 The name of the global autogen target can be changed by setting
5295 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.
5296 By default CMAKE_GLOBAL_AUTOGEN_TARGET is unset.
5298 See the cmake-qt(7) manual for more information on using CMake with Qt.
5300 Note
5302 <ORIGIN>_autogen targets by default inherit their origin target's de‐
5303 pendencies. This might result in unintended dependency target builds
5304 when only <ORIGIN>_autogen targets are built. A solution is to disable
5305 AUTOGEN_ORIGIN_DEPENDS on the respective origin targets.
5306 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME
5308 New in version 3.14.
5309 Change the name of the global autogen target.
5312 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a global custom target
5314 named autogen is created. CMAKE_GLOBAL_AUTOGEN_TARGET_NAME allows to
5315 set a different name for that target.
5316 By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.
5318 See the cmake-qt(7) manual for more information on using CMake with Qt.
5320 CMAKE_GLOBAL_AUTORCC_TARGET
5322 New in version 3.14.
5323 Switch to enable generation of a global autorcc target.
5326 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a custom target autorcc is
5328 generated. This target depends on all AUTORCC generated <ORI‐
5329 GIN>_arcc_<QRC> targets in the project. By building the global autorcc
5330 target, all AUTORCC files in the project will be generated.
5331 The name of the global autorcc target can be changed by setting
5333 CMAKE_GLOBAL_AUTORCC_TARGET_NAME.
5334 By default CMAKE_GLOBAL_AUTORCC_TARGET is unset.
5336 See the cmake-qt(7) manual for more information on using CMake with Qt.
5338 CMAKE_GLOBAL_AUTORCC_TARGET_NAME
5340 New in version 3.14.
5341 Change the name of the global autorcc target.
5344 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a global custom target
5346 named autorcc is created. CMAKE_GLOBAL_AUTORCC_TARGET_NAME allows to
5347 set a different name for that target.
5348 By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.
5350 See the cmake-qt(7) manual for more information on using CMake with Qt.
5352 CMAKE_GNUtoMS
5354 Convert GNU import libraries (.dll.a) to MS format (.lib).
5355 This variable is used to initialize the GNUtoMS property on targets
5357 when they are created. See that target property for additional infor‐
5358 mation.
5359 CMAKE_INCLUDE_CURRENT_DIR
5361 Automatically add the current source and build directories to the in‐
5362 clude path.
5363 If this variable is enabled, CMake automatically adds
5365 CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include
5366 path for each directory. These additional include directories do not
5367 propagate down to subdirectories. This is useful mainly for
5368 out-of-source builds, where files generated into the build tree are in‐
5369 cluded by files located in the source tree.
5370 By default CMAKE_INCLUDE_CURRENT_DIR is OFF.
5372 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
5374 Automatically add the current source and build directories to the
5375 INTERFACE_INCLUDE_DIRECTORIES target property.
5376 If this variable is enabled, CMake automatically adds for each shared
5378 library target, static library target, module target and executable
5379 target, CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the
5380 INTERFACE_INCLUDE_DIRECTORIES target property. By default CMAKE_IN‐
5381 CLUDE_CURRENT_DIR_IN_INTERFACE is OFF.
5382 CMAKE_INSTALL_NAME_DIR
5384 Directory name for installed targets on Apple platforms.
5385 CMAKE_INSTALL_NAME_DIR is used to initialize the INSTALL_NAME_DIR prop‐
5387 erty on all targets. See that target property for more information.
5388 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH
5390 New in version 3.16.
5391 Sets the default for whether toolchain-defined rpaths should be removed
5394 during installation.
5395 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH is a boolean that provides the
5397 default value for the INSTALL_REMOVE_ENVIRONMENT_RPATH property of all
5398 subsequently created targets.
5399 CMAKE_INSTALL_RPATH
5401 The rpath to use for installed targets.
5402 A semicolon-separated list specifying the rpath to use in installed
5404 targets (for platforms that support it). This is used to initialize
5405 the target property INSTALL_RPATH for all targets.
5406 CMAKE_INSTALL_RPATH_USE_LINK_PATH
5408 Add paths to linker search and installed rpath.
5409 CMAKE_INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to True will
5411 append to the runtime search path (rpath) of installed binaries any di‐
5412 rectories outside the project that are in the linker search path or
5413 contain linked library files. The directories are appended after the
5414 value of the INSTALL_RPATH target property.
5415 This variable is used to initialize the target property
5417 INSTALL_RPATH_USE_LINK_PATH for all targets.
5418 CMAKE_INTERPROCEDURAL_OPTIMIZATION
5420 New in version 3.9.
5421 Default value for INTERPROCEDURAL_OPTIMIZATION of targets.
5424 This variable is used to initialize the INTERPROCEDURAL_OPTIMIZATION
5426 property on all the targets. See that target property for additional
5427 information.
5428 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5430 New in version 3.9.
5431 Default value for INTERPROCEDURAL_OPTIMIZATION_<CONFIG> of targets.
5434 This variable is used to initialize the
5436 INTERPROCEDURAL_OPTIMIZATION_<CONFIG> property on all the targets. See
5437 that target property for additional information.
5438 CMAKE_IOS_INSTALL_COMBINED
5440 New in version 3.5.
5441 Default value for IOS_INSTALL_COMBINED of targets.
5444 This variable is used to initialize the IOS_INSTALL_COMBINED property
5446 on all the targets. See that target property for additional informa‐
5447 tion.
5448 CMAKE_<LANG>_CLANG_TIDY
5450 New in version 3.6.
5451 Default value for <LANG>_CLANG_TIDY target property when <LANG> is C,
5454 CXX, OBJC or OBJCXX.
5455 This variable is used to initialize the property on each target as it
5457 is created. For example:
5458 set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*)
5460 add_executable(foo foo.cxx)
5461 CMAKE_<LANG>_COMPILER_LAUNCHER
5463 New in version 3.4.
5464 Default value for <LANG>_COMPILER_LAUNCHER target property. This vari‐
5467 able is used to initialize the property on each target as it is cre‐
5468 ated. This is done only when <LANG> is C, CXX, Fortran, HIP, ISPC,
5469 OBJC, OBJCXX, or CUDA.
5470 This variable is initialized to the CMAKE_<LANG>_COMPILER_LAUNCHER en‐
5472 vironment variable if it is set.
5473 CMAKE_<LANG>_CPPCHECK
5475 New in version 3.10.
5476 Default value for <LANG>_CPPCHECK target property. This variable is
5479 used to initialize the property on each target as it is created. This
5480 is done only when <LANG> is C or CXX.
5481 CMAKE_<LANG>_CPPLINT
5483 New in version 3.8.
5484 Default value for <LANG>_CPPLINT target property. This variable is used
5487 to initialize the property on each target as it is created. This is
5488 done only when <LANG> is C or CXX.
5489 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE
5491 New in version 3.3.
5492 Default value for <LANG>_INCLUDE_WHAT_YOU_USE target property. This
5495 variable is used to initialize the property on each target as it is
5496 created. This is done only when <LANG> is C or CXX.
5497 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
5499 New in version 3.24.
5500 This variable defines how to link a group of libraries for the speci‐
5503 fied <FEATURE> when a LINK_GROUP generator expression is used and the
5504 link language for the target is <LANG>. For this variable to have any
5505 effect, the associated
5506 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be set
5507 to true.
5508 The CMAKE_LINK_GROUP_USING_<FEATURE> variable should be defined instead
5510 for features that are independent of the link language.
5511 Feature names are case-sensitive and may only contain letters, numbers
5513 and underscores. Feature names defined in all uppercase are reserved
5514 for CMake's own built-in features (see Predefined Features further be‐
5515 low).
5516 Feature Definitions
5518 A group feature definition is a list that contains exactly two ele‐
5519 ments:
5520 <PREFIX> <SUFFIX>
5522 On the linker command line, <PREFIX> will precede the list of libraries
5524 in the group and <SUFFIX> will follow after.
5525 For the elements of this variable, the LINKER: prefix can be used.
5527 To pass options to the linker tool, each compiler driver has its own
5529 syntax. The LINKER: prefix and , separator can be used to specify, in
5530 a portable way, options to pass to the linker tool. LINKER: is replaced
5531 by the appropriate driver option and , by the appropriate driver sepa‐
5532 rator. The driver prefix and driver separator are given by the values
5533 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
5534 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
5535 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5537 Clang and -Wl,-z,defs for GNU GCC.
5538 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5540 sion.
5541 The LINKER: prefix supports, as an alternative syntax, specification of
5543 arguments using the SHELL: prefix and space as separator. The previous
5544 example then becomes "LINKER:SHELL:-z defs".
5545 NOTE:
5547 Specifying the SHELL: prefix anywhere other than at the beginning of
5548 the LINKER: prefix is not supported.
5549 Examples
5551 Solving cross-references between two static libraries
5552 A project may define two or more static libraries which have circular
5553 dependencies between them. In order for the linker to resolve all sym‐
5554 bols at link time, it may need to search repeatedly among the libraries
5555 until no new undefined references are created. Different linkers use
5556 different syntax for achieving this. The following example shows how
5557 this may be implemented for some linkers. Note that this is for illus‐
5558 tration purposes only. Projects should use the built-in RESCAN group
5559 feature instead (see Predefined Features), which provides a more com‐
5560 plete and more robust implementation of this functionality.
5561 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
5563 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
5564 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5565 "LINKER:--start-group"
5566 "LINKER:--end-group"
5567 )
5568 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
5569 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5570 "LINKER:-z,rescan-start"
5571 "LINKER:-z,rescan-end"
5572 )
5573 else()
5574 # feature not yet supported for the other environments
5575 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
5576 endif()
5577 add_library(lib1 STATIC ...)
5579 add_library(lib2 SHARED ...)
5580 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
5582 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
5583 else()
5584 target_link_libraries(lib2 PRIVATE lib1 external)
5585 endif()
5586 CMake will generate the following linker command line fragments when
5588 linking lib2:
5589 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
5591 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
5593 can-end
5594 Predefined Features
5596 The following built-in group features are pre-defined by CMake:
5597 RESCAN Some linkers are single-pass only. For such linkers, circular
5599 references between libraries typically result in unresolved sym‐
5600 bols. This feature instructs the linker to search the specified
5601 static libraries repeatedly until no new undefined references
5602 are created.
5603 Normally, a static library is searched only once in the order
5605 that it is specified on the command line. If a symbol in that
5606 library is needed to resolve an undefined symbol referred to by
5607 an object in a library that appears later on the command line,
5608 the linker would not be able to resolve that reference. By
5609 grouping the static libraries with the RESCAN feature, they will
5610 all be searched repeatedly until all possible references are re‐
5611 solved. This will use linker options like --start-group and
5612 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
5613 Using this feature has a significant performance cost. It is
5615 best to use it only when there are unavoidable circular refer‐
5616 ences between two or more static libraries.
5617 This feature is available when using toolchains that target
5619 Linux, BSD, and SunOS. It can also be used when targeting Win‐
5620 dows platforms if the GNU toolchain is used.
5621 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
5623 New in version 3.24.
5624 This variable specifies whether the <FEATURE> is supported for the link
5627 language <LANG>. If this variable is true, then the <FEATURE> must be
5628 defined by CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>, and the more
5629 generic CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED and
5630 CMAKE_LINK_GROUP_USING_<FEATURE> variables are not used.
5631 If CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is false or is not
5633 set, then the CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable will
5634 determine whether <FEATURE> is deemed to be supported.
5635 CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG
5637 New in version 3.16.
5638 Language-specific flag to be used to link a library specified by a path
5641 to its file.
5642 The flag will be used before a library file path is given to the
5644 linker. This is needed only on very few platforms.
5645 CMAKE_<LANG>_LINK_LIBRARY_FLAG
5647 New in version 3.16.
5648 Flag to be used to link a library into a shared library or executable.
5651 This flag will be used to specify a library to link to a shared library
5653 or an executable for the specific language. On most compilers this is
5654 -l.
5655 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>
5657 New in version 3.24.
5658 This variable defines how to link a library or framework for the speci‐
5661 fied <FEATURE> when a LINK_LIBRARY generator expression is used and the
5662 link language for the target is <LANG>. For this variable to have any
5663 effect, the associated
5664 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
5665 set to true.
5666 The CMAKE_LINK_LIBRARY_USING_<FEATURE> variable should be defined in‐
5668 stead for features that are independent of the link language.
5669 Feature names are case-sensitive and may only contain letters, numbers
5671 and underscores. Feature names defined in all uppercase are reserved
5672 for CMake's own built-in features (see Predefined Features further be‐
5673 low).
5674 Feature Definitions
5676 A library feature definition is a list that contains one or three ele‐
5677 ments:
5678 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
5680 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
5682 spectively the whole list of libraries specified in the LINK_LIBRARY
5683 expression, not each library item individually. There is no guarantee
5684 that the list of specified libraries will be kept grouped together
5685 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
5686 library list is reorganized by CMake to satisfy other constraints.
5687 This means constructs like --start-group and --end-group, as supported
5688 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
5689 erator expression should be used instead for such constructs.
5690 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
5692 the corresponding fragment on the linker command line for each library.
5693 The following placeholders can be used in the expression:
5694 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
5696 gets, or to a platform-specific value based on the item otherwise
5697 (the same as <LINK_ITEM> on Windows, or the library base name for
5698 other platforms).
5699 • <LINK_ITEM> is expanded to how the library would normally be linked
5701 on the linker command line.
5702 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
5704 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
5705 SION> otherwise.
5706 In addition to the above, it is possible to have one pattern for paths
5708 (CMake targets and external libraries specified with file paths) and
5709 another for other items specified by name only. The PATH{} and NAME{}
5710 wrappers can be used to provide the expansion for those two cases, re‐
5711 spectively. When wrappers are used, both must be present. For exam‐
5712 ple:
5713 set(CMAKE_LINK_LIBRARY_USING_weak_library
5715 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
5716 )
5717 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
5719 SION>, and <SUFFIX>), the LINKER: prefix can be used.
5720 To pass options to the linker tool, each compiler driver has its own
5722 syntax. The LINKER: prefix and , separator can be used to specify, in
5723 a portable way, options to pass to the linker tool. LINKER: is replaced
5724 by the appropriate driver option and , by the appropriate driver sepa‐
5725 rator. The driver prefix and driver separator are given by the values
5726 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
5727 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
5728 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5730 Clang and -Wl,-z,defs for GNU GCC.
5731 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5733 sion.
5734 The LINKER: prefix supports, as an alternative syntax, specification of
5736 arguments using the SHELL: prefix and space as separator. The previous
5737 example then becomes "LINKER:SHELL:-z defs".
5738 NOTE:
5740 Specifying the SHELL: prefix anywhere other than at the beginning of
5741 the LINKER: prefix is not supported.
5742 Examples
5744 Loading a whole static library
5745 A common need is to prevent the linker from discarding any symbols from
5746 a static library. Different linkers use different syntax for achieving
5747 this. The following example shows how this may be implemented for some
5748 linkers. Note that this is for illustration purposes only. Projects
5749 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
5750 Features), which provides a more complete and more robust implementa‐
5751 tion of this functionality.
5752 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
5754 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
5755 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
5756 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
5757 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
5758 "LINKER:--push-state,--whole-archive"
5759 "<LINK_ITEM>"
5760 "LINKER:--pop-state"
5761 )
5762 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
5763 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
5764 else()
5765 # feature not yet supported for the other environments
5766 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
5767 endif()
5768 add_library(lib1 STATIC ...)
5770 add_library(lib2 SHARED ...)
5771 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
5773 # The -force_load Apple linker option requires a file name
5774 set(external_lib
5775 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
5776 )
5777 target_link_libraries(lib2 PRIVATE
5778 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
5779 )
5780 else()
5781 target_link_libraries(lib2 PRIVATE lib1 external)
5782 endif()
5783 CMake will generate the following link expressions:
5785 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
5787 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
5789 -Wl,--pop-state
5790 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
5792 Linking a library as weak
5794 On macOS, it is possible to link a library in weak mode (the library
5795 and all references are marked as weak imports). Different flags must
5796 be used for a library specified by file path compared to one specified
5797 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
5798 pers. Again, the following example shows how this may be implemented
5799 for some linkers, but it is for illustration purposes only. Projects
5800 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
5801 (see Predefined Features), which provide more complete and more robust
5802 implementations of this functionality.
5803 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
5805 set(CMAKE_LINK_LIBRARY_USING_weak_library
5806 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
5807 )
5808 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
5809 endif()
5810 add_library(lib SHARED ...)
5812 add_executable(main ...)
5813 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
5814 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
5815 else()
5816 target_link_libraries(main PRIVATE lib external)
5817 endif()
5818 CMake will generate the following linker command line fragment when
5820 linking main using the AppleClang toolchain:
5821 -weak_library /path/to/lib -Xlinker -weak-lexternal.
5823 Predefined Features
5825 The following built-in library features are pre-defined by CMake:
5826 DEFAULT
5828 This feature corresponds to standard linking, essentially equiv‐
5829 alent to using no feature at all. It is typically only used
5830 with the LINK_LIBRARY_OVERRIDE and
5831 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
5832 WHOLE_ARCHIVE
5834 Force inclusion of all members of a static library. This fea‐
5835 ture is only supported for the following platforms, with limita‐
5836 tions as noted:
5837 • Linux.
5839 • All BSD variants.
5841 • SunOS.
5843 • All Apple variants. The library must be specified as a CMake
5845 target name, a library file name (such as libfoo.a), or a li‐
5846 brary file path (such as /path/to/libfoo.a). Due to a limita‐
5847 tion of the Apple linker, it cannot be specified as a plain
5848 library name like foo, where foo is not a CMake target.
5849 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
5851 version must be greater than 1900.
5852 • Cygwin.
5854 • MSYS.
5856 FRAMEWORK
5858 This option tells the linker to search for the specified frame‐
5859 work using the -framework linker option. It can only be used on
5860 Apple platforms, and only with a linker that understands the op‐
5861 tion used (i.e. the linker provided with Xcode, or one compati‐
5862 ble with it).
5863 The framework can be specified as a CMake framework target, a
5865 bare framework name, or a file path. If a target is given, that
5866 target must have the FRAMEWORK target property set to true. For
5867 a file path, if it contains a directory part, that directory
5868 will be added as a framework search path.
5869 add_library(lib SHARED ...)
5871 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
5872 # The constructed linker command line will contain:
5874 # -F/path/to -framework my_framework
5875 File paths must conform to one of the following patterns (* is a
5877 wildcard, and optional parts are shown as [...]):
5878 • [/path/to/]FwName[.framework]
5880 • [/path/to/]FwName.framework/FwName[suffix]
5882 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
5884 Note that CMake recognizes and automatically handles framework
5886 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
5887 expression. The generator expression can still be used with a
5888 CMake target if the project wants to be explicit about it, but
5889 it is not required to do so. The linker command line may have
5890 some differences between using the generator expression or not,
5891 but the final result should be the same. On the other hand, if
5892 a file path is given, CMake will recognize some paths automati‐
5893 cally, but not all cases. The project may want to use
5894 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
5895 pected behavior is clear.
5896 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
5898 target property as well as the suffix of the framework library
5899 name are now supported by the FRAMEWORK features.
5900 NEEDED_FRAMEWORK
5903 This is similar to the FRAMEWORK feature, except it forces the
5904 linker to link with the framework even if no symbols are used
5905 from it. It uses the -needed_framework option and has the same
5906 linker constraints as FRAMEWORK.
5907 REEXPORT_FRAMEWORK
5909 This is similar to the FRAMEWORK feature, except it tells the
5910 linker that the framework should be available to clients linking
5911 to the library being created. It uses the -reexport_framework
5912 option and has the same linker constraints as FRAMEWORK.
5913 WEAK_FRAMEWORK
5915 This is similar to the FRAMEWORK feature, except it forces the
5916 linker to mark the framework and all references to it as weak
5917 imports. It uses the -weak_framework option and has the same
5918 linker constraints as FRAMEWORK.
5919 NEEDED_LIBRARY
5921 This is similar to the NEEDED_FRAMEWORK feature, except it is
5922 for use with non-framework targets or libraries (Apple platforms
5923 only). It uses the -needed_library or -needed-l option as ap‐
5924 propriate, and has the same linker constraints as NEEDED_FRAME‐
5925 WORK.
5926 REEXPORT_LIBRARY
5928 This is similar to the REEXPORT_FRAMEWORK feature, except it is
5929 for use with non-framework targets or libraries (Apple platforms
5930 only). It uses the -reexport_library or -reexport-l option as
5931 appropriate, and has the same linker constraints as REEX‐
5932 PORT_FRAMEWORK.
5933 WEAK_LIBRARY
5935 This is similar to the WEAK_FRAMEWORK feature, except it is for
5936 use with non-framework targets or libraries (Apple platforms
5937 only). It uses the -weak_library or -weak-l option as appropri‐
5938 ate, and has the same linker constraints as WEAK_FRAMEWORK.
5939 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
5941 New in version 3.24.
5942 Set to TRUE if the <FEATURE>, as defined by variable
5945 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>, is supported for the linker
5946 language <LANG>.
5947 NOTE:
5949 This variable is evaluated before the more generic variable
5950 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED.
5951 CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG
5953 New in version 3.22.
5954 Linker flag to be used to configure linker so that all specified li‐
5957 braries on the command line will be linked into the target.
5958 See also variable CMAKE_LINK_WHAT_YOU_USE_CHECK.
5960 CMAKE_<LANG>_LINKER_LAUNCHER
5962 New in version 3.21.
5963 Default value for <LANG>_LINKER_LAUNCHER target property. This variable
5966 is used to initialize the property on each target as it is created.
5967 This is done only when <LANG> is C, CXX, OBJC, or OBJCXX.
5968 This variable is initialized to the CMAKE_<LANG>_LINKER_LAUNCHER envi‐
5970 ronment variable if it is set.
5971 CMAKE_<LANG>_VISIBILITY_PRESET
5973 Default value for the <LANG>_VISIBILITY_PRESET target property when a
5974 target is created.
5975 CMAKE_LIBRARY_OUTPUT_DIRECTORY
5977 Where to put all the LIBRARY target files when built.
5978 This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY prop‐
5980 erty on all the targets. See that target property for additional in‐
5981 formation.
5982 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
5984 New in version 3.3.
5985 Where to put all the LIBRARY target files when built for a specific
5988 configuration.
5989 This variable is used to initialize the
5991 LIBRARY_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
5992 that target property for additional information.
5993 CMAKE_LIBRARY_PATH_FLAG
5995 The flag to be used to add a library search path to a compiler.
5996 The flag will be used to specify a library directory to the compiler.
5998 On most compilers this is -L.
5999 CMAKE_LINK_DEF_FILE_FLAG
6001 Linker flag to be used to specify a .def file for dll creation.
6002 The flag will be used to add a .def file when creating a dll on Win‐
6004 dows; this is only defined on Windows.
6005 CMAKE_LINK_DEPENDS_NO_SHARED
6007 Whether to skip link dependencies on shared library files.
6008 This variable initializes the LINK_DEPENDS_NO_SHARED property on tar‐
6010 gets when they are created. See that target property for additional
6011 information.
6012 CMAKE_LINK_GROUP_USING_<FEATURE>
6014 New in version 3.24.
6015 This variable defines how to link a group of libraries for the speci‐
6018 fied <FEATURE> when a LINK_GROUP generator expression is used. Both of
6019 the following conditions must be met for this variable to have any ef‐
6020 fect:
6021 • The associated CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable
6023 must be set to true.
6024 • There is no language-specific definition for the same <FEATURE>.
6026 This means CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED cannot
6027 be true for the link language used by the target for which the
6028 LINK_GROUP generator expression is evaluated.
6029 The CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable should be defined
6031 instead for features that are dependent on the link language.
6032 Feature names are case-sensitive and may only contain letters, numbers
6034 and underscores. Feature names defined in all uppercase are reserved
6035 for CMake's own built-in features (see Predefined Features further be‐
6036 low).
6037 Feature Definitions
6039 A group feature definition is a list that contains exactly two ele‐
6040 ments:
6041 <PREFIX> <SUFFIX>
6043 On the linker command line, <PREFIX> will precede the list of libraries
6045 in the group and <SUFFIX> will follow after.
6046 For the elements of this variable, the LINKER: prefix can be used.
6048 To pass options to the linker tool, each compiler driver has its own
6050 syntax. The LINKER: prefix and , separator can be used to specify, in
6051 a portable way, options to pass to the linker tool. LINKER: is replaced
6052 by the appropriate driver option and , by the appropriate driver sepa‐
6053 rator. The driver prefix and driver separator are given by the values
6054 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6055 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6056 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6058 Clang and -Wl,-z,defs for GNU GCC.
6059 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6061 sion.
6062 The LINKER: prefix supports, as an alternative syntax, specification of
6064 arguments using the SHELL: prefix and space as separator. The previous
6065 example then becomes "LINKER:SHELL:-z defs".
6066 NOTE:
6068 Specifying the SHELL: prefix anywhere other than at the beginning of
6069 the LINKER: prefix is not supported.
6070 Examples
6072 Solving cross-references between two static libraries
6073 A project may define two or more static libraries which have circular
6074 dependencies between them. In order for the linker to resolve all sym‐
6075 bols at link time, it may need to search repeatedly among the libraries
6076 until no new undefined references are created. Different linkers use
6077 different syntax for achieving this. The following example shows how
6078 this may be implemented for some linkers. Note that this is for illus‐
6079 tration purposes only. Projects should use the built-in RESCAN group
6080 feature instead (see Predefined Features), which provides a more com‐
6081 plete and more robust implementation of this functionality.
6082 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
6084 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6085 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6086 "LINKER:--start-group"
6087 "LINKER:--end-group"
6088 )
6089 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
6090 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6091 "LINKER:-z,rescan-start"
6092 "LINKER:-z,rescan-end"
6093 )
6094 else()
6095 # feature not yet supported for the other environments
6096 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
6097 endif()
6098 add_library(lib1 STATIC ...)
6100 add_library(lib2 SHARED ...)
6101 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
6103 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
6104 else()
6105 target_link_libraries(lib2 PRIVATE lib1 external)
6106 endif()
6107 CMake will generate the following linker command line fragments when
6109 linking lib2:
6110 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
6112 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
6114 can-end
6115 Predefined Features
6117 The following built-in group features are pre-defined by CMake:
6118 RESCAN Some linkers are single-pass only. For such linkers, circular
6120 references between libraries typically result in unresolved sym‐
6121 bols. This feature instructs the linker to search the specified
6122 static libraries repeatedly until no new undefined references
6123 are created.
6124 Normally, a static library is searched only once in the order
6126 that it is specified on the command line. If a symbol in that
6127 library is needed to resolve an undefined symbol referred to by
6128 an object in a library that appears later on the command line,
6129 the linker would not be able to resolve that reference. By
6130 grouping the static libraries with the RESCAN feature, they will
6131 all be searched repeatedly until all possible references are re‐
6132 solved. This will use linker options like --start-group and
6133 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
6134 Using this feature has a significant performance cost. It is
6136 best to use it only when there are unavoidable circular refer‐
6137 ences between two or more static libraries.
6138 This feature is available when using toolchains that target
6140 Linux, BSD, and SunOS. It can also be used when targeting Win‐
6141 dows platforms if the GNU toolchain is used.
6142 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
6144 New in version 3.24.
6145 This variable specifies whether the <FEATURE> is supported regardless
6148 of the link language. If this variable is true, then the <FEATURE>
6149 must be defined by CMAKE_LINK_GROUP_USING_<FEATURE>.
6150 Note that this variable has no effect if
6152 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is true for the link
6153 language of the target.
6154 CMAKE_LINK_INTERFACE_LIBRARIES
6156 Default value for LINK_INTERFACE_LIBRARIES of targets.
6157 This variable is used to initialize the LINK_INTERFACE_LIBRARIES prop‐
6159 erty on all the targets. See that target property for additional in‐
6160 formation.
6161 CMAKE_LINK_LIBRARY_FILE_FLAG
6163 Flag to be used to link a library specified by a path to its file.
6164 The flag will be used before a library file path is given to the
6166 linker. This is needed only on very few platforms.
6167 CMAKE_LINK_LIBRARY_FLAG
6169 Flag to be used to link a library into an executable.
6170 The flag will be used to specify a library to link to an executable.
6172 On most compilers this is -l.
6173 CMAKE_LINK_LIBRARY_USING_<FEATURE>
6175 New in version 3.24.
6176 This variable defines how to link a library or framework for the speci‐
6179 fied <FEATURE> when a LINK_LIBRARY generator expression is used. Both
6180 of the following conditions must be met for this variable to have any
6181 effect:
6182 • The associated CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
6184 must be set to true.
6185 • There is no language-specific definition for the same <FEATURE>.
6187 This means CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED cannot
6188 be true for the link language used by the target for which the
6189 LINK_LIBRARY generator expression is evaluated.
6190 Feature names are case-sensitive and may only contain letters, numbers
6192 and underscores. Feature names defined in all uppercase are reserved
6193 for CMake's own built-in features (see Predefined Features further be‐
6194 low).
6195 Feature Definitions
6197 A library feature definition is a list that contains one or three ele‐
6198 ments:
6199 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
6201 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
6203 spectively the whole list of libraries specified in the LINK_LIBRARY
6204 expression, not each library item individually. There is no guarantee
6205 that the list of specified libraries will be kept grouped together
6206 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
6207 library list is reorganized by CMake to satisfy other constraints.
6208 This means constructs like --start-group and --end-group, as supported
6209 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
6210 erator expression should be used instead for such constructs.
6211 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
6213 the corresponding fragment on the linker command line for each library.
6214 The following placeholders can be used in the expression:
6215 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
6217 gets, or to a platform-specific value based on the item otherwise
6218 (the same as <LINK_ITEM> on Windows, or the library base name for
6219 other platforms).
6220 • <LINK_ITEM> is expanded to how the library would normally be linked
6222 on the linker command line.
6223 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
6225 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
6226 SION> otherwise.
6227 In addition to the above, it is possible to have one pattern for paths
6229 (CMake targets and external libraries specified with file paths) and
6230 another for other items specified by name only. The PATH{} and NAME{}
6231 wrappers can be used to provide the expansion for those two cases, re‐
6232 spectively. When wrappers are used, both must be present. For exam‐
6233 ple:
6234 set(CMAKE_LINK_LIBRARY_USING_weak_library
6236 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6237 )
6238 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
6240 SION>, and <SUFFIX>), the LINKER: prefix can be used.
6241 To pass options to the linker tool, each compiler driver has its own
6243 syntax. The LINKER: prefix and , separator can be used to specify, in
6244 a portable way, options to pass to the linker tool. LINKER: is replaced
6245 by the appropriate driver option and , by the appropriate driver sepa‐
6246 rator. The driver prefix and driver separator are given by the values
6247 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6248 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6249 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6251 Clang and -Wl,-z,defs for GNU GCC.
6252 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6254 sion.
6255 The LINKER: prefix supports, as an alternative syntax, specification of
6257 arguments using the SHELL: prefix and space as separator. The previous
6258 example then becomes "LINKER:SHELL:-z defs".
6259 NOTE:
6261 Specifying the SHELL: prefix anywhere other than at the beginning of
6262 the LINKER: prefix is not supported.
6263 Examples
6265 Loading a whole static library
6266 A common need is to prevent the linker from discarding any symbols from
6267 a static library. Different linkers use different syntax for achieving
6268 this. The following example shows how this may be implemented for some
6269 linkers. Note that this is for illustration purposes only. Projects
6270 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
6271 Features), which provides a more complete and more robust implementa‐
6272 tion of this functionality.
6273 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
6275 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6276 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
6277 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6278 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
6279 "LINKER:--push-state,--whole-archive"
6280 "<LINK_ITEM>"
6281 "LINKER:--pop-state"
6282 )
6283 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
6284 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
6285 else()
6286 # feature not yet supported for the other environments
6287 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
6288 endif()
6289 add_library(lib1 STATIC ...)
6291 add_library(lib2 SHARED ...)
6292 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
6294 # The -force_load Apple linker option requires a file name
6295 set(external_lib
6296 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
6297 )
6298 target_link_libraries(lib2 PRIVATE
6299 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
6300 )
6301 else()
6302 target_link_libraries(lib2 PRIVATE lib1 external)
6303 endif()
6304 CMake will generate the following link expressions:
6306 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
6308 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
6310 -Wl,--pop-state
6311 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
6313 Linking a library as weak
6315 On macOS, it is possible to link a library in weak mode (the library
6316 and all references are marked as weak imports). Different flags must
6317 be used for a library specified by file path compared to one specified
6318 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
6319 pers. Again, the following example shows how this may be implemented
6320 for some linkers, but it is for illustration purposes only. Projects
6321 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
6322 (see Predefined Features), which provide more complete and more robust
6323 implementations of this functionality.
6324 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6326 set(CMAKE_LINK_LIBRARY_USING_weak_library
6327 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6328 )
6329 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
6330 endif()
6331 add_library(lib SHARED ...)
6333 add_executable(main ...)
6334 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
6335 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
6336 else()
6337 target_link_libraries(main PRIVATE lib external)
6338 endif()
6339 CMake will generate the following linker command line fragment when
6341 linking main using the AppleClang toolchain:
6342 -weak_library /path/to/lib -Xlinker -weak-lexternal.
6344 Predefined Features
6346 The following built-in library features are pre-defined by CMake:
6347 DEFAULT
6349 This feature corresponds to standard linking, essentially equiv‐
6350 alent to using no feature at all. It is typically only used
6351 with the LINK_LIBRARY_OVERRIDE and
6352 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
6353 WHOLE_ARCHIVE
6355 Force inclusion of all members of a static library. This fea‐
6356 ture is only supported for the following platforms, with limita‐
6357 tions as noted:
6358 • Linux.
6360 • All BSD variants.
6362 • SunOS.
6364 • All Apple variants. The library must be specified as a CMake
6366 target name, a library file name (such as libfoo.a), or a li‐
6367 brary file path (such as /path/to/libfoo.a). Due to a limita‐
6368 tion of the Apple linker, it cannot be specified as a plain
6369 library name like foo, where foo is not a CMake target.
6370 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
6372 version must be greater than 1900.
6373 • Cygwin.
6375 • MSYS.
6377 FRAMEWORK
6379 This option tells the linker to search for the specified frame‐
6380 work using the -framework linker option. It can only be used on
6381 Apple platforms, and only with a linker that understands the op‐
6382 tion used (i.e. the linker provided with Xcode, or one compati‐
6383 ble with it).
6384 The framework can be specified as a CMake framework target, a
6386 bare framework name, or a file path. If a target is given, that
6387 target must have the FRAMEWORK target property set to true. For
6388 a file path, if it contains a directory part, that directory
6389 will be added as a framework search path.
6390 add_library(lib SHARED ...)
6392 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
6393 # The constructed linker command line will contain:
6395 # -F/path/to -framework my_framework
6396 File paths must conform to one of the following patterns (* is a
6398 wildcard, and optional parts are shown as [...]):
6399 • [/path/to/]FwName[.framework]
6401 • [/path/to/]FwName.framework/FwName[suffix]
6403 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
6405 Note that CMake recognizes and automatically handles framework
6407 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
6408 expression. The generator expression can still be used with a
6409 CMake target if the project wants to be explicit about it, but
6410 it is not required to do so. The linker command line may have
6411 some differences between using the generator expression or not,
6412 but the final result should be the same. On the other hand, if
6413 a file path is given, CMake will recognize some paths automati‐
6414 cally, but not all cases. The project may want to use
6415 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
6416 pected behavior is clear.
6417 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
6419 target property as well as the suffix of the framework library
6420 name are now supported by the FRAMEWORK features.
6421 NEEDED_FRAMEWORK
6424 This is similar to the FRAMEWORK feature, except it forces the
6425 linker to link with the framework even if no symbols are used
6426 from it. It uses the -needed_framework option and has the same
6427 linker constraints as FRAMEWORK.
6428 REEXPORT_FRAMEWORK
6430 This is similar to the FRAMEWORK feature, except it tells the
6431 linker that the framework should be available to clients linking
6432 to the library being created. It uses the -reexport_framework
6433 option and has the same linker constraints as FRAMEWORK.
6434 WEAK_FRAMEWORK
6436 This is similar to the FRAMEWORK feature, except it forces the
6437 linker to mark the framework and all references to it as weak
6438 imports. It uses the -weak_framework option and has the same
6439 linker constraints as FRAMEWORK.
6440 NEEDED_LIBRARY
6442 This is similar to the NEEDED_FRAMEWORK feature, except it is
6443 for use with non-framework targets or libraries (Apple platforms
6444 only). It uses the -needed_library or -needed-l option as ap‐
6445 propriate, and has the same linker constraints as NEEDED_FRAME‐
6446 WORK.
6447 REEXPORT_LIBRARY
6449 This is similar to the REEXPORT_FRAMEWORK feature, except it is
6450 for use with non-framework targets or libraries (Apple platforms
6451 only). It uses the -reexport_library or -reexport-l option as
6452 appropriate, and has the same linker constraints as REEX‐
6453 PORT_FRAMEWORK.
6454 WEAK_LIBRARY
6456 This is similar to the WEAK_FRAMEWORK feature, except it is for
6457 use with non-framework targets or libraries (Apple platforms
6458 only). It uses the -weak_library or -weak-l option as appropri‐
6459 ate, and has the same linker constraints as WEAK_FRAMEWORK.
6460 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
6462 New in version 3.24.
6463 Set to TRUE if the <FEATURE>, as defined by variable
6466 CMAKE_LINK_LIBRARY_USING_<FEATURE>, is supported regardless the linker
6467 language.
6468 NOTE:
6470 This variable is evaluated if, and only if, the variable
6471 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED is not defined.
6472 CMAKE_LINK_WHAT_YOU_USE
6474 New in version 3.7.
6475 Default value for LINK_WHAT_YOU_USE target property. This variable is
6478 used to initialize the property on each target as it is created.
6479 CMAKE_LINK_WHAT_YOU_USE_CHECK
6481 New in version 3.22.
6482 Defines the command executed after the link step to check libraries us‐
6485 age. This check is currently only defined on ELF platforms with value
6486 ldd -u -r.
6487 See also CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG variables.
6489 CMAKE_MACOSX_BUNDLE
6491 Default value for MACOSX_BUNDLE of targets.
6492 This variable is used to initialize the MACOSX_BUNDLE property on all
6494 the targets. See that target property for additional information.
6495 This variable is set to ON by default if CMAKE_SYSTEM_NAME equals to
6497 iOS, tvOS or watchOS.
6498 CMAKE_MACOSX_RPATH
6500 Whether to use rpaths on macOS and iOS.
6501 This variable is used to initialize the MACOSX_RPATH property on all
6503 targets.
6504 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>
6506 Default value for MAP_IMPORTED_CONFIG_<CONFIG> of targets.
6507 This variable is used to initialize the MAP_IMPORTED_CONFIG_<CONFIG>
6509 property on all the targets. See that target property for additional
6510 information.
6511 CMAKE_MODULE_LINKER_FLAGS
6513 Linker flags to be used to create modules.
6514 These flags will be used by the linker when creating a module.
6516 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
6518 Flags to be used when linking a module.
6519 Same as CMAKE_C_FLAGS_* but used by the linker when creating modules.
6521 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT
6523 New in version 3.7.
6524 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS_<CONFIG> cache
6527 entry the first time a build tree is configured. This variable is
6528 meant to be set by a toolchain file. CMake may prepend or append con‐
6529 tent to the value based on the environment and target platform.
6530 See also CMAKE_MODULE_LINKER_FLAGS_INIT.
6532 CMAKE_MODULE_LINKER_FLAGS_INIT
6534 New in version 3.7.
6535 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS cache entry the
6538 first time a build tree is configured. This variable is meant to be
6539 set by a toolchain file. CMake may prepend or append content to the
6540 value based on the environment and target platform.
6541 See also the configuration-specific variable
6543 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT.
6544 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
6546 New in version 3.25.
6547 Select the MSVC debug information format targeting the MSVC ABI. This
6550 variable is used to initialize the MSVC_DEBUG_INFORMATION_FORMAT prop‐
6551 erty on all targets as they are created. It is also propagated by
6552 calls to the try_compile() command into the test project.
6553 The allowed values are:
6555 Embedded
6557 Compile with -Z7 or equivalent flag(s) to produce object files
6558 with full symbolic debugging information.
6559 ProgramDatabase
6561 Compile with -Zi or equivalent flag(s) to produce a program
6562 database that contains all the symbolic debugging information.
6563 EditAndContinue
6565 Compile with -ZI or equivalent flag(s) to produce a program
6566 database that supports the Edit and Continue feature.
6567 The value is ignored on compilers not targeting the MSVC ABI, but an
6569 unsupported value will be rejected as an error when using a compiler
6570 targeting the MSVC ABI.
6571 The value may also be the empty string (""), in which case no debug in‐
6573 formation format flag will be added explicitly by CMake.
6574 Use generator expressions to support per-configuration specification.
6576 For example, the code:
6577 set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
6579 selects for all following targets the program database debug informa‐
6581 tion format for the Debug configuration.
6582 If this variable is not set, the MSVC_DEBUG_INFORMATION_FORMAT target
6584 property will not be set automatically. If that property is not set,
6585 CMake selects a debug information format using the default value
6586 $<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>, if supported by the
6587 compiler, and otherwise $<$<CONFIG:Debug,RelWithDebInfo>:Embedded>.
6588 NOTE:
6590 This variable has effect only when policy CMP0141 is set to NEW
6591 prior to the first project() or enable_language() command that en‐
6592 ables a language using a compiler targeting the MSVC ABI.
6593 CMAKE_MSVC_RUNTIME_LIBRARY
6595 New in version 3.15.
6596 Select the MSVC runtime library for use by compilers targeting the MSVC
6599 ABI. This variable is used to initialize the MSVC_RUNTIME_LIBRARY
6600 property on all targets as they are created. It is also propagated by
6601 calls to the try_compile() command into the test project.
6602 The allowed values are:
6604 MultiThreaded
6606 Compile with -MT or equivalent flag(s) to use a multi-threaded
6607 statically-linked runtime library.
6608 MultiThreadedDLL
6610 Compile with -MD or equivalent flag(s) to use a multi-threaded
6611 dynamically-linked runtime library.
6612 MultiThreadedDebug
6614 Compile with -MTd or equivalent flag(s) to use a multi-threaded
6615 statically-linked runtime library.
6616 MultiThreadedDebugDLL
6618 Compile with -MDd or equivalent flag(s) to use a multi-threaded
6619 dynamically-linked runtime library.
6620 The value is ignored on compilers not targeting the MSVC ABI, but an
6622 unsupported value will be rejected as an error when using a compiler
6623 targeting the MSVC ABI.
6624 The value may also be the empty string ("") in which case no runtime
6626 library selection flag will be added explicitly by CMake. Note that
6627 with Visual Studio Generators the native build system may choose to add
6628 its own default runtime library selection flag.
6629 Use generator expressions to support per-configuration specification.
6631 For example, the code:
6632 set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
6634 selects for all following targets a multi-threaded statically-linked
6636 runtime library with or without debug information depending on the con‐
6637 figuration.
6638 If this variable is not set then the MSVC_RUNTIME_LIBRARY target prop‐
6640 erty will not be set automatically. If that property is not set then
6641 CMake uses the default value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL
6642 to select a MSVC runtime library.
6643 NOTE:
6645 This variable has effect only when policy CMP0091 is set to NEW
6646 prior to the first project() or enable_language() command that en‐
6647 ables a language using a compiler targeting the MSVC ABI.
6648 CMAKE_MSVCIDE_RUN_PATH
6650 New in version 3.10.
6651 Extra PATH locations that should be used when executing
6654 add_custom_command() or add_custom_target() when using the Visual Stu‐
6655 dio 9 2008 (or above) generator. This allows for running commands and
6656 using dll's that the IDE environment is not aware of.
6657 If not set explicitly the value is initialized by the CMAKE_MSV‐
6659 CIDE_RUN_PATH environment variable, if set, and otherwise left empty.
6660 CMAKE_NINJA_OUTPUT_PATH_PREFIX
6662 New in version 3.6.
6663 Set output files path prefix for the Ninja generator.
6666 Every output files listed in the generated build.ninja will be prefixed
6668 by the contents of this variable (a trailing slash is appended if miss‐
6669 ing). This is useful when the generated ninja file is meant to be em‐
6670 bedded as a subninja file into a super ninja project. For example, a
6671 ninja build file generated with a command like:
6672 cd top-build-dir/sub &&
6674 cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source
6675 can be embedded in top-build-dir/build.ninja with a directive like
6677 this:
6678 subninja sub/build.ninja
6680 The auto-regeneration rule in top-build-dir/build.ninja must have an
6682 order-only dependency on sub/build.ninja.
6683 NOTE:
6685 When CMAKE_NINJA_OUTPUT_PATH_PREFIX is set, the project generated by
6686 CMake cannot be used as a standalone project. No default targets
6687 are specified.
6688 CMAKE_NO_BUILTIN_CHRPATH
6690 Do not use the builtin binary editor to fix runtime library search
6691 paths on installation.
6692 When an ELF or XCOFF binary needs to have a different runtime library
6694 search path after installation than it does in the build tree, CMake
6695 uses a builtin editor to change the runtime search path in the in‐
6696 stalled copy. If this variable is set to true then CMake will relink
6697 the binary before installation instead of using its builtin editor.
6698 New in version 3.20: This variable also applies to XCOFF binaries' LIB‐
6700 PATH. Prior to the addition of the XCOFF editor in CMake 3.20, this
6701 variable applied only to ELF binaries' RPATH/RUNPATH.
6702 CMAKE_NO_SYSTEM_FROM_IMPORTED
6705 Default value for NO_SYSTEM_FROM_IMPORTED of targets.
6706 This variable is used to initialize the NO_SYSTEM_FROM_IMPORTED prop‐
6708 erty on all the targets. See that target property for additional in‐
6709 formation.
6710 CMAKE_OPTIMIZE_DEPENDENCIES
6712 New in version 3.19.
6713 Initializes the OPTIMIZE_DEPENDENCIES target property.
6716 CMAKE_OSX_ARCHITECTURES
6718 Target specific architectures for macOS and iOS.
6719 This variable is used to initialize the OSX_ARCHITECTURES property on
6721 each target as it is created. See that target property for additional
6722 information.
6723 The value of this variable should be set prior to the first project()
6725 or enable_language() command invocation because it may influence con‐
6726 figuration of the toolchain and flags. It is intended to be set lo‐
6727 cally by the user creating a build tree. This variable should be set
6728 as a CACHE entry (or else CMake may remove it while initializing a
6729 cache entry of the same name) unless policy CMP0126 is set to NEW.
6730 Despite the OSX part in the variable name(s) they apply also to other
6732 SDKs than macOS like iOS, tvOS, or watchOS.
6733 This variable is ignored on platforms other than Apple.
6735 CMAKE_OSX_DEPLOYMENT_TARGET
6737 Specify the minimum version of the target platform (e.g. macOS or iOS)
6738 on which the target binaries are to be deployed. CMake uses this vari‐
6739 able value for the -mmacosx-version-min flag or their respective target
6740 platform equivalents. For older Xcode versions that shipped multiple
6741 macOS SDKs this variable also helps to choose the SDK in case
6742 CMAKE_OSX_SYSROOT is unset.
6743 If not set explicitly the value is initialized by the MACOSX_DEPLOY‐
6745 MENT_TARGET environment variable, if set, and otherwise computed based
6746 on the host platform.
6747 The value of this variable should be set prior to the first project()
6749 or enable_language() command invocation because it may influence con‐
6750 figuration of the toolchain and flags. It is intended to be set lo‐
6751 cally by the user creating a build tree. This variable should be set
6752 as a CACHE entry (or else CMake may remove it while initializing a
6753 cache entry of the same name) unless policy CMP0126 is set to NEW.
6754 Despite the OSX part in the variable name(s) they apply also to other
6756 SDKs than macOS like iOS, tvOS, or watchOS.
6757 This variable is ignored on platforms other than Apple.
6759 CMAKE_OSX_SYSROOT
6761 Specify the location or name of the macOS platform SDK to be used.
6762 CMake uses this value to compute the value of the -isysroot flag or
6763 equivalent and to help the find_* commands locate files in the SDK.
6764 If not set explicitly the value is initialized by the SDKROOT environ‐
6766 ment variable, if set, and otherwise computed based on the
6767 CMAKE_OSX_DEPLOYMENT_TARGET or the host platform.
6768 The value of this variable should be set prior to the first project()
6770 or enable_language() command invocation because it may influence con‐
6771 figuration of the toolchain and flags. It is intended to be set lo‐
6772 cally by the user creating a build tree. This variable should be set
6773 as a CACHE entry (or else CMake may remove it while initializing a
6774 cache entry of the same name) unless policy CMP0126 is set to NEW.
6775 Despite the OSX part in the variable name(s) they apply also to other
6777 SDKs than macOS like iOS, tvOS, or watchOS.
6778 This variable is ignored on platforms other than Apple.
6780 CMAKE_PCH_INSTANTIATE_TEMPLATES
6782 New in version 3.19.
6783 This variable is used to initialize the PCH_INSTANTIATE_TEMPLATES prop‐
6786 erty of targets when they are created.
6787 CMAKE_PCH_WARN_INVALID
6789 New in version 3.18.
6790 This variable is used to initialize the PCH_WARN_INVALID property of
6793 targets when they are created.
6794 CMAKE_PDB_OUTPUT_DIRECTORY
6796 Output directory for MS debug symbol .pdb files generated by the linker
6797 for executable and shared library targets.
6798 This variable is used to initialize the PDB_OUTPUT_DIRECTORY property
6800 on all the targets. See that target property for additional informa‐
6801 tion.
6802 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>
6804 Per-configuration output directory for MS debug symbol .pdb files gen‐
6805 erated by the linker for executable and shared library targets.
6806 This is a per-configuration version of CMAKE_PDB_OUTPUT_DIRECTORY.
6808 This variable is used to initialize the PDB_OUTPUT_DIRECTORY_<CONFIG>
6809 property on all the targets. See that target property for additional
6810 information.
6811 CMAKE_PLATFORM_NO_VERSIONED_SONAME
6813 New in version 3.1.
6814 This variable is used to globally control whether the VERSION and
6817 SOVERSION target properties should be used for shared libraries. When
6818 set to true, adding version information to each shared library target
6819 is disabled.
6820 By default this variable is set only on platforms where CMake knows it
6822 is needed. On other platforms, the specified properties will be used
6823 for shared libraries.
6824 CMAKE_POSITION_INDEPENDENT_CODE
6826 Default value for POSITION_INDEPENDENT_CODE of targets.
6827 This variable is used to initialize the POSITION_INDEPENDENT_CODE prop‐
6829 erty on all the targets. See that target property for additional in‐
6830 formation. If set, its value is also used by the try_compile() com‐
6831 mand.
6832 CMAKE_RUNTIME_OUTPUT_DIRECTORY
6834 Where to put all the RUNTIME target files when built.
6835 This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY prop‐
6837 erty on all the targets. See that target property for additional in‐
6838 formation.
6839 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
6841 New in version 3.3.
6842 Where to put all the RUNTIME target files when built for a specific
6845 configuration.
6846 This variable is used to initialize the
6848 RUNTIME_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
6849 that target property for additional information.
6850 CMAKE_SHARED_LINKER_FLAGS
6852 Linker flags to be used to create shared libraries.
6853 These flags will be used by the linker when creating a shared library.
6855 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
6857 Flags to be used when linking a shared library.
6858 Same as CMAKE_C_FLAGS_* but used by the linker when creating shared li‐
6860 braries.
6861 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT
6863 New in version 3.7.
6864 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS_<CONFIG> cache
6867 entry the first time a build tree is configured. This variable is
6868 meant to be set by a toolchain file. CMake may prepend or append con‐
6869 tent to the value based on the environment and target platform.
6870 See also CMAKE_SHARED_LINKER_FLAGS_INIT.
6872 CMAKE_SHARED_LINKER_FLAGS_INIT
6874 New in version 3.7.
6875 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS cache entry the
6878 first time a build tree is configured. This variable is meant to be
6879 set by a toolchain file. CMake may prepend or append content to the
6880 value based on the environment and target platform.
6881 See also the configuration-specific variable
6883 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT.
6884 CMAKE_SKIP_BUILD_RPATH
6886 Do not include RPATHs in the build tree.
6887 Normally CMake uses the build tree for the RPATH when building executa‐
6889 bles etc on systems that use RPATH. When the software is installed the
6890 executables etc are relinked by CMake to have the install RPATH. If
6891 this variable is set to true then the software is always built with no
6892 RPATH.
6893 CMAKE_SKIP_INSTALL_RPATH
6895 Do not include RPATHs in the install tree.
6896 Normally CMake uses the build tree for the RPATH when building executa‐
6898 bles etc on systems that use RPATH. When the software is installed the
6899 executables etc are relinked by CMake to have the install RPATH. If
6900 this variable is set to true then the software is always installed
6901 without RPATH, even if RPATH is enabled when building. This can be
6902 useful for example to allow running tests from the build directory with
6903 RPATH enabled before the installation step. To omit RPATH in both the
6904 build and install steps, use CMAKE_SKIP_RPATH instead.
6905 CMAKE_STATIC_LINKER_FLAGS
6907 Flags to be used to create static libraries. These flags will be
6908 passed to the archiver when creating a static library.
6909 See also CMAKE_STATIC_LINKER_FLAGS_<CONFIG>.
6911 NOTE:
6913 Static libraries do not actually link. They are essentially ar‐
6914 chives of object files. The use of the name "linker" in the name of
6915 this variable is kept for compatibility.
6916 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
6918 Flags to be used to create static libraries. These flags will be
6919 passed to the archiver when creating a static library in the <CONFIG>
6920 configuration.
6921 See also CMAKE_STATIC_LINKER_FLAGS.
6923 NOTE:
6925 Static libraries do not actually link. They are essentially ar‐
6926 chives of object files. The use of the name "linker" in the name of
6927 this variable is kept for compatibility.
6928 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT
6930 New in version 3.7.
6931 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS_<CONFIG> cache
6934 entry the first time a build tree is configured. This variable is
6935 meant to be set by a toolchain file. CMake may prepend or append con‐
6936 tent to the value based on the environment and target platform.
6937 See also CMAKE_STATIC_LINKER_FLAGS_INIT.
6939 CMAKE_STATIC_LINKER_FLAGS_INIT
6941 New in version 3.7.
6942 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS cache entry the
6945 first time a build tree is configured. This variable is meant to be
6946 set by a toolchain file. CMake may prepend or append content to the
6947 value based on the environment and target platform.
6948 See also the configuration-specific variable
6950 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT.
6951 CMAKE_TASKING_TOOLSET
6953 New in version 3.25.
6954 Select the Tasking toolset which provides the compiler
6957 Architecture compilers are provided by different toolchains with incom‐
6959 patible versioning schemes. Set this variable in a toolchain file so
6960 CMake can detect the compiler features correctly. If no toolset is
6961 specified, Standalone is assumed.
6962 Due to the different versioning schemes, the compiler version (‐
6964 CMAKE_<LANG>_COMPILER_VERSION) depends on the toolset and architecture
6965 in use. If projects can be built with multiple toolsets or architec‐
6966 tures, the specified CMAKE_TASKING_TOOLSET and the automatically deter‐
6967 mined CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID must be taken into account
6968 when comparing against the CMAKE_<LANG>_COMPILER_VERSION.
6969 TriCore
6971 Compilers are provided by the TriCore toolset.
6972 SmartCode
6974 Compilers are provided by the SmartCode toolset.
6975 Standalone
6977 Compilers are provided by the standalone toolsets.
6978 NOTE:
6980 For the TriCore architecture, the compiler from the TriCore
6981 toolset is selected as standalone compiler.
6982 CMAKE_TRY_COMPILE_CONFIGURATION
6984 Build configuration used for try_compile() and try_run() projects.
6985 Projects built by try_compile() and try_run() are built synchronously
6987 during the CMake configuration step. Therefore a specific build con‐
6988 figuration must be chosen even if the generated build system supports
6989 multiple configurations.
6990 CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
6992 New in version 3.24.
6993 Set to a true value to tell the try_compile() command not to propagate
6996 any platform variables into the test project.
6997 The try_compile() command normally passes some CMake variables that
6999 configure the platform and toolchain behavior into test projects. See
7000 policy CMP0137. This variable may be set to disable that behavior.
7001 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
7003 New in version 3.6.
7004 List of variables that the try_compile() command source file signature
7007 must propagate into the test project in order to target the same plat‐
7008 form as the host project.
7009 This variable should not be set by project code. It is meant to be set
7011 by CMake's platform information modules for the current toolchain, or
7012 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
7013 Variables meaningful to CMake, such as CMAKE_<LANG>_FLAGS, are propa‐
7015 gated automatically. The CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable
7016 may be set to pass custom variables meaningful to a toolchain file.
7017 For example, a toolchain file may contain:
7018 set(CMAKE_SYSTEM_NAME ...)
7020 set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE)
7021 # ... use MY_CUSTOM_VARIABLE ...
7022 If a user passes -DMY_CUSTOM_VARIABLE=SomeValue to CMake then this set‐
7024 ting will be made visible to the toolchain file both for the main
7025 project and for test projects generated by the try_compile() command
7026 source file signature.
7027 Changed in version 3.24: Listed variables are propagated to the
7029 try_compile() whole-project signature too. See CMP0137.
7030 New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES vari‐
7033 able may be set to disable passing platform variables into the test
7034 project.
7035 CMAKE_TRY_COMPILE_TARGET_TYPE
7038 New in version 3.6.
7039 Type of target generated for try_compile() calls using the source file
7042 signature. Valid values are:
7043 EXECUTABLE
7045 Use add_executable() to name the source file in the generated
7046 project. This is the default if no value is given.
7047 STATIC_LIBRARY
7049 Use add_library() with the STATIC option to name the source file
7050 in the generated project. This avoids running the linker and is
7051 intended for use with cross-compiling toolchains that cannot
7052 link without custom flags or linker scripts.
7053 CMAKE_UNITY_BUILD
7055 New in version 3.16.
7056 This variable is used to initialize the UNITY_BUILD property of targets
7059 when they are created. Setting it to true enables batch compilation of
7060 multiple sources within each target. This feature is known as a Unity
7061 or Jumbo build.
7062 Projects should not set this variable, it is intended as a developer
7064 control to be set on the cmake(1) command line or other equivalent
7065 methods. The developer must have the ability to enable or disable
7066 unity builds according to the capabilities of their own machine and
7067 compiler.
7068 By default, this variable is not set, which will result in unity builds
7070 being disabled.
7071 NOTE:
7073 This option currently does not work well in combination with the
7074 CMAKE_EXPORT_COMPILE_COMMANDS variable.
7075 CMAKE_UNITY_BUILD_BATCH_SIZE
7077 New in version 3.16.
7078 This variable is used to initialize the UNITY_BUILD_BATCH_SIZE property
7081 of targets when they are created. It specifies the default upper limit
7082 on the number of source files that may be combined in any one unity
7083 source file when unity builds are enabled for a target.
7084 CMAKE_UNITY_BUILD_UNIQUE_ID
7086 New in version 3.20.
7087 This variable is used to initialize the UNITY_BUILD_UNIQUE_ID property
7090 of targets when they are created. It specifies the name of the unique
7091 identifier generated per file in a unity build.
7092 CMAKE_USE_RELATIVE_PATHS
7094 This variable has no effect. The partially implemented effect it had
7095 in previous releases was removed in CMake 3.4.
7096 CMAKE_VERIFY_INTERFACE_HEADER_SETS
7098 New in version 3.24.
7099 This variable is used to initialize the VERIFY_INTERFACE_HEADER_SETS
7102 property of targets when they are created. Setting it to true enables
7103 header set verification.
7104 Projects should not normally set this variable, it is intended as a de‐
7106 veloper control to be set on the cmake(1) command line or other equiva‐
7107 lent methods. The developer must have the ability to enable or disable
7108 header set verification according to the capabilities of their own ma‐
7109 chine and compiler.
7110 Verification of a dependency's header sets is not typically of interest
7112 to developers. Therefore, FetchContent_MakeAvailable() explicitly sets
7113 CMAKE_VERIFY_INTERFACE_HEADER_SETS to false for the duration of its
7114 call, but restores its original value before returning. If a project
7115 brings a dependency directly into the main build (e.g. calling
7116 add_subdirectory() on a vendored project from a git submodule), it
7117 should also do likewise. For example:
7118 # Save original setting so we can restore it later
7120 set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS})
7121 # Include the vendored dependency with header set verification disabled
7123 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF)
7124 add_subdirectory(...) # Vendored sources, e.g. from git submodules
7125 # Add the project's own sources. Restore the developer's original choice
7127 # for whether to enable header set verification.
7128 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification})
7129 add_subdirectory(src)
7130 By default, this variable is not set, which will result in header set
7132 verification being disabled.
7133 CMAKE_VISIBILITY_INLINES_HIDDEN
7135 Default value for the VISIBILITY_INLINES_HIDDEN target property when a
7136 target is created.
7137 CMAKE_VS_GLOBALS
7139 New in version 3.13.
7140 List of Key=Value records to be set per target as target properties
7143 VS_GLOBAL_<variable> with variable=Key and value Value.
7144 For example:
7146 set(CMAKE_VS_GLOBALS
7148 "DefaultLanguage=en-US"
7149 "MinimumVisualStudioVersion=14.0"
7150 )
7151 will set properties VS_GLOBAL_DefaultLanguage to en-US and
7153 VS_GLOBAL_MinimumVisualStudioVersion to 14.0 for all targets (except
7154 for INTERFACE libraries).
7155 This variable is meant to be set by a toolchain file.
7157 CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
7159 New in version 3.3.
7160 Include INSTALL target to default build.
7163 In Visual Studio solution, by default the INSTALL target will not be
7165 part of the default build. Setting this variable will enable the IN‐
7166 STALL target to be part of the default build.
7167 CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
7169 New in version 3.8.
7170 Include PACKAGE target to default build.
7173 In Visual Studio solution, by default the PACKAGE target will not be
7175 part of the default build. Setting this variable will enable the PACK‐
7176 AGE target to be part of the default build.
7177 CMAKE_VS_JUST_MY_CODE_DEBUGGING
7179 New in version 3.15.
7180 Enable Just My Code with Visual Studio debugger.
7183 This variable is used to initialize the VS_JUST_MY_CODE_DEBUGGING prop‐
7185 erty on all targets when they are created. See that target property
7186 for additional information.
7187 CMAKE_VS_NO_COMPILE_BATCHING
7189 New in version 3.24.
7190 Turn off compile batching when using Visual Studio Generators.
7193 This variable is used to initialize the VS_NO_COMPILE_BATCHING property
7195 on all targets when they are created. See that target property for ad‐
7196 ditional information.
7197 Example
7199 This shows setting the property for the target foo using the variable.
7200 set(CMAKE_VS_NO_COMPILE_BATCHING ON)
7202 add_library(foo SHARED foo.cpp)
7203 CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
7205 New in version 3.12.
7206 This variable allows to override Visual Studio default Exclude Directo‐
7209 ries.
7210 CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
7212 New in version 3.12.
7213 This variable allows to override Visual Studio default Executable Di‐
7216 rectories.
7217 CMAKE_VS_SDK_INCLUDE_DIRECTORIES
7219 New in version 3.12.
7220 This variable allows to override Visual Studio default Include Directo‐
7223 ries.
7224 CMAKE_VS_SDK_LIBRARY_DIRECTORIES
7226 New in version 3.12.
7227 This variable allows to override Visual Studio default Library Directo‐
7230 ries.
7231 CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
7233 New in version 3.12.
7234 This variable allows to override Visual Studio default Library WinRT
7237 Directories.
7238 CMAKE_VS_SDK_REFERENCE_DIRECTORIES
7240 New in version 3.12.
7241 This variable allows to override Visual Studio default Reference Direc‐
7244 tories.
7245 CMAKE_VS_SDK_SOURCE_DIRECTORIES
7247 New in version 3.12.
7248 This variable allows to override Visual Studio default Source Directo‐
7251 ries.
7252 CMAKE_VS_WINRT_BY_DEFAULT
7254 New in version 3.13.
7255 Inform Visual Studio Generators for VS 2010 and above that the target
7258 platform enables WinRT compilation by default and it needs to be ex‐
7259 plicitly disabled if /ZW or VS_WINRT_COMPONENT is omitted (as opposed
7260 to enabling it when either of those options is present)
7261 This makes cmake configuration consistent in terms of WinRT among plat‐
7263 forms - if you did not enable the WinRT compilation explicitly, it will
7264 be disabled (by either not enabling it or explicitly disabling it)
7265 Note: WinRT compilation is always explicitly disabled for C language
7267 source files, even if it is expliclty enabled for a project
7268 This variable is meant to be set by a toolchain file for such plat‐
7270 forms.
7271 CMAKE_WATCOM_RUNTIME_LIBRARY
7273 New in version 3.24.
7274 Select the Watcom runtime library for use by compilers targeting the
7277 Watcom ABI. This variable is used to initialize the
7278 WATCOM_RUNTIME_LIBRARY property on all targets as they are created. It
7279 is also propagated by calls to the try_compile() command into the test
7280 project.
7281 The allowed values are:
7283 SingleThreaded
7285 Compile without additional flags to use a single-threaded stati‐
7286 cally-linked runtime library.
7287 SingleThreadedDLL
7289 Compile with -br or equivalent flag(s) to use a single-threaded
7290 dynamically-linked runtime library. This is not available for
7291 Linux targets.
7292 MultiThreaded
7294 Compile with -bm or equivalent flag(s) to use a multi-threaded
7295 statically-linked runtime library.
7296 MultiThreadedDLL
7298 Compile with -bm -br or equivalent flag(s) to use a
7299 multi-threaded dynamically-linked runtime library. This is not
7300 available for Linux targets.
7301 The value is ignored on non-Watcom compilers but an unsupported value
7303 will be rejected as an error when using a compiler targeting the Watcom
7304 ABI.
7305 The value may also be the empty string ("") in which case no runtime
7307 library selection flag will be added explicitly by CMake.
7308 Use generator expressions to support per-configuration specification.
7310 For example, the code:
7312 set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded")
7314 selects for all following targets a multi-threaded statically-linked
7316 runtime library.
7317 If this variable is not set then the WATCOM_RUNTIME_LIBRARY target
7319 property will not be set automatically. If that property is not set
7320 then CMake uses the default value MultiThreadedDLL on Windows and Sin‐
7321 gleThreaded on other platforms to select a Watcom runtime library.
7322 NOTE:
7324 This variable has effect only when policy CMP0136 is set to NEW
7325 prior to the first project() or enable_language() command that en‐
7326 ables a language using a compiler targeting the Watcom ABI.
7327 CMAKE_WIN32_EXECUTABLE
7329 Default value for WIN32_EXECUTABLE of targets.
7330 This variable is used to initialize the WIN32_EXECUTABLE property on
7332 all the targets. See that target property for additional information.
7333 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
7335 New in version 3.4.
7336 Default value for WINDOWS_EXPORT_ALL_SYMBOLS target property. This
7339 variable is used to initialize the property on each target as it is
7340 created.
7341 CMAKE_XCODE_ATTRIBUTE_<an-attribute>
7343 New in version 3.1.
7344 Set Xcode target attributes directly.
7347 Tell the Xcode generator to set <an-attribute> to a given value in the
7349 generated Xcode project. Ignored on other generators.
7350 This offers low-level control over the generated Xcode project file.
7352 It is meant as a last resort for specifying settings that CMake does
7353 not otherwise have a way to control. Although this can override a set‐
7354 ting CMake normally produces on its own, doing so bypasses CMake's
7355 model of the project and can break things.
7356 See the XCODE_ATTRIBUTE_<an-attribute> target property to set at‐
7358 tributes on a specific target.
7359 Contents of CMAKE_XCODE_ATTRIBUTE_<an-attribute> may use "generator ex‐
7361 pressions" with the syntax $<...>. See the
7362 cmake-generator-expressions(7) manual for available expressions. See
7363 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
7364 erties.
7365 EXECUTABLE_OUTPUT_PATH
7367 Old executable location variable.
7368 The target property RUNTIME_OUTPUT_DIRECTORY supersedes this variable
7370 for a target if it is set. Executable targets are otherwise placed in
7371 this directory.
7372 LIBRARY_OUTPUT_PATH
7374 Old library location variable.
7375 The target properties ARCHIVE_OUTPUT_DIRECTORY,
7377 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY supersede this
7378 variable for a target if they are set. Library targets are otherwise
7379 placed in this directory.
7380
7382 CMAKE_C_COMPILE_FEATURES
7383 New in version 3.1.
7384 List of features known to the C compiler
7387 These features are known to be available for use with the C compiler.
7389 This list is a subset of the features listed in the
7390 CMAKE_C_KNOWN_FEATURES global property.
7391 See the cmake-compile-features(7) manual for information on compile
7393 features and a list of supported compilers.
7394 CMAKE_C_EXTENSIONS
7396 New in version 3.1.
7397 Default value for C_EXTENSIONS target property if set when a target is
7400 created.
7401 See the cmake-compile-features(7) manual for information on compile
7403 features and a list of supported compilers.
7404 CMAKE_C_STANDARD
7406 New in version 3.1.
7407 Default value for C_STANDARD target property if set when a target is
7410 created.
7411 See the cmake-compile-features(7) manual for information on compile
7413 features and a list of supported compilers.
7414 CMAKE_C_STANDARD_REQUIRED
7416 New in version 3.1.
7417 Default value for C_STANDARD_REQUIRED target property if set when a
7420 target is created.
7421 See the cmake-compile-features(7) manual for information on compile
7423 features and a list of supported compilers.
7424 CMAKE_COMPILER_IS_GNUCC
7426 True if the C compiler is GNU.
7427 This variable is deprecated. Use CMAKE_C_COMPILER_ID instead.
7429 CMAKE_COMPILER_IS_GNUCXX
7431 True if the C++ (CXX) compiler is GNU.
7432 This variable is deprecated. Use CMAKE_CXX_COMPILER_ID instead.
7434 CMAKE_COMPILER_IS_GNUG77
7436 True if the Fortran compiler is GNU.
7437 This variable is deprecated. Use CMAKE_Fortran_COMPILER_ID instead.
7439 CMAKE_CUDA_ARCHITECTURES
7441 New in version 3.18.
7442 Default value for CUDA_ARCHITECTURES property of targets.
7445 Initialized by the CUDAARCHS environment variable if set. Otherwise as
7447 follows depending on CMAKE_CUDA_COMPILER_ID:
7448 • For Clang: the oldest architecture that works.
7450 • For NVIDIA: the default architecture chosen by the compiler. See
7452 policy CMP0104.
7453 Users are encouraged to override this, as the default varies across
7455 compilers and compiler versions.
7456 This variable is used to initialize the CUDA_ARCHITECTURES property on
7458 all targets. See the target property for additional information.
7459 Examples
7461 cmake_minimum_required(VERSION)
7462 if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
7464 set(CMAKE_CUDA_ARCHITECTURES 75)
7465 endif()
7466 project(example LANGUAGES CUDA)
7468 CMAKE_CUDA_ARCHITECTURES will default to 75 unless overridden by the
7470 user.
7471 CMAKE_CUDA_COMPILE_FEATURES
7473 New in version 3.17.
7474 List of features known to the CUDA compiler
7477 These features are known to be available for use with the CUDA com‐
7479 piler. This list is a subset of the features listed in the
7480 CMAKE_CUDA_KNOWN_FEATURES global property.
7481 See the cmake-compile-features(7) manual for information on compile
7483 features and a list of supported compilers.
7484 CMAKE_CUDA_EXTENSIONS
7486 New in version 3.8.
7487 Default value for CUDA_EXTENSIONS target property if set when a target
7490 is created.
7491 See the cmake-compile-features(7) manual for information on compile
7493 features and a list of supported compilers.
7494 CMAKE_CUDA_HOST_COMPILER
7496 New in version 3.10.
7497 When CMAKE_CUDA_COMPILER_ID is NVIDIA, CMAKE_CUDA_HOST_COMPILER selects
7500 the compiler executable to use when compiling host code for CUDA lan‐
7501 guage files. This maps to the nvcc -ccbin option.
7502 The CMAKE_CUDA_HOST_COMPILER variable may be set explicitly before CUDA
7504 is first enabled by a project() or enable_language() command. This can
7505 be done via -DCMAKE_CUDA_HOST_COMPILER=... on the command line or in a
7506 toolchain file. Or, one may set the CUDAHOSTCXX environment variable
7507 to provide a default value.
7508 Once the CUDA language is enabled, the CMAKE_CUDA_HOST_COMPILER vari‐
7510 able is read-only and changes to it are undefined behavior.
7511 NOTE:
7513 Since CMAKE_CUDA_HOST_COMPILER is meaningful only when the
7514 CMAKE_CUDA_COMPILER_ID is NVIDIA, it does not make sense to set
7515 CMAKE_CUDA_HOST_COMPILER without also setting CMAKE_CUDA_COMPILER to
7516 NVCC.
7517 NOTE:
7519 Ignored when using Visual Studio Generators.
7520 CMAKE_CUDA_STANDARD
7522 New in version 3.8.
7523 Default value for CUDA_STANDARD target property if set when a target is
7526 created.
7527 See the cmake-compile-features(7) manual for information on compile
7529 features and a list of supported compilers.
7530 CMAKE_CUDA_STANDARD_REQUIRED
7532 New in version 3.8.
7533 Default value for CUDA_STANDARD_REQUIRED target property if set when a
7536 target is created.
7537 See the cmake-compile-features(7) manual for information on compile
7539 features and a list of supported compilers.
7540 CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES
7542 New in version 3.8.
7543 When the CUDA language has been enabled, this provides a
7546 semicolon-separated list of include directories provided by the CUDA
7547 Toolkit. The value may be useful for C++ source files to include CUDA
7548 headers.
7549 CMAKE_CXX_COMPILE_FEATURES
7551 New in version 3.1.
7552 List of features known to the C++ compiler
7555 These features are known to be available for use with the C++ compiler.
7557 This list is a subset of the features listed in the
7558 CMAKE_CXX_KNOWN_FEATURES global property.
7559 See the cmake-compile-features(7) manual for information on compile
7561 features and a list of supported compilers.
7562 CMAKE_CXX_EXTENSIONS
7564 New in version 3.1.
7565 Default value for CXX_EXTENSIONS target property if set when a target
7568 is created.
7569 See the cmake-compile-features(7) manual for information on compile
7571 features and a list of supported compilers.
7572 CMAKE_CXX_STANDARD
7574 New in version 3.1.
7575 Default value for CXX_STANDARD target property if set when a target is
7578 created.
7579 See the cmake-compile-features(7) manual for information on compile
7581 features and a list of supported compilers.
7582 CMAKE_CXX_STANDARD_REQUIRED
7584 New in version 3.1.
7585 Default value for CXX_STANDARD_REQUIRED target property if set when a
7588 target is created.
7589 See the cmake-compile-features(7) manual for information on compile
7591 features and a list of supported compilers.
7592 CMAKE_Fortran_MODDIR_DEFAULT
7594 Fortran default module output directory.
7595 Most Fortran compilers write .mod files to the current working direc‐
7597 tory. For those that do not, this is set to . and used when the
7598 Fortran_MODULE_DIRECTORY target property is not set.
7599 CMAKE_Fortran_MODDIR_FLAG
7601 Fortran flag for module output directory.
7602 This stores the flag needed to pass the value of the
7604 Fortran_MODULE_DIRECTORY target property to the compiler.
7605 CMAKE_Fortran_MODOUT_FLAG
7607 Fortran flag to enable module output.
7608 Most Fortran compilers write .mod files out by default. For others,
7610 this stores the flag needed to enable module output.
7611 CMAKE_HIP_ARCHITECTURES
7613 New in version 3.21.
7614 Default value for HIP_ARCHITECTURES property of targets.
7617 This is initialized to the architectures reported by rocm_agent_enumer‐
7619 ator, if available, and otherwise to the default chosen by the com‐
7620 piler.
7621 This variable is used to initialize the HIP_ARCHITECTURES property on
7623 all targets. See the target property for additional information.
7624 CMAKE_HIP_EXTENSIONS
7626 New in version 3.21.
7627 Default value for HIP_EXTENSIONS target property if set when a target
7630 is created.
7631 See the cmake-compile-features(7) manual for information on compile
7633 features and a list of supported compilers.
7634 CMAKE_HIP_STANDARD
7636 New in version 3.21.
7637 Default value for HIP_STANDARD target property if set when a target is
7640 created.
7641 See the cmake-compile-features(7) manual for information on compile
7643 features and a list of supported compilers.
7644 CMAKE_HIP_STANDARD_REQUIRED
7646 New in version 3.21.
7647 Default value for HIP_STANDARD_REQUIRED target property if set when a
7650 target is created.
7651 See the cmake-compile-features(7) manual for information on compile
7653 features and a list of supported compilers.
7654 CMAKE_ISPC_HEADER_DIRECTORY
7656 New in version 3.19.
7657 ISPC generated header output directory.
7660 This variable is used to initialize the ISPC_HEADER_DIRECTORY property
7662 on all the targets. See the target property for additional informa‐
7663 tion.
7664 CMAKE_ISPC_HEADER_SUFFIX
7666 New in version 3.19.2.
7667 Output suffix to be used for ISPC generated headers.
7670 This variable is used to initialize the ISPC_HEADER_SUFFIX property on
7672 all the targets. See the target property for additional information.
7673 CMAKE_ISPC_INSTRUCTION_SETS
7675 New in version 3.19.
7676 Default value for ISPC_INSTRUCTION_SETS property of targets.
7679 This variable is used to initialize the ISPC_INSTRUCTION_SETS property
7681 on all targets. See the target property for additional information.
7682 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE
7684 New in version 3.7.1.
7685 When Cross Compiling for Android this variable contains the toolchain
7688 binutils machine name (e.g. gcc -dumpmachine). The binutils typically
7689 have a <machine>- prefix on their name.
7690 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
7692 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.
7693 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
7695 New in version 3.7.
7696 When Cross Compiling for Android this variable contains the absolute
7699 path prefixing the toolchain GNU compiler and its binutils.
7700 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX and
7702 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
7703 For example, the path to the linker is:
7705 ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX}
7707 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
7709 New in version 3.7.
7710 When Cross Compiling for Android this variable contains the host plat‐
7713 form suffix of the toolchain GNU compiler and its binutils.
7714 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
7716 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
7717 CMAKE_<LANG>_ARCHIVE_APPEND
7719 Rule variable to append to a static archive.
7720 This is a rule variable that tells CMake how to append to a static ar‐
7722 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
7723 some platforms in order to support large object counts. See also
7724 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_FINISH.
7725 CMAKE_<LANG>_ARCHIVE_CREATE
7727 Rule variable to create a new static archive.
7728 This is a rule variable that tells CMake how to create a static ar‐
7730 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
7731 some platforms in order to support large object counts. See also
7732 CMAKE_<LANG>_ARCHIVE_APPEND and CMAKE_<LANG>_ARCHIVE_FINISH.
7733 CMAKE_<LANG>_ARCHIVE_FINISH
7735 Rule variable to finish an existing static archive.
7736 This is a rule variable that tells CMake how to finish a static ar‐
7738 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
7739 some platforms in order to support large object counts. See also
7740 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_APPEND.
7741 CMAKE_<LANG>_BYTE_ORDER
7743 New in version 3.20.
7744 Byte order of <LANG> compiler target architecture, if known. If de‐
7747 fined and not empty, the value is one of:
7748 BIG_ENDIAN
7750 The target architecture is Big Endian.
7751 LITTLE_ENDIAN
7753 The target architecture is Little Endian.
7754 This is defined for languages C, CXX, OBJC, OBJCXX, and CUDA.
7756 If CMAKE_OSX_ARCHITECTURES specifies multiple architectures, the value
7758 of CMAKE_<LANG>_BYTE_ORDER is non-empty only if all architectures share
7759 the same byte order.
7760 CMAKE_<LANG>_COMPILE_OBJECT
7762 Rule variable to compile a single object file.
7763 This is a rule variable that tells CMake how to compile a single object
7765 file for the language <LANG>.
7766 CMAKE_<LANG>_COMPILER
7768 The full path to the compiler for LANG.
7769 This is the command that will be used as the <LANG> compiler. Once
7771 set, you can not change this variable.
7772 Usage
7774 This variable can be set by the user during the first time a build tree
7775 is configured.
7776 If a non-full path value is supplied then CMake will resolve the full
7778 path of the compiler.
7779 The variable could be set in a user supplied toolchain file or via -D
7781 on the command line.
7782 NOTE:
7784 Options that are required to make the compiler work correctly can be
7785 included as items in a list; they can not be changed.
7786 #set within user supplied toolchain file
7788 set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2)
7789 or
7791 $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2'
7793 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN
7795 The external toolchain for cross-compiling, if supported.
7796 Some compiler toolchains do not ship their own auxiliary utilities such
7798 as archivers and linkers. The compiler driver may support a com‐
7799 mand-line argument to specify the location of such tools.
7800 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN may be set to a path to the
7801 external toolchain and will be passed to the compiler driver if sup‐
7802 ported.
7803 This variable may only be set in a toolchain file specified by the
7805 CMAKE_TOOLCHAIN_FILE variable.
7806 CMAKE_<LANG>_COMPILER_ID
7808 Compiler identification string.
7809 A short string unique to the compiler vendor. Possible values include:
7811 ┌─────────────────────┬────────────────────────────┐
7813 │Value │ Name │
7814 ├─────────────────────┼────────────────────────────┤
7815 │Absoft │ Absoft Fortran │
7816 ├─────────────────────┼────────────────────────────┤
7817 │ADSP │ Analog VisualDSP++ │
7818 ├─────────────────────┼────────────────────────────┤
7819 │AppleClang │ Apple Clang │
7820 ├─────────────────────┼────────────────────────────┤
7821 │ARMCC │ ARM Compiler │
7822 ├─────────────────────┼────────────────────────────┤
7823 │ARMClang │ ARM Compiler based on │
7824 │ │ Clang │
7825 ├─────────────────────┼────────────────────────────┤
7826 │Bruce │ Bruce C Compiler │
7827 ├─────────────────────┼────────────────────────────┤
7828 │CCur │ Concurrent Fortran │
7829 ├─────────────────────┼────────────────────────────┤
7830 │Clang │ LLVM Clang │
7831 ├─────────────────────┼────────────────────────────┤
7832 │Cray │ Cray Compiler │
7833 ├─────────────────────┼────────────────────────────┤
7834 │Embarcadero, Borland │ Embarcadero │
7835 ├─────────────────────┼────────────────────────────┤
7836 │Flang │ Classic Flang Fortran Com‐ │
7837 │ │ piler │
7838 ├─────────────────────┼────────────────────────────┤
7839 │LLVMFlang │ LLVM Flang Fortran Com‐ │
7840 │ │ piler │
7841 └─────────────────────┴────────────────────────────┘
7842 │Fujitsu │ Fujitsu HPC compiler (Trad │
7845 │ │ mode) │
7846 ├─────────────────────┼────────────────────────────┤
7847 │FujitsuClang │ Fujitsu HPC compiler │
7848 │ │ (Clang mode) │
7849 ├─────────────────────┼────────────────────────────┤
7850 │G95 │ G95 Fortran │
7851 ├─────────────────────┼────────────────────────────┤
7852 │GNU │ GNU Compiler Collection │
7853 ├─────────────────────┼────────────────────────────┤
7854 │GHS │ Green Hills Software │
7855 ├─────────────────────┼────────────────────────────┤
7856 │HP │ Hewlett-Packard Compiler │
7857 ├─────────────────────┼────────────────────────────┤
7858 │IAR │ IAR Systems │
7859 ├─────────────────────┼────────────────────────────┤
7860 │Intel │ Intel Classic Compiler │
7861 ├─────────────────────┼────────────────────────────┤
7862 │IntelLLVM │ Intel LLVM-Based Compiler │
7863 ├─────────────────────┼────────────────────────────┤
7864 │LCC │ MCST Elbrus C/C++/Fortran │
7865 │ │ Compiler │
7866 ├─────────────────────┼────────────────────────────┤
7867 │MSVC │ Microsoft Visual Studio │
7868 ├─────────────────────┼────────────────────────────┤
7869 │NVHPC │ NVIDIA HPC Compiler │
7870 ├─────────────────────┼────────────────────────────┤
7871 │NVIDIA │ NVIDIA CUDA Compiler │
7872 ├─────────────────────┼────────────────────────────┤
7873 │OpenWatcom │ Open Watcom │
7874 ├─────────────────────┼────────────────────────────┤
7875 │PGI │ The Portland Group │
7876 ├─────────────────────┼────────────────────────────┤
7877 │PathScale │ PathScale │
7878 ├─────────────────────┼────────────────────────────┤
7879 │SDCC │ Small Device C Compiler │
7880 ├─────────────────────┼────────────────────────────┤
7881 │SunPro │ Oracle Solaris Studio │
7882 ├─────────────────────┼────────────────────────────┤
7883 │Tasking │ Tasking Compiler Toolsets │
7884 ├─────────────────────┼────────────────────────────┤
7885 │TI │ Texas Instruments │
7886 ├─────────────────────┼────────────────────────────┤
7887 │TinyCC │ Tiny C Compiler │
7888 ├─────────────────────┼────────────────────────────┤
7889 │XL, VisualAge, zOS │ IBM XL │
7890 ├─────────────────────┼────────────────────────────┤
7891 │XLClang │ IBM Clang-based XL │
7892 ├─────────────────────┼────────────────────────────┤
7893 │IBMClang │ IBM LLVM-based Compiler │
7894 └─────────────────────┴────────────────────────────┘
7895 This variable is not guaranteed to be defined for all compilers or lan‐
7897 guages.
7898 CMAKE_<LANG>_COMPILER_LOADED
7900 Defined to true if the language is enabled.
7901 When language <LANG> is enabled by project() or enable_language() this
7903 variable is defined to 1.
7904 CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND
7906 New in version 3.10.
7907 Command that outputs the compiler pre definitions.
7910 See AUTOMOC which uses CMAKE_CXX_COMPILER_PREDEFINES_COMMAND to gener‐
7912 ate the AUTOMOC_COMPILER_PREDEFINES.
7913 CMAKE_<LANG>_COMPILER_TARGET
7915 The target for cross-compiling, if supported.
7916 Some compiler drivers are inherently cross-compilers, such as clang and
7918 QNX qcc. These compiler drivers support a command-line argument to
7919 specify the target to cross-compile for.
7920 This variable may only be set in a toolchain file specified by the
7922 CMAKE_TOOLCHAIN_FILE variable.
7923 CMAKE_<LANG>_COMPILER_VERSION
7925 Compiler version string.
7926 Compiler version in major[.minor[.patch[.tweak]]] format. This vari‐
7928 able is not guaranteed to be defined for all compilers or languages.
7929 For example CMAKE_C_COMPILER_VERSION and CMAKE_CXX_COMPILER_VERSION
7931 might indicate the respective C and C++ compiler version.
7932 CMAKE_<LANG>_CREATE_SHARED_LIBRARY
7934 Rule variable to create a shared library.
7935 This is a rule variable that tells CMake how to create a shared library
7937 for the language <LANG>. This rule variable is a ; delimited list of
7938 commands to run to perform the linking step.
7939 CMAKE_<LANG>_CREATE_SHARED_MODULE
7941 Rule variable to create a shared module.
7942 This is a rule variable that tells CMake how to create a shared library
7944 for the language <LANG>. This rule variable is a ; delimited list of
7945 commands to run.
7946 CMAKE_<LANG>_CREATE_STATIC_LIBRARY
7948 Rule variable to create a static library.
7949 This is a rule variable that tells CMake how to create a static library
7951 for the language <LANG>.
7952 CMAKE_<LANG>_EXTENSIONS
7954 The variations are:
7955 • CMAKE_C_EXTENSIONS
7957 • CMAKE_CXX_EXTENSIONS
7959 • CMAKE_CUDA_EXTENSIONS
7961 • CMAKE_HIP_EXTENSIONS
7963 • CMAKE_OBJC_EXTENSIONS
7965 • CMAKE_OBJCXX_EXTENSIONS
7967 Default values for <LANG>_EXTENSIONS target properties if set when a
7969 target is created. For the compiler's default setting see
7970 CMAKE_<LANG>_EXTENSIONS_DEFAULT.
7971 For supported CMake versions see the respective pages.
7973 See the cmake-compile-features(7) manual for information on compile
7975 features and a list of supported compilers.
7976 CMAKE_<LANG>_EXTENSIONS_DEFAULT
7978 New in version 3.22.
7979 Compiler's default extensions mode. Used as the default for the
7982 <LANG>_EXTENSIONS target property when CMAKE_<LANG>_EXTENSIONS is not
7983 set (see CMP0128).
7984 This variable is read-only. Modifying it is undefined behavior.
7986 CMAKE_<LANG>_FLAGS
7988 Flags for all build types.
7989 <LANG> flags used regardless of the value of CMAKE_BUILD_TYPE.
7991 For each language, if this variable is not defined, it is initialized
7993 and stored in the cache using values from environment variables in com‐
7994 bination with CMake's builtin defaults for the toolchain:
7995 • CMAKE_C_FLAGS: Initialized by the CFLAGS environment variable.
7997 • CMAKE_CXX_FLAGS: Initialized by the CXXFLAGS environment variable.
7999 • CMAKE_CUDA_FLAGS: Initialized by the CUDAFLAGS environment variable.
8001 • CMAKE_Fortran_FLAGS: Initialized by the FFLAGS environment variable.
8003 • CMAKE_CSharp_FLAGS: Initialized by the CSFLAGS environment variable.
8005 • CMAKE_HIP_FLAGS: Initialized by the HIPFLAGS environment variable.
8007 • CMAKE_ISPC_FLAGS: Initialized by the ISPCFLAGS environment variable.
8009 This value is a command-line string fragment. Therefore, multiple op‐
8011 tions should be separated by spaces, and options with spaces should be
8012 quoted.
8013 The flags in this variable will be passed to the compiler before those
8015 in the per-configuration CMAKE_<LANG>_FLAGS_<CONFIG> variant, and be‐
8016 fore flags added by the add_compile_options() or
8017 target_compile_options() commands.
8018 CMAKE_<LANG>_FLAGS_<CONFIG>
8020 Flags for language <LANG> when building for the <CONFIG> configuration.
8021 The flags in this variable will be passed to the compiler after those
8023 in the CMAKE_<LANG>_FLAGS variable, but before flags added by the
8024 add_compile_options() or target_compile_options() commands.
8025 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8027 New in version 3.11.
8028 Value used to initialize the CMAKE_<LANG>_FLAGS_<CONFIG> cache entry
8031 the first time a build tree is configured for language <LANG>. This
8032 variable is meant to be set by a toolchain file. CMake may prepend or
8033 append content to the value based on the environment and target plat‐
8034 form.
8035 See also CMAKE_<LANG>_FLAGS_INIT.
8037 CMAKE_<LANG>_FLAGS_DEBUG
8039 This variable is the Debug variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8040 variable.
8041 CMAKE_<LANG>_FLAGS_DEBUG_INIT
8043 New in version 3.7.
8044 This variable is the Debug variant of the
8047 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8048 CMAKE_<LANG>_FLAGS_INIT
8050 New in version 3.7.
8051 Value used to initialize the CMAKE_<LANG>_FLAGS cache entry the first
8054 time a build tree is configured for language <LANG>. This variable is
8055 meant to be set by a toolchain file. CMake may prepend or append con‐
8056 tent to the value based on the environment and target platform. For
8057 example, the contents of a xxxFLAGS environment variable will be
8058 prepended, where xxx will be language-specific but not necessarily the
8059 same as <LANG> (e.g. CXXFLAGS for CXX, FFLAGS for Fortran, and so on).
8060 This value is a command-line string fragment. Therefore, multiple op‐
8061 tions should be separated by spaces, and options with spaces should be
8062 quoted.
8063 See also the configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8065 variable.
8066 CMAKE_<LANG>_FLAGS_MINSIZEREL
8068 This variable is the MinSizeRel variant of the
8069 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8070 CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
8072 New in version 3.7.
8073 This variable is the MinSizeRel variant of the
8076 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8077 CMAKE_<LANG>_FLAGS_RELEASE
8079 This variable is the Release variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8080 variable.
8081 CMAKE_<LANG>_FLAGS_RELEASE_INIT
8083 New in version 3.7.
8084 This variable is the Release variant of the
8087 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8088 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
8090 This variable is the RelWithDebInfo variant of the
8091 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8092 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT
8094 New in version 3.7.
8095 This variable is the RelWithDebInfo variant of the
8098 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8099 CMAKE_<LANG>_IGNORE_EXTENSIONS
8101 File extensions that should be ignored by the build.
8102 This is a list of file extensions that may be part of a project for a
8104 given language but are not compiled.
8105 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
8107 Directories implicitly searched by the compiler for header files.
8108 CMake does not explicitly specify these directories on compiler command
8110 lines for language <LANG>. This prevents system include directories
8111 from being treated as user include directories on some compilers, which
8112 is important for C, CXX, and CUDA to avoid overriding standard library
8113 headers.
8114 This value is not used for Fortran because it has no standard library
8116 headers and some compilers do not search their implicit include direc‐
8117 tories for module .mod files.
8118 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8120 Implicit linker search path detected for language <LANG>.
8121 Compilers typically pass directories containing language runtime li‐
8123 braries and default library search paths when they invoke a linker.
8124 These paths are implicit linker search directories for the compiler's
8125 language. For each language enabled by the project() or
8126 enable_language() command, CMake automatically detects these directo‐
8127 ries and reports the results in this variable.
8128 When linking to a static library, CMake adds the implicit link directo‐
8130 ries from this variable for each language used in the static library
8131 (except the language whose compiler is used to drive linking). In the
8132 case of an imported static library, the
8133 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8134 whose implicit link information is needed. If any of the languages is
8135 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8136 variable may instead be provided by the project. Or, a toolchain file
8137 may set the variable to a value known for the specified toolchain. It
8138 will either be overridden when the language is enabled, or used as a
8139 fallback.
8140 Some toolchains read implicit directories from an environment variable
8142 such as LIBRARY_PATH. If using such an environment variable, keep its
8143 value consistent when operating in a given build tree because CMake
8144 saves the value detected when first creating a build tree.
8145 If policy CMP0060 is not set to NEW, then when a library in one of
8147 these directories is given by full path to target_link_libraries()
8148 CMake will generate the -l<name> form on link lines for historical pur‐
8149 poses.
8150 See also the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES variable.
8152 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
8154 Implicit linker framework search path detected for language <LANG>.
8155 These paths are implicit linker framework search directories for the
8157 compiler's language. CMake automatically detects these directories for
8158 each language and reports the results in this variable.
8159 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8161 Implicit link libraries and flags detected for language <LANG>.
8162 Compilers typically pass language runtime library names and other flags
8164 when they invoke a linker. These flags are implicit link options for
8165 the compiler's language. For each language enabled by the project() or
8166 enable_language() command, CMake automatically detects these libraries
8167 and flags and reports the results in this variable.
8168 When linking to a static library, CMake adds the implicit link li‐
8170 braries and flags from this variable for each language used in the
8171 static library (except the language whose compiler is used to drive
8172 linking). In the case of an imported static library, the
8173 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8174 whose implicit link information is needed. If any of the languages is
8175 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8176 variable may instead be provided by the project. Or, a toolchain file
8177 may set the variable to a value known for the specified toolchain. It
8178 will either be overridden when the language is enabled, or used as a
8179 fallback.
8180 See also the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES variable.
8182 CMAKE_<LANG>_LIBRARY_ARCHITECTURE
8184 Target architecture library directory name detected for <LANG>.
8185 If the <LANG> compiler passes to the linker an architecture-specific
8187 system library search directory such as <prefix>/lib/<arch> this vari‐
8188 able contains the <arch> name if/as detected by CMake.
8189 CMAKE_<LANG>_LINK_EXECUTABLE
8191 Rule variable to link an executable.
8192 Rule variable to link an executable for the given language.
8194 CMAKE_<LANG>_LINKER_WRAPPER_FLAG
8196 New in version 3.13.
8197 Defines the syntax of compiler driver option to pass options to the
8200 linker tool. It will be used to translate the LINKER: prefix in the
8201 link options (see add_link_options() and target_link_options()).
8202 This variable holds a semicolon-separated list of tokens. If a space
8204 (i.e. " ") is specified as last token, flag and LINKER: arguments will
8205 be specified as separate arguments to the compiler driver. The
8206 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variable can be specified to man‐
8207 age concatenation of arguments.
8208 For example, for Clang we have:
8210 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")
8212 Specifying "LINKER:-z,defs" will be transformed in -Xlinker -z -Xlinker
8214 defs.
8215 For GNU GCC:
8217 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
8219 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8220 Specifying "LINKER:-z,defs" will be transformed in -Wl,-z,defs.
8222 And for SunPro:
8224 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
8226 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8227 Specifying "LINKER:-z,defs" will be transformed in -Qoption ld -z,defs.
8229 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
8231 New in version 3.13.
8232 This variable is used with CMAKE_<LANG>_LINKER_WRAPPER_FLAG variable to
8235 format LINKER: prefix in the link options (see add_link_options() and
8236 target_link_options()).
8237 When specified, arguments of the LINKER: prefix will be concatenated
8239 using this value as separator.
8240 CMAKE_<LANG>_OUTPUT_EXTENSION
8242 Extension for the output of a compile for a single file.
8243 This is the extension for an object file for the given <LANG>. For ex‐
8245 ample .obj for C on Windows.
8246 CMAKE_<LANG>_SIMULATE_ID
8248 Identification string of the "simulated" compiler.
8249 Some compilers simulate other compilers to serve as drop-in replace‐
8251 ments. When CMake detects such a compiler it sets this variable to
8252 what would have been the CMAKE_<LANG>_COMPILER_ID for the simulated
8253 compiler.
8254 NOTE:
8256 In other words, this variable describes the ABI compatibility of the
8257 generated code.
8258 CMAKE_<LANG>_SIMULATE_VERSION
8260 Version string of "simulated" compiler.
8261 Some compilers simulate other compilers to serve as drop-in replace‐
8263 ments. When CMake detects such a compiler it sets this variable to
8264 what would have been the CMAKE_<LANG>_COMPILER_VERSION for the simu‐
8265 lated compiler.
8266 CMAKE_<LANG>_SIZEOF_DATA_PTR
8268 Size of pointer-to-data types for language <LANG>.
8269 This holds the size (in bytes) of pointer-to-data types in the target
8271 platform ABI. It is defined for languages C and CXX (C++).
8272 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
8274 Extensions of source files for the given language.
8275 This is the list of extensions for a given language's source files.
8277 CMAKE_<LANG>_STANDARD
8279 The variations are:
8280 • CMAKE_C_STANDARD
8282 • CMAKE_CXX_STANDARD
8284 • CMAKE_CUDA_STANDARD
8286 • CMAKE_HIP_STANDARD
8288 • CMAKE_OBJC_STANDARD
8290 • CMAKE_OBJCXX_STANDARD
8292 Default values for <LANG>_STANDARD target properties if set when a tar‐
8294 get is created.
8295 For supported CMake versions see the respective pages.
8297 See the cmake-compile-features(7) manual for information on compile
8299 features and a list of supported compilers.
8300 CMAKE_<LANG>_STANDARD_DEFAULT
8302 New in version 3.9.
8303 The compiler's default standard for the language <LANG>. Empty if the
8306 compiler has no conception of standard levels.
8307 CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES
8309 New in version 3.6.
8310 Include directories to be used for every source file compiled with the
8313 <LANG> compiler. This is meant for specification of system include di‐
8314 rectories needed by the language for the current platform. The direc‐
8315 tories always appear at the end of the include path passed to the com‐
8316 piler.
8317 This variable should not be set by project code. It is meant to be set
8319 by CMake's platform information modules for the current toolchain, or
8320 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8321 See also CMAKE_<LANG>_STANDARD_LIBRARIES.
8323 CMAKE_<LANG>_STANDARD_LIBRARIES
8325 New in version 3.6.
8326 Libraries linked into every executable and shared library linked for
8329 language <LANG>. This is meant for specification of system libraries
8330 needed by the language for the current platform.
8331 This variable should not be set by project code. It is meant to be set
8333 by CMake's platform information modules for the current toolchain, or
8334 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8335 See also CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES.
8337 CMAKE_<LANG>_STANDARD_REQUIRED
8339 The variations are:
8340 • CMAKE_C_STANDARD_REQUIRED
8342 • CMAKE_CXX_STANDARD_REQUIRED
8344 • CMAKE_CUDA_STANDARD_REQUIRED
8346 • CMAKE_HIP_STANDARD_REQUIRED
8348 • CMAKE_OBJC_STANDARD_REQUIRED
8350 • CMAKE_OBJCXX_STANDARD_REQUIRED
8352 Default values for <LANG>_STANDARD_REQUIRED target properties if set
8354 when a target is created.
8355 For supported CMake versions see the respective pages.
8357 See the cmake-compile-features(7) manual for information on compile
8359 features and a list of supported compilers.
8360 CMAKE_OBJC_EXTENSIONS
8362 New in version 3.16.
8363 Default value for OBJC_EXTENSIONS target property if set when a target
8366 is created.
8367 See the cmake-compile-features(7) manual for information on compile
8369 features and a list of supported compilers.
8370 CMAKE_OBJC_STANDARD
8372 New in version 3.16.
8373 Default value for OBJC_STANDARD target property if set when a target is
8376 created.
8377 See the cmake-compile-features(7) manual for information on compile
8379 features and a list of supported compilers.
8380 CMAKE_OBJC_STANDARD_REQUIRED
8382 New in version 3.16.
8383 Default value for OBJC_STANDARD_REQUIRED target property if set when a
8386 target is created.
8387 See the cmake-compile-features(7) manual for information on compile
8389 features and a list of supported compilers.
8390 CMAKE_OBJCXX_EXTENSIONS
8392 New in version 3.16.
8393 Default value for OBJCXX_EXTENSIONS target property if set when a tar‐
8396 get is created.
8397 See the cmake-compile-features(7) manual for information on compile
8399 features and a list of supported compilers.
8400 CMAKE_OBJCXX_STANDARD
8402 New in version 3.16.
8403 Default value for OBJCXX_STANDARD target property if set when a target
8406 is created.
8407 See the cmake-compile-features(7) manual for information on compile
8409 features and a list of supported compilers.
8410 CMAKE_OBJCXX_STANDARD_REQUIRED
8412 New in version 3.16.
8413 Default value for OBJCXX_STANDARD_REQUIRED target property if set when
8416 a target is created.
8417 See the cmake-compile-features(7) manual for information on compile
8419 features and a list of supported compilers.
8420 CMAKE_Swift_LANGUAGE_VERSION
8422 New in version 3.7.
8423 Set to the Swift language version number. If not set, the oldest
8426 legacy version known to be available in the host Xcode version is as‐
8427 sumed:
8428 • Swift 4.0 for Xcode 10.2 and above.
8430 • Swift 3.0 for Xcode 8.3 and above.
8432 • Swift 2.3 for Xcode 8.2 and below.
8434 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
8436 Specify a CMake file that overrides platform information for <LANG>.
8437 This is a language-specific version of CMAKE_USER_MAKE_RULES_OVERRIDE
8439 loaded only when enabling language <LANG>.
8440
8442 CTEST_BINARY_DIRECTORY
8443 New in version 3.1.
8444 Specify the CTest BuildDirectory setting in a ctest(1) dashboard client
8447 script.
8448 CTEST_BUILD_COMMAND
8450 New in version 3.1.
8451 Specify the CTest MakeCommand setting in a ctest(1) dashboard client
8454 script.
8455 CTEST_BUILD_NAME
8457 New in version 3.1.
8458 Specify the CTest BuildName setting in a ctest(1) dashboard client
8461 script.
8462 CTEST_BZR_COMMAND
8464 New in version 3.1.
8465 Specify the CTest BZRCommand setting in a ctest(1) dashboard client
8468 script.
8469 CTEST_BZR_UPDATE_OPTIONS
8471 New in version 3.1.
8472 Specify the CTest BZRUpdateOptions setting in a ctest(1) dashboard
8475 client script.
8476 CTEST_CHANGE_ID
8478 New in version 3.4.
8479 Specify the CTest ChangeId setting in a ctest(1) dashboard client
8482 script.
8483 This setting allows CTest to pass arbitrary information about this
8485 build up to CDash. One use of this feature is to allow CDash to post
8486 comments on your pull request if anything goes wrong with your build.
8487 CTEST_CHECKOUT_COMMAND
8489 New in version 3.1.
8490 Tell the ctest_start() command how to checkout or initialize the source
8493 directory in a ctest(1) dashboard client script.
8494 CTEST_CONFIGURATION_TYPE
8496 New in version 3.1.
8497 Specify the CTest DefaultCTestConfigurationType setting in a ctest(1)
8500 dashboard client script.
8501 If the configuration type is set via -C <cfg> from the command line
8503 then this variable is populated accordingly.
8504 CTEST_CONFIGURE_COMMAND
8506 New in version 3.1.
8507 Specify the CTest ConfigureCommand setting in a ctest(1) dashboard
8510 client script.
8511 CTEST_COVERAGE_COMMAND
8513 New in version 3.1.
8514 Specify the CTest CoverageCommand setting in a ctest(1) dashboard
8517 client script.
8518 Cobertura
8520 Using Cobertura as the coverage generation within your multi-module
8521 Java project can generate a series of XML files.
8522 The Cobertura Coverage parser expects to read the coverage data from a
8524 single XML file which contains the coverage data for all modules.
8525 Cobertura has a program with the ability to merge given cobertura.ser
8526 files and then another program to generate a combined XML file from the
8527 previous merged file. For command line testing, this can be done by
8528 hand prior to CTest looking for the coverage files. For script builds,
8529 set the CTEST_COVERAGE_COMMAND variable to point to a file which will
8530 perform these same steps, such as a .sh or .bat file.
8531 set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh)
8533 where the run-coverage-and-consolidate.sh script is perhaps created by
8535 the configure_file() command and might contain the following code:
8536 #!/usr/bin/env bash
8538 CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")"
8539 SourceDirs="$(find "/path/to/source" -name "java" -type d)"
8540 cobertura-merge --datafile coberturamerge.ser $CoberturaFiles
8541 cobertura-report --datafile coberturamerge.ser --destination . \
8542 --format xml $SourceDirs
8543 The script uses find to capture the paths to all of the cobertura.ser
8545 files found below the project's source directory. It keeps the list of
8546 files and supplies it as an argument to the cobertura-merge program.
8547 The --datafile argument signifies where the result of the merge will be
8548 kept.
8549 The combined coberturamerge.ser file is then used to generate the XML
8551 report using the cobertura-report program. The call to the cober‐
8552 tura-report program requires some named arguments.
8553 --datafila
8555 path to the merged .ser file
8556 --destination
8558 path to put the output files(s)
8559 --format
8561 file format to write output in: xml or html
8562 The rest of the supplied arguments consist of the full paths to the
8564 /src/main/java directories of each module within the source tree. These
8565 directories are needed and should not be forgotten.
8566 CTEST_COVERAGE_EXTRA_FLAGS
8568 New in version 3.1.
8569 Specify the CTest CoverageExtraFlags setting in a ctest(1) dashboard
8572 client script.
8573 CTEST_CURL_OPTIONS
8575 New in version 3.1.
8576 Specify the CTest CurlOptions setting in a ctest(1) dashboard client
8579 script.
8580 CTEST_CUSTOM_COVERAGE_EXCLUDE
8582 A list of regular expressions which will be used to exclude files by
8583 their path from coverage output by the ctest_coverage() command.
8584 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8586 See ctest_read_custom_files() documentation.
8587 CTEST_CUSTOM_ERROR_EXCEPTION
8589 A list of regular expressions which will be used to exclude when de‐
8590 tecting error messages in build outputs by the ctest_test() command.
8591 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8593 See ctest_read_custom_files() documentation.
8594 CTEST_CUSTOM_ERROR_MATCH
8596 A list of regular expressions which will be used to detect error mes‐
8597 sages in build outputs by the ctest_test() command.
8598 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8600 See ctest_read_custom_files() documentation.
8601 CTEST_CUSTOM_ERROR_POST_CONTEXT
8603 The number of lines to include as context which follow an error message
8604 by the ctest_test() command. The default is 10.
8605 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8607 See ctest_read_custom_files() documentation.
8608 CTEST_CUSTOM_ERROR_PRE_CONTEXT
8610 The number of lines to include as context which precede an error mes‐
8611 sage by the ctest_test() command. The default is 10.
8612 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8614 See ctest_read_custom_files() documentation.
8615 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
8617 When saving a failing test's output, this is the maximum size, in
8618 bytes, that will be collected by the ctest_test() command. Defaults to
8619 307200 (300 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
8620 truncation modes.
8621 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
8623 output will not be truncated and may exceed the maximum size.
8624 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8626 See ctest_read_custom_files() documentation.
8627 For controlling the output collection of passing tests, see
8629 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.
8630 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
8632 The maximum number of errors in a single build step which will be de‐
8633 tected. After this, the ctest_test() command will truncate the output.
8634 Defaults to 50.
8635 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8637 See ctest_read_custom_files() documentation.
8638 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
8640 The maximum number of warnings in a single build step which will be de‐
8641 tected. After this, the ctest_test() command will truncate the output.
8642 Defaults to 50.
8643 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8645 See ctest_read_custom_files() documentation.
8646 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
8648 When saving a passing test's output, this is the maximum size, in
8649 bytes, that will be collected by the ctest_test() command. Defaults to
8650 1024 (1 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
8651 truncation modes.
8652 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
8654 output will not be truncated and may exceed the maximum size.
8655 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8657 See ctest_read_custom_files() documentation.
8658 For controlling the output collection of failing tests, see
8660 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.
8661 CTEST_CUSTOM_MEMCHECK_IGNORE
8663 A list of regular expressions to use to exclude tests during the
8664 ctest_memcheck() command.
8665 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8667 See ctest_read_custom_files() documentation.
8668 CTEST_CUSTOM_POST_MEMCHECK
8670 A list of commands to run at the end of the ctest_memcheck() command.
8671 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8673 See ctest_read_custom_files() documentation.
8674 CTEST_CUSTOM_POST_TEST
8676 A list of commands to run at the end of the ctest_test() command.
8677 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8679 See ctest_read_custom_files() documentation.
8680 CTEST_CUSTOM_PRE_MEMCHECK
8682 A list of commands to run at the start of the ctest_memcheck() command.
8683 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8685 See ctest_read_custom_files() documentation.
8686 CTEST_CUSTOM_PRE_TEST
8688 A list of commands to run at the start of the ctest_test() command.
8689 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8691 See ctest_read_custom_files() documentation.
8692 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
8694 New in version 3.24.
8695 Set the test output truncation mode in case a maximum size is config‐
8698 ured via the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE or
8699 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables. By default the
8700 tail of the output will be truncated. Other possible values are middle
8701 and head.
8702 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8704 See ctest_read_custom_files() documentation.
8705 CTEST_CUSTOM_TESTS_IGNORE
8707 A list of test names to be excluded from the set of tests run by the
8708 ctest_test() command.
8709 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8711 See ctest_read_custom_files() documentation.
8712 CTEST_CUSTOM_WARNING_EXCEPTION
8714 A list of regular expressions which will be used to exclude when de‐
8715 tecting warning messages in build outputs by the ctest_build() command.
8716 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8718 See ctest_read_custom_files() documentation.
8719 CTEST_CUSTOM_WARNING_MATCH
8721 A list of regular expressions which will be used to detect warning mes‐
8722 sages in build outputs by the ctest_build() command.
8723 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8725 See ctest_read_custom_files() documentation.
8726 CTEST_CVS_CHECKOUT
8728 New in version 3.1.
8729 Deprecated. Use CTEST_CHECKOUT_COMMAND instead.
8732 CTEST_CVS_COMMAND
8734 New in version 3.1.
8735 Specify the CTest CVSCommand setting in a ctest(1) dashboard client
8738 script.
8739 CTEST_CVS_UPDATE_OPTIONS
8741 New in version 3.1.
8742 Specify the CTest CVSUpdateOptions setting in a ctest(1) dashboard
8745 client script.
8746 CTEST_DROP_LOCATION
8748 New in version 3.1.
8749 Specify the CTest DropLocation setting in a ctest(1) dashboard client
8752 script.
8753 CTEST_DROP_METHOD
8755 New in version 3.1.
8756 Specify the CTest DropMethod setting in a ctest(1) dashboard client
8759 script.
8760 CTEST_DROP_SITE
8762 New in version 3.1.
8763 Specify the CTest DropSite setting in a ctest(1) dashboard client
8766 script.
8767 CTEST_DROP_SITE_CDASH
8769 New in version 3.1.
8770 Specify the CTest IsCDash setting in a ctest(1) dashboard client
8773 script.
8774 CTEST_DROP_SITE_PASSWORD
8776 New in version 3.1.
8777 Specify the CTest DropSitePassword setting in a ctest(1) dashboard
8780 client script.
8781 CTEST_DROP_SITE_USER
8783 New in version 3.1.
8784 Specify the CTest DropSiteUser setting in a ctest(1) dashboard client
8787 script.
8788 CTEST_EXTRA_COVERAGE_GLOB
8790 New in version 3.4.
8791 A list of regular expressions which will be used to find files which
8794 should be covered by the ctest_coverage() command.
8795 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8797 See ctest_read_custom_files() documentation.
8798 CTEST_GIT_COMMAND
8800 New in version 3.1.
8801 Specify the CTest GITCommand setting in a ctest(1) dashboard client
8804 script.
8805 CTEST_GIT_INIT_SUBMODULES
8807 New in version 3.6.
8808 Specify the CTest GITInitSubmodules setting in a ctest(1) dashboard
8811 client script.
8812 CTEST_GIT_UPDATE_CUSTOM
8814 New in version 3.1.
8815 Specify the CTest GITUpdateCustom setting in a ctest(1) dashboard
8818 client script.
8819 CTEST_GIT_UPDATE_OPTIONS
8821 New in version 3.1.
8822 Specify the CTest GITUpdateOptions setting in a ctest(1) dashboard
8825 client script.
8826 CTEST_HG_COMMAND
8828 New in version 3.1.
8829 Specify the CTest HGCommand setting in a ctest(1) dashboard client
8832 script.
8833 CTEST_HG_UPDATE_OPTIONS
8835 New in version 3.1.
8836 Specify the CTest HGUpdateOptions setting in a ctest(1) dashboard
8839 client script.
8840 CTEST_LABELS_FOR_SUBPROJECTS
8842 New in version 3.10.
8843 Specify the CTest LabelsForSubprojects setting in a ctest(1) dashboard
8846 client script.
8847 CTEST_MEMORYCHECK_COMMAND
8849 New in version 3.1.
8850 Specify the CTest MemoryCheckCommand setting in a ctest(1) dashboard
8853 client script.
8854 CTEST_MEMORYCHECK_COMMAND_OPTIONS
8856 New in version 3.1.
8857 Specify the CTest MemoryCheckCommandOptions setting in a ctest(1) dash‐
8860 board client script.
8861 CTEST_MEMORYCHECK_SANITIZER_OPTIONS
8863 New in version 3.1.
8864 Specify the CTest MemoryCheckSanitizerOptions setting in a ctest(1)
8867 dashboard client script.
8868 CTest prepends correct sanitizer options *_OPTIONS environment variable
8870 to executed command. CTests adds its own log_path to sanitizer options,
8871 don't provide your own log_path.
8872 CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
8874 New in version 3.1.
8875 Specify the CTest MemoryCheckSuppressionFile setting in a ctest(1)
8878 dashboard client script.
8879 CTEST_MEMORYCHECK_TYPE
8881 New in version 3.1.
8882 Specify the CTest MemoryCheckType setting in a ctest(1) dashboard
8885 client script. Valid values are Valgrind, Purify, BoundsChecker,
8886 DrMemory, CudaSanitizer, ThreadSanitizer, AddressSanitizer, LeakSani‐
8887 tizer, MemorySanitizer and UndefinedBehaviorSanitizer.
8888 CTEST_NIGHTLY_START_TIME
8890 New in version 3.1.
8891 Specify the CTest NightlyStartTime setting in a ctest(1) dashboard
8894 client script.
8895 Note that this variable must always be set for a nightly build in a
8897 dashboard script. It is needed so that nightly builds can be properly
8898 grouped together in CDash.
8899 CTEST_P4_CLIENT
8901 New in version 3.1.
8902 Specify the CTest P4Client setting in a ctest(1) dashboard client
8905 script.
8906 CTEST_P4_COMMAND
8908 New in version 3.1.
8909 Specify the CTest P4Command setting in a ctest(1) dashboard client
8912 script.
8913 CTEST_P4_OPTIONS
8915 New in version 3.1.
8916 Specify the CTest P4Options setting in a ctest(1) dashboard client
8919 script.
8920 CTEST_P4_UPDATE_OPTIONS
8922 New in version 3.1.
8923 Specify the CTest P4UpdateOptions setting in a ctest(1) dashboard
8926 client script.
8927 CTEST_RESOURCE_SPEC_FILE
8929 New in version 3.18.
8930 Specify the CTest ResourceSpecFile setting in a ctest(1) dashboard
8933 client script.
8934 This can also be used to specify the resource spec file from a CMake
8936 build. If no RESOURCE_SPEC_FILE is passed to ctest_test(), and
8937 CTEST_RESOURCE_SPEC_FILE is not specified in the dashboard script, the
8938 value of this variable from the build is used.
8939 CTEST_RUN_CURRENT_SCRIPT
8941 New in version 3.11.
8942 Setting this to 0 prevents ctest(1) from being run again when it
8945 reaches the end of a script run by calling ctest -S.
8946 CTEST_SCP_COMMAND
8948 New in version 3.1.
8949 Legacy option. Not used.
8952 CTEST_SCRIPT_DIRECTORY
8954 The directory containing the top-level CTest script. The concept is
8955 similar to CMAKE_SOURCE_DIR.
8956 CTEST_SITE
8958 New in version 3.1.
8959 Specify the CTest Site setting in a ctest(1) dashboard client script.
8962 CTEST_SOURCE_DIRECTORY
8964 New in version 3.1.
8965 Specify the CTest SourceDirectory setting in a ctest(1) dashboard
8968 client script.
8969 CTEST_SUBMIT_INACTIVITY_TIMEOUT
8971 New in version 3.23.
8972 Specify the CTest SubmitInactivityTimeout setting in a ctest(1) dash‐
8975 board client script.
8976 CTEST_SUBMIT_URL
8978 New in version 3.14.
8979 Specify the CTest SubmitURL setting in a ctest(1) dashboard client
8982 script.
8983 CTEST_SVN_COMMAND
8985 New in version 3.1.
8986 Specify the CTest SVNCommand setting in a ctest(1) dashboard client
8989 script.
8990 CTEST_SVN_OPTIONS
8992 New in version 3.1.
8993 Specify the CTest SVNOptions setting in a ctest(1) dashboard client
8996 script.
8997 CTEST_SVN_UPDATE_OPTIONS
8999 New in version 3.1.
9000 Specify the CTest SVNUpdateOptions setting in a ctest(1) dashboard
9003 client script.
9004 CTEST_TEST_LOAD
9006 New in version 3.4.
9007 Specify the TestLoad setting in the CTest Test Step of a ctest(1) dash‐
9010 board client script. This sets the default value for the TEST_LOAD op‐
9011 tion of the ctest_test() command.
9012 CTEST_TEST_TIMEOUT
9014 New in version 3.1.
9015 Specify the CTest TimeOut setting in a ctest(1) dashboard client
9018 script.
9019 CTEST_TRIGGER_SITE
9021 New in version 3.1.
9022 Legacy option. Not used.
9025 CTEST_UPDATE_COMMAND
9027 New in version 3.1.
9028 Specify the CTest UpdateCommand setting in a ctest(1) dashboard client
9031 script.
9032 CTEST_UPDATE_OPTIONS
9034 New in version 3.1.
9035 Specify the CTest UpdateOptions setting in a ctest(1) dashboard client
9038 script.
9039 CTEST_UPDATE_VERSION_ONLY
9041 New in version 3.1.
9042 Specify the CTest UpdateVersionOnly setting in a ctest(1) dashboard
9045 client script.
9046 CTEST_UPDATE_VERSION_OVERRIDE
9048 New in version 3.15.
9049 Specify the CTest UpdateVersionOverride setting in a ctest(1) dashboard
9052 client script.
9053 CTEST_USE_LAUNCHERS
9055 New in version 3.1.
9056 Specify the CTest UseLaunchers setting in a ctest(1) dashboard client
9059 script.
9060
9062 CPACK_ABSOLUTE_DESTINATION_FILES
9063 List of files which have been installed using an ABSOLUTE DESTINATION
9064 path.
9065 This variable is a Read-Only variable which is set internally by CPack
9067 during installation and before packaging using
9068 CMAKE_ABSOLUTE_DESTINATION_FILES defined in cmake_install.cmake
9069 scripts. The value can be used within CPack project configuration file
9070 and/or CPack<GEN>.cmake file of <GEN> generator.
9071 CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9073 Boolean toggle to include/exclude top level directory (component case).
9074 Similar usage as CPACK_INCLUDE_TOPLEVEL_DIRECTORY but for the component
9076 case. See CPACK_INCLUDE_TOPLEVEL_DIRECTORY documentation for the de‐
9077 tail.
9078 CPACK_CUSTOM_INSTALL_VARIABLES
9080 New in version 3.21.
9081 CPack variables (set via e.g. cpack -D, CPackConfig.cmake or
9084 CPACK_PROJECT_CONFIG_FILE scripts) are not directly visible in instal‐
9085 lation scripts. Instead, one can pass a list of varName=value pairs in
9086 the CPACK_CUSTOM_INSTALL_VARIABLES variable. At install time, each
9087 list item will result in a variable of the specified name (varName) be‐
9088 ing set to the given value. The = can be omitted for an empty value.
9089 CPACK_CUSTOM_INSTALL_VARIABLES allows the packaging installation to be
9091 influenced by the user or driving script at CPack runtime without hav‐
9092 ing to regenerate the install scripts.
9093 Example
9095 install(FILES large.txt DESTINATION data)
9096 install(CODE [[
9098 if(ENABLE_COMPRESSION)
9099 # "run-compressor" is a fictional tool that produces
9100 # large.txt.xz from large.txt and then removes the input file
9101 execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt)
9102 endif()
9103 ]])
9104 With the above example snippet, cpack will by default run the installa‐
9106 tion script with ENABLE_COMPRESSION unset, resulting in a package con‐
9107 taining the uncompressed large.txt. This can be overridden when invok‐
9108 ing cpack like so:
9109 cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE"
9111 The installation script will then run with ENABLE_COMPRESSION set to
9113 TRUE, resulting in a package containing the compressed large.txt.xz in‐
9114 stead.
9115 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
9117 Ask CPack to error out as soon as a file with absolute INSTALL DESTINA‐
9118 TION is encountered.
9119 The fatal error is emitted before the installation of the offending
9121 file takes place. Some CPack generators, like NSIS, enforce this in‐
9122 ternally. This variable triggers the definition of
9123 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs.
9124 CPACK_INCLUDE_TOPLEVEL_DIRECTORY
9126 Boolean toggle to include/exclude top level directory.
9127 When preparing a package CPack installs the item under the so-called
9129 top level directory. The purpose of is to include (set to 1 or ON or
9130 TRUE) the top level directory in the package or not (set to 0 or OFF or
9131 FALSE).
9132 Each CPack generator has a built-in default value for this variable.
9134 E.g. Archive generators (ZIP, TGZ, ...) includes the top level whereas
9135 RPM or DEB don't. The user may override the default value by setting
9136 this variable.
9137 There is a similar variable CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9139 which may be used to override the behavior for the component packaging
9140 case which may have different default value for historical (now back‐
9141 ward compatibility) reason.
9142 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
9144 New in version 3.11.
9145 Default permissions for implicitly created directories during packag‐
9148 ing.
9149 This variable serves the same purpose during packaging as the
9151 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable serves during in‐
9152 stallation (e.g. make install).
9153 If include(CPack) is used then by default this variable is set to the
9155 content of CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.
9156 CPACK_PACKAGING_INSTALL_PREFIX
9158 The prefix used in the built package.
9159 Each CPack generator has a default value (like /usr). This default
9161 value may be overwritten from the CMakeLists.txt or the cpack(1) com‐
9162 mand line by setting an alternative value. Example:
9163 set(CPACK_PACKAGING_INSTALL_PREFIX "/opt")
9165 This is not the same purpose as CMAKE_INSTALL_PREFIX which is used when
9167 installing from the build tree without building a package.
9168 CPACK_SET_DESTDIR
9170 Boolean toggle to make CPack use DESTDIR mechanism when packaging.
9171 DESTDIR means DESTination DIRectory. It is commonly used by makefile
9173 users in order to install software at non-default location. It is a
9174 basic relocation mechanism that should not be used on Windows (see
9175 CMAKE_INSTALL_PREFIX documentation). It is usually invoked like this:
9176 make DESTDIR=/home/john install
9178 which will install the concerned software using the installation pre‐
9180 fix, e.g. /usr/local prepended with the DESTDIR value which finally
9181 gives /home/john/usr/local. When preparing a package, CPack first in‐
9182 stalls the items to be packaged in a local (to the build tree) direc‐
9183 tory by using the same DESTDIR mechanism. Nevertheless, if
9184 CPACK_SET_DESTDIR is set then CPack will set DESTDIR before doing the
9185 local install. The most noticeable difference is that without
9186 CPACK_SET_DESTDIR, CPack uses CPACK_PACKAGING_INSTALL_PREFIX as a pre‐
9187 fix whereas with CPACK_SET_DESTDIR set, CPack will use
9188 CMAKE_INSTALL_PREFIX as a prefix.
9189 Manually setting CPACK_SET_DESTDIR may help (or simply be necessary) if
9191 some install rules uses absolute DESTINATION (see CMake install() com‐
9192 mand). However, starting with CPack/CMake 2.8.3 RPM and DEB installers
9193 tries to handle DESTDIR automatically so that it is seldom necessary
9194 for the user to set it.
9195 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
9197 Ask CPack to warn each time a file with absolute INSTALL DESTINATION is
9198 encountered.
9199 This variable triggers the definition of
9201 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs cmake_in‐
9202 stall.cmake scripts.
9203
9205 CACHE
9206 New in version 3.13.
9207 Operator to read cache variables.
9210 Use the syntax $CACHE{VAR} to read cache entry VAR. See the
9212 cmake-language(7) variables documentation for more complete documenta‐
9213 tion of the interaction of normal variables and cache entries.
9214 When evaluating Variable References of the form ${VAR}, CMake first
9216 searches for a normal variable with that name, and if not found CMake
9217 will search for a cache entry with that name. The $CACHE{VAR} syntax
9218 can be used to do direct cache lookup and ignore any existing normal
9219 variable.
9220 See the set() and unset() commands to see how to write or remove cache
9222 variables.
9223 ENV
9225 Operator to read environment variables.
9226 Use the syntax $ENV{VAR} to read environment variable VAR.
9228 To test whether an environment variable is defined, use the signature
9230 if(DEFINED ENV{<name>}) of the if() command.
9231 For general information on environment variables, see the Environment
9233 Variables section in the cmake-language(7) manual.
9234
9236 CMake has many internal variables. Most of them are undocumented.
9237 Some of them, however, were at some point described as normal vari‐
9238 ables, and therefore may be encountered in legacy code. They are sub‐
9239 ject to change, and not recommended for use in project code.
9240 CMAKE_HOME_DIRECTORY
9242 Path to top of source tree. Same as CMAKE_SOURCE_DIR.
9243 This is an internal cache entry used to locate the source directory
9245 when loading a CMakeCache.txt from a build tree. It should not be used
9246 in project code. The variable CMAKE_SOURCE_DIR has the same value and
9247 should be preferred.
9248 CMAKE_INTERNAL_PLATFORM_ABI
9250 An internal variable subject to change.
9251 This is used in determining the compiler ABI and is subject to change.
9253 CMAKE_<LANG>_COMPILER_ABI
9255 An internal variable subject to change.
9256 This is used in determining the compiler ABI and is subject to change.
9258 CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID
9260 New in version 3.10.
9261 An internal variable subject to change.
9264 This is used to identify the variant of a compiler based on its target
9266 architecture. For some compilers this is needed to determine the cor‐
9267 rect usage.
9268 CMAKE_<LANG>_COMPILER_VERSION_INTERNAL
9270 New in version 3.10.
9271 An internal variable subject to change.
9274 This is used to identify the variant of a compiler based on an internal
9276 version number. For some compilers this is needed to determine the
9277 correct usage.
9278 CMAKE_<LANG>_LINKER_PREFERENCE
9280 An internal variable subject to change.
9281 Preference value for linker language selection.
9283 The "linker language" for executable, shared library, and module tar‐
9285 gets is the language whose compiler will invoke the linker. The
9286 LINKER_LANGUAGE target property sets the language explicitly. Other‐
9287 wise, the linker language is that whose linker preference value is
9288 highest among languages compiled and linked into the target. See also
9289 the CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES variable.
9290 CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
9292 An internal variable subject to change.
9293 True if CMAKE_<LANG>_LINKER_PREFERENCE propagates across targets.
9295 This is used when CMake selects a linker language for a target. Lan‐
9297 guages compiled directly into the target are always considered. A lan‐
9298 guage compiled into static libraries linked by the target is considered
9299 if this variable is true.
9300 CMAKE_<LANG>_PLATFORM_ID
9302 An internal variable subject to change.
9303 This is used in determining the platform and is subject to change.
9305 CMAKE_NOT_USING_CONFIG_FLAGS
9307 Skip _BUILD_TYPE flags if true.
9308 This is an internal flag used by the generators in CMake to tell CMake
9310 to skip the _BUILD_TYPE flags.
9311 CMAKE_VS_INTEL_Fortran_PROJECT_VERSION
9313 When generating for Visual Studio 9 2008 or greater with the Intel For‐
9314 tran plugin installed, this specifies the .vfproj project file format
9315 version. This is intended for internal use by CMake and should not be
9316 used by project code.
9317
9319 2000-2023 Kitware, Inc. and Contributors
93203.25.2 Jan 19, 2023 CMAKE-VARIABLES(7)