1CMAKE-VARIABLES(7) CMake CMAKE-VARIABLES(7)
2
3
4
6 cmake-variables - CMake Variables Reference
7
8 This page documents variables that are provided by CMake or have mean‐
9 ing to CMake when set by project code.
10
11 For general information on variables, see the Variables section in the
12 cmake-language manual.
13
14 NOTE:
15 CMake reserves identifiers that:
16
17 • begin with CMAKE_ (upper-, lower-, or mixed-case), or
18
19 • begin with _CMAKE_ (upper-, lower-, or mixed-case), or
20
21 • begin with _ followed by the name of any CMake Command.
22
24 CMAKE_AR
25 Name of archiving tool for static libraries.
26
27 This specifies the name of the program that creates archive or static
28 libraries.
29
30 CMAKE_ARGC
31 Number of command line arguments passed to CMake in script mode.
32
33 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
36 CMAKE_ARGV0
37 Command line argument passed to CMake in script mode.
38
39 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
44 CMAKE_BINARY_DIR
45 The path to the top level of the build tree.
46
47 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
50 When run in cmake -P script mode, CMake sets the variables CMAKE_BI‐
51 NARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
52 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
53
54 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
58 CMAKE_CACHE_MAJOR_VERSION
59 Major version of CMake used to create the CMakeCache.txt file
60
61 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
65 CMAKE_CACHE_MINOR_VERSION
66 Minor version of CMake used to create the CMakeCache.txt file
67
68 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
72 CMAKE_CACHE_PATCH_VERSION
73 Patch version of CMake used to create the CMakeCache.txt file
74
75 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
79 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
84 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
89
90 Build-time reference to per-configuration output subdirectory.
91
92 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
99 $(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
106 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
110 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
119 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
125 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
130 CMAKE_COMMAND
131 The full path to the cmake(1) executable.
132
133 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
137 CMAKE_CPACK_COMMAND
138 New in version 3.13.
139
140
141 Full path to cpack(1) command installed with CMake.
142
143 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
146 CMAKE_CROSSCOMPILING
147 This variable is set by CMake to indicate whether it is cross compil‐
148 ing, but note limitations discussed below.
149
150 This variable will be set to true by CMake if the CMAKE_SYSTEM_NAME
151 variable has been set manually (i.e. in a toolchain file or as a cache
152 entry from the cmake command line). In most cases, manually setting
153 CMAKE_SYSTEM_NAME will only be done when cross compiling since, if not
154 manually set, it will be given the same value as
155 CMAKE_HOST_SYSTEM_NAME, which is correct for the non-cross-compiling
156 case. In the event that CMAKE_SYSTEM_NAME is manually set to the same
157 value as CMAKE_HOST_SYSTEM_NAME, then CMAKE_CROSSCOMPILING will still
158 be set to true.
159
160 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
171 CMAKE_CROSSCOMPILING_EMULATOR
172 New in version 3.3.
173
174
175 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
179 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
183
184 The command will be used to run try_run() generated executables, which
185 avoids manual population of the TryRunResults.cmake file.
186
187 It is also used as the default value for the CROSSCOMPILING_EMULATOR
188 target property of executables.
189
190 CMAKE_CTEST_COMMAND
191 Full path to ctest(1) command installed with CMake.
192
193 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
196 CMAKE_CURRENT_BINARY_DIR
197 The path to the binary directory currently being processed.
198
199 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
205 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
209 CMAKE_CURRENT_FUNCTION
210 New in version 3.17.
211
212
213 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
217 See also CMAKE_CURRENT_FUNCTION_LIST_DIR,
218 CMAKE_CURRENT_FUNCTION_LIST_FILE and CMAKE_CURRENT_FUNCTION_LIST_LINE.
219
220 CMAKE_CURRENT_FUNCTION_LIST_DIR
221 New in version 3.17.
222
223
224 When executing code inside a function(), this variable contains the
225 full directory of the listfile that defined the current function.
226
227 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
234 set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
235
236 function(foo)
237 configure_file(
238 "${_THIS_MODULE_BASE_DIR}/some.template.in"
239 some.output
240 )
241 endfunction()
242
243 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
248 function(foo)
249 configure_file(
250 "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
251 some.output
252 )
253 endfunction()
254
255 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_FILE and
256 CMAKE_CURRENT_FUNCTION_LIST_LINE.
257
258 CMAKE_CURRENT_FUNCTION_LIST_FILE
259 New in version 3.17.
260
261
262 When executing code inside a function(), this variable contains the
263 full path to the listfile that defined the current function.
264
265 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
266 CMAKE_CURRENT_FUNCTION_LIST_LINE.
267
268 CMAKE_CURRENT_FUNCTION_LIST_LINE
269 New in version 3.17.
270
271
272 When executing code inside a function(), this variable contains the
273 line number in the listfile where the current function was defined.
274
275 See also CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR and
276 CMAKE_CURRENT_FUNCTION_LIST_FILE.
277
278 CMAKE_CURRENT_LIST_DIR
279 Full directory of the listfile currently being processed.
280
281 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
292 See also CMAKE_CURRENT_LIST_FILE.
293
294 CMAKE_CURRENT_LIST_FILE
295 Full path to the listfile currently being processed.
296
297 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
306 See also CMAKE_PARENT_LIST_FILE.
307
308 CMAKE_CURRENT_LIST_LINE
309 The line number of the current file being processed.
310
311 This is the line number of the file currently being processed by cmake.
312
313 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
317 CMAKE_CURRENT_SOURCE_DIR
318 The path to the source directory currently being processed.
319
320 This is the full path to the source directory that is currently being
321 processed by cmake.
322
323 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
327 CMAKE_DEBUG_TARGET_PROPERTIES
328 Enables tracing output for target properties.
329
330 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
334 • AUTOUIC_OPTIONS
335
336 • COMPILE_DEFINITIONS
337
338 • COMPILE_FEATURES
339
340 • COMPILE_OPTIONS
341
342 • INCLUDE_DIRECTORIES
343
344 • LINK_DIRECTORIES
345
346 • LINK_OPTIONS
347
348 • POSITION_INDEPENDENT_CODE
349
350 • SOURCES
351
352 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
357 CMAKE_DIRECTORY_LABELS
358 New in version 3.10.
359
360
361 Specify labels for the current directory.
362
363 This is used to initialize the LABELS directory property.
364
365 CMAKE_DL_LIBS
366 Name of library containing dlopen and dlclose.
367
368 The name of the library that has dlopen and dlclose in it, usually -ldl
369 on most UNIX machines.
370
371 CMAKE_DOTNET_SDK
372 New in version 3.23.
373
374
375 Default value for DOTNET_SDK property of targets.
376
377 This variable is used to initialize the DOTNET_SDK property on all tar‐
378 gets. See that target property for additional information.
379
380 CMAKE_DOTNET_TARGET_FRAMEWORK
381 New in version 3.17.
382
383
384 Default value for DOTNET_TARGET_FRAMEWORK property of targets.
385
386 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
390 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
394 This variable is only evaluated for Visual Studio Generators VS 2010
395 and above.
396
397 CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
398 New in version 3.12.
399
400
401 Default value for DOTNET_TARGET_FRAMEWORK_VERSION property of targets.
402
403 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
409 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
413 This variable is only evaluated for Visual Studio Generators VS 2010
414 and above.
415
416 CMAKE_EDIT_COMMAND
417 Full path to cmake-gui(1) or ccmake(1). Defined only for Makefile Gen‐
418 erators and Ninja Generators when not using any Extra Generators.
419
420 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
423 CMAKE_EXECUTABLE_SUFFIX
424 The suffix for executables on this platform.
425
426 The suffix to use for the end of an executable filename if any, .exe on
427 Windows.
428
429 CMAKE_EXECUTABLE_SUFFIX_<LANG> overrides this for language <LANG>.
430
431 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
435 It overrides CMAKE_EXECUTABLE_SUFFIX for language <LANG>.
436
437 CMAKE_EXTRA_GENERATOR
438 Deprecated since version 3.27: Support for Extra Generators is depre‐
439 cated and will be removed from a future version of CMake. IDEs may use
440 the cmake-file-api(7) to view CMake-generated project build trees.
441
442
443 The extra generator used to build the project. See
444 cmake-generators(7).
445
446 When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime genera‐
447 tors, CMake generates Makefiles (CMAKE_GENERATOR) and additionally
448 project files for the respective IDE. This IDE project file generator
449 is stored in CMAKE_EXTRA_GENERATOR (e.g. Eclipse CDT4).
450
451 CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
452 Additional suffixes for shared libraries.
453
454 Extensions for shared libraries other than that specified by
455 CMAKE_SHARED_LIBRARY_SUFFIX, if any. CMake uses this to recognize ex‐
456 ternal shared library files during analysis of libraries linked by a
457 target.
458
459 CMAKE_FIND_DEBUG_MODE
460 New in version 3.17.
461
462
463 Print extra find call information for the following commands to stan‐
464 dard error:
465
466 • find_program()
467
468 • find_library()
469
470 • find_file()
471
472 • find_path()
473
474 • find_package()
475
476 Output is designed for human consumption and not for parsing. Enabling
477 this variable is equivalent to using cmake --debug-find with the added
478 ability to enable debugging for a subset of find calls.
479
480 set(CMAKE_FIND_DEBUG_MODE TRUE)
481 find_program(...)
482 set(CMAKE_FIND_DEBUG_MODE FALSE)
483
484 Default is unset.
485
486 CMAKE_FIND_PACKAGE_NAME
487 New in version 3.1.1.
488
489
490 Defined by the find_package() command while loading a find module to
491 record the caller-specified package name. See command documentation
492 for details.
493
494 CMAKE_FIND_PACKAGE_REDIRECTS_DIR
495 New in version 3.24.
496
497
498 This read-only variable specifies a directory that the find_package()
499 command will check first before searching anywhere else for a module or
500 config package file. A config package file in this directory will al‐
501 ways be found in preference to any other Find module file or config
502 package file.
503
504 The primary purpose of this variable is to facilitate integration be‐
505 tween find_package() and FetchContent_MakeAvailable(). The latter com‐
506 mand may create files in the CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory
507 when it populates a dependency. This allows subsequent calls to
508 find_package() for the same dependency to re-use the populated contents
509 instead of trying to satisfy the dependency from somewhere external to
510 the build. Projects may also want to write files into this directory
511 in some situations (see Integrating With find_package() for examples).
512
513 The directory that CMAKE_FIND_PACKAGE_REDIRECTS_DIR points to will al‐
514 ways be erased and recreated empty at the start of every CMake run.
515 Any files written into this directory during the CMake run will be lost
516 the next time CMake configures the project.
517
518 CMAKE_FIND_PACKAGE_REDIRECTS_DIR is only set in CMake project mode. It
519 is not set when CMake is run in script mode (i.e. cmake -P).
520
521 CMAKE_FIND_PACKAGE_SORT_DIRECTION
522 New in version 3.7.
523
524
525 The sorting direction used by CMAKE_FIND_PACKAGE_SORT_ORDER. It can
526 assume one of the following values:
527
528 DEC Default. Ordering is done in descending mode. The highest
529 folder found will be tested first.
530
531 ASC Ordering is done in ascending mode. The lowest folder found
532 will be tested first.
533
534 If CMAKE_FIND_PACKAGE_SORT_ORDER is not set or is set to NONE this
535 variable has no effect.
536
537 CMAKE_FIND_PACKAGE_SORT_ORDER
538 New in version 3.7.
539
540
541 The default order for sorting packages found using find_package(). It
542 can assume one of the following values:
543
544 NONE Default. No attempt is done to sort packages. The first valid
545 package found will be selected.
546
547 NAME Sort packages lexicographically before selecting one.
548
549 NATURAL
550 Sort packages using natural order (see strverscmp(3) manual),
551 i.e. such that contiguous digits are compared as whole numbers.
552
553 Natural sorting can be employed to return the highest version when mul‐
554 tiple versions of the same library are found by find_package(). For
555 example suppose that the following libraries have been found:
556
557 • libX-1.1.0
558
559 • libX-1.2.9
560
561 • libX-1.2.10
562
563 By setting NATURAL order we can select the one with the highest version
564 number libX-1.2.10.
565
566 set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
567 find_package(libX CONFIG)
568
569 The sort direction can be controlled using the
570 CMAKE_FIND_PACKAGE_SORT_DIRECTION variable (by default decrescent, e.g.
571 lib-B will be tested before lib-A).
572
573 CMAKE_GENERATOR
574 The generator used to build the project. See cmake-generators(7).
575
576 The name of the generator that is being used to generate the build
577 files. (e.g. Unix Makefiles, Ninja, etc.)
578
579 The value of this variable should never be modified by project code. A
580 generator may be selected via the cmake -G option, interactively in
581 cmake-gui(1), or via the CMAKE_GENERATOR environment variable.
582
583 CMAKE_GENERATOR_INSTANCE
584 New in version 3.11.
585
586
587 Generator-specific instance specification provided by user.
588
589 Some CMake generators support selection of an instance of the native
590 build system when multiple instances are available. If the user speci‐
591 fies an instance (e.g. by setting this cache entry or via the
592 CMAKE_GENERATOR_INSTANCE environment variable), or after a default in‐
593 stance is chosen when a build tree is first configured, the value will
594 be available in this variable.
595
596 The value of this variable should never be modified by project code. A
597 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
598 tialize CMAKE_GENERATOR_INSTANCE as a cache entry. Once a given build
599 tree has been initialized with a particular value for this variable,
600 changing the value has undefined behavior.
601
602 Instance specification is supported only on specific generators.
603
604 Visual Studio Instance Selection
605 Visual Studio Generators support instance specification for Visual Stu‐
606 dio 2017 and above. The CMAKE_GENERATOR_INSTANCE variable may be set
607 as a cache entry selecting an instance of Visual Studio via one of the
608 following forms:
609
610 • location
611
612 • location[,key=value]*
613
614 • key=value[,key=value]*
615
616 The location specifies the absolute path to the top-level directory of
617 the VS installation.
618
619 The key=value pairs form a comma-separated list of options to specify
620 details of the instance selection. Supported pairs are:
621
622 version=<major>.<minor>.<date>.<build>
623 New in version 3.23.
624
625
626 Specify the 4-component VS Build Version, a.k.a. Build Number.
627
628 The components are:
629
630 <major>.<minor>
631 The VS major and minor version numbers. These are the same
632 as the release version numbers.
633
634 <date>
635 A build date in the format MMMDD, where MMM is a month index
636 since an epoch used by Microsoft, and DD is a day in that
637 month.
638
639 <build>
640 A build index on the day represented by <date>.
641
642 The build number is reported by vswhere as installationVersion.
643 For example, VS 16.11.10 has build number 16.11.32126.315.
644
645 New in version 3.23: A portable VS instance, which is not known to the
646 Visual Studio Installer, may be specified by providing both location
647 and version=.
648
649
650 If the value of CMAKE_GENERATOR_INSTANCE is not specified explicitly by
651 the user or a toolchain file, CMake queries the Visual Studio Installer
652 to locate VS instances, chooses one, and sets the variable as a cache
653 entry to hold the value persistently. If an environment variable of
654 the form VS##0COMNTOOLS, where ## the Visual Studio major version num‐
655 ber, is set and points to the Common7/Tools directory within one of the
656 VS instances, that instance will be used. Otherwise, if more than one
657 VS instance is installed we do not define which one is chosen by de‐
658 fault.
659
660 The VS version build number of the selected VS instance is provided in
661 the CMAKE_VS_VERSION_BUILD_NUMBER variable.
662
663 CMAKE_GENERATOR_PLATFORM
664 New in version 3.1.
665
666
667 Generator-specific target platform specification provided by user.
668
669 Some CMake generators support a target platform name to be given to the
670 native build system to choose a compiler toolchain. If the user speci‐
671 fies a platform name (e.g. via the cmake -A option or via the
672 CMAKE_GENERATOR_PLATFORM environment variable) the value will be avail‐
673 able in this variable.
674
675 The value of this variable should never be modified by project code. A
676 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
677 tialize CMAKE_GENERATOR_PLATFORM. Once a given build tree has been
678 initialized with a particular value for this variable, changing the
679 value has undefined behavior.
680
681 Platform specification is supported only on specific generators:
682
683 • For Visual Studio Generators with VS 2005 and above this specifies
684 the target architecture.
685
686 • For Green Hills MULTI this specifies the target architecture.
687
688 See native build system documentation for allowed platform names.
689
690 Visual Studio Platform Selection
691 The Visual Studio Generators support platform specification using one
692 of these forms:
693
694 • platform
695
696 • platform[,key=value]*
697
698 • key=value[,key=value]*
699
700 The platform specifies the target platform (VS target architecture),
701 such as x64, ARM64, or Win32. The selected platform name is provided
702 in the CMAKE_VS_PLATFORM_NAME variable.
703
704 The key=value pairs form a comma-separated list of options to specify
705 generator-specific details of the platform selection. Supported pairs
706 are:
707
708 version=<version>
709 New in version 3.27.
710
711
712 Specify the Windows SDK version to use. This is supported by VS
713 2015 and above when targeting Windows or Windows Store. CMake
714 will set the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable
715 to the selected SDK version.
716
717 The <version> may be one of:
718
719 10.0 Specify that any 10.0 SDK version may be used, and let
720 Visual Studio pick one. This is supported by VS 2019 and
721 above.
722
723 10.0.<build>.<increment>
724 Specify the exact 4-component SDK version, e.g.,
725 10.0.19041.0. The specified version of the SDK must be
726 installed. It may not exceed the value of
727 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM, if that
728 variable is set.
729
730 8.1 Specify the 8.1 SDK version. This is always supported by
731 VS 2015. On VS 2017 and above the 8.1 SDK must be in‐
732 stalled.
733
734 If the version field is not specified, CMake selects a version
735 as described in the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
736 variable documentation.
737
738 CMAKE_GENERATOR_TOOLSET
739 Native build system toolset specification provided by user.
740
741 Some CMake generators support a toolset specification to tell the na‐
742 tive build system how to choose a compiler. If the user specifies a
743 toolset (e.g. via the cmake -T option or via the
744 CMAKE_GENERATOR_TOOLSET environment variable) the value will be avail‐
745 able in this variable.
746
747 The value of this variable should never be modified by project code. A
748 toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable may ini‐
749 tialize CMAKE_GENERATOR_TOOLSET. Once a given build tree has been ini‐
750 tialized with a particular value for this variable, changing the value
751 has undefined behavior.
752
753 Toolset specification is supported only on specific generators:
754
755 • Visual Studio Generators for VS 2010 and above
756
757 • The Xcode generator for Xcode 3.0 and above
758
759 • The Green Hills MULTI generator
760
761 See native build system documentation for allowed toolset names.
762
763 Visual Studio Toolset Selection
764 The Visual Studio Generators support toolset specification using one of
765 these forms:
766
767 • toolset
768
769 • toolset[,key=value]*
770
771 • key=value[,key=value]*
772
773 The toolset specifies the toolset name. The selected toolset name is
774 provided in the CMAKE_VS_PLATFORM_TOOLSET variable.
775
776 The key=value pairs form a comma-separated list of options to specify
777 generator-specific details of the toolset selection. Supported pairs
778 are:
779
780 cuda=<version>|<path>
781 Specify the CUDA toolkit version to use or the path to a stand‐
782 alone CUDA toolkit directory. Supported by VS 2010 and above.
783 The version can only be used with the CUDA toolkit VS integra‐
784 tion globally installed. See the CMAKE_VS_PLATFORM_TOOLSET_CUDA
785 and CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR variables.
786
787 host=<arch>
788 Specify the host tools architecture as x64 or x86. Supported by
789 VS 2013 and above. See the
790 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE variable.
791
792 version=<version>
793 Specify the toolset version to use. Supported by VS 2017 and
794 above with the specified toolset installed. See the
795 CMAKE_VS_PLATFORM_TOOLSET_VERSION variable.
796
797 VCTargetsPath=<path>
798 Specify an alternative VCTargetsPath value for Visual Studio
799 project files. This allows use of VS platform extension config‐
800 uration files (.props and .targets) that are not installed with
801 VS.
802
803 Visual Studio Toolset Customization
804 These are unstable interfaces with no compatibility guarantees because
805 they hook into undocumented internal CMake implementation details. In‐
806 stitutions may use these to internally maintain support for non-public
807 Visual Studio platforms and toolsets, but must accept responsibility to
808 make updates as changes are made to CMake.
809
810 Additional key=value pairs are available:
811
812 customFlagTableDir=<path>
813 New in version 3.21.
814
815
816 Specify the absolute path to a directory from which to load cus‐
817 tom flag tables stored as JSON documents with file names of the
818 form <platform>_<toolset>_<tool>.json or <platform>_<tool>.json,
819 where <platform> is the CMAKE_VS_PLATFORM_NAME, <toolset> is the
820 CMAKE_VS_PLATFORM_TOOLSET, and <tool> is the tool for which the
821 flag table is meant. This naming pattern is an internal CMake
822 implementation detail. The <tool> names are undocumented. The
823 format of the .json flag table files is undocumented.
824
825 CMAKE_IMPORT_LIBRARY_PREFIX
826 The prefix for import libraries that you link to.
827
828 The prefix to use for the name of an import library if used on this
829 platform.
830
831 CMAKE_IMPORT_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
832
833 CMAKE_IMPORT_LIBRARY_SUFFIX
834 The suffix for import libraries that you link to.
835
836 The suffix to use for the end of an import library filename if used on
837 this platform.
838
839 CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
840
841 CMAKE_JOB_POOL_COMPILE
842 This variable is used to initialize the JOB_POOL_COMPILE property on
843 all the targets. See JOB_POOL_COMPILE for additional information.
844
845 CMAKE_JOB_POOL_LINK
846 This variable is used to initialize the JOB_POOL_LINK property on all
847 the targets. See JOB_POOL_LINK for additional information.
848
849 CMAKE_JOB_POOL_PRECOMPILE_HEADER
850 New in version 3.17.
851
852
853 This variable is used to initialize the JOB_POOL_PRECOMPILE_HEADER
854 property on all the targets. See JOB_POOL_PRECOMPILE_HEADER for addi‐
855 tional information.
856
857 CMAKE_JOB_POOLS
858 New in version 3.11.
859
860
861 If the JOB_POOLS global property is not set, the value of this variable
862 is used in its place. See JOB_POOLS for additional information.
863
864 CMAKE_<LANG>_COMPILER_AR
865 New in version 3.9.
866
867
868 A wrapper around ar adding the appropriate --plugin option for the com‐
869 piler.
870
871 See also CMAKE_AR.
872
873 CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT
874 New in version 3.14.
875
876
877 Identification string of the compiler frontend variant.
878
879 Some compilers have multiple, different frontends for accepting command
880 line options. (For example Clang originally only had a frontend com‐
881 patible with the GNU compiler but since its port to Windows (Clang-Cl)
882 it now also supports a frontend compatible with MSVC.) When CMake de‐
883 tects such a compiler it sets this variable to what would have been the
884 CMAKE_<LANG>_COMPILER_ID for the compiler whose frontend it resembles.
885
886 NOTE:
887 In other words, this variable describes what command line options
888 and language extensions the compiler frontend expects.
889
890 Changed in version 3.26: This variable is set for GNU, MSVC, and Apple‐
891 Clang compilers that have only one frontend variant.
892
893
894 CMAKE_<LANG>_COMPILER_RANLIB
895 New in version 3.9.
896
897
898 A wrapper around ranlib adding the appropriate --plugin option for the
899 compiler.
900
901 See also CMAKE_RANLIB.
902
903 CMAKE_<LANG>_LINK_LIBRARY_SUFFIX
904 New in version 3.16.
905
906
907 Language-specific suffix for libraries that you link to.
908
909 The suffix to use for the end of a library filename, .lib on Windows.
910
911 CMAKE_LINK_LIBRARY_SUFFIX
912 The suffix for libraries that you link to.
913
914 The suffix to use for the end of a library filename, .lib on Windows.
915
916 CMAKE_LINK_SEARCH_END_STATIC
917 New in version 3.4.
918
919
920 End a link line such that static system libraries are used.
921
922 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
923 mine whether to use static or shared libraries for -lXXX options.
924 CMake uses these options to set the link type for libraries whose full
925 paths are not known or (in some cases) are in implicit link directories
926 for the platform. By default CMake adds an option at the end of the
927 library list (if necessary) to set the linker search type back to its
928 starting type. This property switches the final linker search type to
929 -Bstatic regardless of how it started.
930
931 This variable is used to initialize the target property
932 LINK_SEARCH_END_STATIC for all targets. If set, its value is also used
933 by the try_compile() command.
934
935 See also CMAKE_LINK_SEARCH_START_STATIC.
936
937 CMAKE_LINK_SEARCH_START_STATIC
938 New in version 3.4.
939
940
941 Assume the linker looks for static libraries by default.
942
943 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
944 mine whether to use static or shared libraries for -lXXX options.
945 CMake uses these options to set the link type for libraries whose full
946 paths are not known or (in some cases) are in implicit link directories
947 for the platform. By default the linker search type is assumed to be
948 -Bdynamic at the beginning of the library list. This property switches
949 the assumption to -Bstatic. It is intended for use when linking an ex‐
950 ecutable statically (e.g. with the GNU -static option).
951
952 This variable is used to initialize the target property
953 LINK_SEARCH_START_STATIC for all targets. If set, its value is also
954 used by the try_compile() command.
955
956 See also CMAKE_LINK_SEARCH_END_STATIC.
957
958 CMAKE_MAJOR_VERSION
959 First version number component of the CMAKE_VERSION variable.
960
961 CMAKE_MAKE_PROGRAM
962 Tool that can launch the native build system. The value may be the
963 full path to an executable or just the tool name if it is expected to
964 be in the PATH.
965
966 The tool selected depends on the CMAKE_GENERATOR used to configure the
967 project:
968
969 • The Makefile Generators set this to make, gmake, or a generator-spe‐
970 cific tool (e.g. nmake for NMake Makefiles).
971
972 These generators store CMAKE_MAKE_PROGRAM in the CMake cache so that
973 it may be edited by the user.
974
975 • The Ninja generator sets this to ninja.
976
977 This generator stores CMAKE_MAKE_PROGRAM in the CMake cache so that
978 it may be edited by the user.
979
980 • The Xcode generator sets this to xcodebuild.
981
982 This generator prefers to lookup the build tool at build time rather
983 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
984 This is because xcodebuild is easy to find.
985
986 For compatibility with versions of CMake prior to 3.2, if a user or
987 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
988 CMake will use the specified value.
989
990 • The Visual Studio Generators set this to the full path to MSBuild.exe
991 (VS >= 10), devenv.com (VS 7,8,9), or VCExpress.exe (VS Express 8,9).
992 (See also variables CMAKE_VS_MSBUILD_COMMAND and
993 CMAKE_VS_DEVENV_COMMAND.
994
995 These generators prefer to lookup the build tool at build time rather
996 than to store CMAKE_MAKE_PROGRAM in the CMake cache ahead of time.
997 This is because the tools are version-specific and can be located us‐
998 ing the Windows Registry. It is also necessary because the proper
999 build tool may depend on the project content (e.g. the Intel Fortran
1000 plugin to VS 10 and 11 requires devenv.com to build its .vfproj
1001 project files even though MSBuild.exe is normally preferred to sup‐
1002 port the CMAKE_GENERATOR_TOOLSET).
1003
1004 For compatibility with versions of CMake prior to 3.0, if a user or
1005 project explicitly adds CMAKE_MAKE_PROGRAM to the CMake cache then
1006 CMake will use the specified value if possible.
1007
1008 • The Green Hills MULTI generator sets this to the full path to
1009 gbuild.exe(Windows) or gbuild(Linux) based upon the toolset being
1010 used.
1011
1012 Once the generator has initialized a particular value for this vari‐
1013 able, changing the value has undefined behavior.
1014
1015 The CMAKE_MAKE_PROGRAM variable is set for use by project code. The
1016 value is also used by the cmake --build and ctest --build-and-test
1017 tools to launch the native build process.
1018
1019 CMAKE_MATCH_COUNT
1020 New in version 3.2.
1021
1022
1023 The number of matches with the last regular expression.
1024
1025 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
1026 variables with the match contents. The CMAKE_MATCH_COUNT variable
1027 holds the number of match expressions when these are filled.
1028
1029 CMAKE_MATCH_<n>
1030 New in version 3.9.
1031
1032
1033 Capture group <n> matched by the last regular expression, for groups 0
1034 through 9. Group 0 is the entire match. Groups 1 through 9 are the
1035 subexpressions captured by () syntax.
1036
1037 When a regular expression match is used, CMake fills in CMAKE_MATCH_<n>
1038 variables with the match contents. The CMAKE_MATCH_COUNT variable
1039 holds the number of match expressions when these are filled.
1040
1041 CMAKE_MINIMUM_REQUIRED_VERSION
1042 The <min> version of CMake given to the most recent call to the
1043 cmake_minimum_required(VERSION) command in the current variable scope
1044 or any parent variable scope.
1045
1046 CMAKE_MINOR_VERSION
1047 Second version number component of the CMAKE_VERSION variable.
1048
1049 CMAKE_NETRC
1050 New in version 3.11.
1051
1052
1053 This variable is used to initialize the NETRC option for the
1054 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
1055 tional information.
1056
1057 This variable is also used by the ExternalProject and FetchContent mod‐
1058 ules for internal calls to file(DOWNLOAD).
1059
1060 The local option takes precedence over this variable.
1061
1062 CMAKE_NETRC_FILE
1063 New in version 3.11.
1064
1065
1066 This variable is used to initialize the NETRC_FILE option for the
1067 file(DOWNLOAD) and file(UPLOAD) commands. See those commands for addi‐
1068 tional information.
1069
1070 This variable is also used by the ExternalProject and FetchContent mod‐
1071 ules for internal calls to file(DOWNLOAD).
1072
1073 The local option takes precedence over this variable.
1074
1075 CMAKE_PARENT_LIST_FILE
1076 Full path to the CMake file that included the current one.
1077
1078 While processing a CMake file loaded by include() or find_package()
1079 this variable contains the full path to the file including it. The top
1080 of the include stack is always the CMakeLists.txt for the current di‐
1081 rectory. See also CMAKE_CURRENT_LIST_FILE.
1082
1083 CMAKE_PATCH_VERSION
1084 Third version number component of the CMAKE_VERSION variable.
1085
1086 CMAKE_PROJECT_DESCRIPTION
1087 New in version 3.9.
1088
1089
1090 The description of the top level project.
1091
1092 This variable holds the description of the project as specified in the
1093 top level CMakeLists.txt file by a project() command. In the event
1094 that the top level CMakeLists.txt contains multiple project() calls,
1095 the most recently called one from that top level CMakeLists.txt will
1096 determine the value that CMAKE_PROJECT_DESCRIPTION contains. For exam‐
1097 ple, consider the following top level CMakeLists.txt:
1098
1099 cmake_minimum_required(VERSION 3.0)
1100 project(First DESCRIPTION "I am First")
1101 project(Second DESCRIPTION "I am Second")
1102 add_subdirectory(sub)
1103 project(Third DESCRIPTION "I am Third")
1104
1105 And sub/CMakeLists.txt with the following contents:
1106
1107 project(SubProj DESCRIPTION "I am SubProj")
1108 message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")
1109
1110 The most recently seen project() command from the top level CMake‐
1111 Lists.txt would be project(Second ...), so this will print:
1112
1113 CMAKE_PROJECT_DESCRIPTION = I am Second
1114
1115 To obtain the description from the most recent call to project() in the
1116 current directory scope or above, see the PROJECT_DESCRIPTION variable.
1117
1118 CMAKE_PROJECT_HOMEPAGE_URL
1119 New in version 3.12.
1120
1121
1122 The homepage URL of the top level project.
1123
1124 This variable holds the homepage URL of the project as specified in the
1125 top level CMakeLists.txt file by a project() command. In the event
1126 that the top level CMakeLists.txt contains multiple project() calls,
1127 the most recently called one from that top level CMakeLists.txt will
1128 determine the value that CMAKE_PROJECT_HOMEPAGE_URL contains. For ex‐
1129 ample, consider the following top level CMakeLists.txt:
1130
1131 cmake_minimum_required(VERSION 3.0)
1132 project(First HOMEPAGE_URL "http://first.example.com")
1133 project(Second HOMEPAGE_URL "http://second.example.com")
1134 add_subdirectory(sub)
1135 project(Third HOMEPAGE_URL "http://third.example.com")
1136
1137 And sub/CMakeLists.txt with the following contents:
1138
1139 project(SubProj HOMEPAGE_URL "http://subproj.example.com")
1140 message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}")
1141
1142 The most recently seen project() command from the top level CMake‐
1143 Lists.txt would be project(Second ...), so this will print:
1144
1145 CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com
1146
1147 To obtain the homepage URL from the most recent call to project() in
1148 the current directory scope or above, see the PROJECT_HOMEPAGE_URL
1149 variable.
1150
1151 CMAKE_PROJECT_NAME
1152 The name of the top level project.
1153
1154 This variable holds the name of the project as specified in the top
1155 level CMakeLists.txt file by a project() command. In the event that
1156 the top level CMakeLists.txt contains multiple project() calls, the
1157 most recently called one from that top level CMakeLists.txt will deter‐
1158 mine the name that CMAKE_PROJECT_NAME contains. For example, consider
1159 the following top level CMakeLists.txt:
1160
1161 cmake_minimum_required(VERSION 3.0)
1162 project(First)
1163 project(Second)
1164 add_subdirectory(sub)
1165 project(Third)
1166
1167 And sub/CMakeLists.txt with the following contents:
1168
1169 project(SubProj)
1170 message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")
1171
1172 The most recently seen project() command from the top level CMake‐
1173 Lists.txt would be project(Second), so this will print:
1174
1175 CMAKE_PROJECT_NAME = Second
1176
1177 To obtain the name from the most recent call to project() in the cur‐
1178 rent directory scope or above, see the PROJECT_NAME variable.
1179
1180 CMAKE_PROJECT_VERSION
1181 New in version 3.12.
1182
1183
1184 The version of the top level project.
1185
1186 This variable holds the version of the project as specified in the top
1187 level CMakeLists.txt file by a project() command. In the event that
1188 the top level CMakeLists.txt contains multiple project() calls, the
1189 most recently called one from that top level CMakeLists.txt will deter‐
1190 mine the value that CMAKE_PROJECT_VERSION contains. For example, con‐
1191 sider the following top level CMakeLists.txt:
1192
1193 cmake_minimum_required(VERSION 3.0)
1194 project(First VERSION 1.2.3)
1195 project(Second VERSION 3.4.5)
1196 add_subdirectory(sub)
1197 project(Third VERSION 6.7.8)
1198
1199 And sub/CMakeLists.txt with the following contents:
1200
1201 project(SubProj VERSION 1)
1202 message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")
1203
1204 The most recently seen project() command from the top level CMake‐
1205 Lists.txt would be project(Second ...), so this will print:
1206
1207 CMAKE_PROJECT_VERSION = 3.4.5
1208
1209 To obtain the version from the most recent call to project() in the
1210 current directory scope or above, see the PROJECT_VERSION variable.
1211
1212 CMAKE_PROJECT_VERSION_MAJOR
1213 New in version 3.12.
1214
1215
1216 The major version of the top level project.
1217
1218 This variable holds the major version of the project as specified in
1219 the top level CMakeLists.txt file by a project() command. Please see
1220 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1221 project() commands are used in the sources.
1222
1223 CMAKE_PROJECT_VERSION_MINOR
1224 New in version 3.12.
1225
1226
1227 The minor version of the top level project.
1228
1229 This variable holds the minor version of the project as specified in
1230 the top level CMakeLists.txt file by a project() command. Please see
1231 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1232 project() commands are used in the sources.
1233
1234 CMAKE_PROJECT_VERSION_PATCH
1235 New in version 3.12.
1236
1237
1238 The patch version of the top level project.
1239
1240 This variable holds the patch version of the project as specified in
1241 the top level CMakeLists.txt file by a project() command. Please see
1242 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1243 project() commands are used in the sources.
1244
1245 CMAKE_PROJECT_VERSION_TWEAK
1246 New in version 3.12.
1247
1248
1249 The tweak version of the top level project.
1250
1251 This variable holds the tweak version of the project as specified in
1252 the top level CMakeLists.txt file by a project() command. Please see
1253 CMAKE_PROJECT_VERSION documentation for the behavior when multiple
1254 project() commands are used in the sources.
1255
1256 CMAKE_RANLIB
1257 Name of randomizing tool for static libraries.
1258
1259 This specifies name of the program that randomizes libraries on UNIX,
1260 not used on Windows, but may be present.
1261
1262 CMAKE_ROOT
1263 Install directory for running cmake.
1264
1265 This is the install root for the running CMake and the Modules direc‐
1266 tory can be found here. This is commonly used in this format:
1267 ${CMAKE_ROOT}/Modules
1268
1269 CMAKE_RULE_MESSAGES
1270 New in version 3.13.
1271
1272
1273 Specify whether to report a message for each make rule.
1274
1275 If set in the cache it is used to initialize the value of the
1276 RULE_MESSAGES property. Users may disable the option in their local
1277 build tree to disable granular messages and report only as each target
1278 completes in Makefile builds.
1279
1280 CMAKE_SCRIPT_MODE_FILE
1281 Full path to the cmake -P script file currently being processed.
1282
1283 When run in cmake -P script mode, CMake sets this variable to the full
1284 path of the script file. When run to configure a CMakeLists.txt file,
1285 this variable is not set.
1286
1287 CMAKE_SHARED_LIBRARY_PREFIX
1288 The prefix for shared libraries that you link to.
1289
1290 The prefix to use for the name of a shared library, lib on UNIX.
1291
1292 CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1293
1294 CMAKE_SHARED_LIBRARY_SUFFIX
1295 The suffix for shared libraries that you link to.
1296
1297 The suffix to use for the end of a shared library filename, .dll on
1298 Windows.
1299
1300 CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1301
1302 CMAKE_SHARED_MODULE_PREFIX
1303 The prefix for loadable modules that you link to.
1304
1305 The prefix to use for the name of a loadable module on this platform.
1306
1307 CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides this for language <LANG>.
1308
1309 CMAKE_SHARED_MODULE_SUFFIX
1310 The suffix for shared libraries that you link to.
1311
1312 The suffix to use for the end of a loadable module filename on this
1313 platform
1314
1315 CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides this for language <LANG>.
1316
1317 CMAKE_SIZEOF_VOID_P
1318 Size of a void pointer.
1319
1320 This is set to the size of a pointer on the target machine, and is de‐
1321 termined by a try compile. If a 64-bit size is found, then the library
1322 search path is modified to look for 64-bit libraries first.
1323
1324 CMAKE_SKIP_INSTALL_RULES
1325 Whether to disable generation of installation rules.
1326
1327 If TRUE, CMake will neither generate installation rules nor will it
1328 generate cmake_install.cmake files. This variable is FALSE by default.
1329
1330 CMAKE_SKIP_RPATH
1331 If true, do not add run time path information.
1332
1333 If this is set to TRUE, then the rpath information is not added to com‐
1334 piled executables. The default is to add rpath information if the
1335 platform supports it. This allows for easy running from the build
1336 tree. To omit RPATH in the install step, but not the build step, use
1337 CMAKE_SKIP_INSTALL_RPATH instead. To omit RPATH in the build step, use
1338 CMAKE_SKIP_BUILD_RPATH.
1339
1340 For more information on RPATH handling see the INSTALL_RPATH and
1341 BUILD_RPATH target properties.
1342
1343 CMAKE_SOURCE_DIR
1344 The path to the top level of the source tree.
1345
1346 This is the full path to the top level of the current CMake source
1347 tree. For an in-source build, this would be the same as
1348 CMAKE_BINARY_DIR.
1349
1350 When run in cmake -P script mode, CMake sets the variables
1351 CMAKE_BINARY_DIR, CMAKE_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
1352 CMAKE_CURRENT_SOURCE_DIR to the current working directory.
1353
1354 CMAKE_STATIC_LIBRARY_PREFIX
1355 The prefix for static libraries that you link to.
1356
1357 The prefix to use for the name of a static library, lib on UNIX.
1358
1359 CMAKE_STATIC_LIBRARY_PREFIX_<LANG> overrides this for language <LANG>.
1360
1361 CMAKE_STATIC_LIBRARY_SUFFIX
1362 The suffix for static libraries that you link to.
1363
1364 The suffix to use for the end of a static library filename, .lib on
1365 Windows.
1366
1367 CMAKE_STATIC_LIBRARY_SUFFIX_<LANG> overrides this for language <LANG>.
1368
1369 CMAKE_Swift_MODULE_DIRECTORY
1370 New in version 3.15.
1371
1372
1373 Swift module output directory.
1374
1375 This variable is used to initialize the Swift_MODULE_DIRECTORY property
1376 on all the targets. See the target property for additional informa‐
1377 tion.
1378
1379 CMAKE_Swift_NUM_THREADS
1380 New in version 3.15.1.
1381
1382
1383 Number of threads for parallel compilation for Swift targets.
1384
1385 This variable controls the number of parallel jobs that the swift
1386 driver creates for building targets. If not specified, it will default
1387 to the number of logical CPUs on the host.
1388
1389 CMAKE_TOOLCHAIN_FILE
1390 Path to toolchain file supplied to cmake(1).
1391
1392 This variable is specified on the command line when cross-compiling
1393 with CMake. It is the path to a file which is read early in the CMake
1394 run and which specifies locations for compilers and toolchain utili‐
1395 ties, and other target platform and compiler related information.
1396
1397 Relative paths are allowed and are interpreted first as relative to the
1398 build directory, and if not found, relative to the source directory.
1399
1400 This is initialized by the CMAKE_TOOLCHAIN_FILE environment variable if
1401 it is set when a new build tree is first created.
1402
1403 See the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable for setting other
1404 things not directly related to the toolchain.
1405
1406 CMAKE_TWEAK_VERSION
1407 Defined to 0 for compatibility with code written for older CMake ver‐
1408 sions that may have defined higher values.
1409
1410 NOTE:
1411 In CMake versions 2.8.2 through 2.8.12, this variable holds the
1412 fourth version number component of the CMAKE_VERSION variable.
1413
1414 CMAKE_VERBOSE_MAKEFILE
1415 Enable verbose output from Makefile builds.
1416
1417 This variable is a cache entry initialized (to FALSE) by the project()
1418 command. Users may enable the option in their local build tree to get
1419 more verbose output from Makefile builds and show each command line as
1420 it is launched.
1421
1422 CMAKE_VERSION
1423 The CMake version string as three non-negative integer components sepa‐
1424 rated by . and possibly followed by - and other information. The first
1425 two components represent the feature level and the third component rep‐
1426 resents either a bug-fix level or development date.
1427
1428 Release versions and release candidate versions of CMake use the for‐
1429 mat:
1430
1431 <major>.<minor>.<patch>[-rc<n>]
1432
1433 where the <patch> component is less than 20000000. Development ver‐
1434 sions of CMake use the format:
1435
1436 <major>.<minor>.<date>[-<id>]
1437
1438 where the <date> component is of format CCYYMMDD and <id> may contain
1439 arbitrary text. This represents development as of a particular date
1440 following the <major>.<minor> feature release.
1441
1442 Individual component values are also available in variables:
1443
1444 • CMAKE_MAJOR_VERSION
1445
1446 • CMAKE_MINOR_VERSION
1447
1448 • CMAKE_PATCH_VERSION
1449
1450 • CMAKE_TWEAK_VERSION
1451
1452 Use the if() command VERSION_LESS, VERSION_GREATER, VERSION_EQUAL, VER‐
1453 SION_LESS_EQUAL, or VERSION_GREATER_EQUAL operators to compare version
1454 string values against CMAKE_VERSION using a component-wise test. Ver‐
1455 sion component values may be 10 or larger so do not attempt to compare
1456 version strings as floating-point numbers.
1457
1458 NOTE:
1459 CMake versions 2.8.2 through 2.8.12 used three components for the
1460 feature level. Release versions represented the bug-fix level in a
1461 fourth component, i.e. <major>.<minor>.<patch>[.<tweak>][-rc<n>].
1462 Development versions represented the development date in the fourth
1463 component, i.e. <major>.<minor>.<patch>.<date>[-<id>].
1464
1465 CMake versions prior to 2.8.2 used three components for the feature
1466 level and had no bug-fix component. Release versions used an
1467 even-valued second component, i.e. <major>.<even-mi‐
1468 nor>.<patch>[-rc<n>]. Development versions used an odd-valued sec‐
1469 ond component with the development date as the third component, i.e.
1470 <major>.<odd-minor>.<date>.
1471
1472 The CMAKE_VERSION variable is defined by CMake 2.6.3 and higher.
1473 Earlier versions defined only the individual component variables.
1474
1475 CMAKE_VS_DEVENV_COMMAND
1476 The generators for Visual Studio 9 2008 and above set this variable to
1477 the devenv.com command installed with the corresponding Visual Studio
1478 version. Note that this variable may be empty on Visual Studio Express
1479 editions because they do not provide this tool.
1480
1481 This variable is not defined by other generators even if devenv.com is
1482 installed on the computer.
1483
1484 The CMAKE_VS_MSBUILD_COMMAND is also provided for Visual Studio 11 2012
1485 and above. See also the CMAKE_MAKE_PROGRAM variable.
1486
1487 CMAKE_VS_MSBUILD_COMMAND
1488 The generators for Visual Studio 11 2012 and above set this variable to
1489 the MSBuild.exe command installed with the corresponding Visual Studio
1490 version.
1491
1492 This variable is not defined by other generators even if MSBuild.exe is
1493 installed on the computer.
1494
1495 The CMAKE_VS_DEVENV_COMMAND is also provided for the non-Express edi‐
1496 tions of Visual Studio. See also the CMAKE_MAKE_PROGRAM variable.
1497
1498 CMAKE_VS_NsightTegra_VERSION
1499 New in version 3.1.
1500
1501
1502 When using a Visual Studio generator with the CMAKE_SYSTEM_NAME vari‐
1503 able set to Android, this variable contains the version number of the
1504 installed NVIDIA Nsight Tegra Visual Studio Edition.
1505
1506 CMAKE_VS_NUGET_PACKAGE_RESTORE
1507 New in version 3.23.
1508
1509
1510 When using a Visual Studio generator, this cache variable controls if
1511 msbuild should automatically attempt to restore NuGet packages prior to
1512 a build. NuGet packages can be defined using the VS_PACKAGE_REFERENCES
1513 property on a target. If no package references are defined, this set‐
1514 ting will do nothing.
1515
1516 The command line option --resolve-package-references can be used alter‐
1517 natively to control the resolve behavior globally. This option will
1518 take precedence over the cache variable.
1519
1520 Targets that use the DOTNET_SDK are required to run a restore before
1521 building. Disabling this option may cause the build to fail in such
1522 projects.
1523
1524 This setting is stored as a cache entry. Default value is ON.
1525
1526 See also the VS_PACKAGE_REFERENCES property.
1527
1528 CMAKE_VS_PLATFORM_NAME
1529 New in version 3.1.
1530
1531
1532 Visual Studio target platform name used by the current generator.
1533
1534 VS 8 and above allow project files to specify a target platform. CMake
1535 provides the name of the chosen platform in this variable. See the
1536 CMAKE_GENERATOR_PLATFORM variable for details.
1537
1538 See also the CMAKE_VS_PLATFORM_NAME_DEFAULT variable.
1539
1540 CMAKE_VS_PLATFORM_NAME_DEFAULT
1541 New in version 3.14.3.
1542
1543
1544 Default for the Visual Studio target platform name for the current gen‐
1545 erator without considering the value of the CMAKE_GENERATOR_PLATFORM
1546 variable. For Visual Studio Generators for VS 2017 and below this is
1547 always Win32. For VS 2019 and above this is based on the host plat‐
1548 form.
1549
1550 See also the CMAKE_VS_PLATFORM_NAME variable.
1551
1552 CMAKE_VS_PLATFORM_TOOLSET
1553 Visual Studio Platform Toolset name.
1554
1555 VS 10 and above use MSBuild under the hood and support multiple com‐
1556 piler toolchains. CMake may specify a toolset explicitly, such as v110
1557 for VS 11 or Windows7.1SDK for 64-bit support in VS 10 Express. CMake
1558 provides the name of the chosen toolset in this variable.
1559
1560 See the CMAKE_GENERATOR_TOOLSET variable for details.
1561
1562 CMAKE_VS_PLATFORM_TOOLSET_CUDA
1563 New in version 3.9.
1564
1565
1566 NVIDIA CUDA Toolkit version whose Visual Studio toolset to use.
1567
1568 The Visual Studio Generators for VS 2010 and above support using a CUDA
1569 toolset provided by a CUDA Toolkit. The toolset version number may be
1570 specified by a field in CMAKE_GENERATOR_TOOLSET of the form cuda=8.0.
1571 Or it is automatically detected if a path to a standalone CUDA direc‐
1572 tory is specified in the form cuda=C:\path\to\cuda. If none is speci‐
1573 fied CMake will choose a default version. CMake provides the selected
1574 CUDA toolset version in this variable. The value may be empty if no
1575 CUDA Toolkit with Visual Studio integration is installed.
1576
1577 CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
1578 New in version 3.16.
1579
1580
1581 Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer).
1582
1583 The Visual Studio Generators for VS 2010 and above support using a
1584 standalone (non-installed) NVIDIA CUDA toolkit. The path may be speci‐
1585 fied by a field in CMAKE_GENERATOR_TOOLSET of the form
1586 cuda=C:\path\to\cuda. The given directory must at least contain the
1587 nvcc compiler in path .\bin and must provide Visual Studio integration
1588 files in path .\extras\visual_studio_integration\ MSBuildExtensions\.
1589 One can create a standalone CUDA toolkit directory by either opening a
1590 installer with 7zip or copying the files that are extracted by the run‐
1591 ning installer. The value may be empty if no path to a standalone CUDA
1592 Toolkit was specified.
1593
1594 CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
1595 New in version 3.8.
1596
1597
1598 Visual Studio preferred tool architecture.
1599
1600 The Visual Studio Generators for VS 2013 and above support using either
1601 the 32-bit or 64-bit host toolchains by specifying a host=x86 or
1602 host=x64 value in the CMAKE_GENERATOR_TOOLSET option. CMake provides
1603 the selected toolchain architecture preference in this variable (x86,
1604 x64, ARM64 or empty).
1605
1606 CMAKE_VS_PLATFORM_TOOLSET_VERSION
1607 New in version 3.12.
1608
1609
1610 Visual Studio Platform Toolset version.
1611
1612 The Visual Studio Generators for VS 2017 and above allow to select mi‐
1613 nor versions of the same toolset. The toolset version number may be
1614 specified by a field in CMAKE_GENERATOR_TOOLSET of the form ver‐
1615 sion=14.11. If none is specified CMake will choose a default toolset.
1616 The value may be empty if no minor version was selected and the default
1617 is used.
1618
1619 If the value is not empty, it is the version number that MSBuild uses
1620 in its Microsoft.VCToolsVersion.*.props file names.
1621
1622 New in version 3.19.7: VS 16.9's toolset may also be specified as
1623 14.28.16.9 because VS 16.10 uses the file name Microsoft.VCToolsVer‐
1624 sion.14.28.16.9.props.
1625
1626
1627 Three-Component MSVC Toolset Versions
1628 New in version 3.19.7.
1629
1630
1631 The version= field may be given a three-component toolset version such
1632 as 14.28.29910, and CMake will convert it to the name used by MSBuild
1633 Microsoft.VCToolsVersion.*.props files. This is useful to distinguish
1634 between VS 16.8's 14.28.29333 toolset and VS 16.9's 14.28.29910
1635 toolset. It also matches vcvarsall's -vcvars_ver= behavior.
1636
1637 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
1638 New in version 3.22.
1639
1640
1641 Visual Studio target framework identifier.
1642
1643 In some cases, the Visual Studio Generators may use an explicit value
1644 for the MSBuild TargetFrameworkIdentifier setting in .csproj files.
1645 CMake provides the chosen value in this variable.
1646
1647 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1648 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1649
1650 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
1651 New in version 3.22.
1652
1653
1654 Visual Studio target framework targets version.
1655
1656 In some cases, the Visual Studio Generators may use an explicit value
1657 for the MSBuild TargetFrameworkTargetsVersion setting in .csproj files.
1658 CMake provides the chosen value in this variable.
1659
1660 See also CMAKE_VS_TARGET_FRAMEWORK_VERSION and
1661 CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.
1662
1663 CMAKE_VS_TARGET_FRAMEWORK_VERSION
1664 New in version 3.22.
1665
1666
1667 Visual Studio target framework version.
1668
1669 In some cases, the Visual Studio Generators may use an explicit value
1670 for the MSBuild TargetFrameworkVersion setting in .csproj files. CMake
1671 provides the chosen value in this variable.
1672
1673 See the CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION variable and
1674 DOTNET_TARGET_FRAMEWORK_VERSION target property to specify custom Tar‐
1675 getFrameworkVersion values for project targets.
1676
1677 See also CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER and
1678 CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.
1679
1680 CMAKE_VS_VERSION_BUILD_NUMBER
1681 New in version 3.26.
1682
1683
1684 Visual Studio version.
1685
1686 Visual Studio Generators for VS 2017 and above set this variable to the
1687 Visual Studio version build number in the format <major>.<mi‐
1688 nor>.<date>.<build>.
1689
1690 The components are:
1691
1692 <major>.<minor>
1693 The VS major and minor version numbers. These are the same as the
1694 release version numbers.
1695
1696 <date>
1697 A build date in the format MMMDD, where MMM is a month index since
1698 an epoch used by Microsoft, and DD is a day in that month.
1699
1700 <build>
1701 A build index on the day represented by <date>.
1702
1703 The build number is reported by vswhere as installationVersion. For
1704 example, VS 16.11.10 has build number 16.11.32126.315.
1705
1706 See also the CMAKE_GENERATOR_INSTANCE variable.
1707
1708 CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
1709 New in version 3.27.
1710
1711
1712 Tell Visual Studio Generators to use the given Windows Target Platform
1713 Minimum Version.
1714
1715 This variable is used to initialize the
1716 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION property on all targets when
1717 they are created. See that target property for additional information.
1718
1719 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
1720 New in version 3.4.
1721
1722
1723 Visual Studio Windows Target Platform Version.
1724
1725 When targeting Windows 10 and above, Visual Studio Generators for VS
1726 2015 and above support specification of a Windows SDK version:
1727
1728 • If CMAKE_GENERATOR_PLATFORM specifies a version= field, as documented
1729 by Visual Studio Platform Selection, that SDK version is selected.
1730
1731 • Otherwise, if the WindowsSDKVersion environment variable is set to an
1732 available SDK version, that version is selected. This is intended
1733 for use in environments established by vcvarsall.bat or similar
1734 scripts.
1735
1736 New in version 3.27: This is enabled by policy CMP0149.
1737
1738
1739 • Otherwise, if CMAKE_SYSTEM_VERSION is set to an available SDK ver‐
1740 sion, that version is selected.
1741
1742 Changed in version 3.27: This is disabled by policy CMP0149.
1743
1744
1745 • Otherwise, CMake uses the latest Windows SDK version available.
1746
1747 The chosen Windows target version number is provided in CMAKE_VS_WIN‐
1748 DOWS_TARGET_PLATFORM_VERSION. If no Windows 10 SDK is available this
1749 value will be empty.
1750
1751 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to an ab‐
1752 solute path to tell CMake to look for Windows 10 SDKs in a custom loca‐
1753 tion. The specified directory is expected to contain Include/10.0.*
1754 directories.
1755
1756 See also CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.
1757
1758 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
1759 New in version 3.19.
1760
1761
1762 Override the Windows 10 SDK Maximum Version for VS 2015 and beyond.
1763
1764 The CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM variable may be
1765 set to a false value (e.g. OFF, FALSE, or 0) or the SDK version to use
1766 as the maximum (e.g. 10.0.14393.0). If unset, the default depends on
1767 which version of Visual Studio is targeted by the current generator.
1768
1769 This can be used to exclude Windows SDK versions from consideration for
1770 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.
1771
1772 CMAKE_XCODE_BUILD_SYSTEM
1773 New in version 3.19.
1774
1775
1776 Xcode build system selection.
1777
1778 The Xcode generator defines this variable to indicate which variant of
1779 the Xcode build system will be used. The value is the version of Xcode
1780 in which the corresponding build system first became mature enough for
1781 use by CMake. The possible values are:
1782
1783 1 The original Xcode build system. This is the default when using
1784 Xcode 11.x or below.
1785
1786 12 The Xcode "new build system" introduced by Xcode 10. It became
1787 mature enough for use by CMake in Xcode 12. This is the default
1788 when using Xcode 12.x or above.
1789
1790 The CMAKE_XCODE_BUILD_SYSTEM variable is informational and should not
1791 be modified by project code. See the Toolset and Build System Selec‐
1792 tion documentation section to select the Xcode build system.
1793
1794 CMAKE_XCODE_PLATFORM_TOOLSET
1795 Xcode compiler selection.
1796
1797 Xcode supports selection of a compiler from one of the installed
1798 toolsets. CMake provides the name of the chosen toolset in this vari‐
1799 able, if any is explicitly selected (e.g. via the cmake -T option).
1800
1801 <PROJECT-NAME>_BINARY_DIR
1802 Top level binary directory for the named project.
1803
1804 A variable is created with the name used in the project() command, and
1805 is the binary directory for the project. This can be useful when
1806 add_subdirectory() is used to connect several projects.
1807
1808 <PROJECT-NAME>_DESCRIPTION
1809 New in version 3.12.
1810
1811
1812 Value given to the DESCRIPTION option of the most recent call to the
1813 project() command with project name <PROJECT-NAME>, if any.
1814
1815 <PROJECT-NAME>_HOMEPAGE_URL
1816 New in version 3.12.
1817
1818
1819 Value given to the HOMEPAGE_URL option of the most recent call to the
1820 project() command with project name <PROJECT-NAME>, if any.
1821
1822 <PROJECT-NAME>_IS_TOP_LEVEL
1823 New in version 3.21.
1824
1825
1826 A boolean variable indicating whether the named project was called in a
1827 top level CMakeLists.txt file.
1828
1829 To obtain the value from the most recent call to project() in the cur‐
1830 rent directory scope or above, see the PROJECT_IS_TOP_LEVEL variable.
1831
1832 The variable value will be true in:
1833
1834 • the top-level directory of the project
1835
1836 • the top-level directory of an external project added by
1837 ExternalProject
1838
1839 • a directory added by add_subdirectory() that does not also contain a
1840 project() call
1841
1842 • a directory added by FetchContent_MakeAvailable(), if the fetched
1843 content does not contain a project() call
1844
1845 The variable value will be false in:
1846
1847 • a directory added by add_subdirectory() that also contains a
1848 project() call
1849
1850 • a directory added by FetchContent_MakeAvailable(), if the fetched
1851 content contains a project() call
1852
1853 <PROJECT-NAME>_SOURCE_DIR
1854 Top level source directory for the named project.
1855
1856 A variable is created with the name used in the project() command, and
1857 is the source directory for the project. This can be useful when
1858 add_subdirectory() is used to connect several projects.
1859
1860 <PROJECT-NAME>_VERSION
1861 Value given to the VERSION option of the most recent call to the
1862 project() command with project name <PROJECT-NAME>, if any.
1863
1864 See also the component-wise version variables
1865 <PROJECT-NAME>_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MINOR,
1866 <PROJECT-NAME>_VERSION_PATCH, and <PROJECT-NAME>_VERSION_TWEAK.
1867
1868 <PROJECT-NAME>_VERSION_MAJOR
1869 First version number component of the <PROJECT-NAME>_VERSION variable
1870 as set by the project() command.
1871
1872 <PROJECT-NAME>_VERSION_MINOR
1873 Second version number component of the <PROJECT-NAME>_VERSION variable
1874 as set by the project() command.
1875
1876 <PROJECT-NAME>_VERSION_PATCH
1877 Third version number component of the <PROJECT-NAME>_VERSION variable
1878 as set by the project() command.
1879
1880 <PROJECT-NAME>_VERSION_TWEAK
1881 Fourth version number component of the <PROJECT-NAME>_VERSION variable
1882 as set by the project() command.
1883
1884 PROJECT_BINARY_DIR
1885 Full path to build directory for project.
1886
1887 This is the binary directory of the most recent project() command.
1888
1889 PROJECT_DESCRIPTION
1890 New in version 3.9.
1891
1892
1893 Short project description given to the project command.
1894
1895 This is the description given to the most recently called project()
1896 command in the current directory scope or above. To obtain the de‐
1897 scription of the top level project, see the CMAKE_PROJECT_DESCRIPTION
1898 variable.
1899
1900 PROJECT_HOMEPAGE_URL
1901 New in version 3.12.
1902
1903
1904 The homepage URL of the project.
1905
1906 This is the homepage URL given to the most recently called project()
1907 command in the current directory scope or above. To obtain the home‐
1908 page URL of the top level project, see the CMAKE_PROJECT_HOMEPAGE_URL
1909 variable.
1910
1911 PROJECT_IS_TOP_LEVEL
1912 New in version 3.21.
1913
1914
1915 A boolean variable indicating whether the most recently called
1916 project() command in the current scope or above was in the top level
1917 CMakeLists.txt file.
1918
1919 Some modules should only be included as part of the top level CMake‐
1920 Lists.txt file to not cause unintended side effects in the build tree,
1921 and this variable can be used to conditionally execute such code. For
1922 example, consider the CTest module, which creates targets and options:
1923
1924 project(MyProject)
1925 ...
1926 if(PROJECT_IS_TOP_LEVEL)
1927 include(CTest)
1928 endif()
1929
1930 The variable value will be true in:
1931
1932 • the top-level directory of the project
1933
1934 • the top-level directory of an external project added by
1935 ExternalProject
1936
1937 • a directory added by add_subdirectory() that does not also contain a
1938 project() call
1939
1940 • a directory added by FetchContent_MakeAvailable(), if the fetched
1941 content does not contain a project() call
1942
1943 The variable value will be false in:
1944
1945 • a directory added by add_subdirectory() that also contains a
1946 project() call
1947
1948 • a directory added by FetchContent_MakeAvailable(), if the fetched
1949 content contains a project() call
1950
1951 PROJECT_NAME
1952 Name of the project given to the project command.
1953
1954 This is the name given to the most recently called project() command in
1955 the current directory scope or above. To obtain the name of the top
1956 level project, see the CMAKE_PROJECT_NAME variable.
1957
1958 PROJECT_SOURCE_DIR
1959 This is the source directory of the last call to the project() command
1960 made in the current directory scope or one of its parents. Note, it is
1961 not affected by calls to project() made within a child directory scope
1962 (i.e. from within a call to add_subdirectory() from the current scope).
1963
1964 PROJECT_VERSION
1965 Value given to the VERSION option of the most recent call to the
1966 project() command, if any.
1967
1968 See also the component-wise version variables PROJECT_VERSION_MAJOR,
1969 PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH, and
1970 PROJECT_VERSION_TWEAK.
1971
1972 PROJECT_VERSION_MAJOR
1973 First version number component of the PROJECT_VERSION variable as set
1974 by the project() command.
1975
1976 PROJECT_VERSION_MINOR
1977 Second version number component of the PROJECT_VERSION variable as set
1978 by the project() command.
1979
1980 PROJECT_VERSION_PATCH
1981 Third version number component of the PROJECT_VERSION variable as set
1982 by the project() command.
1983
1984 PROJECT_VERSION_TWEAK
1985 Fourth version number component of the PROJECT_VERSION variable as set
1986 by the project() command.
1987
1989 BUILD_SHARED_LIBS
1990 Global flag to cause add_library() to create shared libraries if on.
1991
1992 If present and true, this will cause all libraries to be built shared
1993 unless the library was explicitly added as a static library. This
1994 variable is often added to projects as an option() so that each user of
1995 a project can decide if they want to build the project using shared or
1996 static libraries.
1997
1998 CMAKE_ABSOLUTE_DESTINATION_FILES
1999 List of files which have been installed using an ABSOLUTE DESTINATION
2000 path.
2001
2002 This variable is defined by CMake-generated cmake_install.cmake
2003 scripts. It can be used (read-only) by programs or scripts that source
2004 those install scripts. This is used by some CPack generators (e.g.
2005 RPM).
2006
2007 CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
2008 New in version 3.27.
2009
2010
2011 Whether to enable the DEPENDS_EXPLICIT_ONLY option by default in
2012 add_custom_command().
2013
2014 This variable affects the default behavior of the add_custom_command()
2015 command. Setting this variable to ON is equivalent to using the DE‐
2016 PENDS_EXPLICIT_ONLY option in all uses of that command.
2017
2018 See also CMAKE_OPTIMIZE_DEPENDENCIES.
2019
2020 CMAKE_APPBUNDLE_PATH
2021 Semicolon-separated list of directories specifying a search path for
2022 macOS application bundles used by the find_program(), and
2023 find_package() commands.
2024
2025 There is also an environment variable CMAKE_APPBUNDLE_PATH, which is
2026 used as an additional list of search directories.
2027
2028 CMAKE_AUTOMOC_RELAXED_MODE
2029 Deprecated since version 3.15.
2030
2031
2032 Switch between strict and relaxed automoc mode.
2033
2034 By default, AUTOMOC behaves exactly as described in the documentation
2035 of the AUTOMOC target property. When set to TRUE, it accepts more in‐
2036 put and tries to find the correct input file for moc even if it differs
2037 from the documented behavior. In this mode it e.g. also checks
2038 whether a header file is intended to be processed by moc when a
2039 "foo.moc" file has been included.
2040
2041 Relaxed mode has to be enabled for KDE4 compatibility.
2042
2043 CMAKE_BACKWARDS_COMPATIBILITY
2044 Deprecated. See CMake Policy CMP0001 documentation.
2045
2046 CMAKE_BUILD_TYPE
2047 Specifies the build type on single-configuration generators (e.g.
2048 Makefile Generators or Ninja). Typical values include Debug, Release,
2049 RelWithDebInfo and MinSizeRel, but custom build types can also be de‐
2050 fined.
2051
2052 This variable is initialized by the first project() or
2053 enable_language() command called in a project when a new build tree is
2054 first created. If the CMAKE_BUILD_TYPE environment variable is set,
2055 its value is used. Otherwise, a toolchain-specific default is chosen
2056 when a language is enabled. The default value is often an empty
2057 string, but this is usually not desirable and one of the other standard
2058 build types is usually more appropriate.
2059
2060 Depending on the situation, the value of this variable may be treated
2061 case-sensitively or case-insensitively. See Build Configurations for
2062 discussion of this and other related topics.
2063
2064 For multi-config generators, see CMAKE_CONFIGURATION_TYPES.
2065
2066 CMAKE_CLANG_VFS_OVERLAY
2067 New in version 3.19.
2068
2069
2070 When cross compiling for windows with clang-cl, this variable can be an
2071 absolute path pointing to a clang virtual file system yaml file, which
2072 will enable clang-cl to resolve windows header names on a case sensi‐
2073 tive file system.
2074
2075 CMAKE_CODEBLOCKS_COMPILER_ID
2076 New in version 3.11.
2077
2078
2079 Change the compiler id in the generated CodeBlocks project files.
2080
2081 CodeBlocks uses its own compiler id string which differs from
2082 CMAKE_<LANG>_COMPILER_ID. If this variable is left empty, CMake tries
2083 to recognize the CodeBlocks compiler id automatically. Otherwise the
2084 specified string is used in the CodeBlocks project file. See the Code‐
2085 Blocks documentation for valid compiler id strings.
2086
2087 Other IDEs like QtCreator that also use the CodeBlocks generator may
2088 ignore this setting.
2089
2090 CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
2091 New in version 3.10.
2092
2093
2094 Change the way the CodeBlocks generator creates project files.
2095
2096 If this variable evaluates to ON the generator excludes from the
2097 project file any files that are located outside the project root.
2098
2099 CMAKE_CODELITE_USE_TARGETS
2100 New in version 3.7.
2101
2102
2103 Change the way the CodeLite generator creates projectfiles.
2104
2105 If this variable evaluates to ON at the end of the top-level CMake‐
2106 Lists.txt file, the generator creates projectfiles based on targets
2107 rather than projects.
2108
2109 CMAKE_COLOR_DIAGNOSTICS
2110 New in version 3.24.
2111
2112
2113 Enable color diagnostics throughout.
2114
2115 This variable uses three states: ON, OFF and not defined.
2116
2117 When not defined:
2118
2119 • Makefile Generators initialize the CMAKE_COLOR_MAKEFILE variable to
2120 ON. It controls color buildsystem messages.
2121
2122 • GNU/Clang compilers are not invoked with any color diagnostics flag.
2123
2124 When ON:
2125
2126 • Makefile Generators produce color buildsystem messages by default.
2127 CMAKE_COLOR_MAKEFILE is not initialized, but may be explicitly set to
2128 OFF to disable color buildsystem messages.
2129
2130 • GNU/Clang compilers are invoked with a flag enabling color diagnos‐
2131 tics (-fcolor-diagnostics).
2132
2133 When OFF:
2134
2135 • Makefile Generators do not produce color buildsystem messages by de‐
2136 fault. CMAKE_COLOR_MAKEFILE is not initialized, but may be explic‐
2137 itly set to ON to enable color buildsystem messages.
2138
2139 • GNU/Clang compilers are invoked with a flag disabling color diagnos‐
2140 tics (-fno-color-diagnostics).
2141
2142 If the CMAKE_COLOR_DIAGNOSTICS environment variable is set, its value
2143 is used. Otherwise, CMAKE_COLOR_DIAGNOSTICS is not defined by default.
2144
2145 CMAKE_COLOR_MAKEFILE
2146 Enables color output when using the Makefile Generators.
2147
2148 When enabled, the generated Makefiles will produce colored output. De‐
2149 fault is ON.
2150
2151 CMAKE_CONFIGURATION_TYPES
2152 Specifies the available build types (configurations) on multi-config
2153 generators (e.g. Visual Studio, Xcode, or Ninja Multi-Config) as a
2154 semicolon-separated list. Typical entries include Debug, Release, Rel‐
2155 WithDebInfo and MinSizeRel, but custom build types can also be defined.
2156
2157 This variable is initialized by the first project() or
2158 enable_language() command called in a project when a new build tree is
2159 first created. If the CMAKE_CONFIGURATION_TYPES environment variable
2160 is set, its value is used. Otherwise, the default value is genera‐
2161 tor-specific.
2162
2163 Depending on the situation, the values in this variable may be treated
2164 case-sensitively or case-insensitively. See Build Configurations for
2165 discussion of this and other related topics.
2166
2167 For single-config generators, see CMAKE_BUILD_TYPE.
2168
2169 CMAKE_DEPENDS_IN_PROJECT_ONLY
2170 New in version 3.6.
2171
2172
2173 When set to TRUE in a directory, the build system produced by the
2174 Makefile Generators is set up to only consider dependencies on source
2175 files that appear either in the source or in the binary directories.
2176 Changes to source files outside of these directories will not cause re‐
2177 builds.
2178
2179 This should be used carefully in cases where some source files are
2180 picked up through external headers during the build.
2181
2182 CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
2183 Variable for disabling find_package() calls.
2184
2185 Every non-REQUIRED find_package() call in a project can be disabled by
2186 setting the variable CMAKE_DISABLE_FIND_PACKAGE_<PackageName> to TRUE.
2187 This can be used to build a project without an optional package, al‐
2188 though that package is installed.
2189
2190 This switch should be used during the initial CMake run. Otherwise if
2191 the package has already been found in a previous CMake run, the vari‐
2192 ables which have been stored in the cache will still be there. In that
2193 case it is recommended to remove the cache variables for this package
2194 from the cache using the cache editor or cmake -U.
2195
2196 See also the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable.
2197
2198 CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
2199 New in version 3.6.
2200
2201
2202 This cache variable is used by the Eclipse project generator. See
2203 cmake-generators(7).
2204
2205 The Eclipse project generator generates so-called linked resources e.g.
2206 to the subproject root dirs in the source tree or to the source files
2207 of targets. This can be disabled by setting this variable to FALSE.
2208
2209 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
2210 New in version 3.6.
2211
2212
2213 This cache variable is used by the Eclipse project generator. See
2214 cmake-generators(7).
2215
2216 If this variable is set to TRUE, the Eclipse project generator will
2217 generate an Eclipse project in CMAKE_SOURCE_DIR . This project can then
2218 be used in Eclipse e.g. for the version control functionality.
2219 CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT defaults to FALSE; so nothing is
2220 written into the source directory.
2221
2222 CMAKE_ECLIPSE_MAKE_ARGUMENTS
2223 New in version 3.6.
2224
2225
2226 This cache variable is used by the Eclipse project generator. See
2227 cmake-generators(7).
2228
2229 This variable holds arguments which are used when Eclipse invokes the
2230 make tool. By default it is initialized to hold flags to enable paral‐
2231 lel builds (using -j typically).
2232
2233 CMAKE_ECLIPSE_RESOURCE_ENCODING
2234 New in version 3.16.
2235
2236
2237 This cache variable tells the Eclipse CDT4 project generator to set the
2238 resource encoding to the given value in generated project files. If no
2239 value is given, no encoding will be set.
2240
2241 CMAKE_ECLIPSE_VERSION
2242 New in version 3.6.
2243
2244
2245 This cache variable is used by the Eclipse project generator. See
2246 cmake-generators(7).
2247
2248 When using the Eclipse project generator, CMake tries to find the
2249 Eclipse executable and detect the version of it. Depending on the ver‐
2250 sion it finds, some features are enabled or disabled. If CMake doesn't
2251 find Eclipse, it assumes the oldest supported version, Eclipse Callisto
2252 (3.2).
2253
2254 CMAKE_ERROR_DEPRECATED
2255 Whether to issue errors for deprecated functionality.
2256
2257 If TRUE, use of deprecated functionality will issue fatal errors. If
2258 this variable is not set, CMake behaves as if it were set to FALSE.
2259
2260 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
2261 Ask cmake_install.cmake script to error out as soon as a file with ab‐
2262 solute INSTALL DESTINATION is encountered.
2263
2264 The fatal error is emitted before the installation of the offending
2265 file takes place. This variable is used by CMake-generated cmake_in‐
2266 stall.cmake scripts. If one sets this variable to ON while running the
2267 script, it may get fatal error messages from the script.
2268
2269 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
2270 New in version 3.15.
2271
2272
2273 If this variable is set to STDERR, STDOUT or NONE then commands in
2274 execute_process() calls will be printed to either stderr or stdout or
2275 not at all.
2276
2277 CMAKE_EXPORT_COMPILE_COMMANDS
2278 New in version 3.5.
2279
2280
2281 Enable/Disable output of compile commands during generation.
2282
2283 If enabled, generates a compile_commands.json file containing the exact
2284 compiler calls for all translation units of the project in ma‐
2285 chine-readable form. The format of the JSON file looks like:
2286
2287 [
2288 {
2289 "directory": "/home/user/development/project",
2290 "command": "/usr/bin/c++ ... -c ../foo/foo.cc",
2291 "file": "../foo/foo.cc"
2292 },
2293
2294 ...
2295
2296 {
2297 "directory": "/home/user/development/project",
2298 "command": "/usr/bin/c++ ... -c ../foo/bar.cc",
2299 "file": "../foo/bar.cc"
2300 }
2301 ]
2302
2303 This is initialized by the CMAKE_EXPORT_COMPILE_COMMANDS environment
2304 variable, and initializes the EXPORT_COMPILE_COMMANDS target property
2305 for all targets.
2306
2307 NOTE:
2308 This option is implemented only by Makefile Generators and Ninja
2309 Generators. It is ignored on other generators.
2310
2311 This option currently does not work well in combination with the
2312 UNITY_BUILD target property or the CMAKE_UNITY_BUILD variable.
2313
2314 CMAKE_EXPORT_PACKAGE_REGISTRY
2315 New in version 3.15.
2316
2317
2318 Enables the export(PACKAGE) command when CMP0090 is set to NEW.
2319
2320 The export(PACKAGE) command does nothing by default. In some cases it
2321 is desirable to write to the user package registry, so the CMAKE_EX‐
2322 PORT_PACKAGE_REGISTRY variable may be set to enable it.
2323
2324 If CMP0090 is not set to NEW this variable does nothing, and the
2325 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable controls the behavior in‐
2326 stead.
2327
2328 See also Disabling the Package Registry.
2329
2330 CMAKE_EXPORT_NO_PACKAGE_REGISTRY
2331 New in version 3.1.
2332
2333
2334 Disable the export(PACKAGE) command when CMP0090 is not set to NEW.
2335
2336 In some cases, for example for packaging and for system wide installa‐
2337 tions, it is not desirable to write the user package registry. If the
2338 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the
2339 export(PACKAGE) command will do nothing.
2340
2341 If CMP0090 is set to NEW this variable does nothing, and the
2342 CMAKE_EXPORT_PACKAGE_REGISTRY variable controls the behavior instead.
2343
2344 See also Disabling the Package Registry.
2345
2346 CMAKE_FIND_APPBUNDLE
2347 New in version 3.4.
2348
2349
2350 This variable affects how find_* commands choose between macOS Applica‐
2351 tion Bundles and unix-style package components.
2352
2353 On Darwin or systems supporting macOS Application Bundles, the
2354 CMAKE_FIND_APPBUNDLE variable can be set to empty or one of the follow‐
2355 ing:
2356
2357 FIRST Try to find application bundles before standard programs. This
2358 is the default on Darwin.
2359
2360 LAST Try to find application bundles after standard programs.
2361
2362 ONLY Only try to find application bundles.
2363
2364 NEVER Never try to find application bundles.
2365
2366 CMAKE_FIND_FRAMEWORK
2367 New in version 3.4.
2368
2369
2370 This variable affects how find_* commands choose between macOS Frame‐
2371 works and unix-style package components.
2372
2373 On Darwin or systems supporting macOS Frameworks, the CMAKE_FIND_FRAME‐
2374 WORK variable can be set to empty or one of the following:
2375
2376 FIRST Try to find frameworks before standard libraries or headers.
2377 This is the default on Darwin.
2378
2379 LAST Try to find frameworks after standard libraries or headers.
2380
2381 ONLY Only try to find frameworks.
2382
2383 NEVER Never try to find frameworks.
2384
2385 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
2386 New in version 3.9.
2387
2388
2389 Specify a <suffix> to tell the find_library() command to search in a
2390 lib<suffix> directory before each lib directory that would normally be
2391 searched.
2392
2393 This overrides the behavior of related global properties:
2394
2395 • FIND_LIBRARY_USE_LIB32_PATHS
2396
2397 • FIND_LIBRARY_USE_LIB64_PATHS
2398
2399 • FIND_LIBRARY_USE_LIBX32_PATHS
2400
2401 CMAKE_FIND_LIBRARY_PREFIXES
2402 Prefixes to prepend when looking for libraries.
2403
2404 This specifies what prefixes to add to library names when the
2405 find_library() command looks for libraries. On UNIX systems this is
2406 typically lib, meaning that when trying to find the foo library it will
2407 look for libfoo.
2408
2409 CMAKE_FIND_LIBRARY_SUFFIXES
2410 Suffixes to append when looking for libraries.
2411
2412 This specifies what suffixes to add to library names when the
2413 find_library() command looks for libraries. On Windows systems this is
2414 typically .lib and, depending on the compiler, .dll.a, .a (e.g. GCC and
2415 Clang), so when it tries to find the foo library, it will look for
2416 [<prefix>]foo.lib and/or [<prefix>]foo[.dll].a, depending on the com‐
2417 piler used and the <prefix> specified in the
2418 CMAKE_FIND_LIBRARY_PREFIXES.
2419
2420 CMAKE_FIND_NO_INSTALL_PREFIX
2421 Exclude the values of the CMAKE_INSTALL_PREFIX and CMAKE_STAGING_PREFIX
2422 variables from CMAKE_SYSTEM_PREFIX_PATH. CMake adds these project-des‐
2423 tination prefixes to CMAKE_SYSTEM_PREFIX_PATH by default in order to
2424 support building a series of dependent packages and installing them
2425 into a common prefix. Set CMAKE_FIND_NO_INSTALL_PREFIX to TRUE to sup‐
2426 press this behavior.
2427
2428 The CMAKE_SYSTEM_PREFIX_PATH is initialized on the first call to a
2429 project() or enable_language() command. Therefore one must set
2430 CMAKE_FIND_NO_INSTALL_PREFIX before this in order to take effect. A
2431 user may set the variable as a cache entry on the command line to
2432 achieve this.
2433
2434 Note that the prefix(es) may still be searched for other reasons, such
2435 as being the same prefix as the CMake installation, or for being a
2436 built-in system prefix.
2437
2438 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
2439 New in version 3.1.
2440
2441
2442 Deprecated since version 3.16: Use the CMAKE_FIND_USE_PACKAGE_REGISTRY
2443 variable instead.
2444
2445
2446 By default this variable is not set. If neither
2447 CMAKE_FIND_USE_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_PACKAGE_REG‐
2448 ISTRY is set, then find_package() will use the User Package Registry
2449 unless the NO_CMAKE_PACKAGE_REGISTRY option is provided.
2450
2451 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY is ignored if
2452 CMAKE_FIND_USE_PACKAGE_REGISTRY is set.
2453
2454 In some cases, for example to locate only system wide installations, it
2455 is not desirable to use the User Package Registry when searching for
2456 packages. If the CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable is
2457 TRUE, all the find_package() commands will skip the User Package Reg‐
2458 istry as if they were called with the NO_CMAKE_PACKAGE_REGISTRY argu‐
2459 ment.
2460
2461 See also Disabling the Package Registry.
2462
2463 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
2464 New in version 3.1.
2465
2466
2467 Deprecated since version 3.16: Use the
2468 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable instead.
2469
2470
2471 By default this variable is not set. If neither
2472 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY nor CMAKE_FIND_PACKAGE_NO_SYS‐
2473 TEM_PACKAGE_REGISTRY is set, then find_package() will use the System
2474 Package Registry unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is
2475 provided.
2476
2477 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY is ignored if
2478 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY is set.
2479
2480 In some cases, it is not desirable to use the System Package Registry
2481 when searching for packages. If the CMAKE_FIND_PACKAGE_NO_SYSTEM_PACK‐
2482 AGE_REGISTRY variable is TRUE, all the find_package() commands will
2483 skip the System Package Registry as if they were called with the
2484 NO_CMAKE_SYSTEM_PACKAGE_REGISTRY argument.
2485
2486 See also Disabling the Package Registry.
2487
2488 CMAKE_FIND_PACKAGE_PREFER_CONFIG
2489 New in version 3.15.
2490
2491
2492 Tell find_package() to try "Config" mode before "Module" mode if no
2493 mode was specified.
2494
2495 The command find_package() operates without an explicit mode when the
2496 reduced signature is used without the MODULE option. In this case, by
2497 default, CMake first tries Module mode by searching for a
2498 Find<pkg>.cmake module. If it fails, CMake then searches for the pack‐
2499 age using Config mode.
2500
2501 Set CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to tell find_package() to
2502 first search using Config mode before falling back to Module mode.
2503
2504 This variable may be useful when a developer has compiled a custom ver‐
2505 sion of a common library and wishes to link it to a dependent project.
2506 If this variable is set to TRUE, it would prevent a dependent project's
2507 call to find_package() from selecting the default library located by
2508 the system's Find<pkg>.cmake module before finding the developer's cus‐
2509 tom built library.
2510
2511 Once this variable is set, it is the responsibility of the exported
2512 <pkg>Config.cmake files to provide the same result variables as the
2513 Find<pkg>.cmake modules so that dependent projects can use them inter‐
2514 changeably.
2515
2516 CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
2517 New in version 3.14.
2518
2519
2520 Set to TRUE to tell find_package() calls to resolve symbolic links in
2521 the value of <PackageName>_DIR.
2522
2523 This is helpful in use cases where the package search path points at a
2524 proxy directory in which symlinks to the real package locations appear.
2525 This is not enabled by default because there are also common use cases
2526 in which the symlinks should be preserved.
2527
2528 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
2529 New in version 3.24.
2530
2531
2532 Setting to TRUE promotes all IMPORTED targets discoverd by
2533 find_package() to a GLOBAL scope.
2534
2535 Setting this to TRUE is akin to specifying GLOBAL as an argument to
2536 find_package(). Default value is OFF.
2537
2538 CMAKE_FIND_PACKAGE_WARN_NO_MODULE
2539 Tell find_package() to warn if called without an explicit mode.
2540
2541 If find_package() is called without an explicit mode option (MODULE,
2542 CONFIG, or NO_MODULE) and no Find<pkg>.cmake module is in
2543 CMAKE_MODULE_PATH then CMake implicitly assumes that the caller intends
2544 to search for a package configuration file. If no package configura‐
2545 tion file is found then the wording of the failure message must account
2546 for both the case that the package is really missing and the case that
2547 the project has a bug and failed to provide the intended Find module.
2548 If instead the caller specifies an explicit mode option then the fail‐
2549 ure message can be more specific.
2550
2551 Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_package() to
2552 warn when it implicitly assumes Config mode. This helps developers en‐
2553 force use of an explicit mode in all calls to find_package() within a
2554 project.
2555
2556 This variable has no effect if CMAKE_FIND_PACKAGE_PREFER_CONFIG is set
2557 to TRUE.
2558
2559 CMAKE_FIND_ROOT_PATH
2560 Semicolon-separated list of root paths to search on the filesystem.
2561
2562 This variable is most useful when cross-compiling. CMake uses the paths
2563 in this list as alternative roots to find filesystem items with
2564 find_package(), find_library() etc.
2565
2566 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
2567 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2568 CMAKE_SYSROOT are used by find_file() and find_path().
2569
2570 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2571 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2572 be ignored and only the host system root will be used. If set to BOTH,
2573 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2574 be searched.
2575
2576 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
2577 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2578 CMAKE_SYSROOT are used by find_library().
2579
2580 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2581 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2582 be ignored and only the host system root will be used. If set to BOTH,
2583 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2584 be searched.
2585
2586 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
2587 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2588 CMAKE_SYSROOT are used by find_package().
2589
2590 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2591 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2592 be ignored and only the host system root will be used. If set to BOTH,
2593 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2594 be searched.
2595
2596 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
2597 This variable controls whether the CMAKE_FIND_ROOT_PATH and
2598 CMAKE_SYSROOT are used by find_program().
2599
2600 If set to ONLY, then only the roots in CMAKE_FIND_ROOT_PATH will be
2601 searched. If set to NEVER, then the roots in CMAKE_FIND_ROOT_PATH will
2602 be ignored and only the host system root will be used. If set to BOTH,
2603 then the host system paths and the paths in CMAKE_FIND_ROOT_PATH will
2604 be searched.
2605
2606 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
2607 New in version 3.16.
2608
2609
2610 Controls the default behavior of the following commands for whether or
2611 not to search paths provided by cmake-specific environment variables:
2612
2613 • find_program()
2614
2615 • find_library()
2616
2617 • find_file()
2618
2619 • find_path()
2620
2621 • find_package()
2622
2623 This is useful in cross-compiling environments.
2624
2625 By default this variable is not set, which is equivalent to it having a
2626 value of TRUE. Explicit options given to the above commands take
2627 precedence over this variable.
2628
2629 See also the CMAKE_FIND_USE_CMAKE_PATH,
2630 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2631 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2632 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2633 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2634 variables.
2635
2636 CMAKE_FIND_USE_CMAKE_PATH
2637 New in version 3.16.
2638
2639
2640 Controls the default behavior of the following commands for whether or
2641 not to search paths provided by cmake-specific cache variables:
2642
2643 • find_program()
2644
2645 • find_library()
2646
2647 • find_file()
2648
2649 • find_path()
2650
2651 • find_package()
2652
2653 This is useful in cross-compiling environments.
2654
2655 By default this variable is not set, which is equivalent to it having a
2656 value of TRUE. Explicit options given to the above commands take
2657 precedence over this variable.
2658
2659 See also the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2660 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2661 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2662 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2663 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2664 variables.
2665
2666 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
2667 New in version 3.16.
2668
2669
2670 Controls the default behavior of the following commands for whether or
2671 not to search paths provided by platform-specific cmake variables:
2672
2673 • find_program()
2674
2675 • find_library()
2676
2677 • find_file()
2678
2679 • find_path()
2680
2681 • find_package()
2682
2683 This is useful in cross-compiling environments.
2684
2685 By default this variable is not set, which is equivalent to it having a
2686 value of TRUE. Explicit options given to the above commands take
2687 precedence over this variable.
2688
2689 See also the CMAKE_FIND_USE_CMAKE_PATH,
2690 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2691 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2692 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2693 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2694 variables.
2695
2696 CMAKE_FIND_USE_INSTALL_PREFIX
2697 New in version 3.24.
2698
2699
2700 Controls the default behavior of the following commands for whether or
2701 not to search the locations in the CMAKE_INSTALL_PREFIX and
2702 CMAKE_STAGING_PREFIX variables.
2703
2704 • find_program()
2705
2706 • find_library()
2707
2708 • find_file()
2709
2710 • find_path()
2711
2712 • find_package()
2713
2714 This is useful in cross-compiling environments.
2715
2716 Due to backwards compatibility with CMAKE_FIND_NO_INSTALL_PREFIX, the
2717 behavior of the find command change based on if this variable exists.
2718
2719 ┌───────────────────┬────────────────────┬────────┐
2720 │CMAKE_FIND_USE_IN‐ │ CMAKE_FIND_NO_IN‐ │ Search │
2721 │STALL_PREFIX │ STALL_PREFIX │ │
2722 ├───────────────────┼────────────────────┼────────┤
2723 │Not Defined │ On │ NO │
2724 ├───────────────────┼────────────────────┼────────┤
2725 │Not Defined │ Off || Not Defined │ YES │
2726 ├───────────────────┼────────────────────┼────────┤
2727 │Off │ On │ NO │
2728 ├───────────────────┼────────────────────┼────────┤
2729 │Off │ Off || Not Defined │ NO │
2730 └───────────────────┴────────────────────┴────────┘
2731
2732
2733 │On │ On │ YES │
2734 ├───────────────────┼────────────────────┼────────┤
2735 │On │ Off || Not Defined │ YES │
2736 └───────────────────┴────────────────────┴────────┘
2737
2738 By default this variable is not defined. Explicit options given to the
2739 above commands take precedence over this variable.
2740
2741 See also the CMAKE_FIND_USE_CMAKE_PATH,
2742 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2743 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2744 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY,
2745 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2746 variables.
2747
2748 CMAKE_FIND_USE_PACKAGE_REGISTRY
2749 New in version 3.16.
2750
2751
2752 Controls the default behavior of the find_package() command for whether
2753 or not to search paths provided by the User Package Registry.
2754
2755 By default this variable is not set and the behavior will fall back to
2756 that determined by the deprecated
2757 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY variable. If that is also not
2758 set, then find_package() will use the User Package Registry unless the
2759 NO_CMAKE_PACKAGE_REGISTRY option is provided.
2760
2761 This variable takes precedence over
2762 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY when both are set.
2763
2764 In some cases, for example to locate only system wide installations, it
2765 is not desirable to use the User Package Registry when searching for
2766 packages. If the CMAKE_FIND_USE_PACKAGE_REGISTRY variable is FALSE,
2767 all the find_package() commands will skip the User Package Registry as
2768 if they were called with the NO_CMAKE_PACKAGE_REGISTRY argument.
2769
2770 See also Disabling the Package Registry and the
2771 CMAKE_FIND_USE_CMAKE_PATH, CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH,
2772 CMAKE_FIND_USE_INSTALL_PREFIX, CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2773 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2774 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2775 CMAKE_FIND_USE_PACKAGE_ROOT_PATH variables.
2776
2777 CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2778 New in version 3.16.
2779
2780
2781 Controls the default behavior of the following commands for whether or
2782 not to search paths provided by <PackageName>_ROOT variables:
2783
2784 • find_program()
2785
2786 • find_library()
2787
2788 • find_file()
2789
2790 • find_path()
2791
2792 • find_package()
2793
2794 By default this variable is not set, which is equivalent to it having a
2795 value of TRUE. Explicit options given to the above commands take
2796 precedence over this variable.
2797
2798 See also the CMAKE_FIND_USE_CMAKE_PATH,
2799 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2800 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2801 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2802 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY, and
2803 CMAKE_FIND_USE_PACKAGE_REGISTRY variables.
2804
2805 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
2806 New in version 3.16.
2807
2808
2809 Controls the default behavior of the following commands for whether or
2810 not to search paths provided by standard system environment variables:
2811
2812 • find_program()
2813
2814 • find_library()
2815
2816 • find_file()
2817
2818 • find_path()
2819
2820 • find_package()
2821
2822 This is useful in cross-compiling environments.
2823
2824 By default this variable is not set, which is equivalent to it having a
2825 value of TRUE. Explicit options given to the above commands take
2826 precedence over this variable.
2827
2828 See also the CMAKE_FIND_USE_CMAKE_PATH,
2829 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2830 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH, CMAKE_FIND_USE_PACKAGE_REGISTRY,
2831 CMAKE_FIND_USE_PACKAGE_ROOT_PATH, and
2832 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variables.
2833
2834 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
2835 New in version 3.16.
2836
2837
2838 Controls searching the System Package Registry by the find_package()
2839 command.
2840
2841 By default this variable is not set and the behavior will fall back to
2842 that determined by the deprecated
2843 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variable. If that is
2844 also not set, then find_package() will use the System Package Registry
2845 unless the NO_CMAKE_SYSTEM_PACKAGE_REGISTRY option is provided.
2846
2847 This variable takes precedence over
2848 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY when both are set.
2849
2850 In some cases, for example to locate only user specific installations,
2851 it is not desirable to use the System Package Registry when searching
2852 for packages. If the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable is
2853 FALSE, all the find_package() commands will skip the System Package
2854 Registry as if they were called with the NO_CMAKE_SYSTEM_PACKAGE_REG‐
2855 ISTRY argument.
2856
2857 See also Disabling the Package Registry.
2858
2859 See also the CMAKE_FIND_USE_CMAKE_PATH,
2860 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH, CMAKE_FIND_USE_INSTALL_PREFIX,
2861 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH,
2862 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH,
2863 CMAKE_FIND_USE_PACKAGE_REGISTRY, and CMAKE_FIND_USE_PACKAGE_ROOT_PATH
2864 variables.
2865
2866 CMAKE_FRAMEWORK_PATH
2867 Semicolon-separated list of directories specifying a search path for
2868 macOS frameworks used by the find_library(), find_package(),
2869 find_path(), and find_file() commands.
2870
2871 There is also an environment variable CMAKE_FRAMEWORK_PATH, which is
2872 used as an additional list of search directories.
2873
2874 CMAKE_IGNORE_PATH
2875 Semicolon-separated list of directories to be ignored by the various
2876 find...() commands.
2877
2878 For find_program(), find_library(), find_file(), and find_path(), any
2879 file found in one of the listed directories will be ignored. The listed
2880 directories do not apply recursively, so any subdirectories to be ig‐
2881 nored must also be explicitly listed. CMAKE_IGNORE_PATH does not af‐
2882 fect the search prefixes used by these four commands. To ignore indi‐
2883 vidual paths under a search prefix (e.g. bin, include, lib, etc.), each
2884 path must be listed in CMAKE_IGNORE_PATH as a full absolute path.
2885 CMAKE_IGNORE_PREFIX_PATH provides a more appropriate way to ignore a
2886 whole search prefix.
2887
2888 find_package() is also affected by CMAKE_IGNORE_PATH, but only for Con‐
2889 fig mode searches. Any <Name>Config.cmake or <name>-config.cmake file
2890 found in one of the specified directories will be ignored. In addition,
2891 any search prefix found in CMAKE_IGNORE_PATH will be skipped for back‐
2892 ward compatibility reasons, but new code should prefer to use
2893 CMAKE_IGNORE_PREFIX_PATH to ignore prefixes instead.
2894
2895 Ignoring search locations can be useful in cross-compiling environments
2896 where some system directories contain incompatible but possibly link‐
2897 able libraries. For example, on cross-compiled cluster environments,
2898 this allows a user to ignore directories containing libraries meant for
2899 the front-end machine.
2900
2901 By default, CMAKE_IGNORE_PATH is empty. It is intended to be set by the
2902 project or the end user.
2903
2904 See also the following variables:
2905
2906 • CMAKE_IGNORE_PREFIX_PATH
2907
2908 • CMAKE_SYSTEM_IGNORE_PATH
2909
2910 • CMAKE_PREFIX_PATH
2911
2912 • CMAKE_LIBRARY_PATH
2913
2914 • CMAKE_INCLUDE_PATH
2915
2916 • CMAKE_PROGRAM_PATH
2917
2918 CMAKE_IGNORE_PREFIX_PATH
2919 New in version 3.23.
2920
2921
2922 Semicolon-separated list of search prefixes to be ignored by the
2923 find_program(), find_library(), find_file(), and find_path() commands.
2924 The prefixes are also ignored by the Config mode of the find_package()
2925 command (Module mode is unaffected). To ignore specific directories
2926 instead, see CMAKE_IGNORE_PATH.
2927
2928 Ignoring search locations can be useful in cross-compiling environments
2929 where some system directories contain incompatible but possibly link‐
2930 able libraries. For example, on cross-compiled cluster environments,
2931 this allows a user to ignore directories containing libraries meant for
2932 the front-end machine.
2933
2934 By default, CMAKE_IGNORE_PREFIX_PATH is empty. It is intended to be set
2935 by the project or the end user.
2936
2937 See also the following variables:
2938
2939 • CMAKE_IGNORE_PATH
2940
2941 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
2942
2943 • CMAKE_PREFIX_PATH
2944
2945 • CMAKE_LIBRARY_PATH
2946
2947 • CMAKE_INCLUDE_PATH
2948
2949 • CMAKE_PROGRAM_PATH
2950
2951 CMAKE_INCLUDE_DIRECTORIES_BEFORE
2952 Whether to append or prepend directories by default in
2953 include_directories().
2954
2955 This variable affects the default behavior of the include_directories()
2956 command. Setting this variable to ON is equivalent to using the BEFORE
2957 option in all uses of that command.
2958
2959 CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
2960 Whether to force prepending of project include directories.
2961
2962 This variable affects the order of include directories generated in
2963 compiler command lines. If set to ON, it causes the CMAKE_SOURCE_DIR
2964 and the CMAKE_BINARY_DIR to appear first.
2965
2966 CMAKE_INCLUDE_PATH
2967 Semicolon-separated list of directories specifying a search path for
2968 the find_file() and find_path() commands. By default it is empty, it
2969 is intended to be set by the project.
2970
2971 There is also an environment variable CMAKE_INCLUDE_PATH, which is used
2972 as an additional list of search directories.
2973
2974 See also CMAKE_SYSTEM_INCLUDE_PATH and CMAKE_PREFIX_PATH.
2975
2976 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
2977 Default component used in install() commands.
2978
2979 If an install() command is used without the COMPONENT argument, these
2980 files will be grouped into a default component. The name of this de‐
2981 fault install component will be taken from this variable. It defaults
2982 to Unspecified.
2983
2984 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2985 New in version 3.11.
2986
2987
2988 Default permissions for directories created implicitly during installa‐
2989 tion of files by install() and file(INSTALL).
2990
2991 If make install is invoked and directories are implicitly created they
2992 get permissions set by CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
2993 variable or platform specific default permissions if the variable is
2994 not set.
2995
2996 Implicitly created directories are created if they are not explicitly
2997 installed by install() command but are needed to install a file on a
2998 certain path. Example of such locations are directories created due to
2999 the setting of CMAKE_INSTALL_PREFIX.
3000
3001 Expected content of the CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
3002 variable is a list of permissions that can be used by install() command
3003 PERMISSIONS section.
3004
3005 Example usage:
3006
3007 set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
3008 OWNER_READ
3009 OWNER_WRITE
3010 OWNER_EXECUTE
3011 GROUP_READ
3012 )
3013
3014 CMAKE_INSTALL_MESSAGE
3015 New in version 3.1.
3016
3017
3018 Specify verbosity of installation script code generated by the
3019 install() command (using the file(INSTALL) command). For paths that
3020 are newly installed or updated, installation may print lines like:
3021
3022 -- Installing: /some/destination/path
3023
3024 For paths that are already up to date, installation may print lines
3025 like:
3026
3027 -- Up-to-date: /some/destination/path
3028
3029 The CMAKE_INSTALL_MESSAGE variable may be set to control which messages
3030 are printed:
3031
3032 ALWAYS Print both Installing and Up-to-date messages.
3033
3034 LAZY Print Installing but not Up-to-date messages.
3035
3036 NEVER Print neither Installing nor Up-to-date messages.
3037
3038 Other values have undefined behavior and may not be diagnosed.
3039
3040 If this variable is not set, the default behavior is ALWAYS.
3041
3042 CMAKE_INSTALL_PREFIX
3043 Install directory used by install().
3044
3045 If make install is invoked or INSTALL is built, this directory is
3046 prepended onto all install directories. This variable defaults to
3047 /usr/local on UNIX and c:/Program Files/${PROJECT_NAME} on Windows.
3048 See CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT for how a project might
3049 choose its own default.
3050
3051 On UNIX one can use the DESTDIR mechanism in order to relocate the
3052 whole installation to a staging area. See the DESTDIR environment
3053 variable for more information.
3054
3055 The installation prefix is also added to CMAKE_SYSTEM_PREFIX_PATH so
3056 that find_package(), find_program(), find_library(), find_path(), and
3057 find_file() will search the prefix for other software. This behavior
3058 can be disabled by setting the CMAKE_FIND_NO_INSTALL_PREFIX to TRUE be‐
3059 fore the first project() invocation.
3060
3061 NOTE:
3062 Use the GNUInstallDirs module to provide GNU-style options for the
3063 layout of directories within the installation.
3064
3065 The CMAKE_INSTALL_PREFIX may be defined when configuring a build tree
3066 to set its installation prefix. Or, when using the cmake(1) com‐
3067 mand-line tool's --install mode, one may specify a different prefix us‐
3068 ing the --prefix option:
3069
3070 cmake --install . --prefix /my/install/prefix
3071
3072 CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
3073 New in version 3.7.1.
3074
3075
3076 CMake sets this variable to a TRUE value when the CMAKE_INSTALL_PREFIX
3077 has just been initialized to its default value, typically on the first
3078 run of CMake within a new build tree. This can be used by project code
3079 to change the default without overriding a user-provided value:
3080
3081 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
3082 set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
3083 endif()
3084
3085 CMAKE_KATE_FILES_MODE
3086 New in version 3.27.
3087
3088
3089 This cache variable is used by the Kate project generator and controls
3090 to what mode the files entry in the project file will be set. See
3091 cmake-generators(7).
3092
3093 Possible values are AUTO, SVN, GIT, HG, FOSSIL and LIST.
3094
3095 When set to LIST, CMake will put the list of source files known to
3096 CMake in the project file. When set to SVN, GIT, HG or FOSSIL, CMake
3097 will set the generated project accordingly to Subversion, git, Mercu‐
3098 rial or Fossil, and Kate will then use the respective command line tool
3099 to retrieve the list of files in the project. When unset or set to
3100 AUTO, CMake will try to detect whether the source directory is part of
3101 a git or svn checkout or not, and put the respective entry into the
3102 project file.
3103
3104 CMAKE_KATE_MAKE_ARGUMENTS
3105 New in version 3.0.
3106
3107
3108 This cache variable is used by the Kate project generator. See
3109 cmake-generators(7).
3110
3111 This variable holds arguments which are used when Kate invokes the make
3112 tool. By default it is initialized to hold flags to enable parallel
3113 builds (using -j typically).
3114
3115 CMAKE_LIBRARY_PATH
3116 Semicolon-separated list of directories specifying a search path for
3117 the find_library() command. By default it is empty, it is intended to
3118 be set by the project.
3119
3120 There is also an environment variable CMAKE_LIBRARY_PATH, which is used
3121 as an additional list of search directories.
3122
3123 See also CMAKE_SYSTEM_LIBRARY_PATH and CMAKE_PREFIX_PATH.
3124
3125 CMAKE_LINK_DIRECTORIES_BEFORE
3126 New in version 3.13.
3127
3128
3129 Whether to append or prepend directories by default in
3130 link_directories().
3131
3132 This variable affects the default behavior of the link_directories()
3133 command. Setting this variable to ON is equivalent to using the BEFORE
3134 option in all uses of that command.
3135
3136 CMAKE_LINK_LIBRARIES_ONLY_TARGETS
3137 New in version 3.23.
3138
3139
3140 Set this variable to initialize the LINK_LIBRARIES_ONLY_TARGETS prop‐
3141 erty of non-imported targets when they are created. Setting it to true
3142 enables an additional check that all items named by
3143 target_link_libraries() that can be target names are actually names of
3144 existing targets. See the target property documentation for details.
3145
3146 CMAKE_MAXIMUM_RECURSION_DEPTH
3147 New in version 3.14.
3148
3149
3150 Maximum recursion depth for CMake scripts. It is intended to be set on
3151 the command line with -DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>, or within
3152 CMakeLists.txt by projects that require a large recursion depth.
3153 Projects that set this variable should provide the user with a way to
3154 override it. For example:
3155
3156 # About to perform deeply recursive actions
3157 if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
3158 set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
3159 endif()
3160
3161 If it is not set, or is set to a non-integer value, a sensible default
3162 limit is used. If the recursion limit is reached, the script terminates
3163 immediately with a fatal error.
3164
3165 Calling any of the following commands increases the recursion depth:
3166
3167 • include()
3168
3169 • find_package()
3170
3171 • add_subdirectory()
3172
3173 • try_compile()
3174
3175 • ctest_read_custom_files()
3176
3177 • ctest_run_script() (unless NEW_PROCESS is specified)
3178
3179 • User-defined function()'s and macro()'s (note that function() and
3180 macro() themselves don't increase recursion depth)
3181
3182 • Reading or writing variables that are being watched by a
3183 variable_watch()
3184
3185 See also the CMAKE_MAXIMUM_RECURSION_DEPTH environment variable.
3186
3187 CMAKE_MESSAGE_CONTEXT
3188 New in version 3.17.
3189
3190
3191 When enabled by the cmake --log-context command line option or the
3192 CMAKE_MESSAGE_CONTEXT_SHOW variable, the message() command converts the
3193 CMAKE_MESSAGE_CONTEXT list into a dot-separated string surrounded by
3194 square brackets and prepends it to each line for messages of log levels
3195 NOTICE and below.
3196
3197 For logging contexts to work effectively, projects should generally AP‐
3198 PEND and POP_BACK an item to the current value of CMAKE_MESSAGE_CONTEXT
3199 rather than replace it. Projects should not assume the message context
3200 at the top of the source tree is empty, as there are scenarios where
3201 the context might have already been set (e.g. hierarchical projects).
3202
3203 WARNING:
3204 Valid context names are restricted to anything that could be used as
3205 a CMake variable name. All names that begin with an underscore or
3206 the string cmake_ are also reserved for use by CMake and should not
3207 be used by projects.
3208
3209 Example:
3210
3211 function(bar)
3212 list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
3213 message(VERBOSE "bar VERBOSE message")
3214 endfunction()
3215
3216 function(baz)
3217 list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
3218 message(DEBUG "baz DEBUG message")
3219 endfunction()
3220
3221 function(foo)
3222 list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
3223 bar()
3224 message(TRACE "foo TRACE message")
3225 baz()
3226 endfunction()
3227
3228 list(APPEND CMAKE_MESSAGE_CONTEXT "top")
3229
3230 message(VERBOSE "Before `foo`")
3231 foo()
3232 message(VERBOSE "After `foo`")
3233
3234 list(POP_BACK CMAKE_MESSAGE_CONTEXT)
3235
3236 Which results in the following output:
3237
3238 -- [top] Before `foo`
3239 -- [top.foo.bar] bar VERBOSE message
3240 -- [top.foo] foo TRACE message
3241 -- [top.foo.baz] baz DEBUG message
3242 -- [top] After `foo`
3243
3244 CMAKE_MESSAGE_CONTEXT_SHOW
3245 New in version 3.17.
3246
3247
3248 Setting this variable to true enables showing a context with each line
3249 logged by the message() command (see CMAKE_MESSAGE_CONTEXT for how the
3250 context itself is specified).
3251
3252 This variable is an alternative to providing the --log-context option
3253 on the cmake command line. Whereas the command line option will apply
3254 only to that one CMake run, setting CMAKE_MESSAGE_CONTEXT_SHOW to true
3255 as a cache variable will ensure that subsequent CMake runs will con‐
3256 tinue to show the message context.
3257
3258 Projects should not set CMAKE_MESSAGE_CONTEXT_SHOW. It is intended for
3259 users so that they may control whether or not to include context with
3260 messages.
3261
3262 CMAKE_MESSAGE_INDENT
3263 New in version 3.16.
3264
3265
3266 The message() command joins the strings from this list and for log lev‐
3267 els of NOTICE and below, it prepends the resultant string to each line
3268 of the message.
3269
3270 Example:
3271
3272 list(APPEND listVar one two three)
3273
3274 message(VERBOSE [[Collected items in the "listVar":]])
3275 list(APPEND CMAKE_MESSAGE_INDENT " ")
3276
3277 foreach(item IN LISTS listVar)
3278 message(VERBOSE ${item})
3279 endforeach()
3280
3281 list(POP_BACK CMAKE_MESSAGE_INDENT)
3282 message(VERBOSE "No more indent")
3283
3284 Which results in the following output:
3285
3286 -- Collected items in the "listVar":
3287 -- one
3288 -- two
3289 -- three
3290 -- No more indent
3291
3292 CMAKE_MESSAGE_LOG_LEVEL
3293 New in version 3.17.
3294
3295
3296 When set, this variable specifies the logging level used by the
3297 message() command. Valid values are the same as those for the
3298 --log-level command line option of the cmake(1) program. If this vari‐
3299 able is set and the --log-level command line option is given, the com‐
3300 mand line option takes precedence.
3301
3302 The main advantage to using this variable is to make a log level per‐
3303 sist between CMake runs. Setting it as a cache variable will ensure
3304 that subsequent CMake runs will continue to use the chosen log level.
3305
3306 Projects should not set this variable, it is intended for users so that
3307 they may control the log level according to their own needs.
3308
3309 New in version 3.25: See the cmake_language() cmake_language command
3310 for a way to query the current message logging level.
3311
3312
3313 CMAKE_MFC_FLAG
3314 Use the MFC library for an executable or dll.
3315
3316 Enables the use of the Microsoft Foundation Classes (MFC). It should
3317 be set to 1 for the static MFC library, and 2 for the shared MFC li‐
3318 brary. This is used in Visual Studio project files.
3319
3320 Usage example:
3321
3322 add_definitions(-D_AFXDLL)
3323 set(CMAKE_MFC_FLAG 2)
3324 add_executable(CMakeSetup WIN32 ${SRCS})
3325
3326 Contents of CMAKE_MFC_FLAG may use generator expressions.
3327
3328 CMAKE_MODULE_PATH
3329 Semicolon-separated list of directories, represented using forward
3330 slashes, specifying a search path for CMake modules to be loaded by the
3331 include() or find_package() commands before checking the default mod‐
3332 ules that come with CMake. By default it is empty. It is intended to
3333 be set by the project.
3334
3335 CMAKE_POLICY_DEFAULT_CMP<NNNN>
3336 Default for CMake Policy CMP<NNNN> when it is otherwise left unset.
3337
3338 Commands cmake_minimum_required(VERSION) and cmake_policy(VERSION) by
3339 default leave policies introduced after the given version unset. Set
3340 CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to specify the default for
3341 policy CMP<NNNN>, where <NNNN> is the policy number.
3342
3343 This variable should not be set by a project in CMake code as a way to
3344 set its own policies; use cmake_policy(SET) instead. This variable is
3345 meant to externally set policies for which a project has not itself
3346 been updated:
3347
3348 • Users running CMake may set this variable in the cache (e.g. -DC‐
3349 MAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>). Set it to OLD to quiet a
3350 policy warning while using old behavior or to NEW to try building the
3351 project with new behavior.
3352
3353 • Projects may set this variable before a call to add_subdirectory()
3354 that adds a third-party project in order to set its policies without
3355 modifying third-party code.
3356
3357 CMAKE_POLICY_WARNING_CMP<NNNN>
3358 Explicitly enable or disable the warning when CMake Policy CMP<NNNN>
3359 has not been set explicitly by cmake_policy() or implicitly by
3360 cmake_minimum_required(). This is meaningful only for the policies that
3361 do not warn by default:
3362
3363 • CMAKE_POLICY_WARNING_CMP0025 controls the warning for policy CMP0025.
3364
3365 • CMAKE_POLICY_WARNING_CMP0047 controls the warning for policy CMP0047.
3366
3367 • CMAKE_POLICY_WARNING_CMP0056 controls the warning for policy CMP0056.
3368
3369 • CMAKE_POLICY_WARNING_CMP0060 controls the warning for policy CMP0060.
3370
3371 • CMAKE_POLICY_WARNING_CMP0065 controls the warning for policy CMP0065.
3372
3373 • CMAKE_POLICY_WARNING_CMP0066 controls the warning for policy CMP0066.
3374
3375 • CMAKE_POLICY_WARNING_CMP0067 controls the warning for policy CMP0067.
3376
3377 • CMAKE_POLICY_WARNING_CMP0082 controls the warning for policy CMP0082.
3378
3379 • CMAKE_POLICY_WARNING_CMP0089 controls the warning for policy CMP0089.
3380
3381 • CMAKE_POLICY_WARNING_CMP0102 controls the warning for policy CMP0102.
3382
3383 • CMAKE_POLICY_WARNING_CMP0112 controls the warning for policy CMP0112.
3384
3385 • CMAKE_POLICY_WARNING_CMP0116 controls the warning for policy CMP0116.
3386
3387 • CMAKE_POLICY_WARNING_CMP0126 controls the warning for policy CMP0126.
3388
3389 • CMAKE_POLICY_WARNING_CMP0128 controls the warning for policy CMP0128.
3390
3391 • CMAKE_POLICY_WARNING_CMP0129 controls the warning for policy CMP0129.
3392
3393 • CMAKE_POLICY_WARNING_CMP0133 controls the warning for policy CMP0133.
3394
3395 This variable should not be set by a project in CMake code. Project
3396 developers running CMake may set this variable in their cache to enable
3397 the warning (e.g. -DCMAKE_POLICY_WARNING_CMP<NNNN>=ON). Alternatively,
3398 running cmake(1) with the --debug-output, --trace, or --trace-expand
3399 option will also enable the warning.
3400
3401 CMAKE_PREFIX_PATH
3402 Semicolon-separated list of directories specifying installation pre‐
3403 fixes to be searched by the find_package(), find_program(),
3404 find_library(), find_file(), and find_path() commands. Each command
3405 will add appropriate subdirectories (like bin, lib, or include) as
3406 specified in its own documentation.
3407
3408 By default this is empty. It is intended to be set by the project.
3409
3410 There is also an environment variable CMAKE_PREFIX_PATH, which is used
3411 as an additional list of search prefixes.
3412
3413 See also CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH,
3414 CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH, and CMAKE_IGNORE_PATH.
3415
3416 CMAKE_PROGRAM_PATH
3417 Semicolon-separated list of directories specifying a search path for
3418 the find_program() command. By default it is empty, it is intended to
3419 be set by the project.
3420
3421 There is also an environment variable CMAKE_PROGRAM_PATH, which is used
3422 as an additional list of search directories.
3423
3424 See also CMAKE_SYSTEM_PROGRAM_PATH and CMAKE_PREFIX_PATH.
3425
3426 CMAKE_PROJECT_INCLUDE
3427 New in version 3.15.
3428
3429
3430 A CMake language file or module to be included as the last step of all
3431 project() command calls. This is intended for injecting custom code
3432 into project builds without modifying their source. See Code Injection
3433 for a more detailed discussion of files potentially included during a
3434 project() call.
3435
3436 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3437 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3438 CMAKE_PROJECT_INCLUDE_BEFORE, and CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3439 variables.
3440
3441 CMAKE_PROJECT_INCLUDE_BEFORE
3442 New in version 3.15.
3443
3444
3445 A CMake language file or module to be included as the first step of all
3446 project() command calls. This is intended for injecting custom code
3447 into project builds without modifying their source. See Code Injection
3448 for a more detailed discussion of files potentially included during a
3449 project() call.
3450
3451 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3452 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, CMAKE_PROJECT_INCLUDE, and
3453 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3454
3455 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
3456 A CMake language file or module to be included as the last step of any
3457 project() command calls that specify <PROJECT-NAME> as the project
3458 name. This is intended for injecting custom code into project builds
3459 without modifying their source. See Code Injection for a more detailed
3460 discussion of files potentially included during a project() call.
3461
3462 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE,
3463 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3464 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3465
3466 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
3467 New in version 3.17.
3468
3469
3470 A CMake language file or module to be included as the first step of any
3471 project() command calls that specify <PROJECT-NAME> as the project
3472 name. This is intended for injecting custom code into project builds
3473 without modifying their source. See Code Injection for a more detailed
3474 discussion of files potentially included during a project() call.
3475
3476 See also the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
3477 CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE, and
3478 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variables.
3479
3480 CMAKE_PROJECT_TOP_LEVEL_INCLUDES
3481 New in version 3.24.
3482
3483
3484 Semicolon-separated list of CMake language files to include as part of
3485 the very first project() call. The files will be included immediately
3486 after the toolchain file has been read (if one is specified) and plat‐
3487 form variables have been set, but before any languages have been en‐
3488 abled. Therefore, language-specific variables, including things like
3489 CMAKE_<LANG>_COMPILER, might not be set. See Code Injection for a more
3490 detailed discussion of files potentially included during a project()
3491 call.
3492
3493 This variable is intended for specifying files that perform one-time
3494 setup for the build. It provides an injection point for things like
3495 configuring package managers, adding logic the user shares between
3496 projects (e.g. defining their own custom build types), and so on. It is
3497 primarily for users to add things specific to their environment, but
3498 not for specifying the toolchain details (use CMAKE_TOOLCHAIN_FILE for
3499 that).
3500
3501 By default, this variable is empty. It is intended to be set by the
3502 user.
3503
3504 See also the CMAKE_PROJECT_INCLUDE, CMAKE_PROJECT_INCLUDE_BEFORE,
3505 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, and
3506 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables.
3507
3508 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>
3509 New in version 3.22.
3510
3511
3512 Variable for making find_package() call REQUIRED.
3513
3514 Every non-REQUIRED find_package() call in a project can be turned into
3515 REQUIRED by setting the variable CMAKE_REQUIRE_FIND_PACKAGE_<Package‐
3516 Name> to TRUE. This can be used to assert assumptions about build en‐
3517 vironment and to ensure the build will fail early if they do not hold.
3518
3519 See also the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable.
3520
3521 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
3522 Don't make the install target depend on the all target.
3523
3524 By default, the install target depends on the all target. This has the
3525 effect, that when make install is invoked or INSTALL is built, first
3526 the all target is built, then the installation starts. If
3527 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is set to TRUE, this dependency is
3528 not created, so the installation process will start immediately, inde‐
3529 pendent from whether the project has been completely built or not.
3530
3531 CMAKE_STAGING_PREFIX
3532 This variable may be set to a path to install to when cross-compiling.
3533 This can be useful if the path in CMAKE_SYSROOT is read-only, or other‐
3534 wise should remain pristine.
3535
3536 The CMAKE_STAGING_PREFIX location is also used as a search prefix by
3537 the find_* commands. This can be controlled by setting the
3538 CMAKE_FIND_NO_INSTALL_PREFIX variable.
3539
3540 If any RPATH/RUNPATH entries passed to the linker contain the
3541 CMAKE_STAGING_PREFIX, the matching path fragments are replaced with the
3542 CMAKE_INSTALL_PREFIX.
3543
3544 CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3545 New in version 3.8.
3546
3547
3548 This variable contains a list of env vars as a list of tokens with the
3549 syntax var=value.
3550
3551 Example:
3552
3553 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3554 "FOO=FOO1\;FOO2\;FOON"
3555 "BAR=BAR1\;BAR2\;BARN"
3556 "BAZ=BAZ1\;BAZ2\;BAZN"
3557 "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN"
3558 "VALID="
3559 )
3560
3561 In case of malformed variables CMake will fail:
3562
3563 set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
3564 "THIS_IS_NOT_VALID"
3565 )
3566
3567 CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
3568 New in version 3.8.
3569
3570
3571 If this variable evaluates to ON at the end of the top-level CMake‐
3572 Lists.txt file, the Sublime Text 2 extra generator excludes the build
3573 tree from the .sublime-project if it is inside the source tree.
3574
3575 CMAKE_SUPPRESS_REGENERATION
3576 New in version 3.12.
3577
3578
3579 If CMAKE_SUPPRESS_REGENERATION is OFF, which is default, then CMake
3580 adds a special target on which all other targets depend that checks the
3581 build system and optionally re-runs CMake to regenerate the build sys‐
3582 tem when the target specification source changes.
3583
3584 If this variable evaluates to ON at the end of the top-level CMake‐
3585 Lists.txt file, CMake will not add the regeneration target to the build
3586 system or perform any build system checks.
3587
3588 CMAKE_SYSROOT
3589 Path to pass to the compiler in the --sysroot flag.
3590
3591 The CMAKE_SYSROOT content is passed to the compiler in the --sysroot
3592 flag, if supported. The path is also stripped from the RPATH/RUNPATH
3593 if necessary on installation. The CMAKE_SYSROOT is also used to prefix
3594 paths searched by the find_* commands.
3595
3596 This variable may only be set in a toolchain file specified by the
3597 CMAKE_TOOLCHAIN_FILE variable.
3598
3599 See also the CMAKE_SYSROOT_COMPILE and CMAKE_SYSROOT_LINK variables.
3600
3601 CMAKE_SYSROOT_COMPILE
3602 New in version 3.9.
3603
3604
3605 Path to pass to the compiler in the --sysroot flag when compiling
3606 source files. This is the same as CMAKE_SYSROOT but is used only for
3607 compiling sources and not linking.
3608
3609 This variable may only be set in a toolchain file specified by the
3610 CMAKE_TOOLCHAIN_FILE variable.
3611
3612 CMAKE_SYSROOT_LINK
3613 New in version 3.9.
3614
3615
3616 Path to pass to the compiler in the --sysroot flag when linking. This
3617 is the same as CMAKE_SYSROOT but is used only for linking and not com‐
3618 piling sources.
3619
3620 This variable may only be set in a toolchain file specified by the
3621 CMAKE_TOOLCHAIN_FILE variable.
3622
3623 CMAKE_SYSTEM_APPBUNDLE_PATH
3624 New in version 3.4.
3625
3626
3627 Search path for macOS application bundles used by the find_program(),
3628 and find_package() commands. By default it contains the standard di‐
3629 rectories for the current system. It is not intended to be modified by
3630 the project, use CMAKE_APPBUNDLE_PATH for this.
3631
3632 CMAKE_SYSTEM_FRAMEWORK_PATH
3633 New in version 3.4.
3634
3635
3636 Search path for macOS frameworks used by the find_library(),
3637 find_package(), find_path(), and find_file() commands. By default it
3638 contains the standard directories for the current system. It is not
3639 intended to be modified by the project, use CMAKE_FRAMEWORK_PATH for
3640 this.
3641
3642 CMAKE_SYSTEM_IGNORE_PATH
3643 Semicolon-separated list of directories to be ignored by the various
3644 find...() commands.
3645
3646 For find_program(), find_library(), find_file(), and find_path(), any
3647 file found in one of the listed directories will be ignored. The listed
3648 directories do not apply recursively, so any subdirectories to be ig‐
3649 nored must also be explicitly listed. CMAKE_SYSTEM_IGNORE_PATH does
3650 not affect the search prefixes used by these four commands. To ignore
3651 individual paths under a search prefix (e.g. bin, include, lib, etc.),
3652 each path must be listed in CMAKE_SYSTEM_IGNORE_PATH as a full absolute
3653 path. CMAKE_SYSTEM_IGNORE_PREFIX_PATH provides a more appropriate way
3654 to ignore a whole search prefix.
3655
3656 find_package() is also affected by CMAKE_SYSTEM_IGNORE_PATH, but only
3657 for Config mode searches. Any <Name>Config.cmake or <name>-config.cmake
3658 file found in one of the specified directories will be ignored. In ad‐
3659 dition, any search prefix found in CMAKE_SYSTEM_IGNORE_PATH will be
3660 skipped for backward compatibility reasons, but new code should prefer
3661 to use CMAKE_SYSTEM_IGNORE_PREFIX_PATH to ignore prefixes instead.
3662
3663 Ignoring search locations can be useful in cross-compiling environments
3664 where some system directories contain incompatible but possibly link‐
3665 able libraries. For example, on cross-compiled cluster environments,
3666 this allows a user to ignore directories containing libraries meant for
3667 the front-end machine.
3668
3669 CMAKE_SYSTEM_IGNORE_PATH is populated by CMake as part of its platform
3670 and toolchain setup. Its purpose is to ignore locations containing in‐
3671 compatible binaries meant for the host rather than the target platform.
3672 The project or end user should not modify this variable, they should
3673 use CMAKE_IGNORE_PATH instead.
3674
3675 See also the following variables:
3676
3677 • CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3678
3679 • CMAKE_SYSTEM_PREFIX_PATH
3680
3681 • CMAKE_SYSTEM_LIBRARY_PATH
3682
3683 • CMAKE_SYSTEM_INCLUDE_PATH
3684
3685 • CMAKE_SYSTEM_PROGRAM_PATH
3686
3687 CMAKE_SYSTEM_IGNORE_PREFIX_PATH
3688 New in version 3.23.
3689
3690
3691 Semicolon-separated list of search prefixes to be ignored by the
3692 find_program(), find_library(), find_file(), and find_path() commands.
3693 The prefixes are also ignored by the Config mode of the find_package()
3694 command (Module mode is unaffected). To ignore specific directories
3695 instead, see CMAKE_SYSTEM_IGNORE_PATH.
3696
3697 Ignoring search locations can be useful in cross-compiling environments
3698 where some system directories contain incompatible but possibly link‐
3699 able libraries. For example, on cross-compiled cluster environments,
3700 this allows a user to ignore directories containing libraries meant for
3701 the front-end machine.
3702
3703 CMAKE_SYSTEM_IGNORE_PREFIX_PATH is populated by CMake as part of its
3704 platform and toolchain setup. Its purpose is to ignore locations con‐
3705 taining incompatible binaries meant for the host rather than the target
3706 platform. The project or end user should not modify this variable,
3707 they should use CMAKE_IGNORE_PREFIX_PATH instead.
3708
3709 See also the following variables:
3710
3711 • CMAKE_SYSTEM_IGNORE_PATH
3712
3713 • CMAKE_SYSTEM_PREFIX_PATH
3714
3715 • CMAKE_SYSTEM_LIBRARY_PATH
3716
3717 • CMAKE_SYSTEM_INCLUDE_PATH
3718
3719 • CMAKE_SYSTEM_PROGRAM_PATH
3720
3721 CMAKE_SYSTEM_INCLUDE_PATH
3722 Semicolon-separated list of directories specifying a search path for
3723 the find_file() and find_path() commands. By default this contains the
3724 standard directories for the current system. It is not intended to be
3725 modified by the project; use CMAKE_INCLUDE_PATH for this. See also
3726 CMAKE_SYSTEM_PREFIX_PATH.
3727
3728 CMAKE_SYSTEM_LIBRARY_PATH
3729 Semicolon-separated list of directories specifying a search path for
3730 the find_library() command. By default this contains the standard di‐
3731 rectories for the current system. It is not intended to be modified by
3732 the project; use CMAKE_LIBRARY_PATH for this. See also
3733 CMAKE_SYSTEM_PREFIX_PATH.
3734
3735 CMAKE_SYSTEM_PREFIX_PATH
3736 Semicolon-separated list of directories specifying installation pre‐
3737 fixes to be searched by the find_package(), find_program(),
3738 find_library(), find_file(), and find_path() commands. Each command
3739 will add appropriate subdirectories (like bin, lib, or include) as
3740 specified in its own documentation.
3741
3742 By default this contains the system directories for the current system,
3743 the CMAKE_INSTALL_PREFIX, and the CMAKE_STAGING_PREFIX. The installa‐
3744 tion and staging prefixes may be excluded by setting the
3745 CMAKE_FIND_NO_INSTALL_PREFIX variable before the first project() invo‐
3746 cation.
3747
3748 The system directories that are contained in CMAKE_SYSTEM_PREFIX_PATH
3749 are locations that typically include installed software. An example be‐
3750 ing /usr/local for UNIX based platforms. In addition to standard plat‐
3751 form locations, CMake will also add values to CMAKE_SYSTEM_PREFIX_PATH
3752 based on environment variables. The environment variables and search
3753 locations that CMake uses may evolve over time, as platforms and their
3754 conventions also evolve. The following provides an indicative list of
3755 environment variables and locations that CMake searches, but they are
3756 subject to change:
3757
3758 CrayLinuxEnvironment:
3759
3760 • ENV{SYSROOT_DIR}/
3761
3762 • ENV{SYSROOT_DIR}/usr
3763
3764 • ENV{SYSROOT_DIR}/usr/local
3765
3766 Darwin:
3767
3768 • ENV{SDKROOT}/usr When CMAKE_OSX_SYSROOT is not explicitly
3769 specified.
3770
3771 OpenBSD:
3772
3773 • ENV{LOCALBASE}
3774
3775 Unix:
3776
3777 • ENV{CONDA_PREFIX} when using a conda compiler
3778
3779 Windows:
3780
3781 • ENV{ProgramW6432}
3782
3783 • ENV{ProgramFiles}
3784
3785 • ENV{ProgramFiles(x86)}
3786
3787 • ENV{SystemDrive}/Program Files
3788
3789 • ENV{SystemDrive}/Program Files (x86)
3790
3791 CMAKE_SYSTEM_PREFIX_PATH is not intended to be modified by the project;
3792 use CMAKE_PREFIX_PATH for this.
3793
3794 See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
3795 CMAKE_SYSTEM_PROGRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.
3796
3797 CMAKE_SYSTEM_PROGRAM_PATH
3798 Semicolon-separated list of directories specifying a search path for
3799 the find_program() command. By default this contains the standard di‐
3800 rectories for the current system. It is not intended to be modified by
3801 the project; use CMAKE_PROGRAM_PATH for this. See also
3802 CMAKE_SYSTEM_PREFIX_PATH.
3803
3804 CMAKE_TLS_CAINFO
3805 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3806 mands' TLS_CAINFO options. It is unset by default.
3807
3808 This variable is also used by the ExternalProject and FetchContent mod‐
3809 ules for internal calls to file(DOWNLOAD).
3810
3811 CMAKE_TLS_VERIFY
3812 Specify the default value for the file(DOWNLOAD) and file(UPLOAD) com‐
3813 mands' TLS_VERIFY options. If not set, the default is off.
3814
3815 This variable is also used by the ExternalProject and FetchContent mod‐
3816 ules for internal calls to file(DOWNLOAD).
3817
3818 TLS verification can help provide confidence that one is connecting to
3819 the desired server. When downloading known content, one should also
3820 use file hashes to verify it.
3821
3822 set(CMAKE_TLS_VERIFY TRUE)
3823
3824 CMAKE_USER_MAKE_RULES_OVERRIDE
3825 Specify a CMake file that overrides platform information.
3826
3827 CMake loads the specified file while enabling support for each language
3828 from either the project() or enable_language() commands. It is loaded
3829 after CMake's builtin compiler and platform information modules have
3830 been loaded but before the information is used. The file may set plat‐
3831 form information variables to override CMake's defaults. See
3832 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> for the language-specific version
3833 of this variable.
3834
3835 This feature is intended for use only in overriding information vari‐
3836 ables that must be set before CMake builds its first test project to
3837 check that the compiler for a language works. It should not be used to
3838 load a file in cases that a normal include() will work. Use it only as
3839 a last resort for behavior that cannot be achieved any other way. For
3840 example, one may set the CMAKE_C_FLAGS_INIT variable to change the de‐
3841 fault value used to initialize the CMAKE_C_FLAGS variable before it is
3842 cached. The override file should NOT be used to set anything that
3843 could be set after languages are enabled, such as variables like
3844 CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries.
3845 Information set in the file will be used for try_compile() and
3846 try_run() builds too.
3847
3848 CMAKE_WARN_DEPRECATED
3849 Whether to issue warnings for deprecated functionality.
3850
3851 If not FALSE, use of deprecated functionality will issue warnings. If
3852 this variable is not set, CMake behaves as if it were set to TRUE.
3853
3854 When running cmake(1), this option can be enabled with the -Wdeprecated
3855 option, or disabled with the -Wno-deprecated option.
3856
3857 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
3858 Ask cmake_install.cmake script to warn each time a file with absolute
3859 INSTALL DESTINATION is encountered.
3860
3861 This variable is used by CMake-generated cmake_install.cmake scripts.
3862 If one sets this variable to ON while running the script, it may get
3863 warning messages from the script.
3864
3865 CMAKE_XCODE_GENERATE_SCHEME
3866 New in version 3.9.
3867
3868
3869 If enabled, the Xcode generator will generate schema files. These are
3870 useful to invoke analyze, archive, build-for-testing and test actions
3871 from the command line.
3872
3873 This variable initializes the XCODE_GENERATE_SCHEME target property on
3874 all targets.
3875
3876 CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
3877 New in version 3.11.
3878
3879
3880 If enabled, the Xcode generator will generate only a single Xcode
3881 project file for the topmost project() command instead of generating
3882 one for every project() command.
3883
3884 This could be useful to speed up the CMake generation step for large
3885 projects and to work-around a bug in the ZERO_CHECK logic.
3886
3887 CMAKE_XCODE_LINK_BUILD_PHASE_MODE
3888 New in version 3.19.
3889
3890
3891 This variable is used to initialize the XCODE_LINK_BUILD_PHASE_MODE
3892 property on targets. It affects the methods that the Xcode generator
3893 uses to link different kinds of libraries. Its default value is NONE.
3894
3895 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
3896 New in version 3.13.
3897
3898
3899 Whether to enable Address Sanitizer in the Diagnostics section of the
3900 generated Xcode scheme.
3901
3902 This variable initializes the XCODE_SCHEME_ADDRESS_SANITIZER property
3903 on all targets.
3904
3905 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3906 to see all Xcode schema related properties.
3907
3908 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
3909 New in version 3.13.
3910
3911
3912 Whether to enable Detect use of stack after return in the Diagnostics
3913 section of the generated Xcode scheme.
3914
3915 This variable initializes the
3916 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN property on all tar‐
3917 gets.
3918
3919 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3920 to see all Xcode schema related properties.
3921
3922 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3923 New in version 3.16.
3924
3925
3926 Whether to enable Allow debugging when using document Versions Browser
3927 in the Options section of the generated Xcode scheme.
3928
3929 This variable initializes the XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
3930 property on all targets.
3931
3932 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3933 to see all Xcode schema related properties.
3934
3935 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3936 New in version 3.13.
3937
3938
3939 Whether to disable the Main Thread Checker in the Diagnostics section
3940 of the generated Xcode scheme.
3941
3942 This variable initializes the XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
3943 property on all targets.
3944
3945 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3946 to see all Xcode schema related properties.
3947
3948 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
3949 New in version 3.13.
3950
3951
3952 Whether to enable Dynamic Library Loads in the Diagnostics section of
3953 the generated Xcode scheme.
3954
3955 This variable initializes the XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS prop‐
3956 erty on all targets.
3957
3958 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3959 to see all Xcode schema related properties.
3960
3961 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3962 New in version 3.13.
3963
3964
3965 Whether to enable Dynamic Linker API usage in the Diagnostics section
3966 of the generated Xcode scheme.
3967
3968 This variable initializes the XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
3969 property on all targets.
3970
3971 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3972 to see all Xcode schema related properties.
3973
3974 CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3975 New in version 3.25.
3976
3977
3978 Property value for Metal: API Validation in the Options section of the
3979 generated Xcode scheme.
3980
3981 This variable initializes the XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
3982 property on all targets.
3983
3984 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3985 to see all Xcode schema related properties.
3986
3987 CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
3988 New in version 3.23.
3989
3990
3991 Property value for GPU Frame Capture in the Options section of the gen‐
3992 erated Xcode scheme. Example values are Metal and Disabled.
3993
3994 This variable initializes the
3995 XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE property on all targets.
3996
3997 Please refer to the XCODE_GENERATE_SCHEME target property documentation
3998 to see all Xcode schema related properties.
3999
4000 CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
4001 New in version 3.25.
4002
4003
4004 Property value for Metal: Shader Validation in the Options section of
4005 the generated Xcode scheme.
4006
4007 This variable initializes the XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
4008 property on all targets.
4009
4010 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4011 to see all Xcode schema related properties.
4012
4013 CMAKE_XCODE_SCHEME_ENVIRONMENT
4014 New in version 3.17.
4015
4016
4017 Specify environment variables that should be added to the Arguments
4018 section of the generated Xcode scheme.
4019
4020 If set to a list of environment variables and values of the form MY‐
4021 VAR=value those environment variables will be added to the scheme.
4022
4023 This variable initializes the XCODE_SCHEME_ENVIRONMENT property on all
4024 targets.
4025
4026 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4027 to see all Xcode schema related properties.
4028
4029 CMAKE_XCODE_SCHEME_GUARD_MALLOC
4030 New in version 3.13.
4031
4032
4033 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
4034 ated Xcode scheme.
4035
4036 This variable initializes the XCODE_SCHEME_GUARD_MALLOC property on all
4037 targets.
4038
4039 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4040 to see all Xcode schema related properties.
4041
4042 CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION
4043 New in version 3.25.
4044
4045
4046 Set the build configuration to run the target.
4047
4048 This variable initializes the XCODE_SCHEME_LAUNCH_CONFIGURATION prop‐
4049 erty on all targets.
4050
4051 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4052 to see all Xcode schema related properties.
4053
4054 CMAKE_XCODE_SCHEME_LAUNCH_MODE
4055 New in version 3.25.
4056
4057
4058 Property value for Launch in the Info section of the generated Xcode
4059 scheme.
4060
4061 This variable initializes the XCODE_SCHEME_LAUNCH_MODE property on all
4062 targets.
4063
4064 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4065 to see all Xcode schema related properties.
4066
4067 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
4068 New in version 3.13.
4069
4070
4071 Whether to enable the Main Thread Checker option Pause on issues in the
4072 Diagnostics section of the generated Xcode scheme.
4073
4074 This variable initializes the XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
4075 property on all targets.
4076
4077 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4078 to see all Xcode schema related properties.
4079
4080 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
4081 New in version 3.13.
4082
4083
4084 Whether to enable Malloc Guard Edges in the Diagnostics section of the
4085 generated Xcode scheme.
4086
4087 This variable initializes the XCODE_SCHEME_MALLOC_GUARD_EDGES property
4088 on all targets.
4089
4090 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4091 to see all Xcode schema related properties.
4092
4093 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
4094 New in version 3.13.
4095
4096
4097 Whether to enable Malloc Scribble in the Diagnostics section of the
4098 generated Xcode scheme.
4099
4100 This variable initializes the XCODE_SCHEME_MALLOC_SCRIBBLE property on
4101 all targets.
4102
4103 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4104 to see all Xcode schema related properties.
4105
4106 CMAKE_XCODE_SCHEME_MALLOC_STACK
4107 New in version 3.13.
4108
4109
4110 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
4111 ated Xcode scheme.
4112
4113 This variable initializes the XCODE_SCHEME_MALLOC_STACK property on all
4114 targets.
4115
4116 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4117 to see all Xcode schema related properties.
4118
4119 CMAKE_XCODE_SCHEME_THREAD_SANITIZER
4120 New in version 3.13.
4121
4122
4123 Whether to enable Thread Sanitizer in the Diagnostics section of the
4124 generated Xcode scheme.
4125
4126 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER property on
4127 all targets.
4128
4129 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4130 to see all Xcode schema related properties.
4131
4132 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
4133 New in version 3.13.
4134
4135
4136 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
4137 section of the generated Xcode scheme.
4138
4139 This variable initializes the XCODE_SCHEME_THREAD_SANITIZER_STOP prop‐
4140 erty on all targets.
4141
4142 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4143 to see all Xcode schema related properties.
4144
4145 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
4146 New in version 3.13.
4147
4148
4149 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
4150 tion of the generated Xcode scheme.
4151
4152 This variable initializes the
4153 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER property on all targets.
4154
4155 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4156 to see all Xcode schema related properties.
4157
4158 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
4159 New in version 3.13.
4160
4161
4162 Whether to enable Undefined Behavior Sanitizer option Pause on issues
4163 in the Diagnostics section of the generated Xcode scheme.
4164
4165 This variable initializes the
4166 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP property on all tar‐
4167 gets.
4168
4169 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4170 to see all Xcode schema related properties.
4171
4172 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
4173 New in version 3.17.
4174
4175
4176 Specify the Working Directory of the Run and Profile actions in the
4177 generated Xcode scheme.
4178
4179 This variable initializes the XCODE_SCHEME_WORKING_DIRECTORY property
4180 on all targets.
4181
4182 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4183 to see all Xcode schema related properties.
4184
4185 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
4186 New in version 3.13.
4187
4188
4189 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
4190 erated Xcode scheme.
4191
4192 This variable initializes the XCODE_SCHEME_ZOMBIE_OBJECTS property on
4193 all targets.
4194
4195 Please refer to the XCODE_GENERATE_SCHEME target property documentation
4196 to see all Xcode schema related properties.
4197
4198 CMAKE_XCODE_XCCONFIG
4199 New in version 3.24.
4200
4201
4202 If set, the Xcode generator will register the specified file as a
4203 global XCConfig file. For target-level XCConfig files see the
4204 XCODE_XCCONFIG target property.
4205
4206 This feature is intended to ease migration from native Xcode projects
4207 to CMake projects.
4208
4209 Contents of CMAKE_XCODE_XCCONFIG may use generator expressions.
4210
4211 <PackageName>_ROOT
4212 New in version 3.12.
4213
4214
4215 Calls to find_package(<PackageName>) will search in prefixes specified
4216 by the <PackageName>_ROOT CMake variable, where <PackageName> is the
4217 (case-preserved) name given to the find_package() call and _ROOT is
4218 literal. For example, find_package(Foo) will search prefixes specified
4219 in the Foo_ROOT CMake variable (if set). See policy CMP0074.
4220
4221 This variable may hold a single prefix or a semicolon-separated list of
4222 multiple prefixes.
4223
4224 See also the <PackageName>_ROOT environment variable.
4225
4226 <PACKAGENAME>_ROOT
4227 New in version 3.27.
4228
4229
4230 Calls to find_package(<PackageName>) will also search in pre‐
4231 fixes specified by the upper-case <PACKAGENAME>_ROOT CMake vari‐
4232 able. See policy CMP0144.
4233
4235 ANDROID
4236 New in version 3.7.
4237
4238
4239 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is Android.
4240
4241 APPLE
4242 Set to True when the target system is an Apple platform (macOS, iOS,
4243 tvOS or watchOS).
4244
4245 BORLAND
4246 True if the Borland compiler is being used.
4247
4248 This is set to true if the Borland compiler is being used.
4249
4250 BSD
4251 New in version 3.25.
4252
4253
4254 Set to a string value when the target system is BSD. This value can be
4255 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4256
4257 CMAKE_ANDROID_NDK_VERSION
4258 New in version 3.20.
4259
4260
4261 When Cross Compiling for Android with the NDK and using an Android NDK
4262 version 11 or higher, this variable is provided by CMake to report the
4263 NDK version number.
4264
4265 CMAKE_CL_64
4266 Discouraged. Use CMAKE_SIZEOF_VOID_P instead.
4267
4268 Set to a true value when using a Microsoft Visual Studio cl compiler
4269 that targets a 64-bit architecture.
4270
4271 CMAKE_COMPILER_2005
4272 Using the Visual Studio 2005 compiler from Microsoft
4273
4274 Set to true when using the Visual Studio 2005 compiler from Microsoft.
4275
4276 CMAKE_HOST_APPLE
4277 True for Apple macOS operating systems.
4278
4279 Set to true when the host system is Apple macOS.
4280
4281 CMAKE_HOST_BSD
4282 New in version 3.25.
4283
4284
4285 Set to a string value when the host system is BSD. This value can be
4286 one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.
4287
4288 CMAKE_HOST_LINUX
4289 New in version 3.25.
4290
4291
4292 Set to true when the host system is Linux.
4293
4294 CMAKE_HOST_SOLARIS
4295 New in version 3.6.
4296
4297
4298 True for Oracle Solaris operating systems.
4299
4300 Set to true when the host system is Oracle Solaris.
4301
4302 CMAKE_HOST_SYSTEM
4303 Composite Name of OS CMake is being run on.
4304
4305 This variable is the composite of CMAKE_HOST_SYSTEM_NAME and
4306 CMAKE_HOST_SYSTEM_VERSION, e.g. ${CMAKE_HOST_SYS‐
4307 TEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}. If CMAKE_HOST_SYSTEM_VERSION
4308 is not set, then this variable is the same as CMAKE_HOST_SYSTEM_NAME.
4309
4310 CMAKE_HOST_SYSTEM_NAME
4311 Name of the OS CMake is running on.
4312
4313 On systems that have the uname command, this variable is set to the
4314 output of uname -s. Linux, Windows, and Darwin for macOS are the val‐
4315 ues found on the big three operating systems.
4316
4317 CMAKE_HOST_SYSTEM_PROCESSOR
4318 The name of the CPU CMake is running on.
4319
4320 Windows Platforms
4321 On Windows, this variable is set to the value of the environment vari‐
4322 able PROCESSOR_ARCHITECTURE.
4323
4324 Unix Platforms
4325 On systems that support uname, this variable is set to the output of:
4326
4327 • uname -m on GNU, Linux, Cygwin, Android, or
4328
4329 • arch on OpenBSD, or
4330
4331 • on other systems,
4332
4333 • uname -p if its exit code is nonzero, or
4334
4335 • uname -m otherwise.
4336
4337 macOS Platforms
4338 The value of uname -m is used by default.
4339
4340 On Apple Silicon hosts, the architecture printed by uname -m may vary
4341 based on CMake's own architecture and that of the invoking process
4342 tree.
4343
4344 New in version 3.19.2: On Apple Silicon hosts:
4345
4346 • The CMAKE_APPLE_SILICON_PROCESSOR variable or the
4347 CMAKE_APPLE_SILICON_PROCESSOR environment variable may be set to
4348 specify the host architecture explicitly.
4349
4350 • If CMAKE_OSX_ARCHITECTURES is not set, CMake adds explicit flags to
4351 tell the compiler to build for the host architecture so the toolchain
4352 does not have to guess based on the process tree's architecture.
4353
4354
4355 CMAKE_HOST_SYSTEM_VERSION
4356 The OS version CMake is running on.
4357
4358 A numeric version string for the system. On systems that support un‐
4359 ame, this variable is set to the output of uname -r. On other systems
4360 this is set to major-minor version numbers.
4361
4362 CMAKE_HOST_UNIX
4363 True for UNIX and UNIX like operating systems.
4364
4365 Set to true when the host system is UNIX or UNIX like (i.e. APPLE and
4366 CYGWIN).
4367
4368 CMAKE_HOST_WIN32
4369 True if the host system is running Windows, including Windows 64-bit
4370 and MSYS.
4371
4372 Set to false on Cygwin.
4373
4374 CMAKE_LIBRARY_ARCHITECTURE
4375 Target architecture library directory name, if detected.
4376
4377 This is the value of CMAKE_<LANG>_LIBRARY_ARCHITECTURE as detected for
4378 one of the enabled languages.
4379
4380 CMAKE_LIBRARY_ARCHITECTURE_REGEX
4381 Regex matching possible target architecture library directory names.
4382
4383 This is used to detect CMAKE_<LANG>_LIBRARY_ARCHITECTURE from the im‐
4384 plicit linker search path by matching the <arch> name.
4385
4386 CMAKE_OBJECT_PATH_MAX
4387 Maximum object file full-path length allowed by native build tools.
4388
4389 CMake computes for every source file an object file name that is unique
4390 to the source file and deterministic with respect to the full path to
4391 the source file. This allows multiple source files in a target to
4392 share the same name if they lie in different directories without re‐
4393 building when one is added or removed. However, it can produce long
4394 full paths in a few cases, so CMake shortens the path using a hashing
4395 scheme when the full path to an object file exceeds a limit. CMake has
4396 a built-in limit for each platform that is sufficient for common tools,
4397 but some native tools may have a lower limit. This variable may be set
4398 to specify the limit explicitly. The value must be an integer no less
4399 than 128.
4400
4401 CMAKE_SYSTEM
4402 Composite name of operating system CMake is compiling for.
4403
4404 This variable is the composite of CMAKE_SYSTEM_NAME and
4405 CMAKE_SYSTEM_VERSION, e.g. ${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VER‐
4406 SION}. If CMAKE_SYSTEM_VERSION is not set, then this variable is the
4407 same as CMAKE_SYSTEM_NAME.
4408
4409 CMAKE_SYSTEM_NAME
4410 The name of the operating system for which CMake is to build. See the
4411 CMAKE_SYSTEM_VERSION variable for the OS version.
4412
4413 Note that CMAKE_SYSTEM_NAME is not set to anything by default when run‐
4414 ning in script mode, since it's not building anything.
4415
4416 System Name for Host Builds
4417 CMAKE_SYSTEM_NAME is by default set to the same value as the
4418 CMAKE_HOST_SYSTEM_NAME variable so that the build targets the host sys‐
4419 tem.
4420
4421 System Name for Cross Compiling
4422 CMAKE_SYSTEM_NAME may be set explicitly when first configuring a new
4423 build tree in order to enable cross compiling. In this case the
4424 CMAKE_SYSTEM_VERSION variable must also be set explicitly.
4425
4426 CMAKE_SYSTEM_PROCESSOR
4427 When not cross-compiling, this variable has the same value as the
4428 CMAKE_HOST_SYSTEM_PROCESSOR variable. In many cases, this will corre‐
4429 spond to the target architecture for the build, but this is not guaran‐
4430 teed. (E.g. on Windows, the host may be AMD64 even when using a MSVC
4431 cl compiler with a 32-bit target.)
4432
4433 When cross-compiling, a CMAKE_TOOLCHAIN_FILE should set the CMAKE_SYS‐
4434 TEM_PROCESSOR variable to match target architecture that it specifies
4435 (via CMAKE_<LANG>_COMPILER and perhaps CMAKE_<LANG>_COMPILER_TARGET).
4436
4437 CMAKE_SYSTEM_VERSION
4438 The version of the operating system for which CMake is to build. See
4439 the CMAKE_SYSTEM_NAME variable for the OS name.
4440
4441 System Version for Host Builds
4442 When the CMAKE_SYSTEM_NAME variable takes its default value then
4443 CMAKE_SYSTEM_VERSION is by default set to the same value as the
4444 CMAKE_HOST_SYSTEM_VERSION variable so that the build targets the host
4445 system version.
4446
4447 In the case of a host build then CMAKE_SYSTEM_VERSION may be set ex‐
4448 plicitly when first configuring a new build tree in order to enable
4449 targeting the build for a different version of the host operating sys‐
4450 tem than is actually running on the host. This is allowed and not con‐
4451 sidered cross compiling so long as the binaries built for the specified
4452 OS version can still run on the host.
4453
4454 System Version for Cross Compiling
4455 When the CMAKE_SYSTEM_NAME variable is set explicitly to enable cross
4456 compiling then the value of CMAKE_SYSTEM_VERSION must also be set ex‐
4457 plicitly to specify the target system version.
4458
4459 CYGWIN
4460 True for Cygwin.
4461
4462 Set to true when using Cygwin.
4463
4464 GHSMULTI
4465 New in version 3.3.
4466
4467
4468 1 when using Green Hills MULTI generator.
4469
4470 Also, Set to 1 when the target system is a Green Hills platform (i.e.
4471 When CMAKE_SYSTEM_NAME is GHS-MULTI).
4472
4473 IOS
4474 New in version 3.14.
4475
4476
4477 Set to 1 when the target system (CMAKE_SYSTEM_NAME) is iOS.
4478
4479 LINUX
4480 New in version 3.25.
4481
4482
4483 Set to true when the target system is Linux.
4484
4485 MINGW
4486 New in version 3.2.
4487
4488
4489 Set to a true value when at least one language is enabled with a com‐
4490 piler targeting the GNU ABI on Windows (MinGW).
4491
4492 Otherwise, this variable is not set by CMake.
4493
4494 MSVC
4495 Set to true when the compiler is some version of Microsoft Visual C++
4496 or another compiler simulating the Visual C++ cl command-line syntax.
4497
4498 See also the MSVC_VERSION variable.
4499
4500 MSVC10
4501 Discouraged. Use the MSVC_VERSION variable instead.
4502
4503 True when using the Microsoft Visual Studio v100 toolset (cl version
4504 16) or another compiler that simulates it.
4505
4506 MSVC11
4507 Discouraged. Use the MSVC_VERSION variable instead.
4508
4509 True when using the Microsoft Visual Studio v110 toolset (cl version
4510 17) or another compiler that simulates it.
4511
4512 MSVC12
4513 Discouraged. Use the MSVC_VERSION variable instead.
4514
4515 True when using the Microsoft Visual Studio v120 toolset (cl version
4516 18) or another compiler that simulates it.
4517
4518 MSVC14
4519 New in version 3.1.
4520
4521
4522 Discouraged. Use the MSVC_VERSION variable instead.
4523
4524 True when using the Microsoft Visual Studio v140 or v141 toolset (cl
4525 version 19) or another compiler that simulates it.
4526
4527 MSVC60
4528 Discouraged. Use the MSVC_VERSION variable instead.
4529
4530 True when using Microsoft Visual C++ 6.0.
4531
4532 Set to true when the compiler is version 6.0 of Microsoft Visual C++.
4533
4534 MSVC70
4535 Discouraged. Use the MSVC_VERSION variable instead.
4536
4537 True when using Microsoft Visual C++ 7.0.
4538
4539 Set to true when the compiler is version 7.0 of Microsoft Visual C++.
4540
4541 MSVC71
4542 Discouraged. Use the MSVC_VERSION variable instead.
4543
4544 True when using Microsoft Visual C++ 7.1.
4545
4546 Set to true when the compiler is version 7.1 of Microsoft Visual C++.
4547
4548 MSVC80
4549 Discouraged. Use the MSVC_VERSION variable instead.
4550
4551 True when using the Microsoft Visual Studio v80 toolset (cl version 14)
4552 or another compiler that simulates it.
4553
4554 MSVC90
4555 Discouraged. Use the MSVC_VERSION variable instead.
4556
4557 True when using the Microsoft Visual Studio v90 toolset (cl version 15)
4558 or another compiler that simulates it.
4559
4560 MSVC_IDE
4561 True when using the Microsoft Visual C++ IDE.
4562
4563 Set to true when the target platform is the Microsoft Visual C++ IDE,
4564 as opposed to the command line compiler.
4565
4566 NOTE:
4567 This variable is only available after compiler detection has been
4568 performed, so it is not available to toolchain files or before the
4569 first project() or enable_language() call which uses an MSVC-like
4570 compiler.
4571
4572 MSVC_TOOLSET_VERSION
4573 New in version 3.12.
4574
4575
4576 The toolset version of Microsoft Visual C/C++ being used if any. If
4577 MSVC-like is being used, this variable is set based on the version of
4578 the compiler as given by the MSVC_VERSION variable.
4579
4580 Known toolset version numbers are:
4581
4582 80 = VS 2005 (8.0)
4583 90 = VS 2008 (9.0)
4584 100 = VS 2010 (10.0)
4585 110 = VS 2012 (11.0)
4586 120 = VS 2013 (12.0)
4587 140 = VS 2015 (14.0)
4588 141 = VS 2017 (15.0)
4589 142 = VS 2019 (16.0)
4590 143 = VS 2022 (17.0)
4591
4592 Compiler versions newer than those known to CMake will be reported as
4593 the latest known toolset version.
4594
4595 See also the MSVC_VERSION variable.
4596
4597 MSVC_VERSION
4598 The version of Microsoft Visual C/C++ being used if any. If a compiler
4599 simulating Visual C++ is being used, this variable is set to the
4600 toolset version simulated as given by the _MSC_VER preprocessor defini‐
4601 tion.
4602
4603 Known version numbers are:
4604
4605 1200 = VS 6.0
4606 1300 = VS 7.0
4607 1310 = VS 7.1
4608 1400 = VS 8.0 (v80 toolset)
4609 1500 = VS 9.0 (v90 toolset)
4610 1600 = VS 10.0 (v100 toolset)
4611 1700 = VS 11.0 (v110 toolset)
4612 1800 = VS 12.0 (v120 toolset)
4613 1900 = VS 14.0 (v140 toolset)
4614 1910-1919 = VS 15.0 (v141 toolset)
4615 1920-1929 = VS 16.0 (v142 toolset)
4616 1930-1939 = VS 17.0 (v143 toolset)
4617
4618 See also the CMAKE_<LANG>_COMPILER_VERSION and MSVC_TOOLSET_VERSION
4619 variable.
4620
4621 MSYS
4622 New in version 3.14.
4623
4624
4625 True when using the MSYS Makefiles generator.
4626
4627 UNIX
4628 Set to True when the target system is UNIX or UNIX-like (e.g. APPLE and
4629 CYGWIN). The CMAKE_SYSTEM_NAME variable should be queried if a more
4630 specific understanding of the target system is required.
4631
4632 WIN32
4633 Set to True when the target system is Windows, including Win64.
4634
4635 WINCE
4636 New in version 3.1.
4637
4638
4639 True when the CMAKE_SYSTEM_NAME variable is set to WindowsCE.
4640
4641 WINDOWS_PHONE
4642 New in version 3.1.
4643
4644
4645 True when the CMAKE_SYSTEM_NAME variable is set to WindowsPhone.
4646
4647 WINDOWS_STORE
4648 New in version 3.1.
4649
4650
4651 True when the CMAKE_SYSTEM_NAME variable is set to WindowsStore.
4652
4653 XCODE
4654 New in version 3.7.
4655
4656
4657 True when using Xcode generator.
4658
4659 XCODE_VERSION
4660 Version of Xcode (Xcode generator only).
4661
4662 Under the Xcode generator, this is the version of Xcode as specified in
4663 Xcode.app/Contents/version.plist (such as 3.1.2).
4664
4666 CMAKE_ADSP_ROOT
4667 New in version 3.24.
4668
4669
4670 When Cross Compiling for ADSP SHARC/Blackfin, this variable holds the
4671 absolute path to the latest CCES or VDSP++ install. The directory is
4672 expected to contain the cc21k.exe and ccblkfn.exe compilers. This will
4673 be set automatically if a default install of CCES or VDSP++ can be
4674 found.
4675
4676 See also the ADSP_ROOT environment variable.
4677
4678 CMAKE_AIX_EXPORT_ALL_SYMBOLS
4679 New in version 3.17.
4680
4681
4682 Default value for AIX_EXPORT_ALL_SYMBOLS target property. This vari‐
4683 able is used to initialize the property on each target as it is cre‐
4684 ated.
4685
4686 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
4687 New in version 3.4.
4688
4689
4690 Default value for the ANDROID_ANT_ADDITIONAL_OPTIONS target property.
4691 See that target property for additional information.
4692
4693 CMAKE_ANDROID_API
4694 New in version 3.1.
4695
4696
4697 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4698 Edition, this variable may be set to specify the default value for the
4699 ANDROID_API target property. See that target property for additional
4700 information.
4701
4702 When Cross Compiling for Android, the CMAKE_SYSTEM_VERSION variable
4703 represents the Android API version number targeted. For historical
4704 reasons, if a toolchain file sets CMAKE_ANDROID_API, but not CMAKE_SYS‐
4705 TEM_VERSION, the latter will be initialized using the former.
4706
4707 CMAKE_ANDROID_API_MIN
4708 New in version 3.2.
4709
4710
4711 Default value for the ANDROID_API_MIN target property. See that target
4712 property for additional information.
4713
4714 CMAKE_ANDROID_ARCH
4715 New in version 3.4.
4716
4717
4718 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4719 Edition, this variable may be set to specify the default value for the
4720 ANDROID_ARCH target property. See that target property for additional
4721 information.
4722
4723 Otherwise, when Cross Compiling for Android, this variable provides the
4724 name of the Android architecture corresponding to the value of the
4725 CMAKE_ANDROID_ARCH_ABI variable. The architecture name may be one of:
4726
4727 • arm
4728
4729 • arm64
4730
4731 • mips
4732
4733 • mips64
4734
4735 • x86
4736
4737 • x86_64
4738
4739 CMAKE_ANDROID_ARCH_ABI
4740 New in version 3.7.
4741
4742
4743 When Cross Compiling for Android, this variable specifies the target
4744 architecture and ABI to be used. Valid values are:
4745
4746 • arm64-v8a
4747
4748 • armeabi-v7a
4749
4750 • armeabi-v6
4751
4752 • armeabi
4753
4754 • mips
4755
4756 • mips64
4757
4758 • x86
4759
4760 • x86_64
4761
4762 See also the CMAKE_ANDROID_ARM_MODE and CMAKE_ANDROID_ARM_NEON vari‐
4763 ables.
4764
4765 CMAKE_ANDROID_ARM_MODE
4766 New in version 3.7.
4767
4768
4769 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4770 one of the armeabi architectures, set CMAKE_ANDROID_ARM_MODE to ON to
4771 target 32-bit ARM processors (-marm). Otherwise, the default is to
4772 target the 16-bit Thumb processors (-mthumb).
4773
4774 CMAKE_ANDROID_ARM_NEON
4775 New in version 3.7.
4776
4777
4778 When Cross Compiling for Android and CMAKE_ANDROID_ARCH_ABI is set to
4779 armeabi-v7a set CMAKE_ANDROID_ARM_NEON to ON to target ARM NEON de‐
4780 vices.
4781
4782 CMAKE_ANDROID_ASSETS_DIRECTORIES
4783 New in version 3.4.
4784
4785
4786 Default value for the ANDROID_ASSETS_DIRECTORIES target property. See
4787 that target property for additional information.
4788
4789 CMAKE_ANDROID_EXCEPTIONS
4790 New in version 3.20.
4791
4792
4793 When Cross Compiling for Android with the NDK, this variable may be set
4794 to specify whether exceptions are enabled.
4795
4796 CMAKE_ANDROID_GUI
4797 New in version 3.1.
4798
4799
4800 Default value for the ANDROID_GUI target property of executables. See
4801 that target property for additional information.
4802
4803 CMAKE_ANDROID_JAR_DEPENDENCIES
4804 New in version 3.4.
4805
4806
4807 Default value for the ANDROID_JAR_DEPENDENCIES target property. See
4808 that target property for additional information.
4809
4810 CMAKE_ANDROID_JAR_DIRECTORIES
4811 New in version 3.4.
4812
4813
4814 Default value for the ANDROID_JAR_DIRECTORIES target property. See
4815 that target property for additional information.
4816
4817 CMAKE_ANDROID_JAVA_SOURCE_DIR
4818 New in version 3.4.
4819
4820
4821 Default value for the ANDROID_JAVA_SOURCE_DIR target property. See
4822 that target property for additional information.
4823
4824 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
4825 New in version 3.4.
4826
4827
4828 Default value for the ANDROID_NATIVE_LIB_DEPENDENCIES target property.
4829 See that target property for additional information.
4830
4831 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
4832 New in version 3.4.
4833
4834
4835 Default value for the ANDROID_NATIVE_LIB_DIRECTORIES target property.
4836 See that target property for additional information.
4837
4838 CMAKE_ANDROID_NDK
4839 New in version 3.7.
4840
4841
4842 When Cross Compiling for Android with the NDK, this variable holds the
4843 absolute path to the root directory of the NDK. The directory must
4844 contain a platforms subdirectory holding the android-<api> directories.
4845
4846 CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
4847 New in version 3.9.
4848
4849
4850 When Cross Compiling for Android with the NDK, this variable may be set
4851 to specify whether to use the deprecated per-api-level headers instead
4852 of the unified headers.
4853
4854 If not specified, the default will be false if using a NDK version that
4855 provides the unified headers and true otherwise.
4856
4857 CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
4858 New in version 3.7.1.
4859
4860
4861 When Cross Compiling for Android with the NDK, this variable provides
4862 the NDK's "host tag" used to construct the path to prebuilt toolchains
4863 that run on the host.
4864
4865 CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
4866 New in version 3.7.
4867
4868
4869 When Cross Compiling for Android with the NDK, this variable may be set
4870 to specify the version of the toolchain to be used as the compiler.
4871
4872 On NDK r19 or above, this variable must be unset or set to clang.
4873
4874 On NDK r18 or below, this variable must be set to one of these forms:
4875
4876 • <major>.<minor>: GCC of specified version
4877
4878 • clang<major>.<minor>: Clang of specified version
4879
4880 • clang: Clang of most recent available version
4881
4882 A toolchain of the requested version will be selected automatically to
4883 match the ABI named in the CMAKE_ANDROID_ARCH_ABI variable.
4884
4885 If not specified, the default will be a value that selects the latest
4886 available GCC toolchain.
4887
4888 CMAKE_ANDROID_PROCESS_MAX
4889 New in version 3.4.
4890
4891
4892 Default value for the ANDROID_PROCESS_MAX target property. See that
4893 target property for additional information.
4894
4895 CMAKE_ANDROID_PROGUARD
4896 New in version 3.4.
4897
4898
4899 Default value for the ANDROID_PROGUARD target property. See that tar‐
4900 get property for additional information.
4901
4902 CMAKE_ANDROID_PROGUARD_CONFIG_PATH
4903 New in version 3.4.
4904
4905
4906 Default value for the ANDROID_PROGUARD_CONFIG_PATH target property.
4907 See that target property for additional information.
4908
4909 CMAKE_ANDROID_RTTI
4910 New in version 3.20.
4911
4912
4913 When Cross Compiling for Android with the NDK, this variable may be set
4914 to specify whether RTTI is enabled.
4915
4916 CMAKE_ANDROID_SECURE_PROPS_PATH
4917 New in version 3.4.
4918
4919
4920 Default value for the ANDROID_SECURE_PROPS_PATH target property. See
4921 that target property for additional information.
4922
4923 CMAKE_ANDROID_SKIP_ANT_STEP
4924 New in version 3.4.
4925
4926
4927 Default value for the ANDROID_SKIP_ANT_STEP target property. See that
4928 target property for additional information.
4929
4930 CMAKE_ANDROID_STANDALONE_TOOLCHAIN
4931 New in version 3.7.
4932
4933
4934 When Cross Compiling for Android with a Standalone Toolchain, this
4935 variable holds the absolute path to the root directory of the
4936 toolchain. The specified directory must contain a sysroot subdirec‐
4937 tory.
4938
4939 CMAKE_ANDROID_STL_TYPE
4940 New in version 3.4.
4941
4942
4943 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
4944 Edition, this variable may be set to specify the default value for the
4945 ANDROID_STL_TYPE target property. See that target property for addi‐
4946 tional information.
4947
4948 When Cross Compiling for Android with the NDK, this variable may be set
4949 to specify the STL variant to be used. The value may be one of:
4950
4951 none No C++ Support
4952
4953 system Minimal C++ without STL
4954
4955 gabi++_static
4956 GAbi++ Static
4957
4958 gabi++_shared
4959 GAbi++ Shared
4960
4961 gnustl_static
4962 GNU libstdc++ Static
4963
4964 gnustl_shared
4965 GNU libstdc++ Shared
4966
4967 c++_static
4968 LLVM libc++ Static
4969
4970 c++_shared
4971 LLVM libc++ Shared
4972
4973 stlport_static
4974 STLport Static
4975
4976 stlport_shared
4977 STLport Shared
4978
4979 The default value is gnustl_static on NDK versions that provide it and
4980 otherwise c++_static. Note that this default differs from the native
4981 NDK build system because CMake may be used to build projects for An‐
4982 droid that are not natively implemented for it and use the C++ standard
4983 library.
4984
4985 CMAKE_APPLE_SILICON_PROCESSOR
4986 New in version 3.19.2.
4987
4988
4989 On Apple Silicon hosts running macOS, set this variable to tell CMake
4990 what architecture to use for CMAKE_HOST_SYSTEM_PROCESSOR. The value
4991 must be either arm64 or x86_64.
4992
4993 The value of this variable should never be modified by project code.
4994 It is meant to be set as a cache entry provided by the user, e.g. via
4995 -DCMAKE_APPLE_SILICON_PROCESSOR=....
4996
4997 See also the CMAKE_APPLE_SILICON_PROCESSOR environment variable.
4998
4999 CMAKE_ARCHIVE_OUTPUT_DIRECTORY
5000 Where to put all the ARCHIVE target files when built.
5001
5002 This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY prop‐
5003 erty on all the targets. See that target property for additional in‐
5004 formation.
5005
5006 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
5007 New in version 3.3.
5008
5009
5010 Where to put all the ARCHIVE target files when built for a specific
5011 configuration.
5012
5013 This variable is used to initialize the
5014 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
5015 that target property for additional information.
5016
5017 CMAKE_AUTOGEN_ORIGIN_DEPENDS
5018 New in version 3.14.
5019
5020
5021 Switch for forwarding origin target dependencies to the corresponding
5022 _autogen targets.
5023
5024 This variable is used to initialize the AUTOGEN_ORIGIN_DEPENDS property
5025 on all the targets. See that target property for additional informa‐
5026 tion.
5027
5028 By default CMAKE_AUTOGEN_ORIGIN_DEPENDS is ON.
5029
5030 CMAKE_AUTOGEN_PARALLEL
5031 New in version 3.11.
5032
5033
5034 Number of parallel moc or uic processes to start when using AUTOMOC and
5035 AUTOUIC.
5036
5037 This variable is used to initialize the AUTOGEN_PARALLEL property on
5038 all the targets. See that target property for additional information.
5039
5040 By default CMAKE_AUTOGEN_PARALLEL is unset.
5041
5042 CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
5043 New in version 3.27.
5044
5045
5046 This variable is used to initialize the AUTOGEN_USE_SYSTEM_INCLUDE
5047 property on all targets as they are created. See that target property
5048 for additional information.
5049
5050 By default CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE is unset.
5051
5052 CMAKE_AUTOGEN_VERBOSE
5053 New in version 3.13.
5054
5055
5056 Sets the verbosity of AUTOMOC, AUTOUIC and AUTORCC. A positive integer
5057 value or a true boolean value lets the AUTO* generators output addi‐
5058 tional processing information.
5059
5060 Setting CMAKE_AUTOGEN_VERBOSE has the same effect as setting the VER‐
5061 BOSE environment variable during generation (e.g. by calling make VER‐
5062 BOSE=1). The extra verbosity is limited to the AUTO* generators
5063 though.
5064
5065 By default CMAKE_AUTOGEN_VERBOSE is unset.
5066
5067 CMAKE_AUTOMOC
5068 Whether to handle moc automatically for Qt targets.
5069
5070 This variable is used to initialize the AUTOMOC property on all the
5071 targets. See that target property for additional information.
5072
5073 CMAKE_AUTOMOC_COMPILER_PREDEFINES
5074 New in version 3.10.
5075
5076
5077 This variable is used to initialize the AUTOMOC_COMPILER_PREDEFINES
5078 property on all the targets. See that target property for additional
5079 information.
5080
5081 By default it is ON.
5082
5083 CMAKE_AUTOMOC_DEPEND_FILTERS
5084 New in version 3.9.
5085
5086
5087 Filter definitions used by CMAKE_AUTOMOC to extract file names from
5088 source code as additional dependencies for the moc file.
5089
5090 This variable is used to initialize the AUTOMOC_DEPEND_FILTERS property
5091 on all the targets. See that target property for additional informa‐
5092 tion.
5093
5094 By default it is empty.
5095
5096 CMAKE_AUTOMOC_MACRO_NAMES
5097 New in version 3.10.
5098
5099
5100 Semicolon-separated list list of macro names used by CMAKE_AUTOMOC to
5101 determine if a C++ file needs to be processed by moc.
5102
5103 This variable is used to initialize the AUTOMOC_MACRO_NAMES property on
5104 all the targets. See that target property for additional information.
5105
5106 The default value is Q_OBJECT;Q_GADGET;Q_NAMESPACE;Q_NAMESPACE_EXPORT.
5107
5108 Example
5109 Let CMake know that source files that contain CUSTOM_MACRO must be moc
5110 processed as well:
5111
5112 set(CMAKE_AUTOMOC ON)
5113 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
5114
5115 CMAKE_AUTOMOC_MOC_OPTIONS
5116 Additional options for moc when using CMAKE_AUTOMOC.
5117
5118 This variable is used to initialize the AUTOMOC_MOC_OPTIONS property on
5119 all the targets. See that target property for additional information.
5120
5121 CMAKE_AUTOMOC_PATH_PREFIX
5122 New in version 3.16.
5123
5124
5125 Whether to generate the -p path prefix option for moc on AUTOMOC en‐
5126 abled Qt targets.
5127
5128 This variable is used to initialize the AUTOMOC_PATH_PREFIX property on
5129 all the targets. See that target property for additional information.
5130
5131 The default value is OFF.
5132
5133 CMAKE_AUTOMOC_EXECUTABLE
5134 New in version 3.27.
5135
5136
5137 This variable is used to initialize the AUTOMOC_EXECUTABLE property on
5138 all the targets. See that target property for additional information.
5139
5140 By default it is empty.
5141
5142 CMAKE_AUTORCC
5143 Whether to handle rcc automatically for Qt targets.
5144
5145 This variable is used to initialize the AUTORCC property on all the
5146 targets. See that target property for additional information.
5147
5148 CMAKE_AUTORCC_OPTIONS
5149 Additional options for rcc when using CMAKE_AUTORCC.
5150
5151 This variable is used to initialize the AUTORCC_OPTIONS property on all
5152 the targets. See that target property for additional information.
5153
5154 EXAMPLE
5155 # ...
5156 set(CMAKE_AUTORCC_OPTIONS "--compress;9")
5157 # ...
5158
5159 CMAKE_AUTORCC_EXECUTABLE
5160 New in version 3.27.
5161
5162
5163 This variable is used to initialize the AUTORCC_EXECUTABLE property on
5164 all the targets. See that target property for additional information.
5165
5166 By default it is empty.
5167
5168 CMAKE_AUTOUIC
5169 Whether to handle uic automatically for Qt targets.
5170
5171 This variable is used to initialize the AUTOUIC property on all the
5172 targets. See that target property for additional information.
5173
5174 CMAKE_AUTOUIC_OPTIONS
5175 Additional options for uic when using CMAKE_AUTOUIC.
5176
5177 This variable is used to initialize the AUTOUIC_OPTIONS property on all
5178 the targets. See that target property for additional information.
5179
5180 EXAMPLE
5181 # ...
5182 set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection")
5183 # ...
5184
5185 CMAKE_AUTOUIC_SEARCH_PATHS
5186 New in version 3.9.
5187
5188
5189 Search path list used by CMAKE_AUTOUIC to find included .ui files.
5190
5191 This variable is used to initialize the AUTOUIC_SEARCH_PATHS property
5192 on all the targets. See that target property for additional informa‐
5193 tion.
5194
5195 By default it is empty.
5196
5197 CMAKE_AUTOUIC_EXECUTABLE
5198 New in version 3.27.
5199
5200
5201 This variable is used to initialize the AUTOUIC_EXECUTABLE property on
5202 all the targets. See that target property for additional information.
5203
5204 By default it is empty.
5205
5206 CMAKE_BUILD_RPATH
5207 New in version 3.8.
5208
5209
5210 Semicolon-separated list specifying runtime path (RPATH) entries to add
5211 to binaries linked in the build tree (for platforms that support it).
5212 The entries will not be used for binaries in the install tree. See
5213 also the CMAKE_INSTALL_RPATH variable.
5214
5215 This is used to initialize the BUILD_RPATH target property for all tar‐
5216 gets.
5217
5218 CMAKE_BUILD_RPATH_USE_ORIGIN
5219 New in version 3.14.
5220
5221
5222 Whether to use relative paths for the build RPATH.
5223
5224 This is used to initialize the BUILD_RPATH_USE_ORIGIN target property
5225 for all targets, see that property for more details.
5226
5227 CMAKE_BUILD_WITH_INSTALL_NAME_DIR
5228 New in version 3.9.
5229
5230
5231 Whether to use INSTALL_NAME_DIR on targets in the build tree.
5232
5233 This variable is used to initialize the BUILD_WITH_INSTALL_NAME_DIR
5234 property on all targets.
5235
5236 CMAKE_BUILD_WITH_INSTALL_RPATH
5237 Use the install path for the RPATH.
5238
5239 Normally CMake uses the build tree for the RPATH when building executa‐
5240 bles etc on systems that use RPATH. When the software is installed the
5241 executables etc are relinked by CMake to have the install RPATH. If
5242 this variable is set to true then the software is always built with the
5243 install path for the RPATH and does not need to be relinked when in‐
5244 stalled.
5245
5246 This is used to initialize the BUILD_WITH_INSTALL_RPATH target property
5247 for all targets.
5248
5249 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
5250 New in version 3.1.
5251
5252
5253 Output directory for MS debug symbol .pdb files generated by the com‐
5254 piler while building source files.
5255
5256 This variable is used to initialize the COMPILE_PDB_OUTPUT_DIRECTORY
5257 property on all the targets.
5258
5259 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
5260 New in version 3.1.
5261
5262
5263 Per-configuration output directory for MS debug symbol .pdb files gen‐
5264 erated by the compiler while building source files.
5265
5266 This is a per-configuration version of
5267 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY. This variable is used to initial‐
5268 ize the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property on all the tar‐
5269 gets.
5270
5271 CMAKE_COMPILE_WARNING_AS_ERROR
5272 New in version 3.24.
5273
5274
5275 Specify whether to treat warnings on compile as errors.
5276
5277 This variable is used to initialize the COMPILE_WARNING_AS_ERROR prop‐
5278 erty on all the targets.
5279
5280 CMAKE_<CONFIG>_POSTFIX
5281 Default filename postfix for libraries under configuration <CONFIG>.
5282
5283 When a non-executable target is created its <CONFIG>_POSTFIX target
5284 property is initialized with the value of this variable if it is set.
5285
5286 CMAKE_CROSS_CONFIGS
5287 New in version 3.17.
5288
5289
5290 Specifies a semicolon-separated list of configurations available from
5291 all build-<Config>.ninja files in the Ninja Multi-Config generator.
5292 This variable activates cross-config mode. Targets from each config
5293 specified in this variable can be built from any build-<Config>.ninja
5294 file. Custom commands will use the configuration native to build-<Con‐
5295 fig>.ninja. If it is set to all, all configurations from
5296 CMAKE_CONFIGURATION_TYPES are cross-configs. If it is not specified, or
5297 empty, each build-<Config>.ninja file will only contain build rules for
5298 its own configuration.
5299
5300 The value of this variable must be a subset of
5301 CMAKE_CONFIGURATION_TYPES.
5302
5303 CMAKE_CTEST_ARGUMENTS
5304 New in version 3.17.
5305
5306
5307 Set this to a semicolon-separated list of command-line arguments to
5308 pass to ctest(1) when running tests through the test (or RUN_TESTS)
5309 target of the generated build system.
5310
5311 CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
5312 New in version 3.16.
5313
5314
5315 Default value for CUDA_RESOLVE_DEVICE_SYMBOLS target property when de‐
5316 fined. By default this variable is not defined.
5317
5318 This variable is used to initialize the property on each target as it
5319 is created.
5320
5321 CMAKE_CUDA_RUNTIME_LIBRARY
5322 New in version 3.17.
5323
5324
5325 Select the CUDA runtime library for use when compiling and linking
5326 CUDA. This variable is used to initialize the CUDA_RUNTIME_LIBRARY
5327 property on all targets as they are created.
5328
5329 The allowed case insensitive values are:
5330
5331 None Link with -cudart=none or equivalent flag(s) to use no CUDA run‐
5332 time library.
5333
5334 Shared Link with -cudart=shared or equivalent flag(s) to use a dynami‐
5335 cally-linked CUDA runtime library.
5336
5337 Static Link with -cudart=static or equivalent flag(s) to use a stati‐
5338 cally-linked CUDA runtime library.
5339
5340 Contents of CMAKE_CUDA_RUNTIME_LIBRARY may use generator expressions.
5341
5342 If this variable is not set then the CUDA_RUNTIME_LIBRARY target prop‐
5343 erty will not be set automatically. If that property is not set then
5344 CMake uses an appropriate default value based on the compiler to select
5345 the CUDA runtime library.
5346
5347 NOTE:
5348 This property has effect only when the CUDA language is enabled. To
5349 control the CUDA runtime linking when only using the CUDA SDK with
5350 the C or C++ language we recommend using the FindCUDAToolkit module.
5351
5352 CMAKE_CUDA_SEPARABLE_COMPILATION
5353 New in version 3.11.
5354
5355
5356 Default value for CUDA_SEPARABLE_COMPILATION target property. This
5357 variable is used to initialize the property on each target as it is
5358 created.
5359
5360 CMAKE_CXX_SCAN_FOR_MODULES
5361 New in version 3.26.
5362
5363
5364 Whether to scan C++ source files for module dependencies.
5365
5366 This variable is used to initialize the CXX_SCAN_FOR_MODULES property
5367 on all the targets. See that target property for additional informa‐
5368 tion.
5369
5370 NOTE:
5371 This setting is meaningful only when experimental support for C++
5372 modules has been enabled by the CMAKE_EXPERIMENTAL_CXX_MOD‐
5373 ULE_CMAKE_API gate.
5374
5375 CMAKE_DEBUG_POSTFIX
5376 See variable CMAKE_<CONFIG>_POSTFIX.
5377
5378 This variable is a special case of the more-general
5379 CMAKE_<CONFIG>_POSTFIX variable for the DEBUG configuration.
5380
5381 CMAKE_DEFAULT_BUILD_TYPE
5382 New in version 3.17.
5383
5384
5385 Specifies the configuration to use by default in a build.ninja file in
5386 the Ninja Multi-Config generator. If this variable is specified,
5387 build.ninja uses build rules from build-<Config>.ninja by default. All
5388 custom commands are executed with this configuration. If the variable
5389 is not specified, the first item from CMAKE_CONFIGURATION_TYPES is used
5390 instead.
5391
5392 The value of this variable must be one of the items from
5393 CMAKE_CONFIGURATION_TYPES.
5394
5395 CMAKE_DEFAULT_CONFIGS
5396 New in version 3.17.
5397
5398
5399 Specifies a semicolon-separated list of configurations to build for a
5400 target in build.ninja if no :<Config> suffix is specified in the Ninja
5401 Multi-Config generator. If it is set to all, all configurations from
5402 CMAKE_CROSS_CONFIGS are used. If it is not specified, it defaults to
5403 CMAKE_DEFAULT_BUILD_TYPE.
5404
5405 For example, if you set CMAKE_DEFAULT_BUILD_TYPE to Release, but set
5406 CMAKE_DEFAULT_CONFIGS to Debug or all, all <target> aliases in
5407 build.ninja will resolve to <target>:Debug or <target>:all, but custom
5408 commands will still use the Release configuration.
5409
5410 The value of this variable must be a subset of CMAKE_CROSS_CONFIGS or
5411 be the same as CMAKE_DEFAULT_BUILD_TYPE. It must not be specified if
5412 CMAKE_DEFAULT_BUILD_TYPE or CMAKE_CROSS_CONFIGS is not used.
5413
5414 CMAKE_DEPENDS_USE_COMPILER
5415 New in version 3.20.
5416
5417
5418 For the Makefile Generators, source dependencies are now, for a selec‐
5419 tion of compilers, generated by the compiler itself. By defining this
5420 variable with value FALSE, you can restore the legacy behavior (i.e.
5421 using CMake for dependencies discovery).
5422
5423 CMAKE_DISABLE_PRECOMPILE_HEADERS
5424 New in version 3.16.
5425
5426
5427 Default value for DISABLE_PRECOMPILE_HEADERS of targets.
5428
5429 By default CMAKE_DISABLE_PRECOMPILE_HEADERS is OFF.
5430
5431 CMAKE_DLL_NAME_WITH_SOVERSION
5432 New in version 3.27.
5433
5434
5435 This variable is used to initialize the DLL_NAME_WITH_SOVERSION prop‐
5436 erty on shared library targets for the Windows platform, which is se‐
5437 lected when the WIN32 variable is set.
5438
5439 See this target property for additional information.
5440
5441 Please note that setting this variable has no effect if versioned file‐
5442 names are globally disabled with the CMAKE_PLATFORM_NO_VERSIONED_SONAME
5443 variable.
5444
5445 CMAKE_ENABLE_EXPORTS
5446 New in version 3.4.
5447
5448
5449 Specify whether executables export symbols for loadable modules.
5450
5451 This variable is used to initialize the ENABLE_EXPORTS target property
5452 for executable targets when they are created by calls to the
5453 add_executable() command. See the property documentation for details.
5454
5455 This variable has been superseded by the
5456 CMAKE_EXECUTABLE_ENABLE_EXPORTS variable. It is provided for backward
5457 compatibility with older CMake code, but should not be used in new
5458 projects.
5459
5460 CMAKE_EXECUTABLE_ENABLE_EXPORTS
5461 New in version 3.27.
5462
5463
5464 Specify whether executables export symbols for loadable modules.
5465
5466 This variable is used to initialize the ENABLE_EXPORTS target property
5467 for executable targets when they are created by calls to the
5468 add_executable() command. See the property documentation for details.
5469
5470 This variable supersede the CMAKE_ENABLE_EXPORTS variable.
5471
5472 CMAKE_EXE_LINKER_FLAGS
5473 Linker flags to be used to create executables.
5474
5475 These flags will be used by the linker when creating an executable.
5476
5477 CMAKE_EXE_LINKER_FLAGS_<CONFIG>
5478 Flags to be used when linking an executable.
5479
5480 Same as CMAKE_C_FLAGS_* but used by the linker when creating executa‐
5481 bles.
5482
5483 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT
5484 New in version 3.7.
5485
5486
5487 Value used to initialize the CMAKE_EXE_LINKER_FLAGS_<CONFIG> cache en‐
5488 try the first time a build tree is configured. This variable is meant
5489 to be set by a toolchain file. CMake may prepend or append content to
5490 the value based on the environment and target platform.
5491
5492 See also CMAKE_EXE_LINKER_FLAGS_INIT.
5493
5494 CMAKE_EXE_LINKER_FLAGS_INIT
5495 New in version 3.7.
5496
5497
5498 Value used to initialize the CMAKE_EXE_LINKER_FLAGS cache entry the
5499 first time a build tree is configured. This variable is meant to be
5500 set by a toolchain file. CMake may prepend or append content to the
5501 value based on the environment and target platform.
5502
5503 See also the configuration-specific variable
5504 CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT.
5505
5506 CMAKE_FOLDER
5507 New in version 3.12.
5508
5509
5510 Set the folder name. Use to organize targets in an IDE.
5511
5512 This variable is used to initialize the FOLDER property on all the tar‐
5513 gets. See that target property for additional information.
5514
5515 CMAKE_Fortran_FORMAT
5516 Set to FIXED or FREE to indicate the Fortran source layout.
5517
5518 This variable is used to initialize the Fortran_FORMAT property on all
5519 the targets. See that target property for additional information.
5520
5521 CMAKE_Fortran_MODULE_DIRECTORY
5522 Fortran module output directory.
5523
5524 This variable is used to initialize the Fortran_MODULE_DIRECTORY prop‐
5525 erty on all the targets. See that target property for additional in‐
5526 formation.
5527
5528 CMAKE_Fortran_PREPROCESS
5529 New in version 3.18.
5530
5531
5532 Default value for Fortran_PREPROCESS of targets.
5533
5534 This variable is used to initialize the Fortran_PREPROCESS property on
5535 all the targets. See that target property for additional information.
5536
5537 CMAKE_FRAMEWORK
5538 New in version 3.15.
5539
5540
5541 Default value for FRAMEWORK of targets.
5542
5543 This variable is used to initialize the FRAMEWORK property on all the
5544 targets. See that target property for additional information.
5545
5546 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
5547 New in version 3.18.
5548
5549
5550 Default framework filename postfix under configuration <CONFIG> when
5551 using a multi-config generator.
5552
5553 When a framework target is created its
5554 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property is initialized
5555 with the value of this variable if it is set.
5556
5557 CMAKE_GHS_NO_SOURCE_GROUP_FILE
5558 New in version 3.14.
5559
5560
5561 ON / OFF boolean to control if the project file for a target should be
5562 one single file or multiple files. Refer to GHS_NO_SOURCE_GROUP_FILE
5563 for further details.
5564
5565 CMAKE_GLOBAL_AUTOGEN_TARGET
5566 New in version 3.14.
5567
5568
5569 Switch to enable generation of a global autogen target.
5570
5571 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a custom target autogen is
5572 generated. This target depends on all AUTOMOC and AUTOUIC generated
5573 <ORIGIN>_autogen targets in the project. By building the global auto‐
5574 gen target, all AUTOMOC and AUTOUIC files in the project will be gener‐
5575 ated.
5576
5577 The name of the global autogen target can be changed by setting
5578 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.
5579
5580 By default CMAKE_GLOBAL_AUTOGEN_TARGET is unset.
5581
5582 See the cmake-qt(7) manual for more information on using CMake with Qt.
5583
5584 Note
5585 <ORIGIN>_autogen targets by default inherit their origin target's de‐
5586 pendencies. This might result in unintended dependency target builds
5587 when only <ORIGIN>_autogen targets are built. A solution is to disable
5588 AUTOGEN_ORIGIN_DEPENDS on the respective origin targets.
5589
5590 CMAKE_GLOBAL_AUTOGEN_TARGET_NAME
5591 New in version 3.14.
5592
5593
5594 Change the name of the global autogen target.
5595
5596 When CMAKE_GLOBAL_AUTOGEN_TARGET is enabled, a global custom target
5597 named autogen is created. CMAKE_GLOBAL_AUTOGEN_TARGET_NAME allows to
5598 set a different name for that target.
5599
5600 By default CMAKE_GLOBAL_AUTOGEN_TARGET_NAME is unset.
5601
5602 See the cmake-qt(7) manual for more information on using CMake with Qt.
5603
5604 CMAKE_GLOBAL_AUTORCC_TARGET
5605 New in version 3.14.
5606
5607
5608 Switch to enable generation of a global autorcc target.
5609
5610 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a custom target autorcc is
5611 generated. This target depends on all AUTORCC generated <ORI‐
5612 GIN>_arcc_<QRC> targets in the project. By building the global autorcc
5613 target, all AUTORCC files in the project will be generated.
5614
5615 The name of the global autorcc target can be changed by setting
5616 CMAKE_GLOBAL_AUTORCC_TARGET_NAME.
5617
5618 By default CMAKE_GLOBAL_AUTORCC_TARGET is unset.
5619
5620 See the cmake-qt(7) manual for more information on using CMake with Qt.
5621
5622 CMAKE_GLOBAL_AUTORCC_TARGET_NAME
5623 New in version 3.14.
5624
5625
5626 Change the name of the global autorcc target.
5627
5628 When CMAKE_GLOBAL_AUTORCC_TARGET is enabled, a global custom target
5629 named autorcc is created. CMAKE_GLOBAL_AUTORCC_TARGET_NAME allows to
5630 set a different name for that target.
5631
5632 By default CMAKE_GLOBAL_AUTORCC_TARGET_NAME is unset.
5633
5634 See the cmake-qt(7) manual for more information on using CMake with Qt.
5635
5636 CMAKE_GNUtoMS
5637 Convert GNU import libraries (.dll.a) to MS format (.lib).
5638
5639 This variable is used to initialize the GNUtoMS property on targets
5640 when they are created. See that target property for additional infor‐
5641 mation.
5642
5643 CMAKE_INCLUDE_CURRENT_DIR
5644 Automatically add the current source and build directories to the in‐
5645 clude path.
5646
5647 If this variable is enabled, CMake automatically adds
5648 CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the include
5649 path for each directory. These additional include directories do not
5650 propagate down to subdirectories. This is useful mainly for
5651 out-of-source builds, where files generated into the build tree are in‐
5652 cluded by files located in the source tree.
5653
5654 By default CMAKE_INCLUDE_CURRENT_DIR is OFF.
5655
5656 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
5657 Automatically add the current source and build directories to the
5658 INTERFACE_INCLUDE_DIRECTORIES target property.
5659
5660 If this variable is enabled, CMake automatically adds for each shared
5661 library target, static library target, module target and executable
5662 target, CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_BINARY_DIR to the
5663 INTERFACE_INCLUDE_DIRECTORIES target property. By default CMAKE_IN‐
5664 CLUDE_CURRENT_DIR_IN_INTERFACE is OFF.
5665
5666 CMAKE_INSTALL_NAME_DIR
5667 Directory name for installed targets on Apple platforms.
5668
5669 CMAKE_INSTALL_NAME_DIR is used to initialize the INSTALL_NAME_DIR prop‐
5670 erty on all targets. See that target property for more information.
5671
5672 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH
5673 New in version 3.16.
5674
5675
5676 Sets the default for whether toolchain-defined rpaths should be removed
5677 during installation.
5678
5679 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH is a boolean that provides the
5680 default value for the INSTALL_REMOVE_ENVIRONMENT_RPATH property of all
5681 subsequently created targets.
5682
5683 CMAKE_INSTALL_RPATH
5684 The rpath to use for installed targets.
5685
5686 A semicolon-separated list specifying the rpath to use in installed
5687 targets (for platforms that support it). This is used to initialize
5688 the target property INSTALL_RPATH for all targets.
5689
5690 CMAKE_INSTALL_RPATH_USE_LINK_PATH
5691 Add paths to linker search and installed rpath.
5692
5693 CMAKE_INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to True will
5694 append to the runtime search path (rpath) of installed binaries any di‐
5695 rectories outside the project that are in the linker search path or
5696 contain linked library files. The directories are appended after the
5697 value of the INSTALL_RPATH target property.
5698
5699 This variable is used to initialize the target property
5700 INSTALL_RPATH_USE_LINK_PATH for all targets.
5701
5702 CMAKE_INTERPROCEDURAL_OPTIMIZATION
5703 New in version 3.9.
5704
5705
5706 Default value for INTERPROCEDURAL_OPTIMIZATION of targets.
5707
5708 This variable is used to initialize the INTERPROCEDURAL_OPTIMIZATION
5709 property on all the targets. See that target property for additional
5710 information.
5711
5712 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5713 New in version 3.9.
5714
5715
5716 Default value for INTERPROCEDURAL_OPTIMIZATION_<CONFIG> of targets.
5717
5718 This variable is used to initialize the
5719 INTERPROCEDURAL_OPTIMIZATION_<CONFIG> property on all the targets. See
5720 that target property for additional information.
5721
5722 CMAKE_IOS_INSTALL_COMBINED
5723 New in version 3.5.
5724
5725
5726 Default value for IOS_INSTALL_COMBINED of targets.
5727
5728 This variable is used to initialize the IOS_INSTALL_COMBINED property
5729 on all the targets. See that target property for additional informa‐
5730 tion.
5731
5732 CMAKE_<LANG>_CLANG_TIDY
5733 New in version 3.6.
5734
5735
5736 Default value for <LANG>_CLANG_TIDY target property when <LANG> is C,
5737 CXX, OBJC or OBJCXX.
5738
5739 This variable is used to initialize the property on each target as it
5740 is created. For example:
5741
5742 set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*)
5743 add_executable(foo foo.cxx)
5744
5745 CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR
5746 New in version 3.26.
5747
5748
5749 Default value for <LANG>_CLANG_TIDY_EXPORT_FIXES_DIR target property
5750 when <LANG> is C, CXX, OBJC or OBJCXX.
5751
5752 This variable is used to initialize the property on each target as it
5753 is created. For example:
5754
5755 set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR clang-tidy-fixes)
5756 add_executable(foo foo.cxx)
5757
5758 CMAKE_<LANG>_COMPILER_LAUNCHER
5759 New in version 3.4.
5760
5761
5762 Default value for <LANG>_COMPILER_LAUNCHER target property. This vari‐
5763 able is used to initialize the property on each target as it is cre‐
5764 ated. This is done only when <LANG> is C, CXX, Fortran, HIP, ISPC,
5765 OBJC, OBJCXX, or CUDA.
5766
5767 This variable is initialized to the CMAKE_<LANG>_COMPILER_LAUNCHER en‐
5768 vironment variable if it is set.
5769
5770 CMAKE_<LANG>_CPPCHECK
5771 New in version 3.10.
5772
5773
5774 Default value for <LANG>_CPPCHECK target property. This variable is
5775 used to initialize the property on each target as it is created. This
5776 is done only when <LANG> is C or CXX.
5777
5778 CMAKE_<LANG>_CPPLINT
5779 New in version 3.8.
5780
5781
5782 Default value for <LANG>_CPPLINT target property. This variable is used
5783 to initialize the property on each target as it is created. This is
5784 done only when <LANG> is C or CXX.
5785
5786 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE
5787 New in version 3.3.
5788
5789
5790 Default value for <LANG>_INCLUDE_WHAT_YOU_USE target property. This
5791 variable is used to initialize the property on each target as it is
5792 created. This is done only when <LANG> is C or CXX.
5793
5794 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>
5795 New in version 3.24.
5796
5797
5798 This variable defines how to link a group of libraries for the speci‐
5799 fied <FEATURE> when a LINK_GROUP generator expression is used and the
5800 link language for the target is <LANG>. For this variable to have any
5801 effect, the associated
5802 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be set
5803 to true.
5804
5805 The CMAKE_LINK_GROUP_USING_<FEATURE> variable should be defined instead
5806 for features that are independent of the link language.
5807
5808 Feature names are case-sensitive and may only contain letters, numbers
5809 and underscores. Feature names defined in all uppercase are reserved
5810 for CMake's own built-in features (see Predefined Features further be‐
5811 low).
5812
5813 Feature Definitions
5814 A group feature definition is a list that contains exactly two ele‐
5815 ments:
5816
5817 <PREFIX> <SUFFIX>
5818
5819 On the linker command line, <PREFIX> will precede the list of libraries
5820 in the group and <SUFFIX> will follow after.
5821
5822 For the elements of this variable, the LINKER: prefix can be used.
5823
5824 To pass options to the linker tool, each compiler driver has its own
5825 syntax. The LINKER: prefix and , separator can be used to specify, in
5826 a portable way, options to pass to the linker tool. LINKER: is replaced
5827 by the appropriate driver option and , by the appropriate driver sepa‐
5828 rator. The driver prefix and driver separator are given by the values
5829 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
5830 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
5831
5832 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5833 Clang and -Wl,-z,defs for GNU GCC.
5834
5835 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5836 sion.
5837
5838 The LINKER: prefix supports, as an alternative syntax, specification of
5839 arguments using the SHELL: prefix and space as separator. The previous
5840 example then becomes "LINKER:SHELL:-z defs".
5841
5842 NOTE:
5843 Specifying the SHELL: prefix anywhere other than at the beginning of
5844 the LINKER: prefix is not supported.
5845
5846 Examples
5847 Solving cross-references between two static libraries
5848 A project may define two or more static libraries which have circular
5849 dependencies between them. In order for the linker to resolve all sym‐
5850 bols at link time, it may need to search repeatedly among the libraries
5851 until no new undefined references are created. Different linkers use
5852 different syntax for achieving this. The following example shows how
5853 this may be implemented for some linkers. Note that this is for illus‐
5854 tration purposes only. Projects should use the built-in RESCAN group
5855 feature instead (see Predefined Features), which provides a more com‐
5856 plete and more robust implementation of this functionality.
5857
5858 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
5859 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
5860 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5861 "LINKER:--start-group"
5862 "LINKER:--end-group"
5863 )
5864 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
5865 set(CMAKE_C_LINK_GROUP_USING_cross_refs
5866 "LINKER:-z,rescan-start"
5867 "LINKER:-z,rescan-end"
5868 )
5869 else()
5870 # feature not yet supported for the other environments
5871 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
5872 endif()
5873
5874 add_library(lib1 STATIC ...)
5875 add_library(lib2 SHARED ...)
5876
5877 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
5878 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
5879 else()
5880 target_link_libraries(lib2 PRIVATE lib1 external)
5881 endif()
5882
5883 CMake will generate the following linker command line fragments when
5884 linking lib2:
5885
5886 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
5887
5888 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
5889 can-end
5890
5891 Predefined Features
5892 The following built-in group features are pre-defined by CMake:
5893
5894 RESCAN Some linkers are single-pass only. For such linkers, circular
5895 references between libraries typically result in unresolved sym‐
5896 bols. This feature instructs the linker to search the specified
5897 static libraries repeatedly until no new undefined references
5898 are created.
5899
5900 Normally, a static library is searched only once in the order
5901 that it is specified on the command line. If a symbol in that
5902 library is needed to resolve an undefined symbol referred to by
5903 an object in a library that appears later on the command line,
5904 the linker would not be able to resolve that reference. By
5905 grouping the static libraries with the RESCAN feature, they will
5906 all be searched repeatedly until all possible references are re‐
5907 solved. This will use linker options like --start-group and
5908 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
5909
5910 Using this feature has a significant performance cost. It is
5911 best to use it only when there are unavoidable circular refer‐
5912 ences between two or more static libraries.
5913
5914 This feature is available when using toolchains that target
5915 Linux, BSD, and SunOS. It can also be used when targeting Win‐
5916 dows platforms if the GNU toolchain is used.
5917
5918 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
5919 New in version 3.24.
5920
5921
5922 This variable specifies whether the <FEATURE> is supported for the link
5923 language <LANG>. If this variable is true, then the <FEATURE> must be
5924 defined by CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>, and the more
5925 generic CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED and
5926 CMAKE_LINK_GROUP_USING_<FEATURE> variables are not used.
5927
5928 If CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is false or is not
5929 set, then the CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable will
5930 determine whether <FEATURE> is deemed to be supported.
5931
5932 CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG
5933 New in version 3.16.
5934
5935
5936 Language-specific flag to be used to link a library specified by a path
5937 to its file.
5938
5939 The flag will be used before a library file path is given to the
5940 linker. This is needed only on very few platforms.
5941
5942 CMAKE_<LANG>_LINK_LIBRARY_FLAG
5943 New in version 3.16.
5944
5945
5946 Flag to be used to link a library into a shared library or executable.
5947
5948 This flag will be used to specify a library to link to a shared library
5949 or an executable for the specific language. On most compilers this is
5950 -l.
5951
5952 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>
5953 New in version 3.24.
5954
5955
5956 This variable defines how to link a library or framework for the speci‐
5957 fied <FEATURE> when a LINK_LIBRARY generator expression is used and the
5958 link language for the target is <LANG>. For this variable to have any
5959 effect, the associated
5960 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
5961 set to true.
5962
5963 The CMAKE_LINK_LIBRARY_USING_<FEATURE> variable should be defined in‐
5964 stead for features that are independent of the link language.
5965
5966 Feature names are case-sensitive and may only contain letters, numbers
5967 and underscores. Feature names defined in all uppercase are reserved
5968 for CMake's own built-in features (see Predefined Features further be‐
5969 low).
5970
5971 Feature Definitions
5972 A library feature definition is a list that contains one or three ele‐
5973 ments:
5974
5975 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
5976
5977 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
5978 spectively the whole list of libraries specified in the LINK_LIBRARY
5979 expression, not each library item individually. There is no guarantee
5980 that the list of specified libraries will be kept grouped together
5981 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
5982 library list is reorganized by CMake to satisfy other constraints.
5983 This means constructs like --start-group and --end-group, as supported
5984 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
5985 erator expression should be used instead for such constructs.
5986
5987 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
5988 the corresponding fragment on the linker command line for each library.
5989 The following placeholders can be used in the expression:
5990
5991 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
5992 gets, or to a platform-specific value based on the item otherwise
5993 (the same as <LINK_ITEM> on Windows, or the library base name for
5994 other platforms).
5995
5996 • <LINK_ITEM> is expanded to how the library would normally be linked
5997 on the linker command line.
5998
5999 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
6000 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
6001 SION> otherwise.
6002
6003 In addition to the above, it is possible to have one pattern for paths
6004 (CMake targets and external libraries specified with file paths) and
6005 another for other items specified by name only. The PATH{} and NAME{}
6006 wrappers can be used to provide the expansion for those two cases, re‐
6007 spectively. When wrappers are used, both must be present. For exam‐
6008 ple:
6009
6010 set(CMAKE_LINK_LIBRARY_USING_weak_library
6011 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6012 )
6013
6014 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
6015 SION>, and <SUFFIX>), the LINKER: prefix can be used.
6016
6017 To pass options to the linker tool, each compiler driver has its own
6018 syntax. The LINKER: prefix and , separator can be used to specify, in
6019 a portable way, options to pass to the linker tool. LINKER: is replaced
6020 by the appropriate driver option and , by the appropriate driver sepa‐
6021 rator. The driver prefix and driver separator are given by the values
6022 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6023 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6024
6025 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6026 Clang and -Wl,-z,defs for GNU GCC.
6027
6028 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6029 sion.
6030
6031 The LINKER: prefix supports, as an alternative syntax, specification of
6032 arguments using the SHELL: prefix and space as separator. The previous
6033 example then becomes "LINKER:SHELL:-z defs".
6034
6035 NOTE:
6036 Specifying the SHELL: prefix anywhere other than at the beginning of
6037 the LINKER: prefix is not supported.
6038
6039 Examples
6040 Loading a whole static library
6041 A common need is to prevent the linker from discarding any symbols from
6042 a static library. Different linkers use different syntax for achieving
6043 this. The following example shows how this may be implemented for some
6044 linkers. Note that this is for illustration purposes only. Projects
6045 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
6046 Features), which provides a more complete and more robust implementa‐
6047 tion of this functionality.
6048
6049 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
6050 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6051 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
6052 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6053 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
6054 "LINKER:--push-state,--whole-archive"
6055 "<LINK_ITEM>"
6056 "LINKER:--pop-state"
6057 )
6058 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
6059 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
6060 else()
6061 # feature not yet supported for the other environments
6062 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
6063 endif()
6064
6065 add_library(lib1 STATIC ...)
6066 add_library(lib2 SHARED ...)
6067
6068 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
6069 # The -force_load Apple linker option requires a file name
6070 set(external_lib
6071 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
6072 )
6073 target_link_libraries(lib2 PRIVATE
6074 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
6075 )
6076 else()
6077 target_link_libraries(lib2 PRIVATE lib1 external)
6078 endif()
6079
6080 CMake will generate the following link expressions:
6081
6082 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
6083
6084 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
6085 -Wl,--pop-state
6086
6087 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
6088
6089 Linking a library as weak
6090 On macOS, it is possible to link a library in weak mode (the library
6091 and all references are marked as weak imports). Different flags must
6092 be used for a library specified by file path compared to one specified
6093 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
6094 pers. Again, the following example shows how this may be implemented
6095 for some linkers, but it is for illustration purposes only. Projects
6096 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
6097 (see Predefined Features), which provide more complete and more robust
6098 implementations of this functionality.
6099
6100 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6101 set(CMAKE_LINK_LIBRARY_USING_weak_library
6102 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6103 )
6104 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
6105 endif()
6106
6107 add_library(lib SHARED ...)
6108 add_executable(main ...)
6109 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
6110 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
6111 else()
6112 target_link_libraries(main PRIVATE lib external)
6113 endif()
6114
6115 CMake will generate the following linker command line fragment when
6116 linking main using the AppleClang toolchain:
6117
6118 -weak_library /path/to/lib -Xlinker -weak-lexternal.
6119
6120 Predefined Features
6121 The following built-in library features are pre-defined by CMake:
6122
6123 DEFAULT
6124 This feature corresponds to standard linking, essentially equiv‐
6125 alent to using no feature at all. It is typically only used
6126 with the LINK_LIBRARY_OVERRIDE and
6127 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
6128
6129 WHOLE_ARCHIVE
6130 Force inclusion of all members of a static library. This fea‐
6131 ture is only supported for the following platforms, with limita‐
6132 tions as noted:
6133
6134 • Linux.
6135
6136 • All BSD variants.
6137
6138 • SunOS.
6139
6140 • All Apple variants. The library must be specified as a CMake
6141 target name, a library file name (such as libfoo.a), or a li‐
6142 brary file path (such as /path/to/libfoo.a). Due to a limita‐
6143 tion of the Apple linker, it cannot be specified as a plain
6144 library name like foo, where foo is not a CMake target.
6145
6146 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
6147 version must be greater than 1900.
6148
6149 • Cygwin.
6150
6151 • MSYS.
6152
6153 FRAMEWORK
6154 This option tells the linker to search for the specified frame‐
6155 work using the -framework linker option. It can only be used on
6156 Apple platforms, and only with a linker that understands the op‐
6157 tion used (i.e. the linker provided with Xcode, or one compati‐
6158 ble with it).
6159
6160 The framework can be specified as a CMake framework target, a
6161 bare framework name, or a file path. If a target is given, that
6162 target must have the FRAMEWORK target property set to true. For
6163 a file path, if it contains a directory part, that directory
6164 will be added as a framework search path.
6165
6166 add_library(lib SHARED ...)
6167 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
6168
6169 # The constructed linker command line will contain:
6170 # -F/path/to -framework my_framework
6171
6172 File paths must conform to one of the following patterns (* is a
6173 wildcard, and optional parts are shown as [...]):
6174
6175 • [/path/to/]FwName[.framework]
6176
6177 • [/path/to/]FwName.framework/FwName[suffix]
6178
6179 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
6180
6181 Note that CMake recognizes and automatically handles framework
6182 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
6183 expression. The generator expression can still be used with a
6184 CMake target if the project wants to be explicit about it, but
6185 it is not required to do so. The linker command line may have
6186 some differences between using the generator expression or not,
6187 but the final result should be the same. On the other hand, if
6188 a file path is given, CMake will recognize some paths automati‐
6189 cally, but not all cases. The project may want to use
6190 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
6191 pected behavior is clear.
6192
6193 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
6194 target property as well as the suffix of the framework library
6195 name are now supported by the FRAMEWORK features.
6196
6197
6198 NEEDED_FRAMEWORK
6199 This is similar to the FRAMEWORK feature, except it forces the
6200 linker to link with the framework even if no symbols are used
6201 from it. It uses the -needed_framework option and has the same
6202 linker constraints as FRAMEWORK.
6203
6204 REEXPORT_FRAMEWORK
6205 This is similar to the FRAMEWORK feature, except it tells the
6206 linker that the framework should be available to clients linking
6207 to the library being created. It uses the -reexport_framework
6208 option and has the same linker constraints as FRAMEWORK.
6209
6210 WEAK_FRAMEWORK
6211 This is similar to the FRAMEWORK feature, except it forces the
6212 linker to mark the framework and all references to it as weak
6213 imports. It uses the -weak_framework option and has the same
6214 linker constraints as FRAMEWORK.
6215
6216 NEEDED_LIBRARY
6217 This is similar to the NEEDED_FRAMEWORK feature, except it is
6218 for use with non-framework targets or libraries (Apple platforms
6219 only). It uses the -needed_library or -needed-l option as ap‐
6220 propriate, and has the same linker constraints as NEEDED_FRAME‐
6221 WORK.
6222
6223 REEXPORT_LIBRARY
6224 This is similar to the REEXPORT_FRAMEWORK feature, except it is
6225 for use with non-framework targets or libraries (Apple platforms
6226 only). It uses the -reexport_library or -reexport-l option as
6227 appropriate, and has the same linker constraints as REEX‐
6228 PORT_FRAMEWORK.
6229
6230 WEAK_LIBRARY
6231 This is similar to the WEAK_FRAMEWORK feature, except it is for
6232 use with non-framework targets or libraries (Apple platforms
6233 only). It uses the -weak_library or -weak-l option as appropri‐
6234 ate, and has the same linker constraints as WEAK_FRAMEWORK.
6235
6236 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
6237 New in version 3.24.
6238
6239
6240 Set to TRUE if the <FEATURE>, as defined by variable
6241 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>, is supported for the linker
6242 language <LANG>.
6243
6244 NOTE:
6245 This variable is evaluated before the more generic variable
6246 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED.
6247
6248 CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG
6249 New in version 3.22.
6250
6251
6252 Linker flag to be used to configure linker so that all specified li‐
6253 braries on the command line will be linked into the target.
6254
6255 See also variable CMAKE_LINK_WHAT_YOU_USE_CHECK.
6256
6257 CMAKE_<LANG>_LINKER_LAUNCHER
6258 New in version 3.21.
6259
6260
6261 Default value for <LANG>_LINKER_LAUNCHER target property. This variable
6262 is used to initialize the property on each target as it is created.
6263 This is done only when <LANG> is C, CXX, OBJC, or OBJCXX.
6264
6265 This variable is initialized to the CMAKE_<LANG>_LINKER_LAUNCHER envi‐
6266 ronment variable if it is set.
6267
6268 CMAKE_<LANG>_VISIBILITY_PRESET
6269 Default value for the <LANG>_VISIBILITY_PRESET target property when a
6270 target is created.
6271
6272 CMAKE_LIBRARY_OUTPUT_DIRECTORY
6273 Where to put all the LIBRARY target files when built.
6274
6275 This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY prop‐
6276 erty on all the targets. See that target property for additional in‐
6277 formation.
6278
6279 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
6280 New in version 3.3.
6281
6282
6283 Where to put all the LIBRARY target files when built for a specific
6284 configuration.
6285
6286 This variable is used to initialize the
6287 LIBRARY_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
6288 that target property for additional information.
6289
6290 CMAKE_LIBRARY_PATH_FLAG
6291 The flag to be used to add a library search path to a compiler.
6292
6293 The flag will be used to specify a library directory to the compiler.
6294 On most compilers this is -L.
6295
6296 CMAKE_LINK_DEF_FILE_FLAG
6297 Linker flag to be used to specify a .def file for dll creation.
6298
6299 The flag will be used to add a .def file when creating a dll on Win‐
6300 dows; this is only defined on Windows.
6301
6302 CMAKE_LINK_DEPENDS_NO_SHARED
6303 Whether to skip link dependencies on shared library files.
6304
6305 This variable initializes the LINK_DEPENDS_NO_SHARED property on tar‐
6306 gets when they are created. See that target property for additional
6307 information.
6308
6309 CMAKE_LINK_DEPENDS_USE_LINKER
6310 New in version 3.27.
6311
6312
6313 For the Makefile and Ninja generators, link dependencies are now, for a
6314 selection of linkers, generated by the linker itself. By defining this
6315 variable with value FALSE, you can deactivate this feature.
6316
6317 This feature is also deactivated if the LINK_DEPENDS_NO_SHARED target
6318 property is true.
6319
6320 NOTE:
6321 CMake version 3.27.7 defaults this variable to FALSE because GNU
6322 binutils linkers (ld, ld.bfd, ld.gold) generate spurious dependen‐
6323 cies on temporary files when LTO is enabled. See GNU bug 30568.
6324
6325 CMAKE_LINK_GROUP_USING_<FEATURE>
6326 New in version 3.24.
6327
6328
6329 This variable defines how to link a group of libraries for the speci‐
6330 fied <FEATURE> when a LINK_GROUP generator expression is used. Both of
6331 the following conditions must be met for this variable to have any ef‐
6332 fect:
6333
6334 • The associated CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable
6335 must be set to true.
6336
6337 • There is no language-specific definition for the same <FEATURE>.
6338 This means CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED cannot
6339 be true for the link language used by the target for which the
6340 LINK_GROUP generator expression is evaluated.
6341
6342 The CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable should be defined
6343 instead for features that are dependent on the link language.
6344
6345 Feature names are case-sensitive and may only contain letters, numbers
6346 and underscores. Feature names defined in all uppercase are reserved
6347 for CMake's own built-in features (see Predefined Features further be‐
6348 low).
6349
6350 Feature Definitions
6351 A group feature definition is a list that contains exactly two ele‐
6352 ments:
6353
6354 <PREFIX> <SUFFIX>
6355
6356 On the linker command line, <PREFIX> will precede the list of libraries
6357 in the group and <SUFFIX> will follow after.
6358
6359 For the elements of this variable, the LINKER: prefix can be used.
6360
6361 To pass options to the linker tool, each compiler driver has its own
6362 syntax. The LINKER: prefix and , separator can be used to specify, in
6363 a portable way, options to pass to the linker tool. LINKER: is replaced
6364 by the appropriate driver option and , by the appropriate driver sepa‐
6365 rator. The driver prefix and driver separator are given by the values
6366 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6367 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6368
6369 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6370 Clang and -Wl,-z,defs for GNU GCC.
6371
6372 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6373 sion.
6374
6375 The LINKER: prefix supports, as an alternative syntax, specification of
6376 arguments using the SHELL: prefix and space as separator. The previous
6377 example then becomes "LINKER:SHELL:-z defs".
6378
6379 NOTE:
6380 Specifying the SHELL: prefix anywhere other than at the beginning of
6381 the LINKER: prefix is not supported.
6382
6383 Examples
6384 Solving cross-references between two static libraries
6385 A project may define two or more static libraries which have circular
6386 dependencies between them. In order for the linker to resolve all sym‐
6387 bols at link time, it may need to search repeatedly among the libraries
6388 until no new undefined references are created. Different linkers use
6389 different syntax for achieving this. The following example shows how
6390 this may be implemented for some linkers. Note that this is for illus‐
6391 tration purposes only. Projects should use the built-in RESCAN group
6392 feature instead (see Predefined Features), which provides a more com‐
6393 plete and more robust implementation of this functionality.
6394
6395 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
6396 if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6397 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6398 "LINKER:--start-group"
6399 "LINKER:--end-group"
6400 )
6401 elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
6402 set(CMAKE_C_LINK_GROUP_USING_cross_refs
6403 "LINKER:-z,rescan-start"
6404 "LINKER:-z,rescan-end"
6405 )
6406 else()
6407 # feature not yet supported for the other environments
6408 set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
6409 endif()
6410
6411 add_library(lib1 STATIC ...)
6412 add_library(lib2 SHARED ...)
6413
6414 if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
6415 target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
6416 else()
6417 target_link_libraries(lib2 PRIVATE lib1 external)
6418 endif()
6419
6420 CMake will generate the following linker command line fragments when
6421 linking lib2:
6422
6423 • GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
6424
6425 • SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,res‐
6426 can-end
6427
6428 Predefined Features
6429 The following built-in group features are pre-defined by CMake:
6430
6431 RESCAN Some linkers are single-pass only. For such linkers, circular
6432 references between libraries typically result in unresolved sym‐
6433 bols. This feature instructs the linker to search the specified
6434 static libraries repeatedly until no new undefined references
6435 are created.
6436
6437 Normally, a static library is searched only once in the order
6438 that it is specified on the command line. If a symbol in that
6439 library is needed to resolve an undefined symbol referred to by
6440 an object in a library that appears later on the command line,
6441 the linker would not be able to resolve that reference. By
6442 grouping the static libraries with the RESCAN feature, they will
6443 all be searched repeatedly until all possible references are re‐
6444 solved. This will use linker options like --start-group and
6445 --end-group, or on SunOS, -z rescan-start and -z rescan-end.
6446
6447 Using this feature has a significant performance cost. It is
6448 best to use it only when there are unavoidable circular refer‐
6449 ences between two or more static libraries.
6450
6451 This feature is available when using toolchains that target
6452 Linux, BSD, and SunOS. It can also be used when targeting Win‐
6453 dows platforms if the GNU toolchain is used.
6454
6455 CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED
6456 New in version 3.24.
6457
6458
6459 This variable specifies whether the <FEATURE> is supported regardless
6460 of the link language. If this variable is true, then the <FEATURE>
6461 must be defined by CMAKE_LINK_GROUP_USING_<FEATURE>.
6462
6463 Note that this variable has no effect if
6464 CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is true for the link
6465 language of the target.
6466
6467 CMAKE_LINK_INTERFACE_LIBRARIES
6468 Default value for LINK_INTERFACE_LIBRARIES of targets.
6469
6470 This variable is used to initialize the LINK_INTERFACE_LIBRARIES prop‐
6471 erty on all the targets. See that target property for additional in‐
6472 formation.
6473
6474 CMAKE_LINK_LIBRARY_FILE_FLAG
6475 Flag to be used to link a library specified by a path to its file.
6476
6477 The flag will be used before a library file path is given to the
6478 linker. This is needed only on very few platforms.
6479
6480 CMAKE_LINK_LIBRARY_FLAG
6481 Flag to be used to link a library into an executable.
6482
6483 The flag will be used to specify a library to link to an executable.
6484 On most compilers this is -l.
6485
6486 CMAKE_LINK_LIBRARY_USING_<FEATURE>
6487 New in version 3.24.
6488
6489
6490 This variable defines how to link a library or framework for the speci‐
6491 fied <FEATURE> when a LINK_LIBRARY generator expression is used. Both
6492 of the following conditions must be met for this variable to have any
6493 effect:
6494
6495 • The associated CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
6496 must be set to true.
6497
6498 • There is no language-specific definition for the same <FEATURE>.
6499 This means CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED cannot
6500 be true for the link language used by the target for which the
6501 LINK_LIBRARY generator expression is evaluated.
6502
6503 Feature names are case-sensitive and may only contain letters, numbers
6504 and underscores. Feature names defined in all uppercase are reserved
6505 for CMake's own built-in features (see Predefined Features further be‐
6506 low).
6507
6508 Feature Definitions
6509 A library feature definition is a list that contains one or three ele‐
6510 ments:
6511
6512 [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
6513
6514 When <PREFIX> and <SUFFIX> are specified, they precede and follow re‐
6515 spectively the whole list of libraries specified in the LINK_LIBRARY
6516 expression, not each library item individually. There is no guarantee
6517 that the list of specified libraries will be kept grouped together
6518 though, so the <PREFIX> and <SUFFIX> may appear more than once if the
6519 library list is reorganized by CMake to satisfy other constraints.
6520 This means constructs like --start-group and --end-group, as supported
6521 by the GNU ld linker, cannot be used in this way. The LINK_GROUP gen‐
6522 erator expression should be used instead for such constructs.
6523
6524 <LIBRARY_EXPRESSION> is used to specify the pattern for constructing
6525 the corresponding fragment on the linker command line for each library.
6526 The following placeholders can be used in the expression:
6527
6528 • <LIBRARY> is expanded to the full path to the library for CMake tar‐
6529 gets, or to a platform-specific value based on the item otherwise
6530 (the same as <LINK_ITEM> on Windows, or the library base name for
6531 other platforms).
6532
6533 • <LINK_ITEM> is expanded to how the library would normally be linked
6534 on the linker command line.
6535
6536 • <LIB_ITEM> is expanded to the full path to the library for CMake tar‐
6537 gets, or the item itself exactly as specified in the <LIBRARY_EXPRES‐
6538 SION> otherwise.
6539
6540 In addition to the above, it is possible to have one pattern for paths
6541 (CMake targets and external libraries specified with file paths) and
6542 another for other items specified by name only. The PATH{} and NAME{}
6543 wrappers can be used to provide the expansion for those two cases, re‐
6544 spectively. When wrappers are used, both must be present. For exam‐
6545 ple:
6546
6547 set(CMAKE_LINK_LIBRARY_USING_weak_library
6548 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6549 )
6550
6551 For all three elements of this variable (<PREFIX>, <LIBRARY_EXPRES‐
6552 SION>, and <SUFFIX>), the LINKER: prefix can be used.
6553
6554 To pass options to the linker tool, each compiler driver has its own
6555 syntax. The LINKER: prefix and , separator can be used to specify, in
6556 a portable way, options to pass to the linker tool. LINKER: is replaced
6557 by the appropriate driver option and , by the appropriate driver sepa‐
6558 rator. The driver prefix and driver separator are given by the values
6559 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6560 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6561
6562 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6563 Clang and -Wl,-z,defs for GNU GCC.
6564
6565 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6566 sion.
6567
6568 The LINKER: prefix supports, as an alternative syntax, specification of
6569 arguments using the SHELL: prefix and space as separator. The previous
6570 example then becomes "LINKER:SHELL:-z defs".
6571
6572 NOTE:
6573 Specifying the SHELL: prefix anywhere other than at the beginning of
6574 the LINKER: prefix is not supported.
6575
6576 Examples
6577 Loading a whole static library
6578 A common need is to prevent the linker from discarding any symbols from
6579 a static library. Different linkers use different syntax for achieving
6580 this. The following example shows how this may be implemented for some
6581 linkers. Note that this is for illustration purposes only. Projects
6582 should use the built-in WHOLE_ARCHIVE feature instead (see Predefined
6583 Features), which provides a more complete and more robust implementa‐
6584 tion of this functionality.
6585
6586 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
6587 if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6588 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
6589 elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
6590 set(CMAKE_C_LINK_LIBRARY_USING_load_archive
6591 "LINKER:--push-state,--whole-archive"
6592 "<LINK_ITEM>"
6593 "LINKER:--pop-state"
6594 )
6595 elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
6596 set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
6597 else()
6598 # feature not yet supported for the other environments
6599 set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
6600 endif()
6601
6602 add_library(lib1 STATIC ...)
6603 add_library(lib2 SHARED ...)
6604
6605 if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
6606 # The -force_load Apple linker option requires a file name
6607 set(external_lib
6608 "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
6609 )
6610 target_link_libraries(lib2 PRIVATE
6611 "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
6612 )
6613 else()
6614 target_link_libraries(lib2 PRIVATE lib1 external)
6615 endif()
6616
6617 CMake will generate the following link expressions:
6618
6619 • AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
6620
6621 • GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal
6622 -Wl,--pop-state
6623
6624 • MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib
6625
6626 Linking a library as weak
6627 On macOS, it is possible to link a library in weak mode (the library
6628 and all references are marked as weak imports). Different flags must
6629 be used for a library specified by file path compared to one specified
6630 by name. This constraint can be solved using PATH{} and NAME{} wrap‐
6631 pers. Again, the following example shows how this may be implemented
6632 for some linkers, but it is for illustration purposes only. Projects
6633 should use the built-in WEAK_FRAMEWORK or WEAK_LIBRARY features instead
6634 (see Predefined Features), which provide more complete and more robust
6635 implementations of this functionality.
6636
6637 if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
6638 set(CMAKE_LINK_LIBRARY_USING_weak_library
6639 "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
6640 )
6641 set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
6642 endif()
6643
6644 add_library(lib SHARED ...)
6645 add_executable(main ...)
6646 if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
6647 target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
6648 else()
6649 target_link_libraries(main PRIVATE lib external)
6650 endif()
6651
6652 CMake will generate the following linker command line fragment when
6653 linking main using the AppleClang toolchain:
6654
6655 -weak_library /path/to/lib -Xlinker -weak-lexternal.
6656
6657 Predefined Features
6658 The following built-in library features are pre-defined by CMake:
6659
6660 DEFAULT
6661 This feature corresponds to standard linking, essentially equiv‐
6662 alent to using no feature at all. It is typically only used
6663 with the LINK_LIBRARY_OVERRIDE and
6664 LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.
6665
6666 WHOLE_ARCHIVE
6667 Force inclusion of all members of a static library. This fea‐
6668 ture is only supported for the following platforms, with limita‐
6669 tions as noted:
6670
6671 • Linux.
6672
6673 • All BSD variants.
6674
6675 • SunOS.
6676
6677 • All Apple variants. The library must be specified as a CMake
6678 target name, a library file name (such as libfoo.a), or a li‐
6679 brary file path (such as /path/to/libfoo.a). Due to a limita‐
6680 tion of the Apple linker, it cannot be specified as a plain
6681 library name like foo, where foo is not a CMake target.
6682
6683 • Windows. When using a MSVC or MSVC-like toolchain, the MSVC
6684 version must be greater than 1900.
6685
6686 • Cygwin.
6687
6688 • MSYS.
6689
6690 FRAMEWORK
6691 This option tells the linker to search for the specified frame‐
6692 work using the -framework linker option. It can only be used on
6693 Apple platforms, and only with a linker that understands the op‐
6694 tion used (i.e. the linker provided with Xcode, or one compati‐
6695 ble with it).
6696
6697 The framework can be specified as a CMake framework target, a
6698 bare framework name, or a file path. If a target is given, that
6699 target must have the FRAMEWORK target property set to true. For
6700 a file path, if it contains a directory part, that directory
6701 will be added as a framework search path.
6702
6703 add_library(lib SHARED ...)
6704 target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
6705
6706 # The constructed linker command line will contain:
6707 # -F/path/to -framework my_framework
6708
6709 File paths must conform to one of the following patterns (* is a
6710 wildcard, and optional parts are shown as [...]):
6711
6712 • [/path/to/]FwName[.framework]
6713
6714 • [/path/to/]FwName.framework/FwName[suffix]
6715
6716 • [/path/to/]FwName.framework/Versions/*/FwName[suffix]
6717
6718 Note that CMake recognizes and automatically handles framework
6719 targets, even without using the $<LINK_LIBRARY:FRAMEWORK,...>
6720 expression. The generator expression can still be used with a
6721 CMake target if the project wants to be explicit about it, but
6722 it is not required to do so. The linker command line may have
6723 some differences between using the generator expression or not,
6724 but the final result should be the same. On the other hand, if
6725 a file path is given, CMake will recognize some paths automati‐
6726 cally, but not all cases. The project may want to use
6727 $<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the ex‐
6728 pected behavior is clear.
6729
6730 New in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
6731 target property as well as the suffix of the framework library
6732 name are now supported by the FRAMEWORK features.
6733
6734
6735 NEEDED_FRAMEWORK
6736 This is similar to the FRAMEWORK feature, except it forces the
6737 linker to link with the framework even if no symbols are used
6738 from it. It uses the -needed_framework option and has the same
6739 linker constraints as FRAMEWORK.
6740
6741 REEXPORT_FRAMEWORK
6742 This is similar to the FRAMEWORK feature, except it tells the
6743 linker that the framework should be available to clients linking
6744 to the library being created. It uses the -reexport_framework
6745 option and has the same linker constraints as FRAMEWORK.
6746
6747 WEAK_FRAMEWORK
6748 This is similar to the FRAMEWORK feature, except it forces the
6749 linker to mark the framework and all references to it as weak
6750 imports. It uses the -weak_framework option and has the same
6751 linker constraints as FRAMEWORK.
6752
6753 NEEDED_LIBRARY
6754 This is similar to the NEEDED_FRAMEWORK feature, except it is
6755 for use with non-framework targets or libraries (Apple platforms
6756 only). It uses the -needed_library or -needed-l option as ap‐
6757 propriate, and has the same linker constraints as NEEDED_FRAME‐
6758 WORK.
6759
6760 REEXPORT_LIBRARY
6761 This is similar to the REEXPORT_FRAMEWORK feature, except it is
6762 for use with non-framework targets or libraries (Apple platforms
6763 only). It uses the -reexport_library or -reexport-l option as
6764 appropriate, and has the same linker constraints as REEX‐
6765 PORT_FRAMEWORK.
6766
6767 WEAK_LIBRARY
6768 This is similar to the WEAK_FRAMEWORK feature, except it is for
6769 use with non-framework targets or libraries (Apple platforms
6770 only). It uses the -weak_library or -weak-l option as appropri‐
6771 ate, and has the same linker constraints as WEAK_FRAMEWORK.
6772
6773 CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED
6774 New in version 3.24.
6775
6776
6777 Set to TRUE if the <FEATURE>, as defined by variable
6778 CMAKE_LINK_LIBRARY_USING_<FEATURE>, is supported regardless the linker
6779 language.
6780
6781 NOTE:
6782 This variable is evaluated if, and only if, the variable
6783 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED is not defined.
6784
6785 CMAKE_LINK_WHAT_YOU_USE
6786 New in version 3.7.
6787
6788
6789 Default value for LINK_WHAT_YOU_USE target property. This variable is
6790 used to initialize the property on each target as it is created.
6791
6792 CMAKE_LINK_WHAT_YOU_USE_CHECK
6793 New in version 3.22.
6794
6795
6796 Defines the command executed after the link step to check libraries us‐
6797 age. This check is currently only defined on ELF platforms with value
6798 ldd -u -r.
6799
6800 See also CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG variables.
6801
6802 CMAKE_MACOSX_BUNDLE
6803 Default value for MACOSX_BUNDLE of targets.
6804
6805 This variable is used to initialize the MACOSX_BUNDLE property on all
6806 the targets. See that target property for additional information.
6807
6808 This variable is set to ON by default if CMAKE_SYSTEM_NAME equals to
6809 iOS, tvOS or watchOS.
6810
6811 CMAKE_MACOSX_RPATH
6812 Whether to use rpaths on macOS and iOS.
6813
6814 This variable is used to initialize the MACOSX_RPATH property on all
6815 targets.
6816
6817 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>
6818 Default value for MAP_IMPORTED_CONFIG_<CONFIG> of targets.
6819
6820 This variable is used to initialize the MAP_IMPORTED_CONFIG_<CONFIG>
6821 property on all the targets. See that target property for additional
6822 information.
6823
6824 CMAKE_MODULE_LINKER_FLAGS
6825 Linker flags to be used to create modules.
6826
6827 These flags will be used by the linker when creating a module.
6828
6829 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
6830 Flags to be used when linking a module.
6831
6832 Same as CMAKE_C_FLAGS_* but used by the linker when creating modules.
6833
6834 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT
6835 New in version 3.7.
6836
6837
6838 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS_<CONFIG> cache
6839 entry the first time a build tree is configured. This variable is
6840 meant to be set by a toolchain file. CMake may prepend or append con‐
6841 tent to the value based on the environment and target platform.
6842
6843 See also CMAKE_MODULE_LINKER_FLAGS_INIT.
6844
6845 CMAKE_MODULE_LINKER_FLAGS_INIT
6846 New in version 3.7.
6847
6848
6849 Value used to initialize the CMAKE_MODULE_LINKER_FLAGS cache entry the
6850 first time a build tree is configured. This variable is meant to be
6851 set by a toolchain file. CMake may prepend or append content to the
6852 value based on the environment and target platform.
6853
6854 See also the configuration-specific variable
6855 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT.
6856
6857 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
6858 New in version 3.25.
6859
6860
6861 Select the MSVC debug information format targeting the MSVC ABI. This
6862 variable is used to initialize the MSVC_DEBUG_INFORMATION_FORMAT prop‐
6863 erty on all targets as they are created. It is also propagated by
6864 calls to the try_compile() command into the test project.
6865
6866 The allowed values are:
6867
6868 Embedded
6869 Compile with -Z7 or equivalent flag(s) to produce object files
6870 with full symbolic debugging information.
6871
6872 ProgramDatabase
6873 Compile with -Zi or equivalent flag(s) to produce a program
6874 database that contains all the symbolic debugging information.
6875
6876 EditAndContinue
6877 Compile with -ZI or equivalent flag(s) to produce a program
6878 database that supports the Edit and Continue feature.
6879
6880 The value is ignored on compilers not targeting the MSVC ABI, but an
6881 unsupported value will be rejected as an error when using a compiler
6882 targeting the MSVC ABI.
6883
6884 The value may also be the empty string (""), in which case no debug in‐
6885 formation format flag will be added explicitly by CMake.
6886
6887 Use generator expressions to support per-configuration specification.
6888 For example, the code:
6889
6890 set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
6891
6892 selects for all following targets the program database debug informa‐
6893 tion format for the Debug configuration.
6894
6895 If this variable is not set, the MSVC_DEBUG_INFORMATION_FORMAT target
6896 property will not be set automatically. If that property is not set,
6897 CMake selects a debug information format using the default value
6898 $<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>, if supported by the
6899 compiler, and otherwise $<$<CONFIG:Debug,RelWithDebInfo>:Embedded>.
6900
6901 NOTE:
6902 This variable has effect only when policy CMP0141 is set to NEW
6903 prior to the first project() or enable_language() command that en‐
6904 ables a language using a compiler targeting the MSVC ABI.
6905
6906 CMAKE_MSVC_RUNTIME_LIBRARY
6907 New in version 3.15.
6908
6909
6910 Select the MSVC runtime library for use by compilers targeting the MSVC
6911 ABI. This variable is used to initialize the MSVC_RUNTIME_LIBRARY
6912 property on all targets as they are created. It is also propagated by
6913 calls to the try_compile() command into the test project.
6914
6915 The allowed values are:
6916
6917 MultiThreaded
6918 Compile with -MT or equivalent flag(s) to use a multi-threaded
6919 statically-linked runtime library.
6920
6921 MultiThreadedDLL
6922 Compile with -MD or equivalent flag(s) to use a multi-threaded
6923 dynamically-linked runtime library.
6924
6925 MultiThreadedDebug
6926 Compile with -MTd or equivalent flag(s) to use a multi-threaded
6927 statically-linked runtime library.
6928
6929 MultiThreadedDebugDLL
6930 Compile with -MDd or equivalent flag(s) to use a multi-threaded
6931 dynamically-linked runtime library.
6932
6933 The value is ignored on compilers not targeting the MSVC ABI, but an
6934 unsupported value will be rejected as an error when using a compiler
6935 targeting the MSVC ABI.
6936
6937 The value may also be the empty string ("") in which case no runtime
6938 library selection flag will be added explicitly by CMake. Note that
6939 with Visual Studio Generators the native build system may choose to add
6940 its own default runtime library selection flag.
6941
6942 Use generator expressions to support per-configuration specification.
6943 For example, the code:
6944
6945 set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
6946
6947 selects for all following targets a multi-threaded statically-linked
6948 runtime library with or without debug information depending on the con‐
6949 figuration.
6950
6951 If this variable is not set then the MSVC_RUNTIME_LIBRARY target prop‐
6952 erty will not be set automatically. If that property is not set then
6953 CMake uses the default value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL
6954 to select a MSVC runtime library.
6955
6956 NOTE:
6957 This variable has effect only when policy CMP0091 is set to NEW
6958 prior to the first project() or enable_language() command that en‐
6959 ables a language using a compiler targeting the MSVC ABI.
6960
6961 CMAKE_MSVCIDE_RUN_PATH
6962 New in version 3.10.
6963
6964
6965 Extra PATH locations that should be used when executing
6966 add_custom_command() or add_custom_target() when using the Visual Stu‐
6967 dio 9 2008 (or above) generator. This allows for running commands and
6968 using dll's that the IDE environment is not aware of.
6969
6970 If not set explicitly the value is initialized by the CMAKE_MSV‐
6971 CIDE_RUN_PATH environment variable, if set, and otherwise left empty.
6972
6973 CMAKE_NINJA_OUTPUT_PATH_PREFIX
6974 New in version 3.6.
6975
6976
6977 Tell the Ninja Generators to add a prefix to every output path in
6978 build.ninja. A trailing slash is appended to the prefix, if missing.
6979
6980 This is useful when the generated ninja file is meant to be embedded as
6981 a subninja file into a super ninja project. For example, the command:
6982
6983 cd super-build-dir &&
6984 cmake -G Ninja -S /path/to/src -B sub -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/
6985 # ^^^---------- these match -----------^^^
6986
6987 generates a build directory with its top-level (CMAKE_BINARY_DIR) in
6988 super-build-dir/sub. The path to the build directory ends in the out‐
6989 put path prefix. This makes it suitable for use in a separately-writ‐
6990 ten super-build-dir/build.ninja file with a directive like this:
6991
6992 subninja sub/build.ninja
6993
6994 The auto-regeneration rule in super-build-dir/build.ninja must have an
6995 order-only dependency on sub/build.ninja.
6996
6997 New in version 3.27: The Ninja Multi-Config generator supports this
6998 variable.
6999
7000
7001 NOTE:
7002 When CMAKE_NINJA_OUTPUT_PATH_PREFIX is set, the project generated by
7003 CMake cannot be used as a standalone project. No default targets
7004 are specified.
7005
7006 The value of CMAKE_NINJA_OUTPUT_PATH_PREFIX must match one or more
7007 path components at the end of CMAKE_BINARY_DIR, or the behavior is
7008 undefined. However, this requirement is not checked automatically.
7009
7010 CMAKE_NO_BUILTIN_CHRPATH
7011 Do not use the builtin binary editor to fix runtime library search
7012 paths on installation.
7013
7014 When an ELF or XCOFF binary needs to have a different runtime library
7015 search path after installation than it does in the build tree, CMake
7016 uses a builtin editor to change the runtime search path in the in‐
7017 stalled copy. If this variable is set to true then CMake will relink
7018 the binary before installation instead of using its builtin editor.
7019
7020 For more information on RPATH handling see the INSTALL_RPATH and
7021 BUILD_RPATH target properties.
7022
7023 New in version 3.20: This variable also applies to XCOFF binaries' LIB‐
7024 PATH. Prior to the addition of the XCOFF editor in CMake 3.20, this
7025 variable applied only to ELF binaries' RPATH/RUNPATH.
7026
7027
7028 CMAKE_NO_SYSTEM_FROM_IMPORTED
7029 Default value for NO_SYSTEM_FROM_IMPORTED of targets.
7030
7031 This variable is used to initialize the NO_SYSTEM_FROM_IMPORTED prop‐
7032 erty on all the targets. See that target property for additional in‐
7033 formation.
7034
7035 CMAKE_OPTIMIZE_DEPENDENCIES
7036 New in version 3.19.
7037
7038
7039 Initializes the OPTIMIZE_DEPENDENCIES target property.
7040
7041 CMAKE_OSX_ARCHITECTURES
7042 Target specific architectures for macOS and iOS.
7043
7044 This variable is used to initialize the OSX_ARCHITECTURES property on
7045 each target as it is created. See that target property for additional
7046 information.
7047
7048 The value of this variable should be set prior to the first project()
7049 or enable_language() command invocation because it may influence con‐
7050 figuration of the toolchain and flags. It is intended to be set lo‐
7051 cally by the user creating a build tree. This variable should be set
7052 as a CACHE entry (or else CMake may remove it while initializing a
7053 cache entry of the same name) unless policy CMP0126 is set to NEW.
7054
7055 Despite the OSX part in the variable name(s) they apply also to other
7056 SDKs than macOS like iOS, tvOS, or watchOS.
7057
7058 This variable is ignored on platforms other than Apple.
7059
7060 CMAKE_OSX_DEPLOYMENT_TARGET
7061 Specify the minimum version of the target platform (e.g. macOS or iOS)
7062 on which the target binaries are to be deployed. CMake uses this vari‐
7063 able value for the -mmacosx-version-min flag or their respective target
7064 platform equivalents. For older Xcode versions that shipped multiple
7065 macOS SDKs this variable also helps to choose the SDK in case
7066 CMAKE_OSX_SYSROOT is unset.
7067
7068 If not set explicitly the value is initialized by the MACOSX_DEPLOY‐
7069 MENT_TARGET environment variable, if set, and otherwise computed based
7070 on the host platform.
7071
7072 The value of this variable should be set prior to the first project()
7073 or enable_language() command invocation because it may influence con‐
7074 figuration of the toolchain and flags. It is intended to be set lo‐
7075 cally by the user creating a build tree. This variable should be set
7076 as a CACHE entry (or else CMake may remove it while initializing a
7077 cache entry of the same name) unless policy CMP0126 is set to NEW.
7078
7079 Despite the OSX part in the variable name(s) they apply also to other
7080 SDKs than macOS like iOS, tvOS, or watchOS.
7081
7082 This variable is ignored on platforms other than Apple.
7083
7084 CMAKE_OSX_SYSROOT
7085 Specify the location or name of the macOS platform SDK to be used.
7086 CMake uses this value to compute the value of the -isysroot flag or
7087 equivalent and to help the find_* commands locate files in the SDK.
7088
7089 If not set explicitly the value is initialized by the SDKROOT environ‐
7090 ment variable, if set, and otherwise computed based on the
7091 CMAKE_OSX_DEPLOYMENT_TARGET or the host platform.
7092
7093 The value of this variable should be set prior to the first project()
7094 or enable_language() command invocation because it may influence con‐
7095 figuration of the toolchain and flags. It is intended to be set lo‐
7096 cally by the user creating a build tree. This variable should be set
7097 as a CACHE entry (or else CMake may remove it while initializing a
7098 cache entry of the same name) unless policy CMP0126 is set to NEW.
7099
7100 Despite the OSX part in the variable name(s) they apply also to other
7101 SDKs than macOS like iOS, tvOS, or watchOS.
7102
7103 This variable is ignored on platforms other than Apple.
7104
7105 CMAKE_PCH_INSTANTIATE_TEMPLATES
7106 New in version 3.19.
7107
7108
7109 This variable is used to initialize the PCH_INSTANTIATE_TEMPLATES prop‐
7110 erty of targets when they are created.
7111
7112 CMAKE_PCH_WARN_INVALID
7113 New in version 3.18.
7114
7115
7116 This variable is used to initialize the PCH_WARN_INVALID property of
7117 targets when they are created.
7118
7119 CMAKE_PDB_OUTPUT_DIRECTORY
7120 Output directory for MS debug symbol .pdb files generated by the linker
7121 for executable and shared library targets.
7122
7123 This variable is used to initialize the PDB_OUTPUT_DIRECTORY property
7124 on all the targets. See that target property for additional informa‐
7125 tion.
7126
7127 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>
7128 Per-configuration output directory for MS debug symbol .pdb files gen‐
7129 erated by the linker for executable and shared library targets.
7130
7131 This is a per-configuration version of CMAKE_PDB_OUTPUT_DIRECTORY.
7132 This variable is used to initialize the PDB_OUTPUT_DIRECTORY_<CONFIG>
7133 property on all the targets. See that target property for additional
7134 information.
7135
7136 CMAKE_PLATFORM_NO_VERSIONED_SONAME
7137 New in version 3.1.
7138
7139
7140 This variable is used to globally control whether the VERSION and
7141 SOVERSION target properties should be used for shared libraries. When
7142 set to true, adding version information to each shared library target
7143 is disabled.
7144
7145 By default this variable is set only on platforms where CMake knows it
7146 is needed. On other platforms, the specified properties will be used
7147 for shared libraries.
7148
7149 CMAKE_POSITION_INDEPENDENT_CODE
7150 Default value for POSITION_INDEPENDENT_CODE of targets.
7151
7152 This variable is used to initialize the POSITION_INDEPENDENT_CODE prop‐
7153 erty on all the targets. See that target property for additional in‐
7154 formation. If set, its value is also used by the try_compile() com‐
7155 mand.
7156
7157 CMAKE_RUNTIME_OUTPUT_DIRECTORY
7158 Where to put all the RUNTIME target files when built.
7159
7160 This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY prop‐
7161 erty on all the targets. See that target property for additional in‐
7162 formation.
7163
7164 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
7165 New in version 3.3.
7166
7167
7168 Where to put all the RUNTIME target files when built for a specific
7169 configuration.
7170
7171 This variable is used to initialize the
7172 RUNTIME_OUTPUT_DIRECTORY_<CONFIG> property on all the targets. See
7173 that target property for additional information.
7174
7175 CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS
7176 New in version 3.27.
7177
7178
7179 Specify whether shared library generates an import file.
7180
7181 This variable is used to initialize the ENABLE_EXPORTS target property
7182 for shared library targets when they are created by calls to the
7183 add_library() command. See the property documentation for details.
7184
7185 CMAKE_SHARED_LINKER_FLAGS
7186 Linker flags to be used to create shared libraries.
7187
7188 These flags will be used by the linker when creating a shared library.
7189
7190 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
7191 Flags to be used when linking a shared library.
7192
7193 Same as CMAKE_C_FLAGS_* but used by the linker when creating shared li‐
7194 braries.
7195
7196 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT
7197 New in version 3.7.
7198
7199
7200 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS_<CONFIG> cache
7201 entry the first time a build tree is configured. This variable is
7202 meant to be set by a toolchain file. CMake may prepend or append con‐
7203 tent to the value based on the environment and target platform.
7204
7205 See also CMAKE_SHARED_LINKER_FLAGS_INIT.
7206
7207 CMAKE_SHARED_LINKER_FLAGS_INIT
7208 New in version 3.7.
7209
7210
7211 Value used to initialize the CMAKE_SHARED_LINKER_FLAGS cache entry the
7212 first time a build tree is configured. This variable is meant to be
7213 set by a toolchain file. CMake may prepend or append content to the
7214 value based on the environment and target platform.
7215
7216 See also the configuration-specific variable
7217 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT.
7218
7219 CMAKE_SKIP_BUILD_RPATH
7220 Do not include RPATHs in the build tree.
7221
7222 Normally CMake uses the build tree for the RPATH when building executa‐
7223 bles etc on systems that use RPATH. When the software is installed the
7224 executables etc are relinked by CMake to have the install RPATH. If
7225 this variable is set to TRUE then the software is always built with no
7226 RPATH.
7227
7228 This is used to initialize the SKIP_BUILD_RPATH target property for all
7229 targets. For more information on RPATH handling see the INSTALL_RPATH
7230 and BUILD_RPATH target properties.
7231
7232 See also the CMAKE_SKIP_INSTALL_RPATH variable. To omit RPATH in both
7233 the build and install steps, use CMAKE_SKIP_RPATH instead.
7234
7235 CMAKE_SKIP_INSTALL_RPATH
7236 Do not include RPATHs in the install tree.
7237
7238 Normally CMake uses the build tree for the RPATH when building executa‐
7239 bles etc on systems that use RPATH. When the software is installed the
7240 executables etc are relinked by CMake to have the install RPATH. If
7241 this variable is set to true then the software is always installed
7242 without RPATH, even if RPATH is enabled when building. This can be
7243 useful for example to allow running tests from the build directory with
7244 RPATH enabled before the installation step.
7245
7246 See also the CMAKE_SKIP_BUILD_RPATH variable. To omit RPATH in both
7247 the build and install steps, use CMAKE_SKIP_RPATH instead.
7248
7249 For more information on RPATH handling see the INSTALL_RPATH and
7250 BUILD_RPATH target properties.
7251
7252 CMAKE_STATIC_LINKER_FLAGS
7253 Flags to be used to create static libraries. These flags will be
7254 passed to the archiver when creating a static library.
7255
7256 See also CMAKE_STATIC_LINKER_FLAGS_<CONFIG>.
7257
7258 NOTE:
7259 Static libraries do not actually link. They are essentially ar‐
7260 chives of object files. The use of the name "linker" in the name of
7261 this variable is kept for compatibility.
7262
7263 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
7264 Flags to be used to create static libraries. These flags will be
7265 passed to the archiver when creating a static library in the <CONFIG>
7266 configuration.
7267
7268 See also CMAKE_STATIC_LINKER_FLAGS.
7269
7270 NOTE:
7271 Static libraries do not actually link. They are essentially ar‐
7272 chives of object files. The use of the name "linker" in the name of
7273 this variable is kept for compatibility.
7274
7275 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT
7276 New in version 3.7.
7277
7278
7279 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS_<CONFIG> cache
7280 entry the first time a build tree is configured. This variable is
7281 meant to be set by a toolchain file. CMake may prepend or append con‐
7282 tent to the value based on the environment and target platform.
7283
7284 See also CMAKE_STATIC_LINKER_FLAGS_INIT.
7285
7286 CMAKE_STATIC_LINKER_FLAGS_INIT
7287 New in version 3.7.
7288
7289
7290 Value used to initialize the CMAKE_STATIC_LINKER_FLAGS cache entry the
7291 first time a build tree is configured. This variable is meant to be
7292 set by a toolchain file. CMake may prepend or append content to the
7293 value based on the environment and target platform.
7294
7295 See also the configuration-specific variable
7296 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT.
7297
7298 CMAKE_TASKING_TOOLSET
7299 New in version 3.25.
7300
7301
7302 Select the Tasking toolset which provides the compiler
7303
7304 Architecture compilers are provided by different toolchains with incom‐
7305 patible versioning schemes. Set this variable in a toolchain file so
7306 CMake can detect the compiler features correctly. If no toolset is
7307 specified, Standalone is assumed.
7308
7309 Due to the different versioning schemes, the compiler version (‐
7310 CMAKE_<LANG>_COMPILER_VERSION) depends on the toolset and architecture
7311 in use. If projects can be built with multiple toolsets or architec‐
7312 tures, the specified CMAKE_TASKING_TOOLSET and the automatically deter‐
7313 mined CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID must be taken into account
7314 when comparing against the CMAKE_<LANG>_COMPILER_VERSION.
7315
7316 TriCore
7317 Compilers are provided by the TriCore toolset.
7318
7319 SmartCode
7320 Compilers are provided by the SmartCode toolset.
7321
7322 Standalone
7323 Compilers are provided by the standalone toolsets.
7324
7325 NOTE:
7326 For the TriCore architecture, the compiler from the TriCore
7327 toolset is selected as standalone compiler.
7328
7329 CMAKE_TRY_COMPILE_CONFIGURATION
7330 Build configuration used for try_compile() and try_run() projects.
7331
7332 Projects built by try_compile() and try_run() are built synchronously
7333 during the CMake configuration step. Therefore a specific build con‐
7334 figuration must be chosen even if the generated build system supports
7335 multiple configurations.
7336
7337 CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
7338 New in version 3.24.
7339
7340
7341 Set to a true value to tell the try_compile() command not to propagate
7342 any platform variables into the test project.
7343
7344 The try_compile() command normally passes some CMake variables that
7345 configure the platform and toolchain behavior into test projects. See
7346 policy CMP0137. This variable may be set to disable that behavior.
7347
7348 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
7349 New in version 3.6.
7350
7351
7352 List of variables that the try_compile() command source file signature
7353 must propagate into the test project in order to target the same plat‐
7354 form as the host project.
7355
7356 This variable should not be set by project code. It is meant to be set
7357 by CMake's platform information modules for the current toolchain, or
7358 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
7359
7360 Variables meaningful to CMake, such as CMAKE_<LANG>_FLAGS, are propa‐
7361 gated automatically. The CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable
7362 may be set to pass custom variables meaningful to a toolchain file.
7363 For example, a toolchain file may contain:
7364
7365 set(CMAKE_SYSTEM_NAME ...)
7366 set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE)
7367 # ... use MY_CUSTOM_VARIABLE ...
7368
7369 If a user passes -DMY_CUSTOM_VARIABLE=SomeValue to CMake then this set‐
7370 ting will be made visible to the toolchain file both for the main
7371 project and for test projects generated by the try_compile() command
7372 source file signature.
7373
7374 Changed in version 3.24: Listed variables are propagated to the
7375 try_compile() whole-project signature too. See CMP0137.
7376
7377
7378 New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES vari‐
7379 able may be set to disable passing platform variables into the test
7380 project.
7381
7382
7383 CMAKE_TRY_COMPILE_TARGET_TYPE
7384 New in version 3.6.
7385
7386
7387 Type of target generated for try_compile() calls using the source file
7388 signature. Valid values are:
7389
7390 EXECUTABLE
7391 Use add_executable() to name the source file in the generated
7392 project. This is the default if no value is given.
7393
7394 STATIC_LIBRARY
7395 Use add_library() with the STATIC option to name the source file
7396 in the generated project. This avoids running the linker and is
7397 intended for use with cross-compiling toolchains that cannot
7398 link without custom flags or linker scripts.
7399
7400 CMAKE_UNITY_BUILD
7401 New in version 3.16.
7402
7403
7404 This variable is used to initialize the UNITY_BUILD property of targets
7405 when they are created. Setting it to true enables batch compilation of
7406 multiple sources within each target. This feature is known as a Unity
7407 or Jumbo build.
7408
7409 Projects should not set this variable, it is intended as a developer
7410 control to be set on the cmake(1) command line or other equivalent
7411 methods. The developer must have the ability to enable or disable
7412 unity builds according to the capabilities of their own machine and
7413 compiler.
7414
7415 By default, this variable is not set, which will result in unity builds
7416 being disabled.
7417
7418 NOTE:
7419 This option currently does not work well in combination with the
7420 CMAKE_EXPORT_COMPILE_COMMANDS variable.
7421
7422 CMAKE_UNITY_BUILD_BATCH_SIZE
7423 New in version 3.16.
7424
7425
7426 This variable is used to initialize the UNITY_BUILD_BATCH_SIZE property
7427 of targets when they are created. It specifies the default upper limit
7428 on the number of source files that may be combined in any one unity
7429 source file when unity builds are enabled for a target.
7430
7431 CMAKE_UNITY_BUILD_UNIQUE_ID
7432 New in version 3.20.
7433
7434
7435 This variable is used to initialize the UNITY_BUILD_UNIQUE_ID property
7436 of targets when they are created. It specifies the name of the unique
7437 identifier generated per file in a unity build.
7438
7439 CMAKE_USE_RELATIVE_PATHS
7440 This variable has no effect. The partially implemented effect it had
7441 in previous releases was removed in CMake 3.4.
7442
7443 CMAKE_VERIFY_INTERFACE_HEADER_SETS
7444 New in version 3.24.
7445
7446
7447 This variable is used to initialize the VERIFY_INTERFACE_HEADER_SETS
7448 property of targets when they are created. Setting it to true enables
7449 header set verification.
7450
7451 Projects should not normally set this variable, it is intended as a de‐
7452 veloper control to be set on the cmake(1) command line or other equiva‐
7453 lent methods. The developer must have the ability to enable or disable
7454 header set verification according to the capabilities of their own ma‐
7455 chine and compiler.
7456
7457 Verification of a dependency's header sets is not typically of interest
7458 to developers. Therefore, FetchContent_MakeAvailable() explicitly sets
7459 CMAKE_VERIFY_INTERFACE_HEADER_SETS to false for the duration of its
7460 call, but restores its original value before returning. If a project
7461 brings a dependency directly into the main build (e.g. calling
7462 add_subdirectory() on a vendored project from a git submodule), it
7463 should also do likewise. For example:
7464
7465 # Save original setting so we can restore it later
7466 set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS})
7467
7468 # Include the vendored dependency with header set verification disabled
7469 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF)
7470 add_subdirectory(...) # Vendored sources, e.g. from git submodules
7471
7472 # Add the project's own sources. Restore the developer's original choice
7473 # for whether to enable header set verification.
7474 set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification})
7475 add_subdirectory(src)
7476
7477 By default, this variable is not set, which will result in header set
7478 verification being disabled.
7479
7480 CMAKE_VISIBILITY_INLINES_HIDDEN
7481 Default value for the VISIBILITY_INLINES_HIDDEN target property when a
7482 target is created.
7483
7484 CMAKE_VS_DEBUGGER_COMMAND
7485 New in version 3.27.
7486
7487
7488 This variable is used to initialize the VS_DEBUGGER_COMMAND property on
7489 each target as it is created. See that target property for additional
7490 information.
7491
7492 CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS
7493 New in version 3.27.
7494
7495
7496 This variable is used to initialize the VS_DEBUGGER_COMMAND_ARGUMENTS
7497 property on each target as it is created. See that target property for
7498 additional information.
7499
7500 CMAKE_VS_DEBUGGER_ENVIRONMENT
7501 New in version 3.27.
7502
7503
7504 This variable is used to initialize the VS_DEBUGGER_ENVIRONMENT prop‐
7505 erty on each target as it is created. See that target property for ad‐
7506 ditional information.
7507
7508 CMAKE_VS_DEBUGGER_WORKING_DIRECTORY
7509 New in version 3.27.
7510
7511
7512 This variable is used to initialize the VS_DEBUGGER_WORKING_DIRECTORY
7513 property on each target as it is created. See that target property for
7514 additional information.
7515
7516 CMAKE_VS_GLOBALS
7517 New in version 3.13.
7518
7519
7520 List of Key=Value records to be set per target as target properties
7521 VS_GLOBAL_<variable> with variable=Key and value Value.
7522
7523 For example:
7524
7525 set(CMAKE_VS_GLOBALS
7526 "DefaultLanguage=en-US"
7527 "MinimumVisualStudioVersion=14.0"
7528 )
7529
7530 will set properties VS_GLOBAL_DefaultLanguage to en-US and
7531 VS_GLOBAL_MinimumVisualStudioVersion to 14.0 for all targets (except
7532 for INTERFACE libraries).
7533
7534 This variable is meant to be set by a toolchain file.
7535
7536 CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
7537 New in version 3.3.
7538
7539
7540 Include INSTALL target to default build.
7541
7542 In Visual Studio solution, by default the INSTALL target will not be
7543 part of the default build. Setting this variable will enable the IN‐
7544 STALL target to be part of the default build.
7545
7546 CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
7547 New in version 3.8.
7548
7549
7550 Include PACKAGE target to default build.
7551
7552 In Visual Studio solution, by default the PACKAGE target will not be
7553 part of the default build. Setting this variable will enable the PACK‐
7554 AGE target to be part of the default build.
7555
7556 CMAKE_VS_JUST_MY_CODE_DEBUGGING
7557 New in version 3.15.
7558
7559
7560 Enable Just My Code with Visual Studio debugger.
7561
7562 This variable is used to initialize the VS_JUST_MY_CODE_DEBUGGING prop‐
7563 erty on all targets when they are created. See that target property
7564 for additional information.
7565
7566 CMAKE_VS_NO_COMPILE_BATCHING
7567 New in version 3.24.
7568
7569
7570 Turn off compile batching when using Visual Studio Generators.
7571
7572 This variable is used to initialize the VS_NO_COMPILE_BATCHING property
7573 on all targets when they are created. See that target property for ad‐
7574 ditional information.
7575
7576 Example
7577 This shows setting the property for the target foo using the variable.
7578
7579 set(CMAKE_VS_NO_COMPILE_BATCHING ON)
7580 add_library(foo SHARED foo.cpp)
7581
7582 CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
7583 New in version 3.12.
7584
7585
7586 This variable allows to override Visual Studio default Exclude Directo‐
7587 ries.
7588
7589 CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
7590 New in version 3.12.
7591
7592
7593 This variable allows to override Visual Studio default Executable Di‐
7594 rectories.
7595
7596 CMAKE_VS_SDK_INCLUDE_DIRECTORIES
7597 New in version 3.12.
7598
7599
7600 This variable allows to override Visual Studio default Include Directo‐
7601 ries.
7602
7603 CMAKE_VS_SDK_LIBRARY_DIRECTORIES
7604 New in version 3.12.
7605
7606
7607 This variable allows to override Visual Studio default Library Directo‐
7608 ries.
7609
7610 CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
7611 New in version 3.12.
7612
7613
7614 This variable allows to override Visual Studio default Library WinRT
7615 Directories.
7616
7617 CMAKE_VS_SDK_REFERENCE_DIRECTORIES
7618 New in version 3.12.
7619
7620
7621 This variable allows to override Visual Studio default Reference Direc‐
7622 tories.
7623
7624 CMAKE_VS_SDK_SOURCE_DIRECTORIES
7625 New in version 3.12.
7626
7627
7628 This variable allows to override Visual Studio default Source Directo‐
7629 ries.
7630
7631 CMAKE_VS_WINRT_BY_DEFAULT
7632 New in version 3.13.
7633
7634
7635 Inform Visual Studio Generators for VS 2010 and above that the target
7636 platform enables WinRT compilation by default and it needs to be ex‐
7637 plicitly disabled if /ZW or VS_WINRT_COMPONENT is omitted (as opposed
7638 to enabling it when either of those options is present)
7639
7640 This makes cmake configuration consistent in terms of WinRT among plat‐
7641 forms - if you did not enable the WinRT compilation explicitly, it will
7642 be disabled (by either not enabling it or explicitly disabling it)
7643
7644 Note: WinRT compilation is always explicitly disabled for C language
7645 source files, even if it is expliclty enabled for a project
7646
7647 This variable is meant to be set by a toolchain file for such plat‐
7648 forms.
7649
7650 CMAKE_WATCOM_RUNTIME_LIBRARY
7651 New in version 3.24.
7652
7653
7654 Select the Watcom runtime library for use by compilers targeting the
7655 Watcom ABI. This variable is used to initialize the
7656 WATCOM_RUNTIME_LIBRARY property on all targets as they are created. It
7657 is also propagated by calls to the try_compile() command into the test
7658 project.
7659
7660 The allowed values are:
7661
7662 SingleThreaded
7663 Compile without additional flags to use a single-threaded stati‐
7664 cally-linked runtime library.
7665
7666 SingleThreadedDLL
7667 Compile with -br or equivalent flag(s) to use a single-threaded
7668 dynamically-linked runtime library. This is not available for
7669 Linux targets.
7670
7671 MultiThreaded
7672 Compile with -bm or equivalent flag(s) to use a multi-threaded
7673 statically-linked runtime library.
7674
7675 MultiThreadedDLL
7676 Compile with -bm -br or equivalent flag(s) to use a
7677 multi-threaded dynamically-linked runtime library. This is not
7678 available for Linux targets.
7679
7680 The value is ignored on non-Watcom compilers but an unsupported value
7681 will be rejected as an error when using a compiler targeting the Watcom
7682 ABI.
7683
7684 The value may also be the empty string ("") in which case no runtime
7685 library selection flag will be added explicitly by CMake.
7686
7687 Use generator expressions to support per-configuration specification.
7688
7689 For example, the code:
7690
7691 set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded")
7692
7693 selects for all following targets a multi-threaded statically-linked
7694 runtime library.
7695
7696 If this variable is not set then the WATCOM_RUNTIME_LIBRARY target
7697 property will not be set automatically. If that property is not set
7698 then CMake uses the default value MultiThreadedDLL on Windows and Sin‐
7699 gleThreaded on other platforms to select a Watcom runtime library.
7700
7701 NOTE:
7702 This variable has effect only when policy CMP0136 is set to NEW
7703 prior to the first project() or enable_language() command that en‐
7704 ables a language using a compiler targeting the Watcom ABI.
7705
7706 CMAKE_WIN32_EXECUTABLE
7707 Default value for WIN32_EXECUTABLE of targets.
7708
7709 This variable is used to initialize the WIN32_EXECUTABLE property on
7710 all the targets. See that target property for additional information.
7711
7712 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
7713 New in version 3.4.
7714
7715
7716 Default value for WINDOWS_EXPORT_ALL_SYMBOLS target property. This
7717 variable is used to initialize the property on each target as it is
7718 created.
7719
7720 CMAKE_XCODE_ATTRIBUTE_<an-attribute>
7721 New in version 3.1.
7722
7723
7724 Set Xcode target attributes directly.
7725
7726 Tell the Xcode generator to set <an-attribute> to a given value in the
7727 generated Xcode project. Ignored on other generators.
7728
7729 This offers low-level control over the generated Xcode project file.
7730 It is meant as a last resort for specifying settings that CMake does
7731 not otherwise have a way to control. Although this can override a set‐
7732 ting CMake normally produces on its own, doing so bypasses CMake's
7733 model of the project and can break things.
7734
7735 See the XCODE_ATTRIBUTE_<an-attribute> target property to set at‐
7736 tributes on a specific target.
7737
7738 Contents of CMAKE_XCODE_ATTRIBUTE_<an-attribute> may use "generator ex‐
7739 pressions" with the syntax $<...>. See the
7740 cmake-generator-expressions(7) manual for available expressions. See
7741 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
7742 erties.
7743
7744 EXECUTABLE_OUTPUT_PATH
7745 Old executable location variable.
7746
7747 The target property RUNTIME_OUTPUT_DIRECTORY supersedes this variable
7748 for a target if it is set. Executable targets are otherwise placed in
7749 this directory.
7750
7751 LIBRARY_OUTPUT_PATH
7752 Old library location variable.
7753
7754 The target properties ARCHIVE_OUTPUT_DIRECTORY,
7755 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY supersede this
7756 variable for a target if they are set. Library targets are otherwise
7757 placed in this directory.
7758
7760 CMAKE_C_COMPILE_FEATURES
7761 New in version 3.1.
7762
7763
7764 List of features known to the C compiler
7765
7766 These features are known to be available for use with the C compiler.
7767 This list is a subset of the features listed in the
7768 CMAKE_C_KNOWN_FEATURES global property.
7769
7770 See the cmake-compile-features(7) manual for information on compile
7771 features and a list of supported compilers.
7772
7773 CMAKE_C_EXTENSIONS
7774 New in version 3.1.
7775
7776
7777 Default value for C_EXTENSIONS target property if set when a target is
7778 created.
7779
7780 See the cmake-compile-features(7) manual for information on compile
7781 features and a list of supported compilers.
7782
7783 CMAKE_C_STANDARD
7784 New in version 3.1.
7785
7786
7787 Default value for C_STANDARD target property if set when a target is
7788 created.
7789
7790 See the cmake-compile-features(7) manual for information on compile
7791 features and a list of supported compilers.
7792
7793 CMAKE_C_STANDARD_REQUIRED
7794 New in version 3.1.
7795
7796
7797 Default value for C_STANDARD_REQUIRED target property if set when a
7798 target is created.
7799
7800 See the cmake-compile-features(7) manual for information on compile
7801 features and a list of supported compilers.
7802
7803 CMAKE_COMPILER_IS_GNUCC
7804 True if the C compiler is GNU.
7805
7806 This variable is deprecated. Use CMAKE_C_COMPILER_ID instead.
7807
7808 CMAKE_COMPILER_IS_GNUCXX
7809 True if the C++ (CXX) compiler is GNU.
7810
7811 This variable is deprecated. Use CMAKE_CXX_COMPILER_ID instead.
7812
7813 CMAKE_COMPILER_IS_GNUG77
7814 True if the Fortran compiler is GNU.
7815
7816 This variable is deprecated. Use CMAKE_Fortran_COMPILER_ID instead.
7817
7818 CMAKE_CUDA_ARCHITECTURES
7819 New in version 3.18.
7820
7821
7822 Default value for CUDA_ARCHITECTURES property of targets.
7823
7824 Initialized by the CUDAARCHS environment variable if set. Otherwise as
7825 follows depending on CMAKE_CUDA_COMPILER_ID:
7826
7827 • For Clang: the oldest architecture that works.
7828
7829 • For NVIDIA: the default architecture chosen by the compiler. See
7830 policy CMP0104.
7831
7832 Users are encouraged to override this, as the default varies across
7833 compilers and compiler versions.
7834
7835 This variable is used to initialize the CUDA_ARCHITECTURES property on
7836 all targets. See the target property for additional information.
7837
7838 Examples
7839 cmake_minimum_required(VERSION)
7840
7841 if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
7842 set(CMAKE_CUDA_ARCHITECTURES 75)
7843 endif()
7844
7845 project(example LANGUAGES CUDA)
7846
7847 CMAKE_CUDA_ARCHITECTURES will default to 75 unless overridden by the
7848 user.
7849
7850 CMAKE_CUDA_COMPILE_FEATURES
7851 New in version 3.17.
7852
7853
7854 List of features known to the CUDA compiler
7855
7856 These features are known to be available for use with the CUDA com‐
7857 piler. This list is a subset of the features listed in the
7858 CMAKE_CUDA_KNOWN_FEATURES global property.
7859
7860 See the cmake-compile-features(7) manual for information on compile
7861 features and a list of supported compilers.
7862
7863 CMAKE_CUDA_EXTENSIONS
7864 New in version 3.8.
7865
7866
7867 Default value for CUDA_EXTENSIONS target property if set when a target
7868 is created.
7869
7870 See the cmake-compile-features(7) manual for information on compile
7871 features and a list of supported compilers.
7872
7873 CMAKE_CUDA_HOST_COMPILER
7874 New in version 3.10.
7875
7876
7877 When CMAKE_CUDA_COMPILER_ID is NVIDIA, CMAKE_CUDA_HOST_COMPILER selects
7878 the compiler executable to use when compiling host code for CUDA lan‐
7879 guage files. This maps to the nvcc -ccbin option.
7880
7881 The CMAKE_CUDA_HOST_COMPILER variable may be set explicitly before CUDA
7882 is first enabled by a project() or enable_language() command. This can
7883 be done via -DCMAKE_CUDA_HOST_COMPILER=... on the command line or in a
7884 toolchain file. Or, one may set the CUDAHOSTCXX environment variable
7885 to provide a default value.
7886
7887 Once the CUDA language is enabled, the CMAKE_CUDA_HOST_COMPILER vari‐
7888 able is read-only and changes to it are undefined behavior.
7889
7890 NOTE:
7891 Since CMAKE_CUDA_HOST_COMPILER is meaningful only when the
7892 CMAKE_CUDA_COMPILER_ID is NVIDIA, it does not make sense to set
7893 CMAKE_CUDA_HOST_COMPILER without also setting CMAKE_CUDA_COMPILER to
7894 NVCC.
7895
7896 NOTE:
7897 Ignored when using Visual Studio Generators.
7898
7899 CMAKE_CUDA_STANDARD
7900 New in version 3.8.
7901
7902
7903 Default value for CUDA_STANDARD target property if set when a target is
7904 created.
7905
7906 See the cmake-compile-features(7) manual for information on compile
7907 features and a list of supported compilers.
7908
7909 CMAKE_CUDA_STANDARD_REQUIRED
7910 New in version 3.8.
7911
7912
7913 Default value for CUDA_STANDARD_REQUIRED target property if set when a
7914 target is created.
7915
7916 See the cmake-compile-features(7) manual for information on compile
7917 features and a list of supported compilers.
7918
7919 CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES
7920 New in version 3.8.
7921
7922
7923 When the CUDA language has been enabled, this provides a
7924 semicolon-separated list of include directories provided by the CUDA
7925 Toolkit. The value may be useful for C++ source files to include CUDA
7926 headers.
7927
7928 CMAKE_CXX_COMPILE_FEATURES
7929 New in version 3.1.
7930
7931
7932 List of features known to the C++ compiler
7933
7934 These features are known to be available for use with the C++ compiler.
7935 This list is a subset of the features listed in the
7936 CMAKE_CXX_KNOWN_FEATURES global property.
7937
7938 See the cmake-compile-features(7) manual for information on compile
7939 features and a list of supported compilers.
7940
7941 CMAKE_CXX_EXTENSIONS
7942 New in version 3.1.
7943
7944
7945 Default value for CXX_EXTENSIONS target property if set when a target
7946 is created.
7947
7948 See the cmake-compile-features(7) manual for information on compile
7949 features and a list of supported compilers.
7950
7951 CMAKE_CXX_STANDARD
7952 New in version 3.1.
7953
7954
7955 Default value for CXX_STANDARD target property if set when a target is
7956 created.
7957
7958 See the cmake-compile-features(7) manual for information on compile
7959 features and a list of supported compilers.
7960
7961 CMAKE_CXX_STANDARD_REQUIRED
7962 New in version 3.1.
7963
7964
7965 Default value for CXX_STANDARD_REQUIRED target property if set when a
7966 target is created.
7967
7968 See the cmake-compile-features(7) manual for information on compile
7969 features and a list of supported compilers.
7970
7971 CMAKE_Fortran_MODDIR_DEFAULT
7972 Fortran default module output directory.
7973
7974 Most Fortran compilers write .mod files to the current working direc‐
7975 tory. For those that do not, this is set to . and used when the
7976 Fortran_MODULE_DIRECTORY target property is not set.
7977
7978 CMAKE_Fortran_MODDIR_FLAG
7979 Fortran flag for module output directory.
7980
7981 This stores the flag needed to pass the value of the
7982 Fortran_MODULE_DIRECTORY target property to the compiler.
7983
7984 CMAKE_Fortran_MODOUT_FLAG
7985 Fortran flag to enable module output.
7986
7987 Most Fortran compilers write .mod files out by default. For others,
7988 this stores the flag needed to enable module output.
7989
7990 CMAKE_HIP_ARCHITECTURES
7991 New in version 3.21.
7992
7993
7994 Default value for HIP_ARCHITECTURES property of targets.
7995
7996 This is initialized to the architectures reported by rocm_agent_enumer‐
7997 ator, if available, and otherwise to the default chosen by the com‐
7998 piler.
7999
8000 This variable is used to initialize the HIP_ARCHITECTURES property on
8001 all targets. See the target property for additional information.
8002
8003 CMAKE_HIP_EXTENSIONS
8004 New in version 3.21.
8005
8006
8007 Default value for HIP_EXTENSIONS target property if set when a target
8008 is created.
8009
8010 See the cmake-compile-features(7) manual for information on compile
8011 features and a list of supported compilers.
8012
8013 CMAKE_HIP_STANDARD
8014 New in version 3.21.
8015
8016
8017 Default value for HIP_STANDARD target property if set when a target is
8018 created.
8019
8020 See the cmake-compile-features(7) manual for information on compile
8021 features and a list of supported compilers.
8022
8023 CMAKE_HIP_STANDARD_REQUIRED
8024 New in version 3.21.
8025
8026
8027 Default value for HIP_STANDARD_REQUIRED target property if set when a
8028 target is created.
8029
8030 See the cmake-compile-features(7) manual for information on compile
8031 features and a list of supported compilers.
8032
8033 CMAKE_ISPC_HEADER_DIRECTORY
8034 New in version 3.19.
8035
8036
8037 ISPC generated header output directory.
8038
8039 This variable is used to initialize the ISPC_HEADER_DIRECTORY property
8040 on all the targets. See the target property for additional informa‐
8041 tion.
8042
8043 CMAKE_ISPC_HEADER_SUFFIX
8044 New in version 3.19.2.
8045
8046
8047 Output suffix to be used for ISPC generated headers.
8048
8049 This variable is used to initialize the ISPC_HEADER_SUFFIX property on
8050 all the targets. See the target property for additional information.
8051
8052 CMAKE_ISPC_INSTRUCTION_SETS
8053 New in version 3.19.
8054
8055
8056 Default value for ISPC_INSTRUCTION_SETS property of targets.
8057
8058 This variable is used to initialize the ISPC_INSTRUCTION_SETS property
8059 on all targets. See the target property for additional information.
8060
8061 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE
8062 New in version 3.7.1.
8063
8064
8065 When Cross Compiling for Android this variable contains the toolchain
8066 binutils machine name (e.g. gcc -dumpmachine). The binutils typically
8067 have a <machine>- prefix on their name.
8068
8069 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
8070 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX.
8071
8072 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
8073 New in version 3.7.
8074
8075
8076 When Cross Compiling for Android this variable contains the absolute
8077 path prefixing the toolchain GNU compiler and its binutils.
8078
8079 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX and
8080 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
8081
8082 For example, the path to the linker is:
8083
8084 ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX}
8085
8086 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
8087 New in version 3.7.
8088
8089
8090 When Cross Compiling for Android this variable contains the host plat‐
8091 form suffix of the toolchain GNU compiler and its binutils.
8092
8093 See also CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX and
8094 CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE.
8095
8096 CMAKE_<LANG>_ARCHIVE_APPEND
8097 Rule variable to append to a static archive.
8098
8099 This is a rule variable that tells CMake how to append to a static ar‐
8100 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8101 some platforms in order to support large object counts. See also
8102 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_FINISH.
8103
8104 CMAKE_<LANG>_ARCHIVE_CREATE
8105 Rule variable to create a new static archive.
8106
8107 This is a rule variable that tells CMake how to create a static ar‐
8108 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8109 some platforms in order to support large object counts. See also
8110 CMAKE_<LANG>_ARCHIVE_APPEND and CMAKE_<LANG>_ARCHIVE_FINISH.
8111
8112 CMAKE_<LANG>_ARCHIVE_FINISH
8113 Rule variable to finish an existing static archive.
8114
8115 This is a rule variable that tells CMake how to finish a static ar‐
8116 chive. It is used in place of CMAKE_<LANG>_CREATE_STATIC_LIBRARY on
8117 some platforms in order to support large object counts. See also
8118 CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_APPEND.
8119
8120 CMAKE_<LANG>_BYTE_ORDER
8121 New in version 3.20.
8122
8123
8124 Byte order of <LANG> compiler target architecture, if known. If de‐
8125 fined and not empty, the value is one of:
8126
8127 BIG_ENDIAN
8128 The target architecture is Big Endian.
8129
8130 LITTLE_ENDIAN
8131 The target architecture is Little Endian.
8132
8133 This is defined for languages C, CXX, OBJC, OBJCXX, and CUDA.
8134
8135 If CMAKE_OSX_ARCHITECTURES specifies multiple architectures, the value
8136 of CMAKE_<LANG>_BYTE_ORDER is non-empty only if all architectures share
8137 the same byte order.
8138
8139 CMAKE_<LANG>_COMPILE_OBJECT
8140 Rule variable to compile a single object file.
8141
8142 This is a rule variable that tells CMake how to compile a single object
8143 file for the language <LANG>.
8144
8145 CMAKE_<LANG>_COMPILER
8146 The full path to the compiler for LANG.
8147
8148 This is the command that will be used as the <LANG> compiler. Once
8149 set, you can not change this variable.
8150
8151 Usage
8152 This variable can be set by the user during the first time a build tree
8153 is configured.
8154
8155 If a non-full path value is supplied then CMake will resolve the full
8156 path of the compiler.
8157
8158 The variable could be set in a user supplied toolchain file or via -D
8159 on the command line.
8160
8161 NOTE:
8162 Options that are required to make the compiler work correctly can be
8163 included as items in a list; they can not be changed.
8164
8165 #set within user supplied toolchain file
8166 set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2)
8167
8168 or
8169
8170 $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2'
8171
8172 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN
8173 The external toolchain for cross-compiling, if supported.
8174
8175 Some compiler toolchains do not ship their own auxiliary utilities such
8176 as archivers and linkers. The compiler driver may support a com‐
8177 mand-line argument to specify the location of such tools.
8178 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN may be set to a path to the
8179 external toolchain and will be passed to the compiler driver if sup‐
8180 ported.
8181
8182 This variable may only be set in a toolchain file specified by the
8183 CMAKE_TOOLCHAIN_FILE variable.
8184
8185 CMAKE_<LANG>_COMPILER_ID
8186 Compiler identification string.
8187
8188 A short string unique to the compiler vendor. Possible values include:
8189
8190 ┌─────────────────────┬────────────────────────────┐
8191 │Value │ Name │
8192 ├─────────────────────┼────────────────────────────┤
8193 │Absoft │ Absoft Fortran │
8194 ├─────────────────────┼────────────────────────────┤
8195 │ADSP │ Analog VisualDSP++ │
8196 ├─────────────────────┼────────────────────────────┤
8197 │AppleClang │ Apple Clang │
8198 ├─────────────────────┼────────────────────────────┤
8199 │ARMCC │ ARM Compiler │
8200 ├─────────────────────┼────────────────────────────┤
8201 │ARMClang │ ARM Compiler based on │
8202 │ │ Clang │
8203 ├─────────────────────┼────────────────────────────┤
8204 │Bruce │ Bruce C Compiler │
8205 ├─────────────────────┼────────────────────────────┤
8206 │CCur │ Concurrent Fortran │
8207 ├─────────────────────┼────────────────────────────┤
8208 │Clang │ LLVM Clang │
8209 ├─────────────────────┼────────────────────────────┤
8210 │Cray │ Cray Compiler │
8211 ├─────────────────────┼────────────────────────────┤
8212 │Embarcadero, Borland │ Embarcadero │
8213 ├─────────────────────┼────────────────────────────┤
8214 │Flang │ Classic Flang Fortran Com‐ │
8215 │ │ piler │
8216 ├─────────────────────┼────────────────────────────┤
8217 │LLVMFlang │ LLVM Flang Fortran Com‐ │
8218 │ │ piler │
8219 ├─────────────────────┼────────────────────────────┤
8220 │Fujitsu │ Fujitsu HPC compiler (Trad │
8221 │ │ mode) │
8222 ├─────────────────────┼────────────────────────────┤
8223 │FujitsuClang │ Fujitsu HPC compiler │
8224 │ │ (Clang mode) │
8225 ├─────────────────────┼────────────────────────────┤
8226 │G95 │ G95 Fortran │
8227 ├─────────────────────┼────────────────────────────┤
8228 │GNU │ GNU Compiler Collection │
8229 ├─────────────────────┼────────────────────────────┤
8230 │GHS │ Green Hills Software │
8231 ├─────────────────────┼────────────────────────────┤
8232 │HP │ Hewlett-Packard Compiler │
8233 ├─────────────────────┼────────────────────────────┤
8234 │IAR │ IAR Systems │
8235 └─────────────────────┴────────────────────────────┘
8236
8237
8238 │Intel │ Intel Classic Compiler │
8239 ├─────────────────────┼────────────────────────────┤
8240 │IntelLLVM │ Intel LLVM-Based Compiler │
8241 ├─────────────────────┼────────────────────────────┤
8242 │LCC │ MCST Elbrus C/C++/Fortran │
8243 │ │ Compiler │
8244 ├─────────────────────┼────────────────────────────┤
8245 │MSVC │ Microsoft Visual Studio │
8246 ├─────────────────────┼────────────────────────────┤
8247 │NVHPC │ NVIDIA HPC Compiler │
8248 ├─────────────────────┼────────────────────────────┤
8249 │NVIDIA │ NVIDIA CUDA Compiler │
8250 ├─────────────────────┼────────────────────────────┤
8251 │OpenWatcom │ Open Watcom │
8252 ├─────────────────────┼────────────────────────────┤
8253 │PGI │ The Portland Group │
8254 ├─────────────────────┼────────────────────────────┤
8255 │PathScale │ PathScale │
8256 ├─────────────────────┼────────────────────────────┤
8257 │SDCC │ Small Device C Compiler │
8258 ├─────────────────────┼────────────────────────────┤
8259 │SunPro │ Oracle Solaris Studio │
8260 ├─────────────────────┼────────────────────────────┤
8261 │Tasking │ Tasking Compiler Toolsets │
8262 ├─────────────────────┼────────────────────────────┤
8263 │TI │ Texas Instruments │
8264 ├─────────────────────┼────────────────────────────┤
8265 │TinyCC │ Tiny C Compiler │
8266 ├─────────────────────┼────────────────────────────┤
8267 │XL, VisualAge, zOS │ IBM XL │
8268 ├─────────────────────┼────────────────────────────┤
8269 │XLClang │ IBM Clang-based XL │
8270 ├─────────────────────┼────────────────────────────┤
8271 │IBMClang │ IBM LLVM-based Compiler │
8272 └─────────────────────┴────────────────────────────┘
8273
8274 This variable is not guaranteed to be defined for all compilers or lan‐
8275 guages.
8276
8277 CMAKE_<LANG>_COMPILER_LOADED
8278 Defined to true if the language is enabled.
8279
8280 When language <LANG> is enabled by project() or enable_language() this
8281 variable is defined to 1.
8282
8283 CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND
8284 New in version 3.10.
8285
8286
8287 Command that outputs the compiler pre definitions.
8288
8289 See AUTOMOC which uses CMAKE_CXX_COMPILER_PREDEFINES_COMMAND to gener‐
8290 ate the AUTOMOC_COMPILER_PREDEFINES.
8291
8292 CMAKE_<LANG>_COMPILER_TARGET
8293 The target for cross-compiling, if supported.
8294
8295 Some compiler drivers are inherently cross-compilers, such as clang and
8296 QNX qcc. These compiler drivers support a command-line argument to
8297 specify the target to cross-compile for.
8298
8299 This variable may only be set in a toolchain file specified by the
8300 CMAKE_TOOLCHAIN_FILE variable.
8301
8302 CMAKE_<LANG>_COMPILER_VERSION
8303 Compiler version string.
8304
8305 Compiler version in major[.minor[.patch[.tweak]]] format. This vari‐
8306 able is not guaranteed to be defined for all compilers or languages.
8307
8308 For example CMAKE_C_COMPILER_VERSION and CMAKE_CXX_COMPILER_VERSION
8309 might indicate the respective C and C++ compiler version.
8310
8311 CMAKE_<LANG>_CREATE_SHARED_LIBRARY
8312 Rule variable to create a shared library.
8313
8314 This is a rule variable that tells CMake how to create a shared library
8315 for the language <LANG>. This rule variable is a ; delimited list of
8316 commands to run to perform the linking step.
8317
8318 CMAKE_<LANG>_CREATE_SHARED_MODULE
8319 Rule variable to create a shared module.
8320
8321 This is a rule variable that tells CMake how to create a shared library
8322 for the language <LANG>. This rule variable is a ; delimited list of
8323 commands to run.
8324
8325 CMAKE_<LANG>_CREATE_STATIC_LIBRARY
8326 Rule variable to create a static library.
8327
8328 This is a rule variable that tells CMake how to create a static library
8329 for the language <LANG>.
8330
8331 CMAKE_<LANG>_EXTENSIONS
8332 The variations are:
8333
8334 • CMAKE_C_EXTENSIONS
8335
8336 • CMAKE_CXX_EXTENSIONS
8337
8338 • CMAKE_CUDA_EXTENSIONS
8339
8340 • CMAKE_HIP_EXTENSIONS
8341
8342 • CMAKE_OBJC_EXTENSIONS
8343
8344 • CMAKE_OBJCXX_EXTENSIONS
8345
8346 Default values for <LANG>_EXTENSIONS target properties if set when a
8347 target is created. For the compiler's default setting see
8348 CMAKE_<LANG>_EXTENSIONS_DEFAULT.
8349
8350 For supported CMake versions see the respective pages.
8351
8352 See the cmake-compile-features(7) manual for information on compile
8353 features and a list of supported compilers.
8354
8355 CMAKE_<LANG>_EXTENSIONS_DEFAULT
8356 New in version 3.22.
8357
8358
8359 Compiler's default extensions mode. Used as the default for the
8360 <LANG>_EXTENSIONS target property when CMAKE_<LANG>_EXTENSIONS is not
8361 set (see CMP0128).
8362
8363 This variable is read-only. Modifying it is undefined behavior.
8364
8365 CMAKE_<LANG>_FLAGS
8366 Language-wide flags for language <LANG> used when building for all con‐
8367 figurations. These flags will be passed to all invocations of the com‐
8368 piler. This includes invocations that drive compiling and those that
8369 drive linking.
8370
8371 For each language, if this variable is not defined, it is initialized
8372 and stored in the cache using values from environment variables in com‐
8373 bination with CMake's builtin defaults for the toolchain:
8374
8375 • CMAKE_C_FLAGS: Initialized by the CFLAGS environment variable.
8376
8377 • CMAKE_CXX_FLAGS: Initialized by the CXXFLAGS environment variable.
8378
8379 • CMAKE_CUDA_FLAGS: Initialized by the CUDAFLAGS environment variable.
8380
8381 • CMAKE_Fortran_FLAGS: Initialized by the FFLAGS environment variable.
8382
8383 • CMAKE_CSharp_FLAGS: Initialized by the CSFLAGS environment variable.
8384
8385 • CMAKE_HIP_FLAGS: Initialized by the HIPFLAGS environment variable.
8386
8387 • CMAKE_ISPC_FLAGS: Initialized by the ISPCFLAGS environment variable.
8388
8389 This value is a command-line string fragment. Therefore, multiple op‐
8390 tions should be separated by spaces, and options with spaces should be
8391 quoted.
8392
8393 The flags in this variable will be passed before those in the per-con‐
8394 figuration CMAKE_<LANG>_FLAGS_<CONFIG> variable. On invocations driv‐
8395 ing compiling, flags from both variables will be passed before flags
8396 added by commands such as add_compile_options() and
8397 target_compile_options(). On invocations driving linking, they will be
8398 passed before flags added by commands such as add_link_options() and
8399 target_link_options().
8400
8401 CMAKE_<LANG>_FLAGS_<CONFIG>
8402 Language-wide flags for language <LANG> used when building for the
8403 <CONFIG> configuration. These flags will be passed to all invocations
8404 of the compiler in the corresponding configuration. This includes in‐
8405 vocations that drive compiling and those that drive linking.
8406
8407 The flags in this variable will be passed after those in the
8408 CMAKE_<LANG>_FLAGS variable. On invocations driving compiling, flags
8409 from both variables will be passed before flags added by commands such
8410 as add_compile_options() and target_compile_options(). On invocations
8411 driving linking, they will be passed before flags added by commands
8412 such as add_link_options() and target_link_options().
8413
8414 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8415 New in version 3.11.
8416
8417
8418 Value used to initialize the CMAKE_<LANG>_FLAGS_<CONFIG> cache entry
8419 the first time a build tree is configured for language <LANG>. This
8420 variable is meant to be set by a toolchain file. CMake may prepend or
8421 append content to the value based on the environment and target plat‐
8422 form.
8423
8424 See also CMAKE_<LANG>_FLAGS_INIT.
8425
8426 CMAKE_<LANG>_FLAGS_DEBUG
8427 This variable is the Debug variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8428 variable.
8429
8430 CMAKE_<LANG>_FLAGS_DEBUG_INIT
8431 New in version 3.7.
8432
8433
8434 This variable is the Debug variant of the
8435 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8436
8437 CMAKE_<LANG>_FLAGS_INIT
8438 New in version 3.7.
8439
8440
8441 Value used to initialize the CMAKE_<LANG>_FLAGS cache entry the first
8442 time a build tree is configured for language <LANG>. This variable is
8443 meant to be set by a toolchain file. CMake may prepend or append con‐
8444 tent to the value based on the environment and target platform. For
8445 example, the contents of a xxxFLAGS environment variable will be
8446 prepended, where xxx will be language-specific but not necessarily the
8447 same as <LANG> (e.g. CXXFLAGS for CXX, FFLAGS for Fortran, and so on).
8448 This value is a command-line string fragment. Therefore, multiple op‐
8449 tions should be separated by spaces, and options with spaces should be
8450 quoted.
8451
8452 See also the configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
8453 variable.
8454
8455 CMAKE_<LANG>_FLAGS_MINSIZEREL
8456 This variable is the MinSizeRel variant of the
8457 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8458
8459 CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
8460 New in version 3.7.
8461
8462
8463 This variable is the MinSizeRel variant of the
8464 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8465
8466 CMAKE_<LANG>_FLAGS_RELEASE
8467 This variable is the Release variant of the CMAKE_<LANG>_FLAGS_<CONFIG>
8468 variable.
8469
8470 CMAKE_<LANG>_FLAGS_RELEASE_INIT
8471 New in version 3.7.
8472
8473
8474 This variable is the Release variant of the
8475 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8476
8477 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
8478 This variable is the RelWithDebInfo variant of the
8479 CMAKE_<LANG>_FLAGS_<CONFIG> variable.
8480
8481 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT
8482 New in version 3.7.
8483
8484
8485 This variable is the RelWithDebInfo variant of the
8486 CMAKE_<LANG>_FLAGS_<CONFIG>_INIT variable.
8487
8488 CMAKE_<LANG>_IGNORE_EXTENSIONS
8489 File extensions that should be ignored by the build.
8490
8491 This is a list of file extensions that may be part of a project for a
8492 given language but are not compiled.
8493
8494 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
8495 Directories implicitly searched by the compiler for header files.
8496
8497 CMake does not explicitly specify these directories on compiler command
8498 lines for language <LANG>. This prevents system include directories
8499 from being treated as user include directories on some compilers, which
8500 is important for C, CXX, and CUDA to avoid overriding standard library
8501 headers.
8502
8503 This value is not used for Fortran because it has no standard library
8504 headers and some compilers do not search their implicit include direc‐
8505 tories for module .mod files.
8506
8507 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8508 Implicit linker search path detected for language <LANG>.
8509
8510 Compilers typically pass directories containing language runtime li‐
8511 braries and default library search paths when they invoke a linker.
8512 These paths are implicit linker search directories for the compiler's
8513 language.
8514
8515 For each language enabled by the project() or enable_language() com‐
8516 mand, CMake automatically detects these directories and reports the re‐
8517 sults in this variable. The
8518 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES_EXCLUDE environment variable may
8519 be set to exclude specific directories from the automatically detected
8520 results.
8521
8522 When linking to a static library, CMake adds the implicit link directo‐
8523 ries from this variable for each language used in the static library
8524 (except the language whose compiler is used to drive linking). In the
8525 case of an imported static library, the
8526 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8527 whose implicit link information is needed. If any of the languages is
8528 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
8529 variable may instead be provided by the project. Or, a toolchain file
8530 may set the variable to a value known for the specified toolchain. It
8531 will either be overridden when the language is enabled, or used as a
8532 fallback.
8533
8534 Some toolchains read implicit directories from an environment variable
8535 such as LIBRARY_PATH. If using such an environment variable, keep its
8536 value consistent when operating in a given build tree because CMake
8537 saves the value detected when first creating a build tree.
8538
8539 If policy CMP0060 is not set to NEW, then when a library in one of
8540 these directories is given by full path to target_link_libraries()
8541 CMake will generate the -l<name> form on link lines for historical pur‐
8542 poses.
8543
8544 See also the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES variable.
8545
8546 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
8547 Implicit linker framework search path detected for language <LANG>.
8548
8549 These paths are implicit linker framework search directories for the
8550 compiler's language. CMake automatically detects these directories for
8551 each language and reports the results in this variable.
8552
8553 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8554 Implicit link libraries and flags detected for language <LANG>.
8555
8556 Compilers typically pass language runtime library names and other flags
8557 when they invoke a linker. These flags are implicit link options for
8558 the compiler's language. For each language enabled by the project() or
8559 enable_language() command, CMake automatically detects these libraries
8560 and flags and reports the results in this variable.
8561
8562 When linking to a static library, CMake adds the implicit link li‐
8563 braries and flags from this variable for each language used in the
8564 static library (except the language whose compiler is used to drive
8565 linking). In the case of an imported static library, the
8566 IMPORTED_LINK_INTERFACE_LANGUAGES target property lists the languages
8567 whose implicit link information is needed. If any of the languages is
8568 not enabled, its value for the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
8569 variable may instead be provided by the project. Or, a toolchain file
8570 may set the variable to a value known for the specified toolchain. It
8571 will either be overridden when the language is enabled, or used as a
8572 fallback.
8573
8574 See also the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES variable.
8575
8576 CMAKE_<LANG>_LIBRARY_ARCHITECTURE
8577 Target architecture library directory name detected for <LANG>.
8578
8579 If the <LANG> compiler passes to the linker an architecture-specific
8580 system library search directory such as <prefix>/lib/<arch> this vari‐
8581 able contains the <arch> name if/as detected by CMake.
8582
8583 CMAKE_<LANG>_LINK_EXECUTABLE
8584 Rule variable to link an executable.
8585
8586 Rule variable to link an executable for the given language.
8587
8588 CMAKE_<LANG>_LINKER_WRAPPER_FLAG
8589 New in version 3.13.
8590
8591
8592 Defines the syntax of compiler driver option to pass options to the
8593 linker tool. It will be used to translate the LINKER: prefix in the
8594 link options (see add_link_options() and target_link_options()).
8595
8596 This variable holds a semicolon-separated list of tokens. If a space
8597 (i.e. " ") is specified as last token, flag and LINKER: arguments will
8598 be specified as separate arguments to the compiler driver. The
8599 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variable can be specified to man‐
8600 age concatenation of arguments.
8601
8602 For example, for Clang we have:
8603
8604 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")
8605
8606 Specifying "LINKER:-z,defs" will be transformed in -Xlinker -z -Xlinker
8607 defs.
8608
8609 For GNU GCC:
8610
8611 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
8612 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8613
8614 Specifying "LINKER:-z,defs" will be transformed in -Wl,-z,defs.
8615
8616 And for SunPro:
8617
8618 set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
8619 set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
8620
8621 Specifying "LINKER:-z,defs" will be transformed in -Qoption ld -z,defs.
8622
8623 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
8624 New in version 3.13.
8625
8626
8627 This variable is used with CMAKE_<LANG>_LINKER_WRAPPER_FLAG variable to
8628 format LINKER: prefix in the link options (see add_link_options() and
8629 target_link_options()).
8630
8631 When specified, arguments of the LINKER: prefix will be concatenated
8632 using this value as separator.
8633
8634 CMAKE_<LANG>_OUTPUT_EXTENSION
8635 Extension for the output of a compile for a single file.
8636
8637 This is the extension for an object file for the given <LANG>. For ex‐
8638 ample .obj for C on Windows.
8639
8640 CMAKE_<LANG>_SIMULATE_ID
8641 Identification string of the "simulated" compiler.
8642
8643 Some compilers simulate other compilers to serve as drop-in replace‐
8644 ments. When CMake detects such a compiler it sets this variable to
8645 what would have been the CMAKE_<LANG>_COMPILER_ID for the simulated
8646 compiler.
8647
8648 NOTE:
8649 In other words, this variable describes the ABI compatibility of the
8650 generated code.
8651
8652 CMAKE_<LANG>_SIMULATE_VERSION
8653 Version string of "simulated" compiler.
8654
8655 Some compilers simulate other compilers to serve as drop-in replace‐
8656 ments. When CMake detects such a compiler it sets this variable to
8657 what would have been the CMAKE_<LANG>_COMPILER_VERSION for the simu‐
8658 lated compiler.
8659
8660 CMAKE_<LANG>_SIZEOF_DATA_PTR
8661 Size of pointer-to-data types for language <LANG>.
8662
8663 This holds the size (in bytes) of pointer-to-data types in the target
8664 platform ABI. It is defined for languages C and CXX (C++).
8665
8666 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
8667 Extensions of source files for the given language.
8668
8669 This is the list of extensions for a given language's source files.
8670
8671 CMAKE_<LANG>_STANDARD
8672 The variations are:
8673
8674 • CMAKE_C_STANDARD
8675
8676 • CMAKE_CXX_STANDARD
8677
8678 • CMAKE_CUDA_STANDARD
8679
8680 • CMAKE_HIP_STANDARD
8681
8682 • CMAKE_OBJC_STANDARD
8683
8684 • CMAKE_OBJCXX_STANDARD
8685
8686 Default values for <LANG>_STANDARD target properties if set when a tar‐
8687 get is created.
8688
8689 For supported CMake versions see the respective pages.
8690
8691 See the cmake-compile-features(7) manual for information on compile
8692 features and a list of supported compilers.
8693
8694 CMAKE_<LANG>_STANDARD_DEFAULT
8695 New in version 3.9.
8696
8697
8698 The compiler's default standard for the language <LANG>. Empty if the
8699 compiler has no conception of standard levels.
8700
8701 CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES
8702 New in version 3.6.
8703
8704
8705 Include directories to be used for every source file compiled with the
8706 <LANG> compiler. This is meant for specification of system include di‐
8707 rectories needed by the language for the current platform. The direc‐
8708 tories always appear at the end of the include path passed to the com‐
8709 piler.
8710
8711 This variable should not be set by project code. It is meant to be set
8712 by CMake's platform information modules for the current toolchain, or
8713 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8714
8715 See also CMAKE_<LANG>_STANDARD_LIBRARIES.
8716
8717 CMAKE_<LANG>_STANDARD_LIBRARIES
8718 New in version 3.6.
8719
8720
8721 Libraries linked into every executable and shared library linked for
8722 language <LANG>. This is meant for specification of system libraries
8723 needed by the language for the current platform.
8724
8725 This variable should not be set by project code. It is meant to be set
8726 by CMake's platform information modules for the current toolchain, or
8727 by a toolchain file when used with CMAKE_TOOLCHAIN_FILE.
8728
8729 See also CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES.
8730
8731 CMAKE_<LANG>_STANDARD_REQUIRED
8732 The variations are:
8733
8734 • CMAKE_C_STANDARD_REQUIRED
8735
8736 • CMAKE_CXX_STANDARD_REQUIRED
8737
8738 • CMAKE_CUDA_STANDARD_REQUIRED
8739
8740 • CMAKE_HIP_STANDARD_REQUIRED
8741
8742 • CMAKE_OBJC_STANDARD_REQUIRED
8743
8744 • CMAKE_OBJCXX_STANDARD_REQUIRED
8745
8746 Default values for <LANG>_STANDARD_REQUIRED target properties if set
8747 when a target is created.
8748
8749 For supported CMake versions see the respective pages.
8750
8751 See the cmake-compile-features(7) manual for information on compile
8752 features and a list of supported compilers.
8753
8754 CMAKE_OBJC_EXTENSIONS
8755 New in version 3.16.
8756
8757
8758 Default value for OBJC_EXTENSIONS target property if set when a target
8759 is created.
8760
8761 See the cmake-compile-features(7) manual for information on compile
8762 features and a list of supported compilers.
8763
8764 CMAKE_OBJC_STANDARD
8765 New in version 3.16.
8766
8767
8768 Default value for OBJC_STANDARD target property if set when a target is
8769 created.
8770
8771 See the cmake-compile-features(7) manual for information on compile
8772 features and a list of supported compilers.
8773
8774 CMAKE_OBJC_STANDARD_REQUIRED
8775 New in version 3.16.
8776
8777
8778 Default value for OBJC_STANDARD_REQUIRED target property if set when a
8779 target is created.
8780
8781 See the cmake-compile-features(7) manual for information on compile
8782 features and a list of supported compilers.
8783
8784 CMAKE_OBJCXX_EXTENSIONS
8785 New in version 3.16.
8786
8787
8788 Default value for OBJCXX_EXTENSIONS target property if set when a tar‐
8789 get is created.
8790
8791 See the cmake-compile-features(7) manual for information on compile
8792 features and a list of supported compilers.
8793
8794 CMAKE_OBJCXX_STANDARD
8795 New in version 3.16.
8796
8797
8798 Default value for OBJCXX_STANDARD target property if set when a target
8799 is created.
8800
8801 See the cmake-compile-features(7) manual for information on compile
8802 features and a list of supported compilers.
8803
8804 CMAKE_OBJCXX_STANDARD_REQUIRED
8805 New in version 3.16.
8806
8807
8808 Default value for OBJCXX_STANDARD_REQUIRED target property if set when
8809 a target is created.
8810
8811 See the cmake-compile-features(7) manual for information on compile
8812 features and a list of supported compilers.
8813
8814 CMAKE_Swift_LANGUAGE_VERSION
8815 New in version 3.7.
8816
8817
8818 Set to the Swift language version number. If not set, the oldest
8819 legacy version known to be available in the host Xcode version is as‐
8820 sumed:
8821
8822 • Swift 4.0 for Xcode 10.2 and above.
8823
8824 • Swift 3.0 for Xcode 8.3 and above.
8825
8826 • Swift 2.3 for Xcode 8.2 and below.
8827
8828 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
8829 Specify a CMake file that overrides platform information for <LANG>.
8830
8831 This is a language-specific version of CMAKE_USER_MAKE_RULES_OVERRIDE
8832 loaded only when enabling language <LANG>.
8833
8835 CTEST_BINARY_DIRECTORY
8836 New in version 3.1.
8837
8838
8839 Specify the CTest BuildDirectory setting in a ctest(1) dashboard client
8840 script.
8841
8842 CTEST_BUILD_COMMAND
8843 New in version 3.1.
8844
8845
8846 Specify the CTest MakeCommand setting in a ctest(1) dashboard client
8847 script.
8848
8849 CTEST_BUILD_NAME
8850 New in version 3.1.
8851
8852
8853 Specify the CTest BuildName setting in a ctest(1) dashboard client
8854 script.
8855
8856 CTEST_BZR_COMMAND
8857 New in version 3.1.
8858
8859
8860 Specify the CTest BZRCommand setting in a ctest(1) dashboard client
8861 script.
8862
8863 CTEST_BZR_UPDATE_OPTIONS
8864 New in version 3.1.
8865
8866
8867 Specify the CTest BZRUpdateOptions setting in a ctest(1) dashboard
8868 client script.
8869
8870 CTEST_CHANGE_ID
8871 New in version 3.4.
8872
8873
8874 Specify the CTest ChangeId setting in a ctest(1) dashboard client
8875 script.
8876
8877 This setting allows CTest to pass arbitrary information about this
8878 build up to CDash. One use of this feature is to allow CDash to post
8879 comments on your pull request if anything goes wrong with your build.
8880
8881 CTEST_CHECKOUT_COMMAND
8882 New in version 3.1.
8883
8884
8885 Tell the ctest_start() command how to checkout or initialize the source
8886 directory in a ctest(1) dashboard client script.
8887
8888 CTEST_CONFIGURATION_TYPE
8889 New in version 3.1.
8890
8891
8892 Specify the CTest DefaultCTestConfigurationType setting in a ctest(1)
8893 dashboard client script.
8894
8895 If the configuration type is set via -C <cfg> from the command line
8896 then this variable is populated accordingly.
8897
8898 CTEST_CONFIGURE_COMMAND
8899 New in version 3.1.
8900
8901
8902 Specify the CTest ConfigureCommand setting in a ctest(1) dashboard
8903 client script.
8904
8905 CTEST_COVERAGE_COMMAND
8906 New in version 3.1.
8907
8908
8909 Specify the CTest CoverageCommand setting in a ctest(1) dashboard
8910 client script.
8911
8912 Cobertura
8913 Using Cobertura as the coverage generation within your multi-module
8914 Java project can generate a series of XML files.
8915
8916 The Cobertura Coverage parser expects to read the coverage data from a
8917 single XML file which contains the coverage data for all modules.
8918 Cobertura has a program with the ability to merge given cobertura.ser
8919 files and then another program to generate a combined XML file from the
8920 previous merged file. For command line testing, this can be done by
8921 hand prior to CTest looking for the coverage files. For script builds,
8922 set the CTEST_COVERAGE_COMMAND variable to point to a file which will
8923 perform these same steps, such as a .sh or .bat file.
8924
8925 set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh)
8926
8927 where the run-coverage-and-consolidate.sh script is perhaps created by
8928 the configure_file() command and might contain the following code:
8929
8930 #!/usr/bin/env bash
8931 CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")"
8932 SourceDirs="$(find "/path/to/source" -name "java" -type d)"
8933 cobertura-merge --datafile coberturamerge.ser $CoberturaFiles
8934 cobertura-report --datafile coberturamerge.ser --destination . \
8935 --format xml $SourceDirs
8936
8937 The script uses find to capture the paths to all of the cobertura.ser
8938 files found below the project's source directory. It keeps the list of
8939 files and supplies it as an argument to the cobertura-merge program.
8940 The --datafile argument signifies where the result of the merge will be
8941 kept.
8942
8943 The combined coberturamerge.ser file is then used to generate the XML
8944 report using the cobertura-report program. The call to the cober‐
8945 tura-report program requires some named arguments.
8946
8947 --datafila
8948 path to the merged .ser file
8949
8950 --destination
8951 path to put the output files(s)
8952
8953 --format
8954 file format to write output in: xml or html
8955
8956 The rest of the supplied arguments consist of the full paths to the
8957 /src/main/java directories of each module within the source tree. These
8958 directories are needed and should not be forgotten.
8959
8960 CTEST_COVERAGE_EXTRA_FLAGS
8961 New in version 3.1.
8962
8963
8964 Specify the CTest CoverageExtraFlags setting in a ctest(1) dashboard
8965 client script.
8966
8967 CTEST_CURL_OPTIONS
8968 New in version 3.1.
8969
8970
8971 Specify the CTest CurlOptions setting in a ctest(1) dashboard client
8972 script.
8973
8974 CTEST_CUSTOM_COVERAGE_EXCLUDE
8975 A list of regular expressions which will be used to exclude files by
8976 their path from coverage output by the ctest_coverage() command.
8977
8978 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8979 See ctest_read_custom_files() documentation.
8980
8981 CTEST_CUSTOM_ERROR_EXCEPTION
8982 A list of regular expressions which will be used to exclude when de‐
8983 tecting error messages in build outputs by the ctest_build() command.
8984
8985 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8986 See ctest_read_custom_files() documentation.
8987
8988 CTEST_CUSTOM_ERROR_MATCH
8989 A list of regular expressions which will be used to detect error mes‐
8990 sages in build outputs by the ctest_build() command.
8991
8992 It is initialized by ctest(1), but may be edited in a CTestCustom file.
8993 See ctest_read_custom_files() documentation.
8994
8995 CTEST_CUSTOM_ERROR_POST_CONTEXT
8996 The number of lines to include as context which follow an error message
8997 by the ctest_build() command. The default is 10.
8998
8999 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9000 See ctest_read_custom_files() documentation.
9001
9002 CTEST_CUSTOM_ERROR_PRE_CONTEXT
9003 The number of lines to include as context which precede an error mes‐
9004 sage by the ctest_build() command. The default is 10.
9005
9006 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9007 See ctest_read_custom_files() documentation.
9008
9009 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
9010 When saving a failing test's output, this is the maximum size, in
9011 bytes, that will be collected by the ctest_test() command. Defaults to
9012 307200 (300 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
9013 truncation modes.
9014
9015 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
9016 output will not be truncated and may exceed the maximum size.
9017
9018 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9019 See ctest_read_custom_files() documentation.
9020
9021 For controlling the output collection of passing tests, see
9022 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.
9023
9024 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
9025 The maximum number of errors in a single build step which will be de‐
9026 tected. After this, the ctest_test() command will truncate the output.
9027 Defaults to 50.
9028
9029 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9030 See ctest_read_custom_files() documentation.
9031
9032 CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
9033 The maximum number of warnings in a single build step which will be de‐
9034 tected. After this, the ctest_test() command will truncate the output.
9035 Defaults to 50.
9036
9037 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9038 See ctest_read_custom_files() documentation.
9039
9040 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
9041 When saving a passing test's output, this is the maximum size, in
9042 bytes, that will be collected by the ctest_test() command. Defaults to
9043 1024 (1 KiB). See CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION for possible
9044 truncation modes.
9045
9046 If a test's output contains the literal string "CTEST_FULL_OUTPUT", the
9047 output will not be truncated and may exceed the maximum size.
9048
9049 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9050 See ctest_read_custom_files() documentation.
9051
9052 For controlling the output collection of failing tests, see
9053 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.
9054
9055 CTEST_CUSTOM_MEMCHECK_IGNORE
9056 A list of regular expressions to use to exclude tests during the
9057 ctest_memcheck() command.
9058
9059 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9060 See ctest_read_custom_files() documentation.
9061
9062 CTEST_CUSTOM_POST_MEMCHECK
9063 A list of commands to run at the end of the ctest_memcheck() command.
9064
9065 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9066 See ctest_read_custom_files() documentation.
9067
9068 CTEST_CUSTOM_POST_TEST
9069 A list of commands to run at the end of the ctest_test() command.
9070
9071 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9072 See ctest_read_custom_files() documentation.
9073
9074 CTEST_CUSTOM_PRE_MEMCHECK
9075 A list of commands to run at the start of the ctest_memcheck() command.
9076
9077 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9078 See ctest_read_custom_files() documentation.
9079
9080 CTEST_CUSTOM_PRE_TEST
9081 A list of commands to run at the start of the ctest_test() command.
9082
9083 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9084 See ctest_read_custom_files() documentation.
9085
9086 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
9087 New in version 3.24.
9088
9089
9090 Set the test output truncation mode in case a maximum size is config‐
9091 ured via the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE or
9092 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables. By default the
9093 tail of the output will be truncated. Other possible values are middle
9094 and head.
9095
9096 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9097 See ctest_read_custom_files() documentation.
9098
9099 CTEST_CUSTOM_TESTS_IGNORE
9100 A list of test names to be excluded from the set of tests run by the
9101 ctest_test() command.
9102
9103 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9104 See ctest_read_custom_files() documentation.
9105
9106 CTEST_CUSTOM_WARNING_EXCEPTION
9107 A list of regular expressions which will be used to exclude when de‐
9108 tecting warning messages in build outputs by the ctest_build() command.
9109
9110 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9111 See ctest_read_custom_files() documentation.
9112
9113 CTEST_CUSTOM_WARNING_MATCH
9114 A list of regular expressions which will be used to detect warning mes‐
9115 sages in build outputs by the ctest_build() command.
9116
9117 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9118 See ctest_read_custom_files() documentation.
9119
9120 CTEST_CVS_CHECKOUT
9121 New in version 3.1.
9122
9123
9124 Deprecated. Use CTEST_CHECKOUT_COMMAND instead.
9125
9126 CTEST_CVS_COMMAND
9127 New in version 3.1.
9128
9129
9130 Specify the CTest CVSCommand setting in a ctest(1) dashboard client
9131 script.
9132
9133 CTEST_CVS_UPDATE_OPTIONS
9134 New in version 3.1.
9135
9136
9137 Specify the CTest CVSUpdateOptions setting in a ctest(1) dashboard
9138 client script.
9139
9140 CTEST_DROP_LOCATION
9141 New in version 3.1.
9142
9143
9144 Specify the CTest DropLocation setting in a ctest(1) dashboard client
9145 script.
9146
9147 CTEST_DROP_METHOD
9148 New in version 3.1.
9149
9150
9151 Specify the CTest DropMethod setting in a ctest(1) dashboard client
9152 script.
9153
9154 CTEST_DROP_SITE
9155 New in version 3.1.
9156
9157
9158 Specify the CTest DropSite setting in a ctest(1) dashboard client
9159 script.
9160
9161 CTEST_DROP_SITE_CDASH
9162 New in version 3.1.
9163
9164
9165 Specify the CTest IsCDash setting in a ctest(1) dashboard client
9166 script.
9167
9168 CTEST_DROP_SITE_PASSWORD
9169 New in version 3.1.
9170
9171
9172 Specify the CTest DropSitePassword setting in a ctest(1) dashboard
9173 client script.
9174
9175 CTEST_DROP_SITE_USER
9176 New in version 3.1.
9177
9178
9179 Specify the CTest DropSiteUser setting in a ctest(1) dashboard client
9180 script.
9181
9182 CTEST_EXTRA_COVERAGE_GLOB
9183 New in version 3.4.
9184
9185
9186 A list of regular expressions which will be used to find files which
9187 should be covered by the ctest_coverage() command.
9188
9189 It is initialized by ctest(1), but may be edited in a CTestCustom file.
9190 See ctest_read_custom_files() documentation.
9191
9192 CTEST_GIT_COMMAND
9193 New in version 3.1.
9194
9195
9196 Specify the CTest GITCommand setting in a ctest(1) dashboard client
9197 script.
9198
9199 CTEST_GIT_INIT_SUBMODULES
9200 New in version 3.6.
9201
9202
9203 Specify the CTest GITInitSubmodules setting in a ctest(1) dashboard
9204 client script.
9205
9206 CTEST_GIT_UPDATE_CUSTOM
9207 New in version 3.1.
9208
9209
9210 Specify the CTest GITUpdateCustom setting in a ctest(1) dashboard
9211 client script.
9212
9213 CTEST_GIT_UPDATE_OPTIONS
9214 New in version 3.1.
9215
9216
9217 Specify the CTest GITUpdateOptions setting in a ctest(1) dashboard
9218 client script.
9219
9220 CTEST_HG_COMMAND
9221 New in version 3.1.
9222
9223
9224 Specify the CTest HGCommand setting in a ctest(1) dashboard client
9225 script.
9226
9227 CTEST_HG_UPDATE_OPTIONS
9228 New in version 3.1.
9229
9230
9231 Specify the CTest HGUpdateOptions setting in a ctest(1) dashboard
9232 client script.
9233
9234 CTEST_LABELS_FOR_SUBPROJECTS
9235 New in version 3.10.
9236
9237
9238 Specify the CTest LabelsForSubprojects setting in a ctest(1) dashboard
9239 client script.
9240
9241 CTEST_MEMORYCHECK_COMMAND
9242 New in version 3.1.
9243
9244
9245 Specify the CTest MemoryCheckCommand setting in a ctest(1) dashboard
9246 client script.
9247
9248 CTEST_MEMORYCHECK_COMMAND_OPTIONS
9249 New in version 3.1.
9250
9251
9252 Specify the CTest MemoryCheckCommandOptions setting in a ctest(1) dash‐
9253 board client script.
9254
9255 CTEST_MEMORYCHECK_SANITIZER_OPTIONS
9256 New in version 3.1.
9257
9258
9259 Specify the CTest MemoryCheckSanitizerOptions setting in a ctest(1)
9260 dashboard client script.
9261
9262 CTest prepends correct sanitizer options *_OPTIONS environment variable
9263 to executed command. CTests adds its own log_path to sanitizer options,
9264 don't provide your own log_path.
9265
9266 CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
9267 New in version 3.1.
9268
9269
9270 Specify the CTest MemoryCheckSuppressionFile setting in a ctest(1)
9271 dashboard client script.
9272
9273 CTEST_MEMORYCHECK_TYPE
9274 New in version 3.1.
9275
9276
9277 Specify the CTest MemoryCheckType setting in a ctest(1) dashboard
9278 client script. Valid values are Valgrind, Purify, BoundsChecker,
9279 DrMemory, CudaSanitizer, ThreadSanitizer, AddressSanitizer, LeakSani‐
9280 tizer, MemorySanitizer and UndefinedBehaviorSanitizer.
9281
9282 CTEST_NIGHTLY_START_TIME
9283 New in version 3.1.
9284
9285
9286 Specify the CTest NightlyStartTime setting in a ctest(1) dashboard
9287 client script.
9288
9289 Note that this variable must always be set for a nightly build in a
9290 dashboard script. It is needed so that nightly builds can be properly
9291 grouped together in CDash.
9292
9293 CTEST_P4_CLIENT
9294 New in version 3.1.
9295
9296
9297 Specify the CTest P4Client setting in a ctest(1) dashboard client
9298 script.
9299
9300 CTEST_P4_COMMAND
9301 New in version 3.1.
9302
9303
9304 Specify the CTest P4Command setting in a ctest(1) dashboard client
9305 script.
9306
9307 CTEST_P4_OPTIONS
9308 New in version 3.1.
9309
9310
9311 Specify the CTest P4Options setting in a ctest(1) dashboard client
9312 script.
9313
9314 CTEST_P4_UPDATE_OPTIONS
9315 New in version 3.1.
9316
9317
9318 Specify the CTest P4UpdateOptions setting in a ctest(1) dashboard
9319 client script.
9320
9321 CTEST_RESOURCE_SPEC_FILE
9322 New in version 3.18.
9323
9324
9325 Specify the CTest ResourceSpecFile setting in a ctest(1) dashboard
9326 client script.
9327
9328 This can also be used to specify the resource spec file from a CMake
9329 build. If no RESOURCE_SPEC_FILE is passed to ctest_test(), and
9330 CTEST_RESOURCE_SPEC_FILE is not specified in the dashboard script, the
9331 value of this variable from the build is used.
9332
9333 CTEST_RUN_CURRENT_SCRIPT
9334 New in version 3.11.
9335
9336
9337 Setting this to 0 prevents ctest(1) from being run again when it
9338 reaches the end of a script run by calling ctest -S.
9339
9340 CTEST_SCP_COMMAND
9341 New in version 3.1.
9342
9343
9344 Legacy option. Not used.
9345
9346 CTEST_SCRIPT_DIRECTORY
9347 The directory containing the top-level CTest script. The concept is
9348 similar to CMAKE_SOURCE_DIR.
9349
9350 CTEST_SITE
9351 New in version 3.1.
9352
9353
9354 Specify the CTest Site setting in a ctest(1) dashboard client script.
9355
9356 CTEST_SOURCE_DIRECTORY
9357 New in version 3.1.
9358
9359
9360 Specify the CTest SourceDirectory setting in a ctest(1) dashboard
9361 client script.
9362
9363 CTEST_SUBMIT_INACTIVITY_TIMEOUT
9364 New in version 3.23.
9365
9366
9367 Specify the CTest SubmitInactivityTimeout setting in a ctest(1) dash‐
9368 board client script.
9369
9370 CTEST_SUBMIT_URL
9371 New in version 3.14.
9372
9373
9374 Specify the CTest SubmitURL setting in a ctest(1) dashboard client
9375 script.
9376
9377 CTEST_SVN_COMMAND
9378 New in version 3.1.
9379
9380
9381 Specify the CTest SVNCommand setting in a ctest(1) dashboard client
9382 script.
9383
9384 CTEST_SVN_OPTIONS
9385 New in version 3.1.
9386
9387
9388 Specify the CTest SVNOptions setting in a ctest(1) dashboard client
9389 script.
9390
9391 CTEST_SVN_UPDATE_OPTIONS
9392 New in version 3.1.
9393
9394
9395 Specify the CTest SVNUpdateOptions setting in a ctest(1) dashboard
9396 client script.
9397
9398 CTEST_TEST_LOAD
9399 New in version 3.4.
9400
9401
9402 Specify the TestLoad setting in the CTest Test Step of a ctest(1) dash‐
9403 board client script. This sets the default value for the TEST_LOAD op‐
9404 tion of the ctest_test() command.
9405
9406 CTEST_TEST_TIMEOUT
9407 New in version 3.1.
9408
9409
9410 Specify the CTest TimeOut setting in a ctest(1) dashboard client
9411 script.
9412
9413 CTEST_TRIGGER_SITE
9414 New in version 3.1.
9415
9416
9417 Legacy option. Not used.
9418
9419 CTEST_UPDATE_COMMAND
9420 New in version 3.1.
9421
9422
9423 Specify the CTest UpdateCommand setting in a ctest(1) dashboard client
9424 script.
9425
9426 CTEST_UPDATE_OPTIONS
9427 New in version 3.1.
9428
9429
9430 Specify the CTest UpdateOptions setting in a ctest(1) dashboard client
9431 script.
9432
9433 CTEST_UPDATE_VERSION_ONLY
9434 New in version 3.1.
9435
9436
9437 Specify the CTest UpdateVersionOnly setting in a ctest(1) dashboard
9438 client script.
9439
9440 CTEST_UPDATE_VERSION_OVERRIDE
9441 New in version 3.15.
9442
9443
9444 Specify the CTest UpdateVersionOverride setting in a ctest(1) dashboard
9445 client script.
9446
9447 CTEST_USE_LAUNCHERS
9448 New in version 3.1.
9449
9450
9451 Specify the CTest UseLaunchers setting in a ctest(1) dashboard client
9452 script.
9453
9455 CPACK_ABSOLUTE_DESTINATION_FILES
9456 List of files which have been installed using an ABSOLUTE DESTINATION
9457 path.
9458
9459 This variable is a Read-Only variable which is set internally by CPack
9460 during installation and before packaging using
9461 CMAKE_ABSOLUTE_DESTINATION_FILES defined in cmake_install.cmake
9462 scripts. The value can be used within CPack project configuration file
9463 and/or CPack<GEN>.cmake file of <GEN> generator.
9464
9465 CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9466 Boolean toggle to include/exclude top level directory (component case).
9467
9468 Similar usage as CPACK_INCLUDE_TOPLEVEL_DIRECTORY but for the component
9469 case. See CPACK_INCLUDE_TOPLEVEL_DIRECTORY documentation for the de‐
9470 tail.
9471
9472 CPACK_CUSTOM_INSTALL_VARIABLES
9473 New in version 3.21.
9474
9475
9476 CPack variables (set via e.g. cpack -D, CPackConfig.cmake or
9477 CPACK_PROJECT_CONFIG_FILE scripts) are not directly visible in instal‐
9478 lation scripts. Instead, one can pass a list of varName=value pairs in
9479 the CPACK_CUSTOM_INSTALL_VARIABLES variable. At install time, each
9480 list item will result in a variable of the specified name (varName) be‐
9481 ing set to the given value. The = can be omitted for an empty value.
9482
9483 CPACK_CUSTOM_INSTALL_VARIABLES allows the packaging installation to be
9484 influenced by the user or driving script at CPack runtime without hav‐
9485 ing to regenerate the install scripts.
9486
9487 Example
9488 install(FILES large.txt DESTINATION data)
9489
9490 install(CODE [[
9491 if(ENABLE_COMPRESSION)
9492 # "run-compressor" is a fictional tool that produces
9493 # large.txt.xz from large.txt and then removes the input file
9494 execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt)
9495 endif()
9496 ]])
9497
9498 With the above example snippet, cpack will by default run the installa‐
9499 tion script with ENABLE_COMPRESSION unset, resulting in a package con‐
9500 taining the uncompressed large.txt. This can be overridden when invok‐
9501 ing cpack like so:
9502
9503 cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE"
9504
9505 The installation script will then run with ENABLE_COMPRESSION set to
9506 TRUE, resulting in a package containing the compressed large.txt.xz in‐
9507 stead.
9508
9509 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
9510 Ask CPack to error out as soon as a file with absolute INSTALL DESTINA‐
9511 TION is encountered.
9512
9513 The fatal error is emitted before the installation of the offending
9514 file takes place. Some CPack generators, like NSIS, enforce this in‐
9515 ternally. This variable triggers the definition of
9516 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs.
9517
9518 CPACK_INCLUDE_TOPLEVEL_DIRECTORY
9519 Boolean toggle to include/exclude top level directory.
9520
9521 When preparing a package CPack installs the item under the so-called
9522 top level directory. The purpose of is to include (set to 1 or ON or
9523 TRUE) the top level directory in the package or not (set to 0 or OFF or
9524 FALSE).
9525
9526 Each CPack generator has a built-in default value for this variable.
9527 E.g. Archive generators (ZIP, TGZ, ...) includes the top level whereas
9528 RPM or DEB don't. The user may override the default value by setting
9529 this variable.
9530
9531 There is a similar variable CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
9532 which may be used to override the behavior for the component packaging
9533 case which may have different default value for historical (now back‐
9534 ward compatibility) reason.
9535
9536 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
9537 New in version 3.11.
9538
9539
9540 Default permissions for implicitly created directories during packag‐
9541 ing.
9542
9543 This variable serves the same purpose during packaging as the
9544 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS variable serves during in‐
9545 stallation (e.g. make install).
9546
9547 If include(CPack) is used then by default this variable is set to the
9548 content of CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.
9549
9550 CPACK_PACKAGING_INSTALL_PREFIX
9551 The prefix used in the built package.
9552
9553 Each CPack generator has a default value (like /usr). This default
9554 value may be overwritten from the CMakeLists.txt or the cpack(1) com‐
9555 mand line by setting an alternative value. Example:
9556
9557 set(CPACK_PACKAGING_INSTALL_PREFIX "/opt")
9558
9559 This is not the same purpose as CMAKE_INSTALL_PREFIX which is used when
9560 installing from the build tree without building a package.
9561
9562 CPACK_SET_DESTDIR
9563 Boolean toggle to make CPack use DESTDIR mechanism when packaging.
9564
9565 DESTDIR means DESTination DIRectory. It is commonly used by makefile
9566 users in order to install software at non-default location. It is a
9567 basic relocation mechanism that should not be used on Windows (see
9568 CMAKE_INSTALL_PREFIX documentation). It is usually invoked like this:
9569
9570 make DESTDIR=/home/john install
9571
9572 which will install the concerned software using the installation pre‐
9573 fix, e.g. /usr/local prepended with the DESTDIR value which finally
9574 gives /home/john/usr/local. When preparing a package, CPack first in‐
9575 stalls the items to be packaged in a local (to the build tree) direc‐
9576 tory by using the same DESTDIR mechanism. Nevertheless, if
9577 CPACK_SET_DESTDIR is set then CPack will set DESTDIR before doing the
9578 local install. The most noticeable difference is that without
9579 CPACK_SET_DESTDIR, CPack uses CPACK_PACKAGING_INSTALL_PREFIX as a pre‐
9580 fix whereas with CPACK_SET_DESTDIR set, CPack will use
9581 CMAKE_INSTALL_PREFIX as a prefix.
9582
9583 Manually setting CPACK_SET_DESTDIR may help (or simply be necessary) if
9584 some install rules uses absolute DESTINATION (see CMake install() com‐
9585 mand). However, starting with CPack/CMake 2.8.3 RPM and DEB installers
9586 tries to handle DESTDIR automatically so that it is seldom necessary
9587 for the user to set it.
9588
9589 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
9590 Ask CPack to warn each time a file with absolute INSTALL DESTINATION is
9591 encountered.
9592
9593 This variable triggers the definition of
9594 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runs cmake_in‐
9595 stall.cmake scripts.
9596
9598 CACHE
9599 New in version 3.13.
9600
9601
9602 Operator to read cache variables.
9603
9604 Use the syntax $CACHE{VAR} to read cache entry VAR. See the
9605 cmake-language(7) variables documentation for more complete documenta‐
9606 tion of the interaction of normal variables and cache entries.
9607
9608 When evaluating Variable References of the form ${VAR}, CMake first
9609 searches for a normal variable with that name, and if not found CMake
9610 will search for a cache entry with that name. The $CACHE{VAR} syntax
9611 can be used to do direct cache lookup and ignore any existing normal
9612 variable.
9613
9614 See the set() and unset() commands to see how to write or remove cache
9615 variables.
9616
9617 ENV
9618 Operator to read environment variables.
9619
9620 Use the syntax $ENV{VAR} to read environment variable VAR.
9621
9622 To test whether an environment variable is defined, use the signature
9623 if(DEFINED ENV{<name>}) of the if() command.
9624
9625 For general information on environment variables, see the Environment
9626 Variables section in the cmake-language(7) manual.
9627
9629 CMake has many internal variables. Most of them are undocumented.
9630 Some of them, however, were at some point described as normal vari‐
9631 ables, and therefore may be encountered in legacy code. They are sub‐
9632 ject to change, and not recommended for use in project code.
9633
9634 CMAKE_HOME_DIRECTORY
9635 Path to top of source tree. Same as CMAKE_SOURCE_DIR.
9636
9637 This is an internal cache entry used to locate the source directory
9638 when loading a CMakeCache.txt from a build tree. It should not be used
9639 in project code. The variable CMAKE_SOURCE_DIR has the same value and
9640 should be preferred.
9641
9642 CMAKE_INTERNAL_PLATFORM_ABI
9643 An internal variable subject to change.
9644
9645 This is used in determining the compiler ABI and is subject to change.
9646
9647 CMAKE_<LANG>_COMPILER_ABI
9648 An internal variable subject to change.
9649
9650 This is used in determining the compiler ABI and is subject to change.
9651
9652 CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID
9653 New in version 3.10.
9654
9655
9656 An internal variable subject to change.
9657
9658 This is used to identify the variant of a compiler based on its target
9659 architecture. For some compilers this is needed to determine the cor‐
9660 rect usage.
9661
9662 CMAKE_<LANG>_COMPILER_VERSION_INTERNAL
9663 New in version 3.10.
9664
9665
9666 An internal variable subject to change.
9667
9668 This is used to identify the variant of a compiler based on an internal
9669 version number. For some compilers this is needed to determine the
9670 correct usage.
9671
9672 CMAKE_<LANG>_LINKER_PREFERENCE
9673 An internal variable subject to change.
9674
9675 Preference value for linker language selection.
9676
9677 The "linker language" for executable, shared library, and module tar‐
9678 gets is the language whose compiler will invoke the linker. The
9679 LINKER_LANGUAGE target property sets the language explicitly. Other‐
9680 wise, the linker language is that whose linker preference value is
9681 highest among languages compiled and linked into the target. See also
9682 the CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES variable.
9683
9684 CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
9685 An internal variable subject to change.
9686
9687 True if CMAKE_<LANG>_LINKER_PREFERENCE propagates across targets.
9688
9689 This is used when CMake selects a linker language for a target. Lan‐
9690 guages compiled directly into the target are always considered. A lan‐
9691 guage compiled into static libraries linked by the target is considered
9692 if this variable is true.
9693
9694 CMAKE_<LANG>_PLATFORM_ID
9695 An internal variable subject to change.
9696
9697 This is used in determining the platform and is subject to change.
9698
9699 CMAKE_NOT_USING_CONFIG_FLAGS
9700 Skip _BUILD_TYPE flags if true.
9701
9702 This is an internal flag used by the generators in CMake to tell CMake
9703 to skip the _BUILD_TYPE flags.
9704
9705 CMAKE_VS_INTEL_Fortran_PROJECT_VERSION
9706 When generating for Visual Studio 9 2008 or greater with the Intel For‐
9707 tran plugin installed, this specifies the .vfproj project file format
9708 version. This is intended for internal use by CMake and should not be
9709 used by project code.
9710
9712 2000-2023 Kitware, Inc. and Contributors
9713
9714
9715
9716
97173.27.7 Oct 07, 2023 CMAKE-VARIABLES(7)