1CMAKE-PROPERTIES(7) CMake CMAKE-PROPERTIES(7)
2
6 cmake-properties - CMake Properties Reference
7
9 ALLOW_DUPLICATE_CUSTOM_TARGETS
10 Allow duplicate custom targets to be created.
11 Normally CMake requires that all targets built in a project have glob‐
13 ally unique logical names (see policy CMP0002). This is necessary to
14 generate meaningful project file names in Xcode and Visual Studio Gen‐
15 erators IDE generators. It also allows the target names to be refer‐
16 enced unambiguously.
17 Makefile generators are capable of supporting duplicate
19 add_custom_target() names. For projects that care only about Makefile
20 Generators and do not wish to support Xcode or Visual Studio Generators
21 IDE generators, one may set this property to True to allow duplicate
22 custom targets. The property allows multiple add_custom_target() com‐
23 mand calls in different directories to specify the same target name.
24 However, setting this property will cause non-Makefile generators to
25 produce an error and refuse to generate the project.
26 AUTOGEN_SOURCE_GROUP
28 New in version 3.9.
29 Name of the source_group() for AUTOMOC, AUTORCC and AUTOUIC generated
32 files.
33 Files generated by AUTOMOC, AUTORCC and AUTOUIC are not always known at
35 configure time and therefore can't be passed to source_group().
36 AUTOGEN_SOURCE_GROUP can be used instead to generate or select a source
37 group for AUTOMOC, AUTORCC and AUTOUIC generated files.
38 For AUTOMOC, AUTORCC and AUTOUIC specific overrides see
40 AUTOMOC_SOURCE_GROUP, AUTORCC_SOURCE_GROUP and AUTOUIC_SOURCE_GROUP re‐
41 spectively.
42 AUTOGEN_TARGETS_FOLDER
44 Name of FOLDER for *_autogen targets that are added automatically by
45 CMake for targets for which AUTOMOC is enabled.
46 If not set, CMake uses the FOLDER property of the parent target as a
48 default value for this property. See also the documentation for the
49 FOLDER target property and the AUTOMOC target property.
50 AUTOMOC_SOURCE_GROUP
52 New in version 3.9.
53 Name of the source_group() for AUTOMOC generated files.
56 When set this is used instead of AUTOGEN_SOURCE_GROUP for files gener‐
58 ated by AUTOMOC.
59 AUTOMOC_TARGETS_FOLDER
61 Name of FOLDER for *_autogen targets that are added automatically by
62 CMake for targets for which AUTOMOC is enabled.
63 This property is obsolete. Use AUTOGEN_TARGETS_FOLDER instead.
65 If not set, CMake uses the FOLDER property of the parent target as a
67 default value for this property. See also the documentation for the
68 FOLDER target property and the AUTOMOC target property.
69 AUTORCC_SOURCE_GROUP
71 New in version 3.9.
72 Name of the source_group() for AUTORCC generated files.
75 When set this is used instead of AUTOGEN_SOURCE_GROUP for files gener‐
77 ated by AUTORCC.
78 AUTOUIC_SOURCE_GROUP
80 New in version 3.21.
81 Name of the source_group() for AUTOUIC generated files.
84 When set this is used instead of AUTOGEN_SOURCE_GROUP for files gener‐
86 ated by AUTOUIC.
87 CMAKE_C_KNOWN_FEATURES
89 New in version 3.1.
90 List of C features known to this version of CMake.
93 The features listed in this global property may be known to be avail‐
95 able to the C compiler. If the feature is available with the C com‐
96 piler, it will be listed in the CMAKE_C_COMPILE_FEATURES variable.
97 The features listed here may be used with the target_compile_features()
99 command. See the cmake-compile-features(7) manual for information on
100 compile features and a list of supported compilers.
101 The features known to this version of CMake are listed below.
103 High level meta features indicating C standard support
105 New in version 3.8.
106 c_std_90
109 Compiler mode is at least C 90.
110 c_std_99
112 Compiler mode is at least C 99.
113 c_std_11
115 Compiler mode is at least C 11.
116 c_std_17
118 New in version 3.21.
119 Compiler mode is at least C 17.
122 c_std_23
124 New in version 3.21.
125 Compiler mode is at least C 23.
128 NOTE:
130 If the compiler's default standard level is at least that of the re‐
131 quested feature, CMake may omit the -std= flag. The flag may still
132 be added if the compiler's default extensions mode does not match
133 the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD
134 target property is set.
135 Low level individual compile features
137 c_function_prototypes
138 Function prototypes, as defined in ISO/IEC 9899:1990.
139 c_restrict
141 restrict keyword, as defined in ISO/IEC 9899:1999.
142 c_static_assert
144 Static assert, as defined in ISO/IEC 9899:2011.
145 c_variadic_macros
147 Variadic macros, as defined in ISO/IEC 9899:1999.
148 CMAKE_CUDA_KNOWN_FEATURES
150 New in version 3.17.
151 List of CUDA features known to this version of CMake.
154 The features listed in this global property may be known to be avail‐
156 able to the CUDA compiler. If the feature is available with the C++
157 compiler, it will be listed in the CMAKE_CUDA_COMPILE_FEATURES vari‐
158 able.
159 The features listed here may be used with the target_compile_features()
161 command. See the cmake-compile-features(7) manual for information on
162 compile features and a list of supported compilers.
163 The features known to this version of CMake are:
165 cuda_std_03
167 Compiler mode is at least CUDA/C++ 03.
168 cuda_std_11
170 Compiler mode is at least CUDA/C++ 11.
171 cuda_std_14
173 Compiler mode is at least CUDA/C++ 14.
174 cuda_std_17
176 Compiler mode is at least CUDA/C++ 17.
177 cuda_std_20
179 Compiler mode is at least CUDA/C++ 20.
180 cuda_std_23
182 New in version 3.20.
183 Compiler mode is at least CUDA/C++ 23.
186 cuda_std_26
188 New in version 3.25.
189 Compiler mode is at least CUDA/C++ 26.
192 NOTE:
194 If the compiler's default standard level is at least that of the re‐
195 quested feature, CMake may omit the -std= flag. The flag may still
196 be added if the compiler's default extensions mode does not match
197 the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD
198 target property is set.
199 CMAKE_CXX_KNOWN_FEATURES
201 New in version 3.1.
202 List of C++ features known to this version of CMake.
205 The features listed in this global property may be known to be avail‐
207 able to the C++ compiler. If the feature is available with the C++
208 compiler, it will be listed in the CMAKE_CXX_COMPILE_FEATURES variable.
209 The features listed here may be used with the target_compile_features()
211 command. See the cmake-compile-features(7) manual for information on
212 compile features and a list of supported compilers.
213 The features known to this version of CMake are listed below.
215 High level meta features indicating C++ standard support
217 New in version 3.8.
218 The following meta features indicate general support for the associated
221 language standard. It reflects the language support claimed by the
222 compiler, but it does not necessarily imply complete conformance to
223 that standard.
224 cxx_std_98
226 Compiler mode is at least C++ 98.
227 cxx_std_11
229 Compiler mode is at least C++ 11.
230 cxx_std_14
232 Compiler mode is at least C++ 14.
233 cxx_std_17
235 Compiler mode is at least C++ 17.
236 cxx_std_20
238 New in version 3.12.
239 Compiler mode is at least C++ 20.
242 cxx_std_23
244 New in version 3.20.
245 Compiler mode is at least C++ 23.
248 cxx_std_26
250 New in version 3.25.
251 Compiler mode is at least C++ 26.
254 NOTE:
256 If the compiler's default standard level is at least that of the re‐
257 quested feature, CMake may omit the -std= flag. The flag may still
258 be added if the compiler's default extensions mode does not match
259 the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD
260 target property is set.
261 Low level individual compile features
263 For C++ 11 and C++ 14, compilers were sometimes slow to implement cer‐
264 tain language features. CMake provided some individual compile fea‐
265 tures to help projects determine whether specific features were avail‐
266 able. These individual features are now less relevant and projects
267 should generally prefer to use the high level meta features instead.
268 Individual compile features are not provided for C++ 17 or later.
269 See the cmake-compile-features(7) manual for further discussion of the
271 use of individual compile features.
272 Individual features from C++ 98
274 cxx_template_template_parameters
275 Template template parameters, as defined in ISO/IEC 14882:1998.
276 Individual features from C++ 11
278 cxx_alias_templates
279 Template aliases, as defined in N2258.
280 cxx_alignas
282 Alignment control alignas, as defined in N2341.
283 cxx_alignof
285 Alignment control alignof, as defined in N2341.
286 cxx_attributes
288 Generic attributes, as defined in N2761.
289 cxx_auto_type
291 Automatic type deduction, as defined in N1984.
292 cxx_constexpr
294 Constant expressions, as defined in N2235.
295 cxx_decltype_incomplete_return_types
297 Decltype on incomplete return types, as defined in N3276.
298 cxx_decltype
300 Decltype, as defined in N2343.
301 cxx_default_function_template_args
303 Default template arguments for function templates, as defined in
304 DR226
305 cxx_defaulted_functions
307 Defaulted functions, as defined in N2346.
308 cxx_defaulted_move_initializers
310 Defaulted move initializers, as defined in N3053.
311 cxx_delegating_constructors
313 Delegating constructors, as defined in N1986.
314 cxx_deleted_functions
316 Deleted functions, as defined in N2346.
317 cxx_enum_forward_declarations
319 Enum forward declarations, as defined in N2764.
320 cxx_explicit_conversions
322 Explicit conversion operators, as defined in N2437.
323 cxx_extended_friend_declarations
325 Extended friend declarations, as defined in N1791.
326 cxx_extern_templates
328 Extern templates, as defined in N1987.
329 cxx_final
331 Override control final keyword, as defined in N2928, N3206 and
332 N3272.
333 cxx_func_identifier
335 Predefined __func__ identifier, as defined in N2340.
336 cxx_generalized_initializers
338 Initializer lists, as defined in N2672.
339 cxx_inheriting_constructors
341 Inheriting constructors, as defined in N2540.
342 cxx_inline_namespaces
344 Inline namespaces, as defined in N2535.
345 cxx_lambdas
347 Lambda functions, as defined in N2927.
348 cxx_local_type_template_args
350 Local and unnamed types as template arguments, as defined in
351 N2657.
352 cxx_long_long_type
354 long long type, as defined in N1811.
355 cxx_noexcept
357 Exception specifications, as defined in N3050.
358 cxx_nonstatic_member_init
360 Non-static data member initialization, as defined in N2756.
361 cxx_nullptr
363 Null pointer, as defined in N2431.
364 cxx_override
366 Override control override keyword, as defined in N2928, N3206
367 and N3272.
368 cxx_range_for
370 Range-based for, as defined in N2930.
371 cxx_raw_string_literals
373 Raw string literals, as defined in N2442.
374 cxx_reference_qualified_functions
376 Reference qualified functions, as defined in N2439.
377 cxx_right_angle_brackets
379 Right angle bracket parsing, as defined in N1757.
380 cxx_rvalue_references
382 R-value references, as defined in N2118.
383 cxx_sizeof_member
385 Size of non-static data members, as defined in N2253.
386 cxx_static_assert
388 Static assert, as defined in N1720.
389 cxx_strong_enums
391 Strongly typed enums, as defined in N2347.
392 cxx_thread_local
394 Thread-local variables, as defined in N2659.
395 cxx_trailing_return_types
397 Automatic function return type, as defined in N2541.
398 cxx_unicode_literals
400 Unicode string literals, as defined in N2442.
401 cxx_uniform_initialization
403 Uniform initialization, as defined in N2640.
404 cxx_unrestricted_unions
406 Unrestricted unions, as defined in N2544.
407 cxx_user_literals
409 User-defined literals, as defined in N2765.
410 cxx_variadic_macros
412 Variadic macros, as defined in N1653.
413 cxx_variadic_templates
415 Variadic templates, as defined in N2242.
416 Individual features from C++ 14
418 cxx_aggregate_default_initializers
419 Aggregate default initializers, as defined in N3605.
420 cxx_attribute_deprecated
422 [[deprecated]] attribute, as defined in N3760.
423 cxx_binary_literals
425 Binary literals, as defined in N3472.
426 cxx_contextual_conversions
428 Contextual conversions, as defined in N3323.
429 cxx_decltype_auto
431 decltype(auto) semantics, as defined in N3638.
432 cxx_digit_separators
434 Digit separators, as defined in N3781.
435 cxx_generic_lambdas
437 Generic lambdas, as defined in N3649.
438 cxx_lambda_init_captures
440 Initialized lambda captures, as defined in N3648.
441 cxx_relaxed_constexpr
443 Relaxed constexpr, as defined in N3652.
444 cxx_return_type_deduction
446 Return type deduction on normal functions, as defined in N3386.
447 cxx_variable_templates
449 Variable templates, as defined in N3651.
450 CMAKE_ROLE
452 New in version 3.14.
453 Tells what mode the current running script is in. Could be one of sev‐
456 eral values:
457 PROJECT
459 Running in project mode (processing a CMakeLists.txt file).
460 SCRIPT Running in -P script mode.
462 FIND_PACKAGE
464 Running in --find-package mode.
465 CTEST Running in CTest script mode.
467 CPACK Running in CPack.
469 DEBUG_CONFIGURATIONS
471 Specify which configurations are for debugging.
472 The value must be a semi-colon separated list of configuration names.
474 Currently this property is used only by the target_link_libraries()
475 command. Additional uses may be defined in the future.
476 This property must be set at the top level of the project and before
478 the first target_link_libraries() command invocation. If any entry in
479 the list does not match a valid configuration for the project the be‐
480 havior is undefined.
481 DISABLED_FEATURES
483 List of features which are disabled during the CMake run.
484 List of features which are disabled during the CMake run. By default
486 it contains the names of all packages which were not found. This is
487 determined using the <NAME>_FOUND variables. Packages which are
488 searched QUIET are not listed. A project can add its own features to
489 this list. This property is used by the macros in FeatureSum‐
490 mary.cmake.
491 ECLIPSE_EXTRA_CPROJECT_CONTENTS
493 New in version 3.12.
494 Additional contents to be inserted into the generated Eclipse cproject
497 file.
498 The cproject file defines the CDT specific information. Some third
500 party IDE's are based on Eclipse with the addition of other information
501 specific to that IDE. Through this property, it is possible to add
502 this additional contents to the generated project. It is expected to
503 contain valid XML.
504 Also see the ECLIPSE_EXTRA_NATURES property.
506 ECLIPSE_EXTRA_NATURES
508 List of natures to add to the generated Eclipse project file.
509 Eclipse projects specify language plugins by using natures. This prop‐
511 erty should be set to the unique identifier for a nature (which looks
512 like a Java package name).
513 Also see the ECLIPSE_EXTRA_CPROJECT_CONTENTS property.
515 ENABLED_FEATURES
517 List of features which are enabled during the CMake run.
518 List of features which are enabled during the CMake run. By default it
520 contains the names of all packages which were found. This is deter‐
521 mined using the <NAME>_FOUND variables. Packages which are searched
522 QUIET are not listed. A project can add its own features to this list.
523 This property is used by the macros in FeatureSummary.cmake.
524 ENABLED_LANGUAGES
526 Read-only property that contains the list of currently enabled lan‐
527 guages
528 Set to list of currently enabled languages.
530 FIND_LIBRARY_USE_LIB32_PATHS
532 New in version 3.7.
533 Whether the find_library() command should automatically search lib32
536 directories.
537 FIND_LIBRARY_USE_LIB32_PATHS is a boolean specifying whether the
539 find_library() command should automatically search the lib32 variant of
540 directories called lib in the search path when building 32-bit bina‐
541 ries.
542 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
544 FIND_LIBRARY_USE_LIB64_PATHS
546 Whether find_library() should automatically search lib64 directories.
547 FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
549 find_library() command should automatically search the lib64 variant of
550 directories called lib in the search path when building 64-bit bina‐
551 ries.
552 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
554 FIND_LIBRARY_USE_LIBX32_PATHS
556 New in version 3.9.
557 Whether the find_library() command should automatically search libx32
560 directories.
561 FIND_LIBRARY_USE_LIBX32_PATHS is a boolean specifying whether the
563 find_library() command should automatically search the libx32 variant
564 of directories called lib in the search path when building x32-abi bi‐
565 naries.
566 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
568 FIND_LIBRARY_USE_OPENBSD_VERSIONING
570 Whether find_library() should find OpenBSD-style shared libraries.
571 This property is a boolean specifying whether the find_library() com‐
573 mand should find shared libraries with OpenBSD-style versioned exten‐
574 sion: ".so.<major>.<minor>". The property is set to true on OpenBSD
575 and false on other platforms.
576 GENERATOR_IS_MULTI_CONFIG
578 New in version 3.9.
579 Read-only property that is true on multi-configuration generators.
582 True when using a multi-configuration generator such as:
584 • Ninja Multi-Config
586 • Visual Studio Generators
588 • Xcode
590 Multi-config generators use CMAKE_CONFIGURATION_TYPES as the set of
592 configurations and ignore CMAKE_BUILD_TYPE.
593 GLOBAL_DEPENDS_DEBUG_MODE
595 Enable global target dependency graph debug mode.
596 CMake automatically analyzes the global inter-target dependency graph
598 at the beginning of native build system generation. This property
599 causes it to display details of its analysis to stderr.
600 GLOBAL_DEPENDS_NO_CYCLES
602 Disallow global target dependency graph cycles.
603 CMake automatically analyzes the global inter-target dependency graph
605 at the beginning of native build system generation. It reports an er‐
606 ror if the dependency graph contains a cycle that does not consist of
607 all STATIC library targets. This property tells CMake to disallow all
608 cycles completely, even among static libraries.
609 IN_TRY_COMPILE
611 Read-only property that is true during a try-compile configuration.
612 True when building a project inside a try_compile() or try_run() com‐
614 mand.
615 JOB_POOLS
617 Ninja only: List of available pools.
618 A pool is a named integer property and defines the maximum number of
620 concurrent jobs which can be started by a rule assigned to the pool.
621 The JOB_POOLS property is a semicolon-separated list of pairs using the
622 syntax NAME=integer (without a space after the equality sign).
623 For instance:
625 set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10)
627 Defined pools could be used globally by setting CMAKE_JOB_POOL_COMPILE
629 and CMAKE_JOB_POOL_LINK or per target by setting the target properties
630 JOB_POOL_COMPILE and JOB_POOL_LINK. Custom commands and custom targets
631 can specify pools using the option JOB_POOL. Using a pool that is not
632 defined by JOB_POOLS causes an error by ninja at build time.
633 If not set, this property uses the value of the CMAKE_JOB_POOLS vari‐
635 able.
636 Build targets provided by CMake that are meant for individual interac‐
638 tive use, such as install, are placed in the console pool automati‐
639 cally.
640 PACKAGES_FOUND
642 List of packages which were found during the CMake run.
643 List of packages which were found during the CMake run. Whether a
645 package has been found is determined using the <NAME>_FOUND variables.
646 PACKAGES_NOT_FOUND
648 List of packages which were not found during the CMake run.
649 List of packages which were not found during the CMake run. Whether a
651 package has been found is determined using the <NAME>_FOUND variables.
652 PREDEFINED_TARGETS_FOLDER
654 Name of FOLDER for targets that are added automatically by CMake.
655 If not set, CMake uses "CMakePredefinedTargets" as a default value for
657 this property. Targets such as INSTALL, PACKAGE and RUN_TESTS will be
658 organized into this FOLDER. See also the documentation for the FOLDER
659 target property.
660 REPORT_UNDEFINED_PROPERTIES
662 If set, report any undefined properties to this file.
663 If this property is set to a filename then when CMake runs it will re‐
665 port any properties or variables that were accessed but not defined
666 into the filename specified in this property.
667 RULE_LAUNCH_COMPILE
669 Specify a launcher for compile rules.
670 NOTE:
672 This property is intended for internal use by ctest(1). Projects
673 and developers should use the <LANG>_COMPILER_LAUNCHER target prop‐
674 erties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables
675 instead.
676 Makefile Generators and the Ninja generator prefix compiler commands
678 with the given launcher command line. This is intended to allow
679 launchers to intercept build problems with high granularity. Other
680 generators ignore this property because their underlying build systems
681 provide no hook to wrap individual commands with a launcher.
682 RULE_LAUNCH_CUSTOM
684 Specify a launcher for custom rules.
685 Makefile Generators and the Ninja generator prefix custom commands with
687 the given launcher command line. This is intended to allow launchers
688 to intercept build problems with high granularity. Other generators
689 ignore this property because their underlying build systems provide no
690 hook to wrap individual commands with a launcher.
691 RULE_LAUNCH_LINK
693 Specify a launcher for link rules.
694 NOTE:
696 This property is intended for internal use by ctest(1). Projects
697 and developers should use the <LANG>_LINKER_LAUNCHER target proper‐
698 ties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables in‐
699 stead.
700 Makefile Generators and the Ninja generator prefix link and archive
702 commands with the given launcher command line. This is intended to al‐
703 low launchers to intercept build problems with high granularity. Other
704 generators ignore this property because their underlying build systems
705 provide no hook to wrap individual commands with a launcher.
706 RULE_MESSAGES
708 Specify whether to report a message for each make rule.
709 This property specifies whether Makefile generators should add a
711 progress message describing what each build rule does. If the property
712 is not set the default is ON. Set the property to OFF to disable gran‐
713 ular messages and report only as each target completes. This is in‐
714 tended to allow scripted builds to avoid the build time cost of de‐
715 tailed reports. If a CMAKE_RULE_MESSAGES cache entry exists its value
716 initializes the value of this property. Non-Makefile generators cur‐
717 rently ignore this property.
718 TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
720 Set if shared libraries may be named like archives.
721 On AIX shared libraries may be named "lib<name>.a". This property is
723 set to true on such platforms.
724 TARGET_MESSAGES
726 New in version 3.4.
727 Specify whether to report the completion of each target.
730 This property specifies whether Makefile Generators should add a
732 progress message describing that each target has been completed. If
733 the property is not set the default is ON. Set the property to OFF to
734 disable target completion messages.
735 This option is intended to reduce build output when little or no work
737 needs to be done to bring the build tree up to date.
738 If a CMAKE_TARGET_MESSAGES cache entry exists its value initializes the
740 value of this property.
741 Non-Makefile generators currently ignore this property.
743 See the counterpart property RULE_MESSAGES to disable everything except
745 for target completion messages.
746 TARGET_SUPPORTS_SHARED_LIBS
748 Does the target platform support shared libraries.
749 TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target
751 platform supports shared libraries. Basically all current general gen‐
752 eral purpose OS do so, the exception are usually embedded systems with
753 no or special OSs.
754 USE_FOLDERS
756 Use the FOLDER target property to organize targets into folders.
757 If not set, CMake treats this property as OFF by default. CMake gener‐
759 ators that are capable of organizing into a hierarchy of folders use
760 the values of the FOLDER target property to name those folders. See
761 also the documentation for the FOLDER target property.
762 XCODE_EMIT_EFFECTIVE_PLATFORM_NAME
764 New in version 3.8.
765 Control emission of EFFECTIVE_PLATFORM_NAME by the Xcode generator.
768 It is required for building the same target with multiple SDKs. A com‐
770 mon use case is the parallel use of iphoneos and iphonesimulator SDKs.
771 Three different states possible that control when the Xcode generator
773 emits the EFFECTIVE_PLATFORM_NAME variable:
774 • If set to ON it will always be emitted
776 • If set to OFF it will never be emitted
778 • If unset (the default) it will only be emitted when the project was
780 configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
781 of the simulators.
782 NOTE:
784 When this behavior is enable for generated Xcode projects, the EF‐
785 FECTIVE_PLATFORM_NAME variable will leak into Generator expressions
786 like TARGET_FILE and will render those mostly unusable.
787
789 ADDITIONAL_CLEAN_FILES
790 New in version 3.15.
791 A ;-list of files or directories that will be removed as a part of the
794 global clean target. It is useful for specifying generated files or
795 directories that are used by multiple targets or by CMake itself, or
796 that are generated in ways which cannot be captured as outputs or
797 byproducts of custom commands.
798 If an additional clean file is specific to a single target only, then
800 the ADDITIONAL_CLEAN_FILES target property would usually be a better
801 choice than this directory property.
802 Relative paths are allowed and are interpreted relative to the current
804 binary directory.
805 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
807 This property only works for the Ninja and the Makefile generators. It
809 is ignored by other generators.
810 BINARY_DIR
812 New in version 3.7.
813 This read-only directory property reports absolute path to the binary
816 directory corresponding to the source on which it is read.
817 BUILDSYSTEM_TARGETS
819 New in version 3.7.
820 This read-only directory property contains a semicolon-separated list
823 of buildsystem targets added in the directory by calls to the
824 add_library(), add_executable(), and add_custom_target() commands. The
825 list does not include any Imported Targets or Alias Targets, but does
826 include Interface Libraries. Each entry in the list is the logical
827 name of a target, suitable to pass to the get_property() command TARGET
828 option.
829 See also the IMPORTED_TARGETS directory property.
831 CACHE_VARIABLES
833 List of cache variables available in the current directory.
834 This read-only property specifies the list of CMake cache variables
836 currently defined. It is intended for debugging purposes.
837 CLEAN_NO_CUSTOM
839 Set to true to tell Makefile Generators not to remove the outputs of
840 custom commands for this directory during the make clean operation.
841 This is ignored on other generators because it is not possible to im‐
842 plement.
843 CMAKE_CONFIGURE_DEPENDS
845 Tell CMake about additional input files to the configuration process.
846 If any named file is modified the build system will re-run CMake to
847 re-configure the file and generate the build system again.
848 Specify files as a semicolon-separated list of paths. Relative paths
850 are interpreted as relative to the current source directory.
851 COMPILE_DEFINITIONS
853 Preprocessor definitions for compiling a directory's sources.
854 This property specifies the list of options given so far to the
856 add_compile_definitions() (or add_definitions()) command.
857 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
859 list of preprocessor definitions using the syntax VAR or VAR=value.
860 Function-style definitions are not supported. CMake will automatically
861 escape the value correctly for the native build system (note that CMake
862 language syntax may require escapes to specify some values).
863 This property will be initialized in each directory by its value in the
865 directory's parent.
866 CMake will automatically drop some definitions that are not supported
868 by the native build tool.
869 Disclaimer: Most native build tools have poor support for escaping cer‐
871 tain values. CMake has work-arounds for many cases but some values may
872 just not be possible to pass correctly. If a value does not seem to be
873 escaped correctly, do not attempt to work-around the problem by adding
874 escape sequences to the value. Your work-around may break in a future
875 version of CMake that has improved escape support. Instead consider
876 defining the macro in a (configured) header file. Then report the lim‐
877 itation. Known limitations include:
878 # - broken almost everywhere
880 ; - broken in VS IDE 7.0 and Borland Makefiles
881 , - broken in VS IDE
882 % - broken in some cases in NMake
883 & | - broken in some cases on MinGW
884 ^ < > \" - broken in most Make tools on Windows
885 CMake does not reject these values outright because they do work in
887 some cases. Use with caution.
888 Contents of COMPILE_DEFINITIONS may use "generator expressions" with
890 the syntax $<...>. See the cmake-generator-expressions(7) manual for
891 available expressions. See the cmake-buildsystem(7) manual for more on
892 defining buildsystem properties.
893 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
895 specify per-configuration definitions. Generator expressions should be
896 preferred instead of setting the alternative property.
897 COMPILE_OPTIONS
899 List of options to pass to the compiler.
900 This property holds a semicolon-separated list of options given so far
902 to the add_compile_options() command.
903 This property is used to initialize the COMPILE_OPTIONS target property
905 when a target is created, which is used by the generators to set the
906 options for the compiler.
907 Contents of COMPILE_OPTIONS may use "generator expressions" with the
909 syntax $<...>. See the cmake-generator-expressions(7) manual for
910 available expressions. See the cmake-buildsystem(7) manual for more on
911 defining buildsystem properties.
912 DEFINITIONS
914 For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead.
915 This read-only property specifies the list of flags given so far to the
917 add_definitions() command. It is intended for debugging purposes. Use
918 the COMPILE_DEFINITIONS directory property instead.
919 This built-in read-only property does not exist if policy CMP0059 is
921 set to NEW.
922 EXCLUDE_FROM_ALL
924 Set this directory property to a true value on a subdirectory to ex‐
925 clude its targets from the "all" target of its ancestors. If excluded,
926 running e.g. make in the parent directory will not build targets the
927 subdirectory by default. This does not affect the "all" target of the
928 subdirectory itself. Running e.g. make inside the subdirectory will
929 still build its targets.
930 If the EXCLUDE_FROM_ALL target property is set on a target then its
932 value determines whether the target is included in the "all" target of
933 this directory and its ancestors.
934 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
936 Specify #include line transforms for dependencies in a directory.
937 This property specifies rules to transform macro-like #include lines
939 during implicit dependency scanning of C and C++ source files. The
940 list of rules must be semicolon-separated with each entry of the form
941 A_MACRO(%)=value-with-% (the % must be literal). During dependency
942 scanning occurrences of A_MACRO(...) on #include lines will be replaced
943 by the value given with the macro argument substituted for %. For ex‐
944 ample, the entry
945 MYDIR(%)=<mydir/%>
947 will convert lines of the form
949 #include MYDIR(myheader.h)
951 to
953 #include <mydir/myheader.h>
955 allowing the dependency to be followed.
957 This property applies to sources in all targets within a directory.
959 The property value is initialized in each directory by its value in the
960 directory's parent.
961 IMPORTED_TARGETS
963 New in version 3.21.
964 This read-only directory property contains a semicolon-separated list
967 of Imported Targets added in the directory by calls to the
968 add_library() and add_executable() commands. Each entry in the list is
969 the logical name of a target, suitable to pass to the get_property()
970 command TARGET option when called in the same directory.
971 See also the BUILDSYSTEM_TARGETS directory property.
973 INCLUDE_DIRECTORIES
975 List of preprocessor include file search directories.
976 This property specifies the list of directories given so far to the
978 include_directories() command.
979 This property is used to populate the INCLUDE_DIRECTORIES target prop‐
981 erty, which is used by the generators to set the include directories
982 for the compiler.
983 In addition to accepting values from that command, values may be set
985 directly on any directory using the set_property() command, and can be
986 set on the current directory using the set_directory_properties() com‐
987 mand. A directory gets its initial value from its parent directory if
988 it has one. The initial value of the INCLUDE_DIRECTORIES target prop‐
989 erty comes from the value of this property. Both directory and target
990 property values are adjusted by calls to the include_directories() com‐
991 mand. Calls to set_property() or set_directory_properties(), however,
992 will update the directory property value without updating target prop‐
993 erty values. Therefore direct property updates must be made before
994 calls to add_executable() or add_library() for targets they are meant
995 to affect.
996 The target property values are used by the generators to set the in‐
998 clude paths for the compiler.
999 Contents of INCLUDE_DIRECTORIES may use "generator expressions" with
1001 the syntax $<...>. See the cmake-generator-expressions(7) manual for
1002 available expressions. See the cmake-buildsystem(7) manual for more on
1003 defining buildsystem properties.
1004 INCLUDE_REGULAR_EXPRESSION
1006 Include file scanning regular expression.
1007 This property specifies the regular expression used during dependency
1009 scanning to match include files that should be followed. See the
1010 include_regular_expression() command for a high-level interface to set
1011 this property.
1012 INTERPROCEDURAL_OPTIMIZATION
1014 Enable interprocedural optimization for targets in a directory.
1015 If set to true, enables interprocedural optimizations if they are known
1017 to be supported by the compiler.
1018 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
1020 Per-configuration interprocedural optimization for a directory.
1021 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
1023 If set, this property overrides the generic property for the named con‐
1024 figuration.
1025 LABELS
1027 New in version 3.10.
1028 Specify a list of text labels associated with a directory and all of
1031 its subdirectories. This is equivalent to setting the LABELS target
1032 property and the LABELS test property on all targets and tests in the
1033 current directory and subdirectories. Note: Launchers must enabled to
1034 propagate labels to targets.
1035 The CMAKE_DIRECTORY_LABELS variable can be used to initialize this
1037 property.
1038 The list is reported in dashboard submissions.
1040 LINK_DIRECTORIES
1042 List of linker search directories.
1043 This property holds a semicolon-separated list of directories and is
1045 typically populated using the link_directories() command. It gets its
1046 initial value from its parent directory, if it has one.
1047 The directory property is used to initialize the LINK_DIRECTORIES tar‐
1049 get property when a target is created. That target property is used by
1050 the generators to set the library search directories for the linker.
1051 Contents of LINK_DIRECTORIES may use "generator expressions" with the
1053 syntax $<...>. See the cmake-generator-expressions(7) manual for
1054 available expressions. See the cmake-buildsystem(7) manual for more on
1055 defining buildsystem properties.
1056 LINK_OPTIONS
1058 New in version 3.13.
1059 List of options to use for the link step of shared library, module and
1062 executable targets as well as the device link step.
1063 This property holds a semicolon-separated list of options given so far
1065 to the add_link_options() command.
1066 This property is used to initialize the LINK_OPTIONS target property
1068 when a target is created, which is used by the generators to set the
1069 options for the compiler.
1070 Contents of LINK_OPTIONS may use "generator expressions" with the syn‐
1072 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
1073 able expressions. See the cmake-buildsystem(7) manual for more on
1074 defining buildsystem properties.
1075 LISTFILE_STACK
1077 The current stack of listfiles being processed.
1078 This property is mainly useful when trying to debug errors in your
1080 CMake scripts. It returns a list of what list files are currently be‐
1081 ing processed, in order. So if one listfile does an include() command
1082 then that is effectively pushing the included listfile onto the stack.
1083 MACROS
1085 List of macro commands available in the current directory.
1086 This read-only property specifies the list of CMake macros currently
1088 defined. It is intended for debugging purposes. See the macro() com‐
1089 mand.
1090 PARENT_DIRECTORY
1092 Source directory that added current subdirectory.
1093 This read-only property specifies the source directory that added the
1095 current source directory as a subdirectory of the build. In the
1096 top-level directory the value is the empty-string.
1097 RULE_LAUNCH_COMPILE
1099 Specify a launcher for compile rules.
1100 NOTE:
1102 This property is intended for internal use by ctest(1). Projects
1103 and developers should use the <LANG>_COMPILER_LAUNCHER target prop‐
1104 erties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables
1105 instead.
1106 See the global property of the same name for details. This overrides
1108 the global property for a directory.
1109 RULE_LAUNCH_CUSTOM
1111 Specify a launcher for custom rules.
1112 See the global property of the same name for details. This overrides
1114 the global property for a directory.
1115 RULE_LAUNCH_LINK
1117 Specify a launcher for link rules.
1118 NOTE:
1120 This property is intended for internal use by ctest(1). Projects
1121 and developers should use the <LANG>_LINKER_LAUNCHER target proper‐
1122 ties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables in‐
1123 stead.
1124 See the global property of the same name for details. This overrides
1126 the global property for a directory.
1127 SOURCE_DIR
1129 New in version 3.7.
1130 This read-only directory property reports absolute path to the source
1133 directory on which it is read.
1134 SUBDIRECTORIES
1136 New in version 3.7.
1137 This read-only directory property contains a semicolon-separated list
1140 of subdirectories processed so far by the add_subdirectory() or
1141 subdirs() commands. Each entry is the absolute path to the source di‐
1142 rectory (containing the CMakeLists.txt file). This is suitable to pass
1143 to the get_property() command DIRECTORY option.
1144 NOTE:
1146 The subdirs() command does not process its arguments until after the
1147 calling directory is fully processed. Therefore looking up this
1148 property in the current directory will not see them.
1149 SYSTEM
1151 New in version 3.25.
1152 This directory property is used to initialize the SYSTEM target prop‐
1155 erty for non-imported targets created in that directory. It is set to
1156 true by add_subdirectory() and FetchContent_Declare() when the SYSTEM
1157 option is given as an argument to those commands.
1158 TESTS
1160 New in version 3.12.
1161 List of tests.
1164 This read-only property holds a semicolon-separated list of tests de‐
1166 fined so far, in the current directory, by the add_test() command.
1167 TEST_INCLUDE_FILES
1169 New in version 3.10.
1170 A list of cmake files that will be included when ctest is run.
1173 If you specify TEST_INCLUDE_FILES, those files will be included and
1175 processed when ctest is run on the directory.
1176 VARIABLES
1178 List of variables defined in the current directory.
1179 This read-only property specifies the list of CMake variables currently
1181 defined. It is intended for debugging purposes.
1182 VS_GLOBAL_SECTION_POST_<section>
1184 Specify a postSolution global section in Visual Studio.
1185 Setting a property like this generates an entry of the following form
1187 in the solution file:
1188 GlobalSection(<section>) = postSolution
1190 <contents based on property value>
1191 EndGlobalSection
1192 The property must be set to a semicolon-separated list of key=value
1194 pairs. Each such pair will be transformed into an entry in the solu‐
1195 tion global section. Whitespace around key and value is ignored. List
1196 elements which do not contain an equal sign are skipped.
1197 This property only works for Visual Studio 9 and above; it is ignored
1199 on other generators. The property only applies when set on a directory
1200 whose CMakeLists.txt contains a project() command.
1201 Note that CMake generates postSolution sections ExtensibilityGlobals
1203 and ExtensibilityAddIns by default. If you set the corresponding prop‐
1204 erty, it will override the default section. For example, setting
1205 VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default
1206 contents of the ExtensibilityGlobals section, while keeping Extensibil‐
1207 ityAddIns on its default. However, CMake will always add a Solu‐
1208 tionGuid to the ExtensibilityGlobals section if it is not specified ex‐
1209 plicitly.
1210 VS_GLOBAL_SECTION_PRE_<section>
1212 Specify a preSolution global section in Visual Studio.
1213 Setting a property like this generates an entry of the following form
1215 in the solution file:
1216 GlobalSection(<section>) = preSolution
1218 <contents based on property value>
1219 EndGlobalSection
1220 The property must be set to a semicolon-separated list of key=value
1222 pairs. Each such pair will be transformed into an entry in the solu‐
1223 tion global section. Whitespace around key and value is ignored. List
1224 elements which do not contain an equal sign are skipped.
1225 This property only works for Visual Studio 9 and above; it is ignored
1227 on other generators. The property only applies when set on a directory
1228 whose CMakeLists.txt contains a project() command.
1229 VS_STARTUP_PROJECT
1231 New in version 3.6.
1232 Specify the default startup project in a Visual Studio solution.
1235 The Visual Studio Generators create a .sln file for each directory
1237 whose CMakeLists.txt file calls the project() command. Set this prop‐
1238 erty in the same directory as a project() command call (e.g. in the
1239 top-level CMakeLists.txt file) to specify the default startup project
1240 for the corresponding solution file.
1241 The property must be set to the name of an existing target. This will
1243 cause that project to be listed first in the generated solution file
1244 causing Visual Studio to make it the startup project if the solution
1245 has never been opened before.
1246 If this property is not specified, then the ALL_BUILD project will be
1248 the default.
1249
1251 ADDITIONAL_CLEAN_FILES
1252 New in version 3.15.
1253 A ;-list of files or directories that will be removed as a part of the
1256 global clean target. It can be used to specify files and directories
1257 that are generated as part of building the target or that are directly
1258 associated with the target in some way (e.g. created as a result of
1259 running the target).
1260 For custom targets, if such files can be captured as outputs or byprod‐
1262 ucts instead, then that should be preferred over adding them to this
1263 property. If an additional clean file is used by multiple targets or
1264 isn't target-specific, then the ADDITIONAL_CLEAN_FILES directory prop‐
1265 erty may be the more appropriate property to use.
1266 Relative paths are allowed and are interpreted relative to the current
1268 binary directory.
1269 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
1271 This property only works for the Ninja and the Makefile generators. It
1273 is ignored by other generators.
1274 AIX_EXPORT_ALL_SYMBOLS
1276 New in version 3.17.
1277 On AIX, CMake automatically exports all symbols from shared libraries,
1280 and from executables with the ENABLE_EXPORTS target property set. Ex‐
1281 plicitly disable this boolean property to suppress the behavior and ex‐
1282 port no symbols by default. In this case it is expected that the
1283 project will use other means to export some symbols.
1284 This property is initialized by the value of the
1286 CMAKE_AIX_EXPORT_ALL_SYMBOLS variable if it is set when a target is
1287 created.
1288 ALIAS_GLOBAL
1290 New in version 3.18.
1291 Read-only property indicating of whether an ALIAS target is globally
1294 visible.
1295 The boolean value of this property is TRUE for aliases to IMPORTED tar‐
1297 gets created with the GLOBAL options to add_executable() or
1298 add_library(), FALSE otherwise. It is undefined for targets built
1299 within the project.
1300 NOTE:
1302 Promoting an IMPORTED target from LOCAL to GLOBAL scope by changing
1303 the value or IMPORTED_GLOBAL target property do not change the scope
1304 of local aliases.
1305 ALIASED_TARGET
1307 Name of target aliased by this target.
1308 If this is an Alias Target, this property contains the name of the tar‐
1310 get aliased.
1311 ANDROID_ANT_ADDITIONAL_OPTIONS
1313 New in version 3.4.
1314 Set the additional options for Android Ant build system. This is a
1317 string value containing all command line options for the Ant build.
1318 This property is initialized by the value of the
1319 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS variable if it is set when a tar‐
1320 get is created.
1321 ANDROID_API
1323 New in version 3.1.
1324 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1327 Edition, this property sets the Android target API version (e.g. 15).
1328 The version number must be a positive decimal integer. This property
1329 is initialized by the value of the CMAKE_ANDROID_API variable if it is
1330 set when a target is created.
1331 ANDROID_API_MIN
1333 New in version 3.2.
1334 Set the Android MIN API version (e.g. 9). The version number must be a
1337 positive decimal integer. This property is initialized by the value of
1338 the CMAKE_ANDROID_API_MIN variable if it is set when a target is cre‐
1339 ated. Native code builds using this API version.
1340 ANDROID_ARCH
1342 New in version 3.4.
1343 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1346 Edition, this property sets the Android target architecture.
1347 This is a string property that could be set to the one of the following
1349 values:
1350 • armv7-a: "ARMv7-A (armv7-a)"
1352 • armv7-a-hard: "ARMv7-A, hard-float ABI (armv7-a)"
1354 • arm64-v8a: "ARMv8-A, 64bit (arm64-v8a)"
1356 • x86: "x86 (x86)"
1358 • x86_64: "x86_64 (x86_64)"
1360 This property is initialized by the value of the CMAKE_ANDROID_ARCH
1362 variable if it is set when a target is created.
1363 ANDROID_ASSETS_DIRECTORIES
1365 New in version 3.4.
1366 Set the Android assets directories to copy into the main assets folder
1369 before build. This a string property that contains the directory paths
1370 separated by semicolon. This property is initialized by the value of
1371 the CMAKE_ANDROID_ASSETS_DIRECTORIES variable if it is set when a tar‐
1372 get is created.
1373 ANDROID_GUI
1375 New in version 3.1.
1376 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1379 Edition, this property specifies whether to build an executable as an
1380 application package on Android.
1381 When this property is set to true the executable when built for Android
1383 will be created as an application package. This property is initial‐
1384 ized by the value of the CMAKE_ANDROID_GUI variable if it is set when a
1385 target is created.
1386 Add the AndroidManifest.xml source file explicitly to the target
1388 add_executable() command invocation to specify the root directory of
1389 the application package source.
1390 ANDROID_JAR_DEPENDENCIES
1392 New in version 3.4.
1393 Set the Android property that specifies JAR dependencies. This is a
1396 string value property. This property is initialized by the value of the
1397 CMAKE_ANDROID_JAR_DEPENDENCIES variable if it is set when a target is
1398 created.
1399 ANDROID_JAR_DIRECTORIES
1401 New in version 3.4.
1402 Set the Android property that specifies directories to search for the
1405 JAR libraries.
1406 This a string property that contains the directory paths separated by
1408 semicolons. This property is initialized by the value of the
1409 CMAKE_ANDROID_JAR_DIRECTORIES variable if it is set when a target is
1410 created.
1411 Contents of ANDROID_JAR_DIRECTORIES may use "generator expressions"
1413 with the syntax $<...>. See the cmake-generator-expressions(7) manual
1414 for available expressions.
1415 ANDROID_JAVA_SOURCE_DIR
1417 New in version 3.4.
1418 Set the Android property that defines the Java source code root direc‐
1421 tories. This a string property that contains the directory paths sepa‐
1422 rated by semicolon. This property is initialized by the value of the
1423 CMAKE_ANDROID_JAVA_SOURCE_DIR variable if it is set when a target is
1424 created.
1425 ANDROID_NATIVE_LIB_DEPENDENCIES
1427 New in version 3.4.
1428 Set the Android property that specifies the .so dependencies. This is
1431 a string property.
1432 This property is initialized by the value of the
1434 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES variable if it is set when a tar‐
1435 get is created.
1436 Contents of ANDROID_NATIVE_LIB_DEPENDENCIES may use "generator expres‐
1438 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
1439 manual for available expressions.
1440 ANDROID_NATIVE_LIB_DIRECTORIES
1442 New in version 3.4.
1443 Set the Android property that specifies directories to search for the
1446 .so libraries.
1447 This a string property that contains the directory paths separated by
1449 semicolons.
1450 This property is initialized by the value of the
1452 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES variable if it is set when a tar‐
1453 get is created.
1454 Contents of ANDROID_NATIVE_LIB_DIRECTORIES may use "generator expres‐
1456 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
1457 manual for available expressions.
1458 ANDROID_PROCESS_MAX
1460 New in version 3.4.
1461 Set the Android property that defines the maximum number of a parallel
1464 Android NDK compiler processes (e.g. 4). This property is initialized
1465 by the value of the CMAKE_ANDROID_PROCESS_MAX variable if it is set
1466 when a target is created.
1467 ANDROID_PROGUARD
1469 New in version 3.4.
1470 When this property is set to true that enables the ProGuard tool to
1473 shrink, optimize, and obfuscate the code by removing unused code and
1474 renaming classes, fields, and methods with semantically obscure names.
1475 This property is initialized by the value of the CMAKE_ANDROID_PROGUARD
1476 variable if it is set when a target is created.
1477 ANDROID_PROGUARD_CONFIG_PATH
1479 New in version 3.4.
1480 Set the Android property that specifies the location of the ProGuard
1483 config file. Leave empty to use the default one. This a string prop‐
1484 erty that contains the path to ProGuard config file. This property is
1485 initialized by the value of the CMAKE_ANDROID_PROGUARD_CONFIG_PATH
1486 variable if it is set when a target is created.
1487 ANDROID_SECURE_PROPS_PATH
1489 New in version 3.4.
1490 Set the Android property that states the location of the secure proper‐
1493 ties file. This is a string property that contains the file path.
1494 This property is initialized by the value of the
1495 CMAKE_ANDROID_SECURE_PROPS_PATH variable if it is set when a target is
1496 created.
1497 ANDROID_SKIP_ANT_STEP
1499 New in version 3.4.
1500 Set the Android property that defines whether or not to skip the Ant
1503 build step. This is a boolean property initialized by the value of the
1504 CMAKE_ANDROID_SKIP_ANT_STEP variable if it is set when a target is cre‐
1505 ated.
1506 ANDROID_STL_TYPE
1508 New in version 3.4.
1509 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1512 Edition, this property specifies the type of STL support for the
1513 project. This is a string property that could set to the one of the
1514 following values:
1515 none No C++ Support
1517 system Minimal C++ without STL
1519 gabi++_static
1521 GAbi++ Static
1522 gabi++_shared
1524 GAbi++ Shared
1525 gnustl_static
1527 GNU libstdc++ Static
1528 gnustl_shared
1530 GNU libstdc++ Shared
1531 stlport_static
1533 STLport Static
1534 stlport_shared
1536 STLport Shared
1537 This property is initialized by the value of the CMAKE_ANDROID_STL_TYPE
1539 variable if it is set when a target is created.
1540 ARCHIVE_OUTPUT_DIRECTORY
1542 Output directory in which to build ARCHIVE target files.
1543 This property specifies the directory into which archive target files
1545 should be built. The property value may use generator expressions.
1546 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
1547 fig) append a per-configuration subdirectory to the specified directory
1548 unless a generator expression is used.
1549 This property is initialized by the value of the
1551 CMAKE_ARCHIVE_OUTPUT_DIRECTORY variable if it is set when a target is
1552 created.
1553 See also the ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> target property.
1555 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
1557 Per-configuration output directory for ARCHIVE target files.
1558 This is a per-configuration version of the ARCHIVE_OUTPUT_DIRECTORY
1560 target property, but multi-configuration generators (VS, Xcode) do NOT
1561 append a per-configuration subdirectory to the specified directory.
1562 This property is initialized by the value of the
1563 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
1564 target is created.
1565 Contents of ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
1567 sions.
1568 ARCHIVE_OUTPUT_NAME
1570 Output name for ARCHIVE target files.
1571 This property specifies the base name for archive target files. It
1573 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
1574 See also the ARCHIVE_OUTPUT_NAME_<CONFIG> target property.
1576 ARCHIVE_OUTPUT_NAME_<CONFIG>
1578 Per-configuration output name for ARCHIVE target files.
1579 This is the configuration-specific version of the ARCHIVE_OUTPUT_NAME
1581 target property.
1582 AUTOGEN_BUILD_DIR
1584 New in version 3.9.
1585 Directory where AUTOMOC, AUTOUIC and AUTORCC generate files for the
1588 target.
1589 The directory is created on demand and automatically added to the
1591 ADDITIONAL_CLEAN_FILES target property.
1592 When unset or empty the directory <dir>/<target-name>_autogen is used
1594 where <dir> is CMAKE_CURRENT_BINARY_DIR and <target-name> is NAME.
1595 By default AUTOGEN_BUILD_DIR is unset.
1597 See the cmake-qt(7) manual for more information on using CMake with Qt.
1599 AUTOGEN_ORIGIN_DEPENDS
1601 New in version 3.14.
1602 Switch for forwarding origin target dependencies to the corresponding
1605 _autogen target.
1606 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1608 sponding _autogen target which generates moc and uic files. As this
1609 _autogen target is created at generate-time, it is not possible to de‐
1610 fine dependencies of it using e.g. add_dependencies(). Instead the
1611 AUTOGEN_ORIGIN_DEPENDS target property decides whether the origin tar‐
1612 get dependencies should be forwarded to the _autogen target or not.
1613 By default AUTOGEN_ORIGIN_DEPENDS is initialized from
1615 CMAKE_AUTOGEN_ORIGIN_DEPENDS which is ON by default.
1616 In total the dependencies of the _autogen target are composed from
1618 • forwarded origin target dependencies (enabled by default via
1620 AUTOGEN_ORIGIN_DEPENDS)
1621 • additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1623 See the cmake-qt(7) manual for more information on using CMake with Qt.
1625 Note
1627 Disabling AUTOGEN_ORIGIN_DEPENDS is useful to avoid building of origin
1628 target dependencies when building the _autogen target only. This is
1629 especially interesting when a global autogen target is enabled.
1630 When the _autogen target doesn't require all the origin target's depen‐
1632 dencies, and AUTOGEN_ORIGIN_DEPENDS is disabled, it might be necessary
1633 to extend AUTOGEN_TARGET_DEPENDS to add missing dependencies.
1634 AUTOGEN_PARALLEL
1636 New in version 3.11.
1637 Number of parallel moc or uic processes to start when using AUTOMOC and
1640 AUTOUIC.
1641 The custom <origin>_autogen target starts a number of threads of which
1643 each one parses a source file and on demand starts a moc or uic
1644 process. AUTOGEN_PARALLEL controls how many parallel threads (and
1645 therefore moc or uic processes) are started.
1646 • An empty (or unset) value or the string AUTO sets the number of
1648 threads/processes to the number of physical CPUs on the host system.
1649 • A positive non zero integer value sets the exact thread/process
1651 count.
1652 • Otherwise a single thread/process is started.
1654 By default AUTOGEN_PARALLEL is initialized from CMAKE_AUTOGEN_PARALLEL.
1656 See the cmake-qt(7) manual for more information on using CMake with Qt.
1658 AUTOGEN_TARGET_DEPENDS
1660 Additional target dependencies of the corresponding _autogen target.
1661 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1663 sponding _autogen target which generates moc and uic files. As this
1664 _autogen target is created at generate-time, it is not possible to de‐
1665 fine dependencies of it using e.g. add_dependencies(). Instead the
1666 AUTOGEN_TARGET_DEPENDS target property can be set to a ;-list of addi‐
1667 tional dependencies for the _autogen target. Dependencies can be tar‐
1668 get names or file names.
1669 In total the dependencies of the _autogen target are composed from
1671 • forwarded origin target dependencies (enabled by default via
1673 AUTOGEN_ORIGIN_DEPENDS)
1674 • additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1676 See the cmake-qt(7) manual for more information on using CMake with Qt.
1678 Use cases
1680 If AUTOMOC or AUTOUIC depends on a file that is either
1681 • a GENERATED non C++ file (e.g. a GENERATED .json or .ui file) or
1683 • a GENERATED C++ file that isn't recognized by AUTOMOC and AUTOUIC be‐
1685 cause it's skipped by SKIP_AUTOMOC, SKIP_AUTOUIC, SKIP_AUTOGEN or
1686 CMP0071 or
1687 • a file that isn't in the origin target's sources
1689 it must be added to AUTOGEN_TARGET_DEPENDS.
1691 AUTOMOC
1693 Should the target be processed with auto-moc (for Qt projects).
1694 AUTOMOC is a boolean specifying whether CMake will handle the Qt moc
1696 preprocessor automatically, i.e. without having to use commands like
1697 QT4_WRAP_CPP(), QT5_WRAP_CPP(), etc. Currently, Qt versions 4 to 6 are
1698 supported.
1699 This property is initialized by the value of the CMAKE_AUTOMOC variable
1701 if it is set when a target is created.
1702 When this property is set ON, CMake will scan the header and source
1704 files at build time and invoke moc accordingly.
1705 Header file processing
1707 At configuration time, a list of header files that should be scanned by
1708 AUTOMOC is computed from the target's sources.
1709 • All header files in the target's sources are added to the scan list.
1711 • For all C++ source files <source_base>.<source_extension> in the tar‐
1713 get's sources, CMake searches for
1714 • a regular header with the same base name (<source_base>.<header_ex‐
1716 tention>) and
1717 • a private header with the same base name and a _p suffix
1719 (<source_base>_p.<header_extention>)
1720 and adds these to the scan list.
1722 At build time, CMake scans each unknown or modified header file from
1724 the list and searches for
1725 • a Qt macro from AUTOMOC_MACRO_NAMES,
1727 • additional file dependencies from the FILE argument of a
1729 Q_PLUGIN_METADATA macro and
1730 • additional file dependencies detected by filters defined in
1732 AUTOMOC_DEPEND_FILTERS.
1733 If a Qt macro is found, then the header will be compiled by the moc to
1735 the output file moc_<base_name>.cpp. The complete output file path is
1736 described in the section Output file location.
1737 The header will be moc compiled again if a file from the additional
1739 file dependencies changes.
1740 Header moc output files moc_<base_name>.cpp can be included in source
1742 files. In the section Including header moc files in sources there is
1743 more information on that topic.
1744 Source file processing
1746 At build time, CMake scans each unknown or modified C++ source file
1747 from the target's sources for
1748 • a Qt macro from AUTOMOC_MACRO_NAMES,
1750 • includes of header moc files (see Including header moc files in
1752 sources),
1753 • additional file dependencies from the FILE argument of a
1755 Q_PLUGIN_METADATA macro and
1756 • additional file dependencies detected by filters defined in
1758 AUTOMOC_DEPEND_FILTERS.
1759 If a Qt macro is found, then the C++ source file <base>.<source_exten‐
1761 sion> is expected to as well contain an include statement
1762 #include <<base>.moc> // or
1764 #include "<base>.moc"
1765 The source file then will be compiled by the moc to the output file
1767 <base>.moc. A description of the complete output file path is in sec‐
1768 tion Output file location.
1769 The source will be moc compiled again if a file from the additional
1771 file dependencies changes.
1772 Including header moc files in sources
1774 A source file can include the moc output file of a header
1775 <header_base>.<header_extension> by using an include statement of the
1776 form
1777 #include <moc_<header_base>.cpp> // or
1779 #include "moc_<header_base>.cpp"
1780 If the moc output file of a header is included by a source, it will be
1782 generated in a different location than if it was not included. This is
1783 described in the section Output file location.
1784 Output file location
1786 Included moc output files
1787 moc output files that are included by a source file will be generated
1788 in
1789 • <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
1791 • <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
1793 tors.
1794 Where <AUTOGEN_BUILD_DIR> is the value of the target property
1796 AUTOGEN_BUILD_DIR.
1797 The include directory is automatically added to the target's
1799 INCLUDE_DIRECTORIES.
1800 Not included moc output files
1802 moc output files that are not included in a source file will be gener‐
1803 ated in
1804 • <AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM> for single configuration
1806 generators or in,
1807 • <AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM> for multi
1809 configuration generators.
1810 Where <SOURCE_DIR_CHECKSUM> is a checksum computed from the relative
1812 parent directory path of the moc input file. This scheme allows to
1813 have moc input files with the same name in different directories.
1814 All not included moc output files will be included automatically by the
1816 CMake generated file
1817 • <AUTOGEN_BUILD_DIR>/mocs_compilation.cpp, or
1819 • <AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp,
1821 which is added to the target's sources.
1823 Qt version detection
1825 AUTOMOC enabled targets need to know the Qt major and minor version
1826 they're working with. The major version usually is provided by the IN‐
1827 TERFACE_QT_MAJOR_VERSION property of the Qt[456]Core library, that the
1828 target links to. To find the minor version, CMake builds a list of
1829 available Qt versions from
1830 • Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR variables (usually
1832 set by find_package(Qt6...))
1833 • Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR directory properties
1835 • Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR variables (usually
1837 set by find_package(Qt5...))
1838 • Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR directory properties
1840 • QT_VERSION_MAJOR and QT_VERSION_MINOR variables (usually set by
1842 find_package(Qt4...))
1843 • QT_VERSION_MAJOR and QT_VERSION_MINOR directory properties
1845 in the context of the add_executable() or add_library() call.
1847 Assumed INTERFACE_QT_MAJOR_VERSION is a valid number, the first entry
1849 in the list with a matching major version is taken. If no matching ma‐
1850 jor version was found, an error is generated. If INTERFACE_QT_MA‐
1851 JOR_VERSION is not a valid number, the first entry in the list is
1852 taken.
1853 A find_package(Qt[456]...) call sets the QT/Qt[56]Core_VERSION_MA‐
1855 JOR/MINOR variables. If the call is in a different context than the
1856 add_executable() or add_library() call, e.g. in a function, then the
1857 version variables might not be available to the AUTOMOC enabled target.
1858 In that case the version variables can be forwarded from the find_pack‐
1859 age(Qt[456]...) calling context to the add_executable() or
1860 add_library() calling context as directory properties. The following
1861 Qt5 example demonstrates the procedure.
1862 function (add_qt5_client)
1864 find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets)
1865 ...
1866 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1867 PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}")
1868 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1869 PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}")
1870 ...
1871 endfunction ()
1872 ...
1873 add_qt5_client()
1874 add_executable(myTarget main.cpp)
1875 target_link_libraries(myTarget Qt5::QtWidgets)
1876 set_property(TARGET myTarget PROPERTY AUTOMOC ON)
1877 Modifiers
1879 AUTOMOC_EXECUTABLE: The moc executable will be detected automatically,
1880 but can be forced to a certain binary using this target property.
1881 AUTOMOC_MOC_OPTIONS: Additional command line options for moc can be set
1883 in this target property.
1884 AUTOMOC_MACRO_NAMES: This list of Qt macro names can be extended to
1886 search for additional macros in headers and sources.
1887 AUTOMOC_DEPEND_FILTERS: moc dependency file names can be extracted from
1889 headers or sources by defining file name filters in this target prop‐
1890 erty.
1891 AUTOMOC_COMPILER_PREDEFINES: Compiler pre definitions for moc are writ‐
1893 ten to the moc_predefs.h file. The generation of this file can be en‐
1894 abled or disabled in this target property.
1895 SKIP_AUTOMOC: Sources and headers can be excluded from AUTOMOC process‐
1897 ing by setting this source file property.
1898 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
1900 AUTORCC processing by setting this source file property.
1901 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
1903 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
1904 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
1906 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
1907 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
1909 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
1910 project, will be generated when this variable is ON.
1911 AUTOGEN_PARALLEL: This target property controls the number of moc or
1913 uic processes to start in parallel during builds.
1914 See the cmake-qt(7) manual for more information on using CMake with Qt.
1916 AUTOMOC_COMPILER_PREDEFINES
1918 New in version 3.10.
1919 Boolean value used by AUTOMOC to determine if the compiler pre defini‐
1922 tions file moc_predefs.h should be generated.
1923 CMake generates a moc_predefs.h file with compiler pre definitions from
1925 the output of the command defined in
1926 CMAKE_CXX_COMPILER_PREDEFINES_COMMAND when
1927 • AUTOMOC is enabled,
1929 • AUTOMOC_COMPILER_PREDEFINES is enabled,
1931 • CMAKE_CXX_COMPILER_PREDEFINES_COMMAND isn't empty and
1933 • the Qt version is greater or equal 5.8.
1935 The moc_predefs.h file, which is generated in AUTOGEN_BUILD_DIR, is
1937 passed to moc as the argument to the --include option.
1938 By default AUTOMOC_COMPILER_PREDEFINES is initialized from
1940 CMAKE_AUTOMOC_COMPILER_PREDEFINES, which is ON by default.
1941 See the cmake-qt(7) manual for more information on using CMake with Qt.
1943 AUTOMOC_DEPEND_FILTERS
1945 New in version 3.9.
1946 Filter definitions used by AUTOMOC to extract file names from a source
1949 file that are registered as additional dependencies for the moc file of
1950 the source file.
1951 Filters are defined as KEYWORD;REGULAR_EXPRESSION pairs. First the file
1953 content is searched for KEYWORD. If it is found at least once, then
1954 file names are extracted by successively searching for REGULAR_EXPRES‐
1955 SION and taking the first match group.
1956 The file name found in the first match group is searched for
1958 • first in the vicinity of the source file
1960 • and afterwards in the target's INCLUDE_DIRECTORIES.
1962 If any of the extracted files changes, then the moc file for the source
1964 file gets rebuilt even when the source file itself doesn't change.
1965 If any of the extracted files is GENERATED or if it is not in the tar‐
1967 get's sources, then it might be necessary to add it to the _autogen
1968 target dependencies. See AUTOGEN_TARGET_DEPENDS for reference.
1969 By default AUTOMOC_DEPEND_FILTERS is initialized from
1971 CMAKE_AUTOMOC_DEPEND_FILTERS, which is empty by default.
1972 From Qt 5.15.0 on this variable is ignored as moc is able to output the
1974 correct dependencies.
1975 See the cmake-qt(7) manual for more information on using CMake with Qt.
1977 Example 1
1979 A header file my_class.hpp uses a custom macro JSON_FILE_MACRO which is
1980 defined in an other header macros.hpp. We want the moc file of
1981 my_class.hpp to depend on the file name argument of JSON_FILE_MACRO:
1982 // my_class.hpp
1984 class My_Class : public QObject
1985 {
1986 Q_OBJECT
1987 JSON_FILE_MACRO ( "info.json" )
1988 ...
1989 };
1990 In CMakeLists.txt we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS like
1992 this:
1993 list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
1995 "JSON_FILE_MACRO"
1996 "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
1997 )
1998 We assume info.json is a plain (not GENERATED) file that is listed in
2000 the target's source. Therefore we do not need to add it to
2001 AUTOGEN_TARGET_DEPENDS.
2002 Example 2
2004 In the target my_target a header file complex_class.hpp uses a custom
2005 macro JSON_BASED_CLASS which is defined in an other header macros.hpp:
2006 // macros.hpp
2008 ...
2009 #define JSON_BASED_CLASS(name, json) \
2010 class name : public QObject \
2011 { \
2012 Q_OBJECT \
2013 Q_PLUGIN_METADATA(IID "demo" FILE json) \
2014 name() {} \
2015 };
2016 ...
2017 // complex_class.hpp
2019 #pragma once
2020 JSON_BASED_CLASS(Complex_Class, "meta.json")
2021 // end of file
2022 Since complex_class.hpp doesn't contain a Q_OBJECT macro it would be
2024 ignored by AUTOMOC. We change this by adding JSON_BASED_CLASS to
2025 CMAKE_AUTOMOC_MACRO_NAMES:
2026 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")
2028 We want the moc file of complex_class.hpp to depend on meta.json. So
2030 we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS:
2031 list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
2033 "JSON_BASED_CLASS"
2034 "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
2035 )
2036 Additionally we assume meta.json is GENERATED which is why we have to
2038 add it to AUTOGEN_TARGET_DEPENDS:
2039 set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")
2041 AUTOMOC_EXECUTABLE
2043 New in version 3.14.
2044 AUTOMOC_EXECUTABLE is file path pointing to the moc executable to use
2047 for AUTOMOC enabled files. Setting this property will make CMake skip
2048 the automatic detection of the moc binary as well as the sanity-tests
2049 normally run to ensure that the binary is available and working as ex‐
2050 pected.
2051 Usually this property does not need to be set. Only consider this prop‐
2053 erty if auto-detection of moc can not work -- e.g. because you are
2054 building the moc binary as part of your project.
2055 See the cmake-qt(7) manual for more information on using CMake with Qt.
2057 AUTOMOC_MACRO_NAMES
2059 New in version 3.10.
2060 A semicolon-separated list list of macro names used by AUTOMOC to de‐
2063 termine if a C++ file needs to be processed by moc.
2064 This property is only used if the AUTOMOC property is ON for this tar‐
2066 get.
2067 When running AUTOMOC, CMake searches for the strings listed in
2069 AUTOMOC_MACRO_NAMES in C++ source and header files. If any of the
2070 strings is found
2071 • as the first non space string on a new line or
2073 • as the first non space string after a { on a new line,
2075 then the file will be processed by moc.
2077 By default AUTOMOC_MACRO_NAMES is initialized from
2079 CMAKE_AUTOMOC_MACRO_NAMES.
2080 See the cmake-qt(7) manual for more information on using CMake with Qt.
2082 Example
2084 In this case the Q_OBJECT macro is hidden inside another macro called
2085 CUSTOM_MACRO. To let CMake know that source files that contain CUS‐
2086 TOM_MACRO need to be moc processed, we call:
2087 set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
2089 AUTOMOC_MOC_OPTIONS
2091 Additional options for moc when using AUTOMOC
2092 This property is only used if the AUTOMOC property is ON for this tar‐
2094 get. In this case, it holds additional command line options which will
2095 be used when moc is executed during the build, i.e. it is equivalent
2096 to the optional OPTIONS argument of the qt4_wrap_cpp() macro.
2097 This property is initialized by the value of the
2099 CMAKE_AUTOMOC_MOC_OPTIONS variable if it is set when a target is cre‐
2100 ated, or an empty string otherwise.
2101 See the cmake-qt(7) manual for more information on using CMake with Qt.
2103 AUTOMOC_PATH_PREFIX
2105 New in version 3.16.
2106 When this property is ON, CMake will generate the -p path prefix option
2109 for moc on AUTOMOC enabled Qt targets.
2110 To generate the path prefix, CMake tests if the header compiled by moc
2112 is in any of the target include directories. If so, CMake will compute
2113 the relative path accordingly. If the header is not in the include di‐
2114 rectories, CMake will omit the -p path prefix option. moc usually gen‐
2115 erates a relative include path in that case.
2116 AUTOMOC_PATH_PREFIX is initialized from the variable
2118 CMAKE_AUTOMOC_PATH_PREFIX, which is OFF by default.
2119 See the cmake-qt(7) manual for more information on using CMake with Qt.
2121 Reproducible builds
2123 For reproducible builds it is recommended to keep headers that are moc
2124 compiled in one of the target include directories and set
2125 AUTOMOC_PATH_PREFIX to ON. This ensures that:
2126 • moc output files are identical on different build setups,
2128 • moc output files will compile correctly when the source and/or build
2130 directory is a symbolic link.
2131 AUTORCC
2133 Should the target be processed with auto-rcc (for Qt projects).
2134 AUTORCC is a boolean specifying whether CMake will handle the Qt rcc
2136 code generator automatically, i.e. without having to use commands like
2137 QT4_ADD_RESOURCES(), QT5_ADD_RESOURCES(), etc. Currently, Qt versions
2138 4 to 6 are supported.
2139 When this property is ON, CMake will handle .qrc files added as target
2141 sources at build time and invoke rcc accordingly. This property is
2142 initialized by the value of the CMAKE_AUTORCC variable if it is set
2143 when a target is created.
2144 By default AUTORCC is processed by a custom command. If the .qrc file
2146 is GENERATED, a custom target is used instead.
2147 When there are multiple .qrc files with the same name, CMake will gen‐
2149 erate unspecified unique output file names for rcc. Therefore, if
2150 Q_INIT_RESOURCE() or Q_CLEANUP_RESOURCE() need to be used, the .qrc
2151 file name must be unique.
2152 Modifiers
2154 AUTORCC_EXECUTABLE: The rcc executable will be detected automatically,
2155 but can be forced to a certain binary by setting this target property.
2156 AUTORCC_OPTIONS: Additional command line options for rcc can be set via
2158 this target property. The corresponding AUTORCC_OPTIONS source file
2159 property can be used to specify options to be applied only to a spe‐
2160 cific .qrc file.
2161 SKIP_AUTORCC: .qrc files can be excluded from AUTORCC processing by
2163 setting this source file property.
2164 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
2166 AUTORCC processing by setting this source file property.
2167 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
2169 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
2170 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
2172 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
2173 CMAKE_GLOBAL_AUTORCC_TARGET: A global autorcc target that depends on
2175 all AUTORCC targets in the project will be generated when this variable
2176 is ON.
2177 See the cmake-qt(7) manual for more information on using CMake with Qt.
2179 AUTORCC_EXECUTABLE
2181 New in version 3.14.
2182 AUTORCC_EXECUTABLE is file path pointing to the rcc executable to use
2185 for AUTORCC enabled files. Setting this property will make CMake skip
2186 the automatic detection of the rcc binary as well as the sanity-tests
2187 normally run to ensure that the binary is available and working as ex‐
2188 pected.
2189 Usually this property does not need to be set. Only consider this prop‐
2191 erty if auto-detection of rcc can not work -- e.g. because you are
2192 building the rcc binary as part of your project.
2193 See the cmake-qt(7) manual for more information on using CMake with Qt.
2195 AUTORCC_OPTIONS
2197 Additional options for rcc when using AUTORCC
2198 This property holds additional command line options which will be used
2200 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
2201 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
2202 This property is initialized by the value of the CMAKE_AUTORCC_OPTIONS
2204 variable if it is set when a target is created, or an empty string oth‐
2205 erwise.
2206 The options set on the target may be overridden by AUTORCC_OPTIONS set
2208 on the .qrc source file.
2209 See the cmake-qt(7) manual for more information on using CMake with Qt.
2211 EXAMPLE
2213 # ...
2214 set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9")
2215 # ...
2216 AUTOUIC
2218 Should the target be processed with auto-uic (for Qt projects).
2219 AUTOUIC is a boolean specifying whether CMake will handle the Qt uic
2221 code generator automatically, i.e. without having to use commands like
2222 QT4_WRAP_UI(), QT5_WRAP_UI(), etc. Currently, Qt versions 4 to 6 are
2223 supported.
2224 This property is initialized by the value of the CMAKE_AUTOUIC variable
2226 if it is set when a target is created.
2227 When this property is ON, CMake will scan the header and source files
2229 at build time and invoke uic accordingly.
2230 Header and source file processing
2232 At build time, CMake scans each header and source file from the tar‐
2233 get's sources for include statements of the form
2234 #include "ui_<ui_base>.h"
2236 Once such an include statement is found in a file, CMake searches for
2238 the uic input file <ui_base>.ui
2239 • in the vicinity of the file and
2241 • in the AUTOUIC_SEARCH_PATHS of the target.
2243 If the <ui_base>.ui file was found, uic is called on it to generate
2245 ui_<ui_base>.h in the directory
2246 • <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
2248 • <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
2250 tors.
2251 Where <AUTOGEN_BUILD_DIR> is the value of the target property
2253 AUTOGEN_BUILD_DIR.
2254 The include directory is automatically added to the target's
2256 INCLUDE_DIRECTORIES.
2257 Modifiers
2259 AUTOUIC_EXECUTABLE: The uic executable will be detected automatically,
2260 but can be forced to a certain binary using this target property.
2261 AUTOUIC_OPTIONS: Additional command line options for uic can be set via
2263 this target property. The corresponding AUTOUIC_OPTIONS source file
2264 property can be used to specify options to be applied only to a spe‐
2265 cific <base_name>.ui file.
2266 SKIP_AUTOUIC: Source files can be excluded from AUTOUIC processing by
2268 setting this source file property.
2269 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
2271 AUTORCC processing by setting this source file property.
2272 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
2274 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
2275 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
2277 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
2278 project, will be generated when this variable is ON.
2279 AUTOGEN_PARALLEL: This target property controls the number of moc or
2281 uic processes to start in parallel during builds.
2282 See the cmake-qt(7) manual for more information on using CMake with Qt.
2284 AUTOUIC_EXECUTABLE
2286 New in version 3.14.
2287 AUTOUIC_EXECUTABLE is file path pointing to the uic executable to use
2290 for AUTOUIC enabled files. Setting this property will make CMake skip
2291 the automatic detection of the uic binary as well as the sanity-tests
2292 normally run to ensure that the binary is available and working as ex‐
2293 pected.
2294 Usually this property does not need to be set. Only consider this prop‐
2296 erty if auto-detection of uic can not work -- e.g. because you are
2297 building the uic binary as part of your project.
2298 See the cmake-qt(7) manual for more information on using CMake with Qt.
2300 AUTOUIC_OPTIONS
2302 Additional options for uic when using AUTOUIC
2303 This property holds additional command line options which will be used
2305 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
2306 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
2307 This property is initialized by the value of the CMAKE_AUTOUIC_OPTIONS
2309 variable if it is set when a target is created, or an empty string oth‐
2310 erwise.
2311 The options set on the target may be overridden by AUTOUIC_OPTIONS set
2313 on the .ui source file.
2314 This property may use "generator expressions" with the syntax $<...>.
2316 See the cmake-generator-expressions(7) manual for available expres‐
2317 sions.
2318 See the cmake-qt(7) manual for more information on using CMake with Qt.
2320 EXAMPLE
2322 # ...
2323 set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection")
2324 # ...
2325 AUTOUIC_SEARCH_PATHS
2327 New in version 3.9.
2328 Search path list used by AUTOUIC to find included .ui files.
2331 This property is initialized by the value of the
2333 CMAKE_AUTOUIC_SEARCH_PATHS variable if it is set when a target is cre‐
2334 ated. Otherwise it is empty.
2335 See the cmake-qt(7) manual for more information on using CMake with Qt.
2337 BINARY_DIR
2339 New in version 3.4.
2340 This read-only property reports the value of the
2343 CMAKE_CURRENT_BINARY_DIR variable in the directory in which the target
2344 was defined.
2345 BUILD_RPATH
2347 New in version 3.8.
2348 A semicolon-separated list specifying runtime path (RPATH) entries to
2351 add to binaries linked in the build tree (for platforms that support
2352 it). The entries will not be used for binaries in the install tree.
2353 See also the INSTALL_RPATH target property.
2354 This property is initialized by the value of the variable
2356 CMAKE_BUILD_RPATH if it is set when a target is created.
2357 This property supports generator expressions.
2359 BUILD_RPATH_USE_ORIGIN
2361 New in version 3.14.
2362 Whether to use relative paths for the build RPATH.
2365 This property is initialized by the value of the variable
2367 CMAKE_BUILD_RPATH_USE_ORIGIN.
2368 On platforms that support runtime paths (RPATH) with the $ORIGIN token,
2370 setting this property to TRUE enables relative paths in the build RPATH
2371 for executables and shared libraries that point to shared libraries in
2372 the same build tree.
2373 Normally the build RPATH of a binary contains absolute paths to the di‐
2375 rectory of each shared library it links to. The RPATH entries for di‐
2376 rectories contained within the build tree can be made relative to en‐
2377 able relocatable builds and to help achieve reproducible builds by
2378 omitting the build directory from the build environment.
2379 This property has no effect on platforms that do not support the $ORI‐
2381 GIN token in RPATH, or when the CMAKE_SKIP_RPATH variable is set. The
2382 runtime path set through the BUILD_RPATH target property is also unaf‐
2383 fected by this property.
2384 BUILD_WITH_INSTALL_NAME_DIR
2386 New in version 3.9.
2387 BUILD_WITH_INSTALL_NAME_DIR is a boolean specifying whether the macOS
2390 install_name of a target in the build tree uses the directory given by
2391 INSTALL_NAME_DIR. This setting only applies to targets on macOS.
2392 This property is initialized by the value of the variable
2394 CMAKE_BUILD_WITH_INSTALL_NAME_DIR if it is set when a target is cre‐
2395 ated.
2396 If this property is not set and policy CMP0068 is not NEW, the value of
2398 BUILD_WITH_INSTALL_RPATH is used in its place.
2399 BUILD_WITH_INSTALL_RPATH
2401 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
2402 target in the build tree with the INSTALL_RPATH. This takes precedence
2403 over SKIP_BUILD_RPATH and avoids the need for relinking before instal‐
2404 lation.
2405 This property is initialized by the value of the
2407 CMAKE_BUILD_WITH_INSTALL_RPATH variable if it is set when a target is
2408 created.
2409 If policy CMP0068 is not NEW, this property also controls use of
2411 INSTALL_NAME_DIR in the build tree on macOS. Either way, the
2412 BUILD_WITH_INSTALL_NAME_DIR target property takes precedence.
2413 BUNDLE
2415 This target is a CFBundle on the macOS.
2416 If a module library target has this property set to true it will be
2418 built as a CFBundle when built on the mac. It will have the directory
2419 structure required for a CFBundle and will be suitable to be used for
2420 creating Browser Plugins or other application resources.
2421 BUNDLE_EXTENSION
2423 The file extension used to name a BUNDLE, a FRAMEWORK, or a
2424 MACOSX_BUNDLE target on the macOS and iOS.
2425 The default value is bundle, framework, or app for the respective tar‐
2427 get types.
2428 C_EXTENSIONS
2430 New in version 3.1.
2431 Boolean specifying whether compiler specific extensions are requested.
2434 This property specifies whether compiler specific extensions should be
2436 used. For some compilers, this results in adding a flag such as
2437 -std=gnu11 instead of -std=c11 to the compile line. This property is
2438 ON by default. The basic C standard level is controlled by the
2439 C_STANDARD target property.
2440 See the cmake-compile-features(7) manual for information on compile
2442 features and a list of supported compilers.
2443 This property is initialized by the value of the CMAKE_C_EXTENSIONS
2445 variable if set when a target is created and otherwise by the value of
2446 CMAKE_C_EXTENSIONS_DEFAULT (see CMP0128).
2447 C_STANDARD
2449 New in version 3.1.
2450 The C standard whose features are requested to build this target.
2453 This property specifies the C standard whose features are requested to
2455 build this target. For some compilers, this results in adding a flag
2456 such as -std=gnu11 to the compile line. For compilers that have no no‐
2457 tion of a C standard level, such as Microsoft Visual C++ before VS
2458 16.7, this property has no effect.
2459 Supported values are:
2461 90 C89/C90
2463 99 C99
2465 11 C11
2467 17 New in version 3.21.
2469 C17
2472 23 New in version 3.21.
2474 C23
2477 If the value requested does not result in a compile flag being added
2479 for the compiler in use, a previous standard flag will be added in‐
2480 stead. This means that using:
2481 set_property(TARGET tgt PROPERTY C_STANDARD 11)
2483 with a compiler which does not support -std=gnu11 or an equivalent flag
2485 will not result in an error or warning, but will instead add the
2486 -std=gnu99 or -std=gnu90 flag if supported. This "decay" behavior may
2487 be controlled with the C_STANDARD_REQUIRED target property. Addition‐
2488 ally, the C_EXTENSIONS target property may be used to control whether
2489 compiler-specific extensions are enabled on a per-target basis.
2490 See the cmake-compile-features(7) manual for information on compile
2492 features and a list of supported compilers.
2493 This property is initialized by the value of the CMAKE_C_STANDARD vari‐
2495 able if it is set when a target is created.
2496 C_STANDARD_REQUIRED
2498 New in version 3.1.
2499 Boolean describing whether the value of C_STANDARD is a requirement.
2502 If this property is set to ON, then the value of the C_STANDARD target
2504 property is treated as a requirement. If this property is OFF or un‐
2505 set, the C_STANDARD target property is treated as optional and may "de‐
2506 cay" to a previous standard if the requested is not available. For
2507 compilers that have no notion of a C standard level, such as Microsoft
2508 Visual C++ before VS 16.7, this property has no effect.
2509 See the cmake-compile-features(7) manual for information on compile
2511 features and a list of supported compilers.
2512 This property is initialized by the value of the
2514 CMAKE_C_STANDARD_REQUIRED variable if it is set when a target is cre‐
2515 ated.
2516 COMMON_LANGUAGE_RUNTIME
2518 New in version 3.12.
2519 By setting this target property, the target is configured to build with
2522 C++/CLI support.
2523 The Visual Studio generator defines the clr parameter depending on the
2525 value of COMMON_LANGUAGE_RUNTIME:
2526 • property not set: native C++ (i.e. default)
2528 • property set but empty: mixed unmanaged/managed C++
2530 • property set to any non empty value: managed C++
2532 Supported values: "", "pure", "safe"
2534 This property is only evaluated Visual Studio Generators for VS 2010
2536 and above.
2537 To be able to build managed C++ targets with VS 2017 and above the com‐
2539 ponent C++/CLI support must be installed, which may not be done by de‐
2540 fault.
2541 See also IMPORTED_COMMON_LANGUAGE_RUNTIME
2543 COMPATIBLE_INTERFACE_BOOL
2545 Properties which must be compatible with their link interface
2546 The COMPATIBLE_INTERFACE_BOOL property may contain a list of properties
2548 for this target which must be consistent when evaluated as a boolean
2549 with the INTERFACE variant of the property in all linked dependees.
2550 For example, if a property FOO appears in the list, then for each de‐
2551 pendee, the INTERFACE_FOO property content in all of its dependencies
2552 must be consistent with each other, and with the FOO property in the
2553 depender.
2554 Consistency in this sense has the meaning that if the property is set,
2556 then it must have the same boolean value as all others, and if the
2557 property is not set, then it is ignored.
2558 Note that for each dependee, the set of properties specified in this
2560 property must not intersect with the set specified in any of the other
2561 Compatible Interface Properties.
2562 COMPATIBLE_INTERFACE_NUMBER_MAX
2564 Properties whose maximum value from the link interface will be used.
2565 The COMPATIBLE_INTERFACE_NUMBER_MAX property may contain a list of
2567 properties for this target whose maximum value may be read at generate
2568 time when evaluated in the INTERFACE variant of the property in all
2569 linked dependees. For example, if a property FOO appears in the list,
2570 then for each dependee, the INTERFACE_FOO property content in all of
2571 its dependencies will be compared with each other and with the FOO
2572 property in the depender. When reading the FOO property at generate
2573 time, the maximum value will be returned. If the property is not set,
2574 then it is ignored.
2575 Note that for each dependee, the set of properties specified in this
2577 property must not intersect with the set specified in any of the other
2578 Compatible Interface Properties.
2579 COMPATIBLE_INTERFACE_NUMBER_MIN
2581 Properties whose maximum value from the link interface will be used.
2582 The COMPATIBLE_INTERFACE_NUMBER_MIN property may contain a list of
2584 properties for this target whose minimum value may be read at generate
2585 time when evaluated in the INTERFACE variant of the property of all
2586 linked dependees. For example, if a property FOO appears in the list,
2587 then for each dependee, the INTERFACE_FOO property content in all of
2588 its dependencies will be compared with each other and with the FOO
2589 property in the depender. When reading the FOO property at generate
2590 time, the minimum value will be returned. If the property is not set,
2591 then it is ignored.
2592 Note that for each dependee, the set of properties specified in this
2594 property must not intersect with the set specified in any of the other
2595 Compatible Interface Properties.
2596 COMPATIBLE_INTERFACE_STRING
2598 Properties which must be string-compatible with their link interface
2599 The COMPATIBLE_INTERFACE_STRING property may contain a list of proper‐
2601 ties for this target which must be the same when evaluated as a string
2602 in the INTERFACE variant of the property all linked dependees. For ex‐
2603 ample, if a property FOO appears in the list, then for each dependee,
2604 the INTERFACE_FOO property content in all of its dependencies must be
2605 equal with each other, and with the FOO property in the depender. If
2606 the property is not set, then it is ignored.
2607 Note that for each dependee, the set of properties specified in this
2609 property must not intersect with the set specified in any of the other
2610 Compatible Interface Properties.
2611 COMPILE_DEFINITIONS
2613 Preprocessor definitions for compiling a target's sources.
2614 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
2616 list of preprocessor definitions using the syntax VAR or VAR=value.
2617 Function-style definitions are not supported. CMake will automatically
2618 escape the value correctly for the native build system (note that CMake
2619 language syntax may require escapes to specify some values).
2620 CMake will automatically drop some definitions that are not supported
2622 by the native build tool.
2623 Disclaimer: Most native build tools have poor support for escaping cer‐
2625 tain values. CMake has work-arounds for many cases but some values may
2626 just not be possible to pass correctly. If a value does not seem to be
2627 escaped correctly, do not attempt to work-around the problem by adding
2628 escape sequences to the value. Your work-around may break in a future
2629 version of CMake that has improved escape support. Instead consider
2630 defining the macro in a (configured) header file. Then report the lim‐
2631 itation. Known limitations include:
2632 # - broken almost everywhere
2634 ; - broken in VS IDE 7.0 and Borland Makefiles
2635 , - broken in VS IDE
2636 % - broken in some cases in NMake
2637 & | - broken in some cases on MinGW
2638 ^ < > \" - broken in most Make tools on Windows
2639 CMake does not reject these values outright because they do work in
2641 some cases. Use with caution.
2642 Contents of COMPILE_DEFINITIONS may use "generator expressions" with
2644 the syntax $<...>. See the cmake-generator-expressions(7) manual for
2645 available expressions. See the cmake-buildsystem(7) manual for more on
2646 defining buildsystem properties.
2647 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
2649 specify per-configuration definitions. Generator expressions should be
2650 preferred instead of setting the alternative property.
2651 COMPILE_FEATURES
2653 New in version 3.1.
2654 Compiler features enabled for this target.
2657 The list of features in this property are a subset of the features
2659 listed in the CMAKE_C_COMPILE_FEATURES, CMAKE_CUDA_COMPILE_FEATURES,
2660 and CMAKE_CXX_COMPILE_FEATURES variables.
2661 Contents of COMPILE_FEATURES may use "generator expressions" with the
2663 syntax $<...>. See the cmake-generator-expressions(7) manual for
2664 available expressions. See the cmake-compile-features(7) manual for
2665 information on compile features and a list of supported compilers.
2666 COMPILE_FLAGS
2668 Additional flags to use when compiling this target's sources.
2669 The COMPILE_FLAGS property sets additional compiler flags used to build
2671 sources within the target. Use COMPILE_DEFINITIONS to pass additional
2672 preprocessor definitions.
2673 This property is deprecated. Use the COMPILE_OPTIONS property or the
2675 target_compile_options() command instead.
2676 COMPILE_OPTIONS
2678 List of options to pass to the compiler.
2679 This property holds a semicolon-separated list of options specified so
2681 far for its target. Use the target_compile_options() command to append
2682 more options. The options will be added after after flags in the
2683 CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> variables, but be‐
2684 fore those propagated from dependencies by the
2685 INTERFACE_COMPILE_OPTIONS property.
2686 This property is initialized by the COMPILE_OPTIONS directory property
2688 when a target is created, and is used by the generators to set the op‐
2689 tions for the compiler.
2690 Contents of COMPILE_OPTIONS may use "generator expressions" with the
2692 syntax $<...>. See the cmake-generator-expressions(7) manual for
2693 available expressions. See the cmake-buildsystem(7) manual for more on
2694 defining buildsystem properties.
2695 Option De-duplication
2697 The final set of options used for a target is constructed by accumulat‐
2698 ing options from the current target and the usage requirements of its
2699 dependencies. The set of options is de-duplicated to avoid repetition.
2700 New in version 3.12: While beneficial for individual options, the
2702 de-duplication step can break up option groups. For example, -option A
2703 -option B becomes -option A B. One may specify a group of options us‐
2704 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
2705 is dropped, and the rest of the option string is parsed using the
2706 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
2707 "SHELL:-option B" becomes -option A -option B.
2708 COMPILE_PDB_NAME
2711 New in version 3.1.
2712 Output name for the MS debug symbol .pdb file generated by the compiler
2715 while building source files.
2716 This property specifies the base name for the debug symbols file. If
2718 not set, the default is unspecified.
2719 NOTE:
2721 The compiler-generated program database files are specified by the
2722 /Fd compiler flag and are not the same as linker-generated program
2723 database files specified by the /pdb linker flag. Use the PDB_NAME
2724 property to specify the latter.
2725 COMPILE_PDB_NAME_<CONFIG>
2727 New in version 3.1.
2728 Per-configuration output name for the MS debug symbol .pdb file gener‐
2731 ated by the compiler while building source files.
2732 This is the configuration-specific version of COMPILE_PDB_NAME.
2734 NOTE:
2736 The compiler-generated program database files are specified by the
2737 /Fd compiler flag and are not the same as linker-generated program
2738 database files specified by the /pdb linker flag. Use the
2739 PDB_NAME_<CONFIG> property to specify the latter.
2740 COMPILE_PDB_OUTPUT_DIRECTORY
2742 New in version 3.1.
2743 Output directory for the MS debug symbol .pdb file generated by the
2746 compiler while building source files.
2747 This property specifies the directory into which the MS debug symbols
2749 will be placed by the compiler. This property is initialized by the
2750 value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY variable if it is set
2751 when a target is created.
2752 NOTE:
2754 The compiler-generated program database files are specified by the
2755 /Fd compiler flag and are not the same as linker-generated program
2756 database files specified by the /pdb linker flag. Use the
2757 PDB_OUTPUT_DIRECTORY property to specify the latter.
2758 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
2760 New in version 3.1.
2761 Per-configuration output directory for the MS debug symbol .pdb file
2764 generated by the compiler while building source files.
2765 This is a per-configuration version of COMPILE_PDB_OUTPUT_DIRECTORY,
2767 but multi-configuration generators (Visual Studio, Xcode) do NOT append
2768 a per-configuration subdirectory to the specified directory. This
2769 property is initialized by the value of the
2770 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when
2771 a target is created.
2772 NOTE:
2774 The compiler-generated program database files are specified by the
2775 /Fd compiler flag and are not the same as linker-generated program
2776 database files specified by the /pdb linker flag. Use the
2777 PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the latter.
2778 COMPILE_WARNING_AS_ERROR
2780 New in version 3.24.
2781 Specify whether to treat warnings on compile as errors. If enabled,
2784 adds a flag to treat warnings on compile as errors. If the cmake
2785 --compile-no-warning-as-error option is given on the cmake(1) command
2786 line, this property is ignored.
2787 This property is not implemented for all compilers. It is silently ig‐
2789 nored if there is no implementation for the compiler being used. The
2790 currently implemented compiler IDs are:
2791 • GNU
2793 • Clang
2795 • AppleClang
2797 • Fujitsu
2799 • FujitsuClang
2801 • IBMClang
2803 • Intel
2805 • IntelLLVM
2807 • LCC
2809 • MSVC
2811 • NVHPC
2813 • NVIDIA (CUDA)
2815 • QCC
2817 • SunPro
2819 • Tasking
2821 • TI
2823 • VisualAge
2825 • XL
2827 • XLClang
2829 This property is initialized by the value of the variable
2831 CMAKE_COMPILE_WARNING_AS_ERROR if it is set when a target is created.
2832 <CONFIG>_OUTPUT_NAME
2834 Old per-configuration target file base name. Use OUTPUT_NAME_<CONFIG>
2835 instead.
2836 This is a configuration-specific version of the OUTPUT_NAME target
2838 property.
2839 <CONFIG>_POSTFIX
2841 Postfix to append to the target file name for configuration <CONFIG>.
2842 When building with configuration <CONFIG> the value of this property is
2844 appended to the target file name built on disk. For non-executable
2845 targets, this property is initialized by the value of the
2846 CMAKE_<CONFIG>_POSTFIX variable if it is set when a target is created.
2847 This property is ignored on macOS for Frameworks and App Bundles.
2848 For macOS see also the FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target
2850 property.
2851 CROSSCOMPILING_EMULATOR
2853 New in version 3.3.
2854 Use the given emulator to run executables created when crosscompiling.
2857 This command will be added as a prefix to add_test(),
2858 add_custom_command(), and add_custom_target() commands for built target
2859 system executables.
2860 New in version 3.15: If this property contains a semicolon-separated
2862 list, then the first value is the command and remaining values are its
2863 arguments.
2864 This property is initialized by the value of the
2867 CMAKE_CROSSCOMPILING_EMULATOR variable if it is set when a target is
2868 created.
2869 CUDA_ARCHITECTURES
2871 New in version 3.18.
2872 List of architectures to generate device code for.
2875 An architecture can be suffixed by either -real or -virtual to specify
2877 the kind of architecture to generate code for. If no suffix is given
2878 then code is generated for both real and virtual architectures.
2879 A non-empty false value (e.g. OFF) disables adding architectures. This
2881 is intended to support packagers and rare cases where full control over
2882 the passed flags is required.
2883 This property is initialized by the value of the
2885 CMAKE_CUDA_ARCHITECTURES variable if it is set when a target is cre‐
2886 ated.
2887 The CUDA_ARCHITECTURES target property must be set to a non-empty value
2889 on targets that compile CUDA sources, or it is an error. See policy
2890 CMP0104.
2891 The CUDA_ARCHITECTURES may be set to one of the following special val‐
2893 ues:
2894 all New in version 3.23.
2896 Compile for all supported major and minor real architectures,
2899 and the highest major virtual architecture.
2900 all-major
2902 New in version 3.23.
2903 Compile for all supported major real architectures, and the
2906 highest major virtual architecture.
2907 native New in version 3.24.
2909 Compile for the architecture(s) of the host's GPU(s).
2912 Examples
2914 set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72")
2915 Generates code for real and virtual architectures 30, 50 and 72.
2917 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
2919 Generates code for real architecture 70 and virtual architecture 72.
2921 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)
2923 CMake will not pass any architecture flags to the compiler.
2925 CUDA_EXTENSIONS
2927 New in version 3.8.
2928 Boolean specifying whether compiler specific extensions are requested.
2931 This property specifies whether compiler specific extensions should be
2933 used. For some compilers, this results in adding a flag such as
2934 -std=gnu++11 instead of -std=c++11 to the compile line. This property
2935 is ON by default. The basic CUDA/C++ standard level is controlled by
2936 the CUDA_STANDARD target property.
2937 See the cmake-compile-features(7) manual for information on compile
2939 features and a list of supported compilers.
2940 This property is initialized by the value of the CMAKE_CUDA_EXTENSIONS
2942 variable if set when a target is created and otherwise by the value of
2943 CMAKE_CUDA_EXTENSIONS_DEFAULT (see CMP0128).
2944 CUDA_PTX_COMPILATION
2946 New in version 3.9.
2947 Compile CUDA sources to .ptx files instead of .obj files within Object
2950 Libraries.
2951 For example:
2953 add_library(myptx OBJECT a.cu b.cu)
2955 set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)
2956 CUDA_RESOLVE_DEVICE_SYMBOLS
2958 New in version 3.9.
2959 CUDA only: Enables device linking for the specific library target where
2962 required.
2963 If set, this will tell the required compilers to enable device linking
2965 on the library target. Device linking is an additional link step re‐
2966 quired by some CUDA compilers when CUDA_SEPARABLE_COMPILATION is en‐
2967 abled. Normally device linking is deferred until a shared library or
2968 executable is generated, allowing for multiple static libraries to re‐
2969 solve device symbols at the same time when they are used by a shared
2970 library or executable.
2971 By default static library targets have this property is disabled, while
2973 shared, module, and executable targets have this property enabled.
2974 Note that device linking is not supported for Object Libraries.
2976 For instance:
2978 set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
2980 CUDA_RUNTIME_LIBRARY
2982 New in version 3.17.
2983 Select the CUDA runtime library for use by compilers targeting the CUDA
2986 language.
2987 The allowed case insensitive values are:
2989 None Link with -cudart=none or equivalent flag(s) to use no CUDA run‐
2991 time library.
2992 Shared Link with -cudart=shared or equivalent flag(s) to use a dynami‐
2994 cally-linked CUDA runtime library.
2995 Static Link with -cudart=static or equivalent flag(s) to use a stati‐
2997 cally-linked CUDA runtime library.
2998 Contents of CUDA_RUNTIME_LIBRARY may use generator expressions.
3000 If that property is not set then CMake uses an appropriate default
3002 value based on the compiler to select the CUDA runtime library.
3003 NOTE:
3005 This property has effect only when the CUDA language is enabled. To
3006 control the CUDA runtime linking when only using the CUDA SDK with
3007 the C or C++ language we recommend using the FindCUDAToolkit module.
3008 CUDA_SEPARABLE_COMPILATION
3010 New in version 3.8.
3011 CUDA only: Enables separate compilation of device code
3014 If set this will enable separable compilation for all CUDA files for
3016 the given target.
3017 For instance:
3019 set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)
3021 This property is initialized by the value of the
3023 CMAKE_CUDA_SEPARABLE_COMPILATION variable if it is set when a target is
3024 created.
3025 CUDA_STANDARD
3027 New in version 3.8.
3028 The CUDA/C++ standard whose features are requested to build this tar‐
3031 get.
3032 This property specifies the CUDA/C++ standard whose features are re‐
3034 quested to build this target. For some compilers, this results in
3035 adding a flag such as -std=gnu++11 to the compile line.
3036 Supported values are:
3038 98 CUDA C++98. Note that this maps to the same as 03 internally.
3040 03 CUDA C++03
3042 11 CUDA C++11
3044 14 CUDA C++14. While CMake 3.8 and later recognize 14 as a valid
3046 value, CMake 3.9 was the first version to include support for
3047 any compiler.
3048 17 CUDA C++17. While CMake 3.8 and later recognize 17 as a valid
3050 value, CMake 3.18 was the first version to include support for
3051 any compiler.
3052 20 New in version 3.12.
3054 CUDA C++20. While CMake 3.12 and later recognize 20 as a valid
3057 value, CMake 3.18 was the first version to include support for
3058 any compiler.
3059 23 New in version 3.20.
3061 CUDA C++23
3064 26 New in version 3.25.
3066 CUDA C++26. CMake 3.25 and later recognize 26 as a valid value,
3069 no version has support for any compiler.
3070 If the value requested does not result in a compile flag being added
3072 for the compiler in use, a previous standard flag will be added in‐
3073 stead. This means that using:
3074 set_property(TARGET tgt PROPERTY CUDA_STANDARD 11)
3076 with a compiler which does not support -std=gnu++11 or an equivalent
3078 flag will not result in an error or warning, but will instead add the
3079 -std=gnu++03 flag if supported. This "decay" behavior may be con‐
3080 trolled with the CUDA_STANDARD_REQUIRED target property. Additionally,
3081 the CUDA_EXTENSIONS target property may be used to control whether com‐
3082 piler-specific extensions are enabled on a per-target basis.
3083 See the cmake-compile-features(7) manual for information on compile
3085 features and a list of supported compilers.
3086 This property is initialized by the value of the CMAKE_CUDA_STANDARD
3088 variable if it is set when a target is created.
3089 CUDA_STANDARD_REQUIRED
3091 New in version 3.8.
3092 Boolean describing whether the value of CUDA_STANDARD is a requirement.
3095 If this property is set to ON, then the value of the CUDA_STANDARD tar‐
3097 get property is treated as a requirement. If this property is OFF or
3098 unset, the CUDA_STANDARD target property is treated as optional and may
3099 "decay" to a previous standard if the requested is not available. For
3100 compilers that have no notion of a standard level, such as MSVC 1800
3101 (Visual Studio 2013) and lower, this has no effect.
3102 See the cmake-compile-features(7) manual for information on compile
3104 features and a list of supported compilers.
3105 This property is initialized by the value of the
3107 CMAKE_CUDA_STANDARD_REQUIRED variable if it is set when a target is
3108 created.
3109 CXX_EXTENSIONS
3111 New in version 3.1.
3112 Boolean specifying whether compiler specific extensions are requested.
3115 This property specifies whether compiler specific extensions should be
3117 used. For some compilers, this results in adding a flag such as
3118 -std=gnu++11 instead of -std=c++11 to the compile line. This property
3119 is ON by default. The basic C++ standard level is controlled by the
3120 CXX_STANDARD target property.
3121 See the cmake-compile-features(7) manual for information on compile
3123 features and a list of supported compilers.
3124 This property is initialized by the value of the CMAKE_CXX_EXTENSIONS
3126 variable if set when a target is created and otherwise by the value of
3127 CMAKE_CXX_EXTENSIONS_DEFAULT (see CMP0128).
3128 CXX_MODULE_DIRS
3130 New in version 3.25.
3131 NOTE:
3134 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3135 Semicolon-separated list of base directories of the target's default
3137 C++ module set (i.e. the file set with name and type CXX_MODULES). The
3138 property supports generator expressions.
3139 This property is normally only set by target_sources(FILE_SET) rather
3141 than being manipulated directly.
3142 See CXX_MODULE_DIRS_<NAME> for the list of base directories in other
3144 C++ module sets.
3145 CXX_MODULE_DIRS_<NAME>
3147 New in version 3.25.
3148 NOTE:
3151 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3152 Semicolon-separated list of base directories of the target's <NAME> C++
3154 module set, which has the set type CXX_MODULES. The property supports
3155 generator expressions.
3156 This property is normally only set by target_sources(FILE_SET) rather
3158 than being manipulated directly.
3159 See CXX_MODULE_DIRS for the list of base directories in the default C++
3161 module set. See CXX_MODULE_SETS for the file set names of all C++ mod‐
3162 ule sets.
3163 CXX_MODULE_HEADER_UNIT_DIRS
3165 New in version 3.25.
3166 NOTE:
3169 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3170 Semicolon-separated list of base directories of the target's default
3172 C++ module header set (i.e. the file set with name and type CXX_MOD‐
3173 ULE_HEADER_UNITS). The property supports generator expressions.
3174 This property is normally only set by target_sources(FILE_SET) rather
3176 than being manipulated directly.
3177 See CXX_MODULE_HEADER_UNIT_DIRS_<NAME> for the list of base directories
3179 in other C++ module header sets.
3180 CXX_MODULE_HEADER_UNIT_DIRS_<NAME>
3182 New in version 3.25.
3183 NOTE:
3186 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3187 Semicolon-separated list of base directories of the target's <NAME> C++
3189 module header set, which has the set type CXX_MODULE_HEADER_UNITS. The
3190 property supports generator expressions.
3191 This property is normally only set by target_sources(FILE_SET) rather
3193 than being manipulated directly.
3194 See CXX_MODULE_HEADER_UNIT_DIRS for the list of base directories in the
3196 default C++ module header set. See CXX_MODULE_HEADER_UNIT_SETS for the
3197 file set names of all C++ module header sets.
3198 CXX_MODULE_HEADER_UNIT_SET
3200 New in version 3.25.
3201 NOTE:
3204 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3205 Semicolon-separated list of files in the target's default C++ module
3207 header set, (i.e. the file set with name and type CXX_MOD‐
3208 ULE_HEADER_UNITS). If any of the paths are relative, they are computed
3209 relative to the target's source directory. The property supports
3210 generator expressions.
3211 This property is normally only set by target_sources(FILE_SET) rather
3213 than being manipulated directly.
3214 See CXX_MODULE_HEADER_UNIT_SET_<NAME> for the list of files in other
3216 C++ module header sets.
3217 CXX_MODULE_HEADER_UNIT_SET_<NAME>
3219 New in version 3.25.
3220 NOTE:
3223 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3224 Semicolon-separated list of files in the target's <NAME> C++ module
3226 header set, which has the set type CXX_MODULE_HEADER_UNITS. If any of
3227 the paths are relative, they are computed relative to the target's
3228 source directory. The property supports generator expressions.
3229 This property is normally only set by target_sources(FILE_SET) rather
3231 than being manipulated directly.
3232 See CXX_MODULE_HEADER_UNIT_SET for the list of files in the default C++
3234 module header set. See CXX_MODULE_HEADER_UNIT_SETS for the file set
3235 names of all C++ module header sets.
3236 CXX_MODULE_HEADER_UNIT_SETS
3238 New in version 3.25.
3239 NOTE:
3242 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3243 Read-only list of the target's PRIVATE and PUBLIC C++ module header
3245 sets (i.e. all file sets with the type CXX_MODULE_HEADER_UNITS). Files
3246 listed in these file sets are treated as source files for the purpose
3247 of IDE integration.
3248 C++ module header sets may be defined using the target_sources() com‐
3250 mand FILE_SET option with type CXX_MODULE_HEADER_UNITS.
3251 See also CXX_MODULE_HEADER_UNIT_SET_<NAME>, CXX_MODULE_HEADER_UNIT_SET
3253 and INTERFACE_CXX_MODULE_HEADER_UNIT_SETS.
3254 CXX_MODULE_SET
3256 New in version 3.25.
3257 NOTE:
3260 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3261 Semicolon-separated list of files in the target's default C++ module
3263 set, (i.e. the file set with name and type CXX_MODULES). If any of the
3264 paths are relative, they are computed relative to the target's source
3265 directory. The property supports generator expressions.
3266 This property is normally only set by target_sources(FILE_SET) rather
3268 than being manipulated directly.
3269 See CXX_MODULE_SET_<NAME> for the list of files in other C++ module
3271 sets.
3272 CXX_MODULE_SET_<NAME>
3274 New in version 3.25.
3275 NOTE:
3278 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3279 Semicolon-separated list of files in the target's <NAME> C++ module
3281 set, which has the set type CXX_MODULES. If any of the paths are rela‐
3282 tive, they are computed relative to the target's source directory. The
3283 property supports generator expressions.
3284 This property is normally only set by target_sources(FILE_SET) rather
3286 than being manipulated directly.
3287 See CXX_MODULE_SET for the list of files in the default C++ module set.
3289 See CXX_MODULE_SETS for the file set names of all C++ module sets.
3290 CXX_MODULE_SETS
3292 New in version 3.25.
3293 NOTE:
3296 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3297 Read-only list of the target's PRIVATE and PUBLIC C++ module sets (i.e.
3299 all file sets with the type CXX_MODULES). Files listed in these file
3300 sets are treated as source files for the purpose of IDE integration.
3301 C++ module sets may be defined using the target_sources() command
3303 FILE_SET option with type CXX_MODULES.
3304 See also CXX_MODULE_SET_<NAME>, CXX_MODULE_SET and
3306 INTERFACE_CXX_MODULE_SETS.
3307 CXX_STANDARD
3309 New in version 3.1.
3310 The C++ standard whose features are requested to build this target.
3313 This property specifies the C++ standard whose features are requested
3315 to build this target. For some compilers, this results in adding a
3316 flag such as -std=gnu++11 to the compile line. For compilers that have
3317 no notion of a standard level, such as Microsoft Visual C++ before 2015
3318 Update 3, this has no effect.
3319 Supported values are:
3321 98 C++98
3323 11 C++11
3325 14 C++14
3327 17 New in version 3.8.
3329 C++17
3332 20 New in version 3.12.
3334 C++20
3337 23 New in version 3.20.
3339 C++23
3342 26 New in version 3.25.
3344 C++26. CMake 3.25 and later recognize 26 as a valid value, no
3347 version has support for any compiler.
3348 If the value requested does not result in a compile flag being added
3350 for the compiler in use, a previous standard flag will be added in‐
3351 stead. This means that using:
3352 set_property(TARGET tgt PROPERTY CXX_STANDARD 11)
3354 with a compiler which does not support -std=gnu++11 or an equivalent
3356 flag will not result in an error or warning, but will instead add the
3357 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
3358 trolled with the CXX_STANDARD_REQUIRED target property. Additionally,
3359 the CXX_EXTENSIONS target property may be used to control whether com‐
3360 piler-specific extensions are enabled on a per-target basis.
3361 See the cmake-compile-features(7) manual for information on compile
3363 features and a list of supported compilers.
3364 This property is initialized by the value of the CMAKE_CXX_STANDARD
3366 variable if it is set when a target is created.
3367 CXX_STANDARD_REQUIRED
3369 New in version 3.1.
3370 Boolean describing whether the value of CXX_STANDARD is a requirement.
3373 If this property is set to ON, then the value of the CXX_STANDARD tar‐
3375 get property is treated as a requirement. If this property is OFF or
3376 unset, the CXX_STANDARD target property is treated as optional and may
3377 "decay" to a previous standard if the requested is not available. For
3378 compilers that have no notion of a standard level, such as MSVC 1800
3379 (Visual Studio 2013) and lower, this has no effect.
3380 See the cmake-compile-features(7) manual for information on compile
3382 features and a list of supported compilers.
3383 This property is initialized by the value of the
3385 CMAKE_CXX_STANDARD_REQUIRED variable if it is set when a target is cre‐
3386 ated.
3387 DEBUG_POSTFIX
3389 See target property <CONFIG>_POSTFIX.
3390 This property is a special case of the more-general <CONFIG>_POSTFIX
3392 property for the DEBUG configuration.
3393 DEFINE_SYMBOL
3395 Define a symbol when compiling this target's sources.
3396 DEFINE_SYMBOL sets the name of the preprocessor symbol defined when
3398 compiling sources in a shared library. If not set here then it is set
3399 to target_EXPORTS by default (with some substitutions if the target is
3400 not a valid C identifier). This is useful for headers to know whether
3401 they are being included from inside their library or outside to prop‐
3402 erly setup dllexport/dllimport decorations.
3403 DEPLOYMENT_ADDITIONAL_FILES
3405 New in version 3.13.
3406 Set the WinCE project AdditionalFiles in DeploymentTool in .vcproj
3409 files generated by the Visual Studio 9 2008 generator. This is useful
3410 when you want to debug on remote WinCE device. Specify additional
3411 files that will be copied to the device. For example:
3412 set_property(TARGET ${TARGET} PROPERTY
3414 DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0"
3415 "german.lng|local_folder|remote_folder|0")
3416 produces:
3418 <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... />
3420 DEPLOYMENT_REMOTE_DIRECTORY
3422 New in version 3.6.
3423 Set the WinCE project RemoteDirectory in DeploymentTool and RemoteExe‐
3426 cutable in DebuggerTool in .vcproj files generated by the Visual Studio
3427 9 2008 generator. This is useful when you want to debug on remote
3428 WinCE device. For example:
3429 set_property(TARGET ${TARGET} PROPERTY
3431 DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage")
3432 produces:
3434 <DeploymentTool RemoteDirectory="\FlashStorage" ... />
3436 <DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... />
3437 DEPRECATION
3439 New in version 3.17.
3440 Deprecation message from imported target's developer.
3443 DEPRECATION is the message regarding a deprecation status to be dis‐
3445 played to downstream users of a target.
3446 The message is formatted as follows:
3448 • Lines that do not start in whitespace are wrapped as paragraph text.
3450 • Lines that start in whitespace are preserved as preformatted text.
3452 DISABLE_PRECOMPILE_HEADERS
3454 New in version 3.16.
3455 Disables the precompilation of header files specified by
3458 PRECOMPILE_HEADERS property.
3459 If the property is not set, CMake will use the value provided by
3461 CMAKE_DISABLE_PRECOMPILE_HEADERS.
3462 DOTNET_SDK
3464 New in version 3.23.
3465 Specify the .NET SDK for C# projects. For example: Microsoft.NET.Sdk.
3468 This property tells Visual Studio Generators for VS 2019 and above to
3470 generate a .NET SDK-style project using the specified SDK. The prop‐
3471 erty is meaningful only to these generators, and only in C# targets.
3472 It is ignored for C++ projects, even if they are managed (e.g. using
3473 COMMON_LANGUAGE_RUNTIME).
3474 This property must be a non-empty string to generate .NET SDK-style
3476 projects. CMake does not perform any validations for the value of the
3477 property.
3478 This property may be initialized for all targets using the
3480 CMAKE_DOTNET_SDK variable.
3481 NOTE:
3483 The Visual Studio Generators in this version of CMake have not yet
3484 learned to support add_custom_command() in .NET SDK-style projects.
3485 It is currently an error to attach a custom command to a target with
3486 the DOTNET_SDK property set.
3487 DOTNET_TARGET_FRAMEWORK
3489 New in version 3.17.
3490 Specify the .NET target framework.
3493 Used to specify the .NET target framework for C++/CLI and C#. For ex‐
3495 ample: netcoreapp2.1.
3496 This property is only evaluated for Visual Studio Generators VS 2010
3498 and above.
3499 Can be initialized for all targets using the variable
3501 CMAKE_DOTNET_TARGET_FRAMEWORK.
3502 DOTNET_TARGET_FRAMEWORK_VERSION
3504 New in version 3.12.
3505 Specify the .NET target framework version.
3508 Used to specify the .NET target framework version for C++/CLI and C#.
3510 For example: v4.5.
3511 This property is only evaluated for Visual Studio Generators VS 2010
3513 and above.
3514 To initialize this variable for all targets set
3516 CMAKE_DOTNET_TARGET_FRAMEWORK or CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.
3517 If both are set, the latter is ignored.
3518 EchoString
3520 A message to be displayed when the target is built.
3521 A message to display on some generators (such as Makefile Generators)
3523 when the target is built.
3524 ENABLE_EXPORTS
3526 Specify whether an executable exports symbols for loadable modules.
3527 Normally an executable does not export any symbols because it is the
3529 final program. It is possible for an executable to export symbols to
3530 be used by loadable modules. When this property is set to true CMake
3531 will allow other targets to "link" to the executable with the
3532 target_link_libraries() command. On all platforms a target-level de‐
3533 pendency on the executable is created for targets that link to it.
3534 Handling of the executable on the link lines of the loadable modules
3535 varies by platform:
3536 • On Windows-based systems (including Cygwin) an "import library" is
3538 created along with the executable to list the exported symbols.
3539 Loadable modules link to the import library to get the symbols.
3540 • On macOS, loadable modules link to the executable itself using the
3542 -bundle_loader flag.
3543 • On AIX, a linker "import file" is created along with the executable
3545 to list the exported symbols for import when linking other targets.
3546 Loadable modules link to the import file to get the symbols.
3547 • On other platforms, loadable modules are simply linked without refer‐
3549 encing the executable since the dynamic loader will automatically
3550 bind symbols when the module is loaded.
3551 This property is initialized by the value of the variable
3553 CMAKE_ENABLE_EXPORTS if it is set when a target is created.
3554 EXCLUDE_FROM_ALL
3556 Set this target property to a true (or false) value to exclude (or in‐
3557 clude) the target from the "all" target of the containing directory and
3558 its ancestors. If excluded, running e.g. make in the containing direc‐
3559 tory or its ancestors will not build the target by default.
3560 If this target property is not set then the target will be included in
3562 the "all" target of the containing directory. Furthermore, it will be
3563 included in the "all" target of its ancestor directories unless the
3564 EXCLUDE_FROM_ALL directory property is set.
3565 With EXCLUDE_FROM_ALL set to false or not set at all, the target will
3567 be brought up to date as part of doing a make install or its equivalent
3568 for the CMake generator being used.
3569 If a target has EXCLUDE_FROM_ALL set to true, it may still be listed in
3571 an install(TARGETS) command, but the user is responsible for ensuring
3572 that the target's build artifacts are not missing or outdated when an
3573 install is performed.
3574 This property may use "generator expressions" with the syntax $<...>.
3576 See the cmake-generator-expressions(7) manual for available expres‐
3577 sions.
3578 Only the "Ninja Multi-Config" generator supports a property value that
3580 varies by configuration. For all other generators the value of this
3581 property must be the same for all configurations.
3582 EXCLUDE_FROM_DEFAULT_BUILD
3584 Exclude target from Build Solution.
3585 This property is only used by Visual Studio generators. When set to
3587 TRUE, the target will not be built when you press Build Solution.
3588 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
3590 Per-configuration version of target exclusion from Build Solution.
3591 This is the configuration-specific version of
3593 EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD
3594 is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes
3595 precedence in configurations for which it has a value.
3596 EXPORT_COMPILE_COMMANDS
3598 New in version 3.20.
3599 Enable/Disable output of compile commands during generation for a tar‐
3602 get.
3603 This property is initialized by the value of the variable
3605 CMAKE_EXPORT_COMPILE_COMMANDS if it is set when a target is created.
3606 EXPORT_NAME
3608 Exported name for target files.
3609 This sets the name for the IMPORTED target generated by the
3611 install(EXPORT) and export() commands. If not set, the logical target
3612 name is used by default.
3613 EXPORT_NO_SYSTEM
3615 New in version 3.25.
3616 This property affects the behavior of the install(EXPORT) and export()
3619 commands when they install or export the target respectively. When EX‐
3620 PORT_NO_SYSTEM is set to true, those commands generate an imported tar‐
3621 get with SYSTEM property set to false.
3622 See the NO_SYSTEM_FROM_IMPORTED target property to set this behavior on
3624 the target consuming the include directories rather than the one pro‐
3625 viding them.
3626 EXPORT_PROPERTIES
3628 New in version 3.12.
3629 List additional properties to export for a target.
3632 This property contains a list of property names that should be exported
3634 by the install(EXPORT) and export() commands. By default only a lim‐
3635 ited number of properties are exported. This property can be used to
3636 additionally export other properties as well.
3637 Properties starting with INTERFACE_ or IMPORTED_ are not allowed as
3639 they are reserved for internal CMake use.
3640 Properties containing generator expressions are also not allowed.
3642 NOTE:
3644 Since CMake 3.19, Interface Libraries may have arbitrary target
3645 properties. If a project exports an interface library with custom
3646 properties, the resulting package may not work with dependents con‐
3647 figured by older versions of CMake that reject the custom proper‐
3648 ties.
3649 FOLDER
3651 Set the folder name. Use to organize targets in an IDE.
3652 Targets with no FOLDER property will appear as top level entities in
3654 IDEs like Visual Studio. Targets with the same FOLDER property value
3655 will appear next to each other in a folder of that name. To nest fold‐
3656 ers, use FOLDER values such as 'GUI/Dialogs' with '/' characters sepa‐
3657 rating folder levels.
3658 This property is initialized by the value of the variable CMAKE_FOLDER
3660 if it is set when a target is created.
3661 Fortran_BUILDING_INSTRINSIC_MODULES
3663 New in version 3.22.
3664 Instructs the CMake Fortran preprocessor that the target is building
3667 Fortran intrinsics for building a Fortran compiler.
3668 This property is off by default and should be turned only on projects
3670 that build a Fortran compiler. It should not be turned on for projects
3671 that use a Fortran compiler.
3672 Turning this property on will correctly add dependencies for building
3674 Fortran intrinsic modules whereas turning the property off will ignore
3675 Fortran intrinsic modules in the dependency graph as they are supplied
3676 by the compiler itself.
3677 Fortran_FORMAT
3679 Set to FIXED or FREE to indicate the Fortran source layout.
3680 This property tells CMake whether the Fortran source files in a target
3682 use fixed-format or free-format. CMake will pass the corresponding
3683 format flag to the compiler. Use the source-specific Fortran_FORMAT
3684 property to change the format of a specific source file. If the vari‐
3685 able CMAKE_Fortran_FORMAT is set when a target is created its value is
3686 used to initialize this property.
3687 Fortran_MODULE_DIRECTORY
3689 Specify output directory for Fortran modules provided by the target.
3690 If the target contains Fortran source files that provide modules and
3692 the compiler supports a module output directory this specifies the di‐
3693 rectory in which the modules will be placed. When this property is not
3694 set the modules will be placed in the build directory corresponding to
3695 the target's source directory. If the variable
3696 CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its
3697 value is used to initialize this property.
3698 When using one of the Visual Studio Generators with the Intel Fortran
3700 plugin installed in Visual Studio, a subdirectory named after the con‐
3701 figuration will be appended to the path where modules are created. For
3702 example, if Fortran_MODULE_DIRECTORY is set to C:/some/path, modules
3703 will end up in C:/some/path/Debug (or C:/some/path/Release etc.) when
3704 an Intel Fortran .vfproj file is generated, and in C:/some/path when
3705 any other generator is used.
3706 Note that some compilers will automatically search the module output
3708 directory for modules USEd during compilation but others will not. If
3709 your sources USE modules their location must be specified by
3710 INCLUDE_DIRECTORIES regardless of this property.
3711 Fortran_PREPROCESS
3713 New in version 3.18.
3714 Control whether the Fortran source file should be unconditionally pre‐
3717 processed.
3718 If unset or empty, rely on the compiler to determine whether the file
3720 should be preprocessed. If explicitly set to OFF then the file does not
3721 need to be preprocessed. If explicitly set to ON, then the file does
3722 need to be preprocessed as part of the compilation step.
3723 When using the Ninja generator, all source files are first preprocessed
3725 in order to generate module dependency information. Setting this prop‐
3726 erty to OFF will make Ninja skip this step.
3727 Use the source-specific Fortran_PREPROCESS property if a single file
3729 needs to be preprocessed. If the variable CMAKE_Fortran_PREPROCESS is
3730 set when a target is created its value is used to initialize this prop‐
3731 erty.
3732 NOTE:
3734 For some compilers, NAG, PGI and Solaris Studio, setting this to OFF
3735 will have no effect.
3736 FRAMEWORK
3738 Build SHARED or STATIC library as Framework Bundle on the macOS and
3739 iOS.
3740 If such a library target has this property set to TRUE it will be built
3742 as a framework when built on the macOS and iOS. It will have the di‐
3743 rectory structure required for a framework and will be suitable to be
3744 used with the -framework option. This property is initialized by the
3745 value of the CMAKE_FRAMEWORK variable if it is set when a target is
3746 created.
3747 To customize Info.plist file in the framework, use
3749 MACOSX_FRAMEWORK_INFO_PLIST target property.
3750 For macOS see also the FRAMEWORK_VERSION target property.
3752 Example of creation dynamicFramework:
3754 add_library(dynamicFramework SHARED
3756 dynamicFramework.c
3757 dynamicFramework.h
3758 )
3759 set_target_properties(dynamicFramework PROPERTIES
3760 FRAMEWORK TRUE
3761 FRAMEWORK_VERSION C
3762 MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework
3763 MACOSX_FRAMEWORK_INFO_PLIST Info.plist
3764 # "current version" in semantic format in Mach-O binary file
3765 VERSION 16.4.0
3766 # "compatibility version" in semantic format in Mach-O binary file
3767 SOVERSION 1.0.0
3768 PUBLIC_HEADER dynamicFramework.h
3769 XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer"
3770 )
3771 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
3773 New in version 3.18.
3774 Postfix to append to the framework file name for configuration <CON‐
3777 FIG>, when using a multi-config generator (like Xcode and Ninja
3778 Multi-Config).
3779 When building with configuration <CONFIG> the value of this property is
3781 appended to the framework file name built on disk.
3782 For example, given a framework called my_fw, a value of _debug for the
3784 FRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG property, and Debug;Release in
3785 CMAKE_CONFIGURATION_TYPES, the following relevant files would be cre‐
3786 ated for the Debug and Release configurations:
3787 • Release/my_fw.framework/my_fw
3789 • Release/my_fw.framework/Versions/A/my_fw
3791 • Debug/my_fw.framework/my_fw_debug
3793 • Debug/my_fw.framework/Versions/A/my_fw_debug
3795 For framework targets, this property is initialized by the value of the
3797 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> variable if it is set
3798 when a target is created.
3799 This property is ignored for non-framework targets, and when using sin‐
3801 gle config generators.
3802 FRAMEWORK_VERSION
3804 New in version 3.4.
3805 Version of a framework created using the FRAMEWORK target property
3808 (e.g. A).
3809 This property only affects macOS, as iOS doesn't have versioned direc‐
3811 tory structure.
3812 GENERATOR_FILE_NAME
3814 Generator's file for this target.
3815 An internal property used by some generators to record the name of the
3817 project or dsp file associated with this target. Note that at config‐
3818 ure time, this property is only set for targets created by
3819 include_external_msproject().
3820 GHS_INTEGRITY_APP
3822 New in version 3.14.
3823 ON / OFF boolean to determine if an executable target should be treated
3826 as an Integrity Application.
3827 If no value is set and if a .int file is added as a source file to the
3829 executable target it will be treated as an Integrity Application.
3830 Supported on Green Hills MULTI.
3832 GHS_NO_SOURCE_GROUP_FILE
3834 New in version 3.14.
3835 ON / OFF boolean to control if the project file for a target should be
3838 one single file or multiple files.
3839 The default behavior or when the property is OFF is to generate a
3841 project file for the target and then a sub-project file for each source
3842 group.
3843 When this property is ON or if CMAKE_GHS_NO_SOURCE_GROUP_FILE is ON
3845 then only a single project file is generated for the target.
3846 Supported on Green Hills MULTI.
3848 GNUtoMS
3850 Convert GNU import library (.dll.a) to MS format (.lib).
3851 When linking a shared library or executable that exports symbols using
3853 GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert
3854 the import library (.dll.a) from GNU to MS format (.lib). Both import
3855 libraries will be installed by install(TARGETS) and exported by
3856 install(EXPORT) and export() to be linked by applications with either
3857 GNU- or MS-compatible tools.
3858 If the variable CMAKE_GNUtoMS is set when a target is created its value
3860 is used to initialize this property. The variable must be set prior to
3861 the first command that enables a language such as project() or
3862 enable_language(). CMake provides the variable as an option to the
3863 user automatically when configuring on Windows with GNU tools.
3864 HAS_CXX
3866 Link the target using the C++ linker tool (obsolete).
3867 This is equivalent to setting the LINKER_LANGUAGE property to CXX.
3869 HEADER_DIRS
3871 New in version 3.23.
3872 Semicolon-separated list of base directories of the target's default
3875 header set (i.e. the file set with name and type HEADERS). The property
3876 supports generator expressions.
3877 This property is normally only set by target_sources(FILE_SET) rather
3879 than being manipulated directly.
3880 See HEADER_DIRS_<NAME> for the list of base directories in other header
3882 sets.
3883 HEADER_DIRS_<NAME>
3885 New in version 3.23.
3886 Semicolon-separated list of base directories of the target's <NAME>
3889 header set, which has the set type HEADERS. The property supports
3890 generator expressions.
3891 This property is normally only set by target_sources(FILE_SET) rather
3893 than being manipulated directly.
3894 See HEADER_DIRS for the list of base directories in the default header
3896 set. See HEADER_SETS for the file set names of all header sets.
3897 HEADER_SET
3899 New in version 3.23.
3900 Semicolon-separated list of files in the target's default header set,
3903 (i.e. the file set with name and type HEADERS). If any of the paths are
3904 relative, they are computed relative to the target's source directory.
3905 The property supports generator expressions.
3906 This property is normally only set by target_sources(FILE_SET) rather
3908 than being manipulated directly.
3909 See HEADER_SET_<NAME> for the list of files in other header sets.
3911 HEADER_SET_<NAME>
3913 New in version 3.23.
3914 Semicolon-separated list of files in the target's <NAME> header set,
3917 which has the set type HEADERS. If any of the paths are relative, they
3918 are computed relative to the target's source directory. The property
3919 supports generator expressions.
3920 This property is normally only set by target_sources(FILE_SET) rather
3922 than being manipulated directly.
3923 See HEADER_SET for the list of files in the default header set. See
3925 HEADER_SETS for the file set names of all header sets.
3926 HEADER_SETS
3928 New in version 3.23.
3929 Read-only list of the target's PRIVATE and PUBLIC header sets (i.e.
3932 all file sets with the type HEADERS). Files listed in these file sets
3933 are treated as source files for the purpose of IDE integration. The
3934 files also have their HEADER_FILE_ONLY property set to TRUE.
3935 Header sets may be defined using the target_sources() command FILE_SET
3937 option with type HEADERS.
3938 See also HEADER_SET_<NAME>, HEADER_SET and INTERFACE_HEADER_SETS.
3940 HIP_ARCHITECTURES
3942 New in version 3.21.
3943 List of AMD GPU architectures to generate device code for.
3946 A non-empty false value (e.g. OFF) disables adding architectures. This
3948 is intended to support packagers and rare cases where full control over
3949 the passed flags is required.
3950 This property is initialized by the value of the
3952 CMAKE_HIP_ARCHITECTURES variable if it is set when a target is created.
3953 The HIP compilation model has two modes: whole and separable. Whole
3955 compilation generates device code at compile time. Separable compila‐
3956 tion generates device code at link time. Therefore the HIP_ARCHITEC‐
3957 TURES target property should be set on targets that compile or link
3958 with any HIP sources.
3959 Examples
3961 set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900)
3962 Generates code for both gfx801 and gfx900.
3964 HIP_EXTENSIONS
3966 New in version 3.21.
3967 Boolean specifying whether compiler specific extensions are requested.
3970 This property specifies whether compiler specific extensions should be
3972 used. For some compilers, this results in adding a flag such as
3973 -std=gnu++11 instead of -std=c++11 to the compile line. This property
3974 is ON by default. The basic HIP/C++ standard level is controlled by the
3975 HIP_STANDARD target property.
3976 See the cmake-compile-features(7) manual for information on compile
3978 features and a list of supported compilers.
3979 This property is initialized by the value of the CMAKE_HIP_EXTENSIONS
3981 variable if set when a target is created and otherwise by the value of
3982 CMAKE_HIP_EXTENSIONS_DEFAULT (see CMP0128).
3983 HIP_STANDARD
3985 New in version 3.21.
3986 The HIP/C++ standard requested to build this target.
3989 Supported values are:
3991 98 HIP C++98
3993 11 HIP C++11
3995 14 HIP C++14
3997 17 HIP C++17
3999 20 HIP C++20
4001 23 HIP C++23
4003 26 New in version 3.25.
4005 HIP C++26. CMake 3.25 and later recognize 26 as a valid value,
4008 no version has support for any compiler.
4009 If the value requested does not result in a compile flag being added
4011 for the compiler in use, a previous standard flag will be added in‐
4012 stead. This means that using:
4013 set_property(TARGET tgt PROPERTY HIP_STANDARD 11)
4015 with a compiler which does not support -std=gnu++11 or an equivalent
4017 flag will not result in an error or warning, but will instead add the
4018 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
4019 trolled with the HIP_STANDARD_REQUIRED target property. Additionally,
4020 the HIP_EXTENSIONS target property may be used to control whether com‐
4021 piler-specific extensions are enabled on a per-target basis.
4022 See the cmake-compile-features(7) manual for information on compile
4024 features and a list of supported compilers.
4025 This property is initialized by the value of the CMAKE_HIP_STANDARD
4027 variable if it is set when a target is created.
4028 HIP_STANDARD_REQUIRED
4030 New in version 3.21.
4031 Boolean describing whether the value of HIP_STANDARD is a requirement.
4034 If this property is set to ON, then the value of the HIP_STANDARD tar‐
4036 get property is treated as a requirement. If this property is OFF or
4037 unset, the HIP_STANDARD target property is treated as optional and may
4038 "decay" to a previous standard if the requested is not available.
4039 See the cmake-compile-features(7) manual for information on compile
4041 features and a list of supported compilers.
4042 This property is initialized by the value of the
4044 CMAKE_HIP_STANDARD_REQUIRED variable if it is set when a target is cre‐
4045 ated.
4046 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
4048 Specify #include line transforms for dependencies in a target.
4049 This property specifies rules to transform macro-like #include lines
4051 during implicit dependency scanning of C and C++ source files. The
4052 list of rules must be semicolon-separated with each entry of the form
4053 A_MACRO(%)=value-with-% (the % must be literal). During dependency
4054 scanning occurrences of A_MACRO(...) on #include lines will be replaced
4055 by the value given with the macro argument substituted for %. For ex‐
4056 ample, the entry
4057 MYDIR(%)=<mydir/%>
4059 will convert lines of the form
4061 #include MYDIR(myheader.h)
4063 to
4065 #include <mydir/myheader.h>
4067 allowing the dependency to be followed.
4069 This property applies to sources in the target on which it is set.
4071 IMPORTED
4073 Read-only indication of whether a target is IMPORTED.
4074 The boolean value of this property is True for targets created with the
4076 IMPORTED option to add_executable() or add_library(). It is False for
4077 targets built within the project.
4078 IMPORTED_COMMON_LANGUAGE_RUNTIME
4080 New in version 3.12.
4081 Property to define if the target uses C++/CLI.
4084 Ignored for non-imported targets.
4086 See also the COMMON_LANGUAGE_RUNTIME target property.
4088 IMPORTED_CONFIGURATIONS
4090 Configurations provided for an IMPORTED target.
4091 Set this to the list of configuration names available for an IMPORTED
4093 target. The names correspond to configurations defined in the project
4094 from which the target is imported. If the importing project uses a
4095 different set of configurations the names may be mapped using the
4096 MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non-imported tar‐
4097 gets.
4098 IMPORTED_GLOBAL
4100 New in version 3.11.
4101 Indication of whether an IMPORTED target is globally visible.
4104 The boolean value of this property is True for targets created with the
4106 IMPORTED GLOBAL options to add_executable() or add_library(). It is al‐
4107 ways False for targets built within the project.
4108 For targets created with the IMPORTED option to add_executable() or
4110 add_library() but without the additional option GLOBAL this is False,
4111 too. However, setting this property for such a locally IMPORTED target
4112 to True promotes that target to global scope. This promotion can only
4113 be done in the same directory where that IMPORTED target was created in
4114 the first place.
4115 NOTE:
4117 Once an imported target has been made global, it cannot be changed
4118 back to non-global. Therefore, if a project sets this property, it
4119 may only provide a value of True. CMake will issue an error if the
4120 project tries to set the property to a non-True value, even if the
4121 value was already False.
4122 NOTE:
4124 Local ALIAS targets created before promoting an IMPORTED target from
4125 LOCAL to GLOBAL, keep their initial scope (see ALIAS_GLOBAL target
4126 property).
4127 IMPORTED_IMPLIB
4129 Full path to the import library for an IMPORTED target.
4130 Set this to the location of the .lib part of a Windows DLL, or on AIX
4132 set it to an import file created for executables that export symbols
4133 (see the ENABLE_EXPORTS target property). Ignored for non-imported
4134 targets.
4135 IMPORTED_IMPLIB_<CONFIG>
4137 <CONFIG>-specific version of IMPORTED_IMPLIB property.
4138 Configuration names correspond to those provided by the project from
4140 which the target is imported.
4141 IMPORTED_LIBNAME
4143 New in version 3.8.
4144 Specify the link library name for an imported Interface Library.
4147 An interface library builds no library file itself but does specify us‐
4149 age requirements for its consumers. The IMPORTED_LIBNAME property may
4150 be set to specify a single library name to be placed on the link line
4151 in place of the interface library target name as a requirement for us‐
4152 ing the interface.
4153 This property is intended for use in naming libraries provided by a
4155 platform SDK for which the full path to a library file may not be
4156 known. The value may be a plain library name such as foo but may not
4157 be a path (e.g. /usr/lib/libfoo.so) or a flag (e.g. -Wl,...). The name
4158 is never treated as a library target name even if it happens to name
4159 one.
4160 The IMPORTED_LIBNAME property is allowed only on imported Interface Li‐
4162 braries and is rejected on targets of other types (for which the
4163 IMPORTED_LOCATION target property may be used).
4164 IMPORTED_LIBNAME_<CONFIG>
4166 New in version 3.8.
4167 <CONFIG>-specific version of IMPORTED_LIBNAME property.
4170 Configuration names correspond to those provided by the project from
4172 which the target is imported.
4173 IMPORTED_LINK_DEPENDENT_LIBRARIES
4175 Dependent shared libraries of an imported shared library.
4176 Shared libraries may be linked to other shared libraries as part of
4178 their implementation. On some platforms the linker searches for the
4179 dependent libraries of shared libraries they are including in the link.
4180 Set this property to the list of dependent shared libraries of an im‐
4181 ported library. The list should be disjoint from the list of interface
4182 libraries in the INTERFACE_LINK_LIBRARIES property. On platforms re‐
4183 quiring dependent shared libraries to be found at link time CMake uses
4184 this list to add appropriate files or paths to the link command line.
4185 Ignored for non-imported targets.
4186 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
4188 <CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
4189 Configuration names correspond to those provided by the project from
4191 which the target is imported. If set, this property completely over‐
4192 rides the generic property for the named configuration.
4193 IMPORTED_LINK_INTERFACE_LANGUAGES
4195 Languages compiled into an IMPORTED static library.
4196 Set this to the list of languages of source files compiled to produce a
4198 STATIC IMPORTED library (such as C or CXX). CMake accounts for these
4199 languages when computing how to link a target to the imported library.
4200 For example, when a C executable links to an imported C++ static li‐
4201 brary CMake chooses the C++ linker to satisfy language runtime depen‐
4202 dencies of the static library.
4203 This property is ignored for targets that are not STATIC libraries.
4205 This property is ignored for non-imported targets.
4206 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
4208 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.
4209 Configuration names correspond to those provided by the project from
4211 which the target is imported. If set, this property completely over‐
4212 rides the generic property for the named configuration.
4213 IMPORTED_LINK_INTERFACE_LIBRARIES
4215 Transitive link interface of an IMPORTED target.
4216 Set this to the list of libraries whose interface is included when an
4218 IMPORTED library target is linked to another target. The libraries
4219 will be included on the link line for the target. Unlike the
4220 LINK_INTERFACE_LIBRARIES property, this property applies to all im‐
4221 ported target types, including STATIC libraries. This property is ig‐
4222 nored for non-imported targets.
4223 This property is ignored if the target also has a non-empty
4225 INTERFACE_LINK_LIBRARIES property.
4226 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
4228 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
4230 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.
4231 Configuration names correspond to those provided by the project from
4233 which the target is imported. If set, this property completely over‐
4234 rides the generic property for the named configuration.
4235 This property is ignored if the target also has a non-empty
4237 INTERFACE_LINK_LIBRARIES property.
4238 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
4240 IMPORTED_LINK_INTERFACE_MULTIPLICITY
4242 Repetition count for cycles of IMPORTED static libraries.
4243 This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
4245 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
4247 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY.
4248 If set, this property completely overrides the generic property for the
4250 named configuration.
4251 IMPORTED_LOCATION
4253 Full path to the main file on disk for an IMPORTED target.
4254 Set this to the location of an IMPORTED target file on disk. For exe‐
4256 cutables this is the location of the executable file. For STATIC li‐
4257 braries and modules this is the location of the library or module. For
4258 SHARED libraries on non-DLL platforms this is the location of the
4259 shared library. For application bundles on macOS this is the location
4260 of the executable file inside Contents/MacOS within the bundle folder.
4261 For frameworks on macOS this is the location of the library file sym‐
4262 link just inside the framework folder. For DLLs this is the location
4263 of the .dll part of the library. For UNKNOWN libraries this is the lo‐
4264 cation of the file to be linked. Ignored for non-imported targets.
4265 The IMPORTED_LOCATION target property may be overridden for a given
4267 configuration <CONFIG> by the configuration-specific
4268 IMPORTED_LOCATION_<CONFIG> target property. Furthermore, the
4269 MAP_IMPORTED_CONFIG_<CONFIG> target property may be used to map between
4270 a project's configurations and those of an imported target. If none of
4271 these is set then the name of any other configuration listed in the
4272 IMPORTED_CONFIGURATIONS target property may be selected and its
4273 IMPORTED_LOCATION_<CONFIG> value used.
4274 To get the location of an imported target read one of the LOCATION or
4276 LOCATION_<CONFIG> properties.
4277 For platforms with import libraries (e.g. Windows) see also
4279 IMPORTED_IMPLIB.
4280 IMPORTED_LOCATION_<CONFIG>
4282 <CONFIG>-specific version of IMPORTED_LOCATION property.
4283 Configuration names correspond to those provided by the project from
4285 which the target is imported.
4286 IMPORTED_NO_SONAME
4288 Specifies that an IMPORTED shared library target has no soname.
4289 Set this property to true for an imported shared library file that has
4291 no soname field. CMake may adjust generated link commands for some
4292 platforms to prevent the linker from using the path to the library in
4293 place of its missing soname. Ignored for non-imported targets.
4294 IMPORTED_NO_SONAME_<CONFIG>
4296 <CONFIG>-specific version of IMPORTED_NO_SONAME property.
4297 Configuration names correspond to those provided by the project from
4299 which the target is imported.
4300 IMPORTED_NO_SYSTEM
4302 New in version 3.23.
4303 Deprecated since version 3.25: IMPORTED_NO_SYSTEM is deprecated. Please
4306 use the following alternatives instead:
4307 • Set SYSTEM to false if you don't want a target's include directories
4309 to be treated as system directories when compiling consumers.
4310 • Set EXPORT_NO_SYSTEM to true if you don't want the include directo‐
4312 ries of the imported target generated by install(EXPORT) and export()
4313 commands to be treated as system directories when compiling con‐
4314 sumers.
4315 Setting IMPORTED_NO_SYSTEM to true on an imported target specifies that
4318 it is not a system target. This has the following effects:
4319 • Entries of INTERFACE_INCLUDE_DIRECTORIES are not treated as system
4321 include directories when compiling consumers (regardless of the value
4322 of the consumed target's SYSTEM property), as they would be by de‐
4323 fault. Entries of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES are not af‐
4324 fected, and will always be treated as system include directories.
4325 This property can also be enabled on a non-imported target. Doing so
4327 does not affect the build system, but does tell the install(EXPORT) and
4328 export() commands to enable it on the imported targets they generate.
4329 See the NO_SYSTEM_FROM_IMPORTED target property to set this behavior on
4331 the target consuming the include directories rather than the one pro‐
4332 viding them.
4333 IMPORTED_OBJECTS
4335 New in version 3.9.
4336 A semicolon-separated list of absolute paths to the object files on
4339 disk for an imported object library.
4340 Ignored for non-imported targets.
4342 Projects may skip IMPORTED_OBJECTS if the configuration-specific prop‐
4344 erty IMPORTED_OBJECTS_<CONFIG> is set instead, except in situations as
4345 noted in the section below.
4346 Xcode Generator Considerations
4348 New in version 3.20.
4349 For Apple platforms, a project may be built for more than one architec‐
4352 ture. This is controlled by the CMAKE_OSX_ARCHITECTURES variable. For
4353 all but the Xcode generator, CMake invokes compilers once per source
4354 file and passes multiple -arch flags, leading to a single object file
4355 which will be a universal binary. Such object files work well when
4356 listed in the IMPORTED_OBJECTS of a separate CMake build, even for the
4357 Xcode generator. But producing such object files with the Xcode gener‐
4358 ator is more difficult, since it invokes the compiler once per archi‐
4359 tecture for each source file. Unlike the other generators, it does not
4360 generate universal object file binaries.
4361 A further complication with the Xcode generator is that when targeting
4363 device platforms (iOS, tvOS or watchOS), the Xcode generator has the
4364 ability to use either the device or simulator SDK without needing CMake
4365 to be re-run. The SDK can be selected at build time. But since some
4366 architectures can be supported by both the device and the simulator
4367 SDKs (e.g. arm64 with Xcode 12 or later), not all combinations can be
4368 represented in a single universal binary. The only solution in this
4369 case is to have multiple object files.
4370 IMPORTED_OBJECTS doesn't support generator expressions, so every file
4372 it lists needs to be valid for every architecture and SDK. If incorpo‐
4373 rating object files that are not universal binaries, the path and/or
4374 file name of each object file has to somehow encapsulate the different
4375 architectures and SDKs. With the Xcode generator, Xcode variables of
4376 the form $(...) can be used to represent these aspects and Xcode will
4377 substitute the appropriate values at build time. CMake doesn't inter‐
4378 pret these variables and embeds them unchanged in the Xcode project
4379 file. $(CURRENT_ARCH) can be used to represent the architecture, while
4380 $(EFFECTIVE_PLATFORM_NAME) can be used to differentiate between SDKs.
4381 The following shows one example of how these two variables can be used
4383 to refer to an object file whose location depends on both the SDK and
4384 the architecture:
4385 add_library(someObjs OBJECT IMPORTED)
4387 set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
4389 # Quotes are required because of the ()
4390 "/path/to/somewhere/objects$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o"
4391 )
4392 # Example paths:
4394 # /path/to/somewhere/objects-iphoneos/arm64/func.o
4395 # /path/to/somewhere/objects-iphonesimulator/x86_64/func.o
4396 In some cases, you may want to have configuration-specific object files
4398 as well. The $(CONFIGURATION) Xcode variable is often used for this
4399 and can be used in conjunction with the others mentioned above:
4400 add_library(someObjs OBJECT IMPORTED)
4402 set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
4403 "/path/to/somewhere/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o"
4404 )
4405 # Example paths:
4407 # /path/to/somewhere/Release-iphoneos/arm64/func.o
4408 # /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o
4409 When any Xcode variable is used, CMake is not able to fully evaluate
4411 the path(s) at configure time. One consequence of this is that the
4412 configuration-specific IMPORTED_OBJECTS_<CONFIG> properties cannot be
4413 used, since CMake cannot determine whether an object file exists at a
4414 particular <CONFIG> location. The IMPORTED_OBJECTS property must be
4415 used for these situations and the configuration-specific aspects of the
4416 path should be handled by the $(CONFIGURATION) Xcode variable.
4417 IMPORTED_OBJECTS_<CONFIG>
4419 New in version 3.9.
4420 <CONFIG>-specific version of IMPORTED_OBJECTS property.
4423 Configuration names correspond to those provided by the project from
4425 which the target is imported.
4426 Xcode Generator Considerations
4428 Do not use this <CONFIG>-specific property if you need to use Xcode
4429 variables like $(CURRENT_ARCH) or $(EFFECTIVE_PLATFORM_NAME) in the
4430 value. The <CONFIG>-specific properties will be ignored in such cases
4431 because CMake cannot determine whether a file exists at the configura‐
4432 tion-specific path at configuration time. For such cases, use
4433 IMPORTED_OBJECTS instead.
4434 IMPORTED_SONAME
4436 The soname of an IMPORTED target of shared library type.
4437 Set this to the soname embedded in an imported shared library. This is
4439 meaningful only on platforms supporting the feature. Ignored for
4440 non-imported targets.
4441 IMPORTED_SONAME_<CONFIG>
4443 <CONFIG>-specific version of IMPORTED_SONAME property.
4444 Configuration names correspond to those provided by the project from
4446 which the target is imported.
4447 IMPORT_PREFIX
4449 What comes before the import library name.
4450 Similar to the target property PREFIX, but used for import libraries
4452 (typically corresponding to a DLL) instead of regular libraries. A
4453 target property that can be set to override the prefix (such as lib) on
4454 an import library name.
4455 IMPORT_SUFFIX
4457 What comes after the import library name.
4458 Similar to the target property SUFFIX, but used for import libraries
4460 (typically corresponding to a DLL) instead of regular libraries. A
4461 target property that can be set to override the suffix (such as .lib)
4462 on an import library name.
4463 INCLUDE_DIRECTORIES
4465 List of preprocessor include file search directories.
4466 This property specifies the list of directories given so far to the
4468 target_include_directories() command. In addition to accepting values
4469 from that command, values may be set directly on any target using the
4470 set_property() command. A target gets its initial value for this prop‐
4471 erty from the value of the INCLUDE_DIRECTORIES directory property.
4472 Both directory and target property values are adjusted by calls to the
4473 include_directories() command.
4474 The value of this property is used by the generators to set the include
4476 paths for the compiler.
4477 Relative paths should not be added to this property directly. Use one
4479 of the commands above instead to handle relative paths.
4480 Contents of INCLUDE_DIRECTORIES may use cmake-generator-expressions(7)
4482 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4483 for available expressions. See the cmake-buildsystem(7) manual for
4484 more on defining buildsystem properties.
4485 INSTALL_NAME_DIR
4487 Directory name for installed targets on Apple platforms.
4488 INSTALL_NAME_DIR is a string specifying the directory portion of the
4490 "install_name" field of shared libraries on Apple platforms for in‐
4491 stalled targets. When not set, the default directory used is deter‐
4492 mined by MACOSX_RPATH. Policies CMP0068 and CMP0042 are also relevant.
4493 This property is initialized by the value of the variable
4495 CMAKE_INSTALL_NAME_DIR if it is set when a target is created.
4496 This property supports generator expressions. In particular, the
4498 $<INSTALL_PREFIX> generator expression can be used to set the directory
4499 relative to the install-time prefix.
4500 INSTALL_REMOVE_ENVIRONMENT_RPATH
4502 New in version 3.16.
4503 Controls whether toolchain-defined rpaths should be removed during in‐
4506 stallation.
4507 When a target is being installed, CMake may need to rewrite its rpath
4509 information. This occurs when the install rpath (as specified by the
4510 INSTALL_RPATH target property) has different contents to the rpath that
4511 the target was built with. Some toolchains insert their own rpath con‐
4512 tents into the binary as part of the build. By default, CMake will
4513 preserve those extra inserted contents in the install rpath. For those
4514 scenarios where such toolchain-inserted entries need to be discarded
4515 during install, set the INSTALL_REMOVE_ENVIRONMENT_RPATH target prop‐
4516 erty to true.
4517 This property is initialized by the value of
4519 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH when the target is created.
4520 INSTALL_RPATH
4522 The rpath to use for installed targets.
4523 A semicolon-separated list specifying the rpath to use in installed
4525 targets (for platforms that support it). This property is initialized
4526 by the value of the variable CMAKE_INSTALL_RPATH if it is set when a
4527 target is created.
4528 Because the rpath may contain ${ORIGIN}, which coincides with CMake
4530 syntax, the contents of INSTALL_RPATH are properly escaped in the
4531 cmake_install.cmake script (see policy CMP0095.)
4532 This property supports generator expressions.
4534 INSTALL_RPATH_USE_LINK_PATH
4536 Add paths to linker search and installed rpath.
4537 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to True will ap‐
4539 pend to the runtime search path (rpath) of installed binaries any di‐
4540 rectories outside the project that are in the linker search path or
4541 contain linked library files. The directories are appended after the
4542 value of the INSTALL_RPATH target property.
4543 This property is initialized by the value of the variable
4545 CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a target is cre‐
4546 ated.
4547 INTERFACE_AUTOUIC_OPTIONS
4549 List of interface options to pass to uic.
4550 Targets may populate this property to publish the options required to
4552 use when invoking uic. Consuming targets can add entries to their own
4553 AUTOUIC_OPTIONS property such as $<TARGET_PROPERTY:foo,INTER‐
4554 FACE_AUTOUIC_OPTIONS> to use the uic options specified in the interface
4555 of foo. This is done automatically by the target_link_libraries() com‐
4556 mand.
4557 This property supports generator expressions. See the
4559 cmake-generator-expressions(7) manual for available expressions.
4560 INTERFACE_COMPILE_DEFINITIONS
4562 List of public compile definitions requirements for a library.
4563 Targets may populate this property to publish the compile definitions
4565 required to compile against the headers for the target. The
4566 target_compile_definitions() command populates this property with val‐
4567 ues given to the PUBLIC and INTERFACE keywords. Projects may also get
4568 and set the property directly.
4569 When target dependencies are specified using target_link_libraries(),
4571 CMake will read this property from all target dependencies to determine
4572 the build properties of the consumer.
4573 Contents of INTERFACE_COMPILE_DEFINITIONS may use "generator expres‐
4575 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
4576 manual for available expressions. See the cmake-buildsystem(7) -manual
4577 for more on defining buildsystem properties.
4578 INTERFACE_COMPILE_FEATURES
4580 New in version 3.1.
4581 List of public compile features requirements for a library.
4584 Targets may populate this property to publish the compile features re‐
4586 quired to compile against the headers for the target. The
4587 target_compile_features() command populates this property with values
4588 given to the PUBLIC and INTERFACE keywords. Projects may also get and
4589 set the property directly.
4590 When target dependencies are specified using target_link_libraries(),
4592 CMake will read this property from all target dependencies to determine
4593 the build properties of the consumer.
4594 Contents of INTERFACE_COMPILE_FEATURES may use "generator expressions"
4596 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4597 for available expressions. See the cmake-buildsystem(7) -manual for
4598 more on defining buildsystem properties.
4599 See the cmake-compile-features(7) manual for information on compile
4601 features and a list of supported compilers.
4602 INTERFACE_COMPILE_OPTIONS
4604 List of public compile options requirements for a library.
4605 Targets may populate this property to publish the compile options re‐
4607 quired to compile against the headers for the target. The
4608 target_compile_options() command populates this property with values
4609 given to the PUBLIC and INTERFACE keywords. Projects may also get and
4610 set the property directly.
4611 When target dependencies are specified using target_link_libraries(),
4613 CMake will read this property from all target dependencies to determine
4614 the build properties of the consumer.
4615 Contents of INTERFACE_COMPILE_OPTIONS may use "generator expressions"
4617 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4618 for available expressions. See the cmake-buildsystem(7) -manual for
4619 more on defining buildsystem properties.
4620 INTERFACE_CXX_MODULE_HEADER_UNIT_SETS
4622 New in version 3.25.
4623 NOTE:
4626 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
4627 Read-only list of the target's PUBLIC C++ module header sets (i.e. all
4629 file sets with the type CXX_MODULE_HEADER_UNITS). Files listed in these
4630 C++ module header sets can be installed with install(TARGETS) and ex‐
4631 ported with install(EXPORT) and export().
4632 C++ module header sets may be defined using the target_sources() com‐
4634 mand FILE_SET option with type CXX_MODULE_HEADER_UNITS.
4635 See also CXX_MODULE_HEADER_UNIT_SETS.
4637 INTERFACE_CXX_MODULE_SETS
4639 New in version 3.25.
4640 NOTE:
4643 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
4644 Read-only list of the target's PUBLIC C++ module sets (i.e. all file
4646 sets with the type CXX_MODULES). Files listed in these C++ module sets
4647 can be installed with install(TARGETS) and exported with
4648 install(EXPORT) and export().
4649 C++ module sets may be defined using the target_sources() command
4651 FILE_SET option with type CXX_MODULES.
4652 See also CXX_MODULE_SETS.
4654 INTERFACE_HEADER_SETS
4656 New in version 3.23.
4657 Read-only list of the target's INTERFACE and PUBLIC header sets (i.e.
4660 all file sets with the type HEADERS). Files listed in these header sets
4661 can be installed with install(TARGETS) and exported with
4662 install(EXPORT) and export().
4663 Header sets may be defined using the target_sources() command FILE_SET
4665 option with type HEADERS.
4666 See also HEADER_SETS.
4668 INTERFACE_HEADER_SETS_TO_VERIFY
4670 New in version 3.24.
4671 Used to specify which PUBLIC and INTERFACE header sets of a target
4674 should be verified.
4675 This property contains a semicolon-separated list of header sets which
4677 should be verified if VERIFY_INTERFACE_HEADER_SETS is set to TRUE. If
4678 the list is empty, all PUBLIC and INTERFACE header sets are verified.
4679 (If the project does not want to verify any header sets on the target,
4680 simply set VERIFY_INTERFACE_HEADER_SETS to FALSE.)
4681 INTERFACE_INCLUDE_DIRECTORIES
4683 List of public include directories requirements for a library.
4684 Targets may populate this property to publish the include directories
4686 required to compile against the headers for the target. The
4687 target_include_directories() command populates this property with val‐
4688 ues given to the PUBLIC and INTERFACE keywords. Projects may also get
4689 and set the property directly.
4690 When target dependencies are specified using target_link_libraries(),
4692 CMake will read this property from all target dependencies to determine
4693 the build properties of the consumer.
4694 Contents of INTERFACE_INCLUDE_DIRECTORIES may use "generator expres‐
4696 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
4697 manual for available expressions. See the cmake-buildsystem(7) -manual
4698 for more on defining buildsystem properties.
4699 Include directories usage requirements commonly differ between the
4701 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
4702 TERFACE generator expressions can be used to describe separate usage
4703 requirements based on the usage location. Relative paths are allowed
4704 within the INSTALL_INTERFACE expression and are interpreted relative to
4705 the installation prefix. For example:
4706 target_include_directories(mylib INTERFACE
4708 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
4709 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
4710 )
4711 Creating Relocatable Packages
4713 Note that it is not advisable to populate the INSTALL_INTERFACE of the
4714 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
4715 include directories of dependencies. That would hard-code into in‐
4716 stalled packages the include directory paths for dependencies as found
4717 on the machine the package was made on.
4718 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
4720 suitable for specifying the required include directories for headers
4721 provided with the target itself, not those provided by the transitive
4722 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
4723 Those dependencies should themselves be targets that specify their own
4724 header locations in INTERFACE_INCLUDE_DIRECTORIES.
4725 See the Creating Relocatable Packages section of the cmake-packages(7)
4727 manual for discussion of additional care that must be taken when speci‐
4728 fying usage requirements while creating packages for redistribution.
4729 INTERFACE_LINK_DEPENDS
4731 New in version 3.13.
4732 Additional public interface files on which a target binary depends for
4735 linking.
4736 This property is supported only by Ninja and Makefile Generators. It
4738 is intended to specify dependencies on "linker scripts" for custom
4739 Makefile link rules.
4740 When target dependencies are specified using target_link_libraries(),
4742 CMake will read this property from all target dependencies to determine
4743 the build properties of the consumer.
4744 Contents of INTERFACE_LINK_DEPENDS may use "generator expressions" with
4746 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4747 available expressions. See the cmake-buildsystem(7) -manual for more
4748 on defining buildsystem properties.
4749 Link dependency files usage requirements commonly differ between the
4751 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
4752 TERFACE generator expressions can be used to describe separate usage
4753 requirements based on the usage location. Relative paths are allowed
4754 within the INSTALL_INTERFACE expression and are interpreted relative to
4755 the installation prefix. For example:
4756 set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS
4758 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript>
4759 $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript
4760 )
4761 INTERFACE_LINK_DIRECTORIES
4763 New in version 3.13.
4764 List of public link directories requirements for a library.
4767 Targets may populate this property to publish the link directories re‐
4769 quired to compile against the headers for the target. The
4770 target_link_directories() command populates this property with values
4771 given to the PUBLIC and INTERFACE keywords. Projects may also get and
4772 set the property directly.
4773 When target dependencies are specified using target_link_libraries(),
4775 CMake will read this property from all target dependencies to determine
4776 the build properties of the consumer.
4777 Contents of INTERFACE_LINK_DIRECTORIES may use "generator expressions"
4779 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4780 for available expressions. See the cmake-buildsystem(7) -manual for
4781 more on defining buildsystem properties.
4782 INTERFACE_LINK_LIBRARIES
4784 List public interface libraries for a library.
4785 This property contains the list of transitive link dependencies. When
4787 the target is linked into another target using the
4788 target_link_libraries() command, the libraries listed (and recursively
4789 their link interface libraries) will be provided to the other target
4790 also. This property is overridden by the LINK_INTERFACE_LIBRARIES or
4791 LINK_INTERFACE_LIBRARIES_<CONFIG> property if policy CMP0022 is OLD or
4792 unset.
4793 The value of this property is used by the generators when constructing
4795 the link rule for a dependent target. A dependent target's direct link
4796 dependencies, specified by its LINK_LIBRARIES target property, are
4797 linked first, followed by indirect dependencies from the transitive
4798 closure of the direct dependencies' INTERFACE_LINK_LIBRARIES proper‐
4799 ties. See policy CMP0022.
4800 Contents of INTERFACE_LINK_LIBRARIES may use "generator expressions"
4802 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4803 for available expressions. See the cmake-buildsystem(7) manual for
4804 more on defining buildsystem properties.
4805 NOTE:
4807 A call to target_link_libraries(<target> ...) may update this prop‐
4808 erty on <target>. If <target> was not created in the same directory
4809 as the call then target_link_libraries() will wrap each entry with
4810 the form ::@(directory-id);...;::@, where the ::@ is literal and the
4811 (directory-id) is unspecified. This tells the generators that the
4812 named libraries must be looked up in the scope of the caller rather
4813 than in the scope in which the <target> was created. Valid direc‐
4814 tory ids are stripped on export by the install(EXPORT) and export()
4815 commands.
4816 INTERFACE_LINK_LIBRARIES adds transitive link dependencies for a tar‐
4818 get's dependents. In advanced use cases, one may update the direct
4819 link dependencies of a target's dependents by using the
4820 INTERFACE_LINK_LIBRARIES_DIRECT and
4821 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties.
4822 Creating Relocatable Packages
4824 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
4825 of a target with absolute paths to dependencies. That would hard-code
4826 into installed packages the library file paths for dependencies as
4827 found on the machine the package was made on.
4828 See the Creating Relocatable Packages section of the cmake-packages(7)
4830 manual for discussion of additional care that must be taken when speci‐
4831 fying usage requirements while creating packages for redistribution.
4832 INTERFACE_LINK_LIBRARIES_DIRECT
4834 New in version 3.24.
4835 List of libraries that consumers of this library should treat as direct
4838 link dependencies.
4839 This target property may be set to include items in a dependent tar‐
4841 get's final set of direct link dependencies. See the
4842 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property to exclude
4843 items.
4844 The initial set of a dependent target's direct link dependencies is
4846 specified by its LINK_LIBRARIES target property. Indirect link depen‐
4847 dencies are specified by the transitive closure of the direct link de‐
4848 pendencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency
4849 may specify additional direct link dependencies using the INTER‐
4850 FACE_LINK_LIBRARIES_DIRECT target property. The set of direct link de‐
4851 pendencies is then filtered to exclude items named by any dependency's
4852 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.
4853 The value of INTERFACE_LINK_LIBRARIES_DIRECT may use generator expres‐
4855 sions.
4856 NOTE:
4858 The INTERFACE_LINK_LIBRARIES_DIRECT target property is intended for
4859 advanced use cases such as injection of static plugins into a con‐
4860 suming executable. It should not be used as a substitute for orga‐
4861 nizing normal calls to target_link_libraries().
4862 Direct Link Dependencies as Usage Requirements
4864 The INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DI‐
4865 RECT_EXCLUDE target properties are usage requirements. Their effects
4866 propagate to dependent targets transitively, and can therefore affect
4867 the direct link dependencies of every target in a chain of dependent
4868 libraries. Whenever some library target X links to another library
4869 target Y whose direct or transitive usage requirements contain INTER‐
4870 FACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE,
4871 the properties may affect X's list of direct link dependencies:
4872 • If X is a shared library or executable, its dependencies are linked.
4874 They also affect the usage requirements with which X's sources are
4875 compiled.
4876 • If X is a static library or object library, it does not actually
4878 link, so its dependencies at most affect the usage requirements with
4879 which X's sources are compiled.
4880 The properties may also affect the list of direct link dependencies on
4882 X's dependents:
4883 • If X links Y publicly:
4885 target_link_libraries(X PUBLIC Y)
4887 then Y is placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage re‐
4889 quirements, including INTERFACE_LINK_LIBRARIES_DIRECT, INTER‐
4890 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the usage requirements de‐
4891 clared by the direct link dependencies they add, are propagated to
4892 X's dependents.
4893 • If X is a static library or object library, and links Y privately:
4895 target_link_libraries(X PRIVATE Y)
4897 then $<LINK_ONLY:Y> is placed in X's INTERFACE_LINK_LIBRARIES. Y's
4899 linking requirements, including INTERFACE_LINK_LIBRARIES_DIRECT, IN‐
4900 TERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the transitive link depen‐
4901 dencies declared by the direct link dependencies they add, are propa‐
4902 gated to X's dependents. However, Y's non-linking usage requirements
4903 are blocked by the LINK_ONLY generator expression, and are not propa‐
4904 gated to X's dependents.
4905 • If X is a shared library or executable, and links Y privately:
4907 target_link_libraries(X PRIVATE Y)
4909 then Y is not placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage
4911 requirements, even INTERFACE_LINK_LIBRARIES_DIRECT and INTER‐
4912 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE, are not propagated to X's depen‐
4913 dents.
4914 • In all cases, the content of X's INTERFACE_LINK_LIBRARIES is not af‐
4916 fected by Y's INTERFACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LI‐
4917 BRARIES_DIRECT_EXCLUDE.
4918 One may limit the effects of INTERFACE_LINK_LIBRARIES_DIRECT and INTER‐
4920 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE to a subset of dependent targets by
4921 using the TARGET_PROPERTY generator expression. For example, to limit
4922 the effects to executable targets, use an entry of the form:
4923 "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
4925 Similarly, to limit the effects to specific targets, use an entry of
4927 the form:
4928 "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
4930 This entry will only affect targets that set their USE_IT target prop‐
4932 erty to a true value.
4933 Direct Link Dependency Ordering
4935 The list of direct link dependencies for a target is computed from an
4936 initial ordered list in its LINK_LIBRARIES target property. For each
4937 item, additional direct link dependencies are discovered from its di‐
4938 rect and transitive INTERFACE_LINK_LIBRARIES_DIRECT usage requirements.
4939 Each discovered item is injected before the item that specified it.
4940 However, a discovered item is added at most once, and only if it did
4941 not appear anywhere in the initial list. This gives LINK_LIBRARIES
4942 control over ordering of those direct link dependencies that it explic‐
4943 itly specifies.
4944 Once all direct link dependencies have been collected, items named by
4946 all of their INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE usage requirements
4947 are removed from the final list. This does not affect the order of the
4948 items that remain.
4949 Example: Static Plugins
4951 Consider a static library Foo that provides a static plugin FooPlugin
4952 to consuming application executables, where the implementation of the
4953 plugin depends on Foo and other things. In this case, the application
4954 should link to FooPlugin directly, before Foo. However, the applica‐
4955 tion author only knows about Foo. We can express this as follows:
4956 # Core library used by other components.
4958 add_library(Core STATIC core.cpp)
4959 # Foo is a static library for use by applications.
4961 # Implementation of Foo depends on Core.
4962 add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
4963 target_link_libraries(Foo PRIVATE Core)
4964 # Extra parts of Foo for use by its static plugins.
4966 # Implementation of Foo's extra parts depends on both Core and Foo.
4967 add_library(FooExtras STATIC foo_extras.cpp)
4968 target_link_libraries(FooExtras PRIVATE Core Foo)
4969 # The Foo library has an associated static plugin
4971 # that should be linked into the final executable.
4972 # Implementation of the plugin depends on Core, Foo, and FooExtras.
4973 add_library(FooPlugin STATIC foo_plugin.cpp)
4974 target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
4975 # An app that links Foo should link Foo's plugin directly.
4977 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
4978 # An app does not need to link Foo directly because the plugin links it.
4980 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
4981 An application app only needs to specify that it links to Foo:
4983 add_executable(app main.cpp)
4985 target_link_libraries(app PRIVATE Foo)
4986 The INTERFACE_LINK_LIBRARIES_DIRECT target property on Foo tells CMake
4988 to pretend that app also links directly to FooPlugin. The INTER‐
4989 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property on Foo tells CMake
4990 to pretend that app did not link directly to Foo. Instead, Foo will be
4991 linked as a dependency of FooPlugin. The final link line for app will
4992 link the libraries in the following order:
4993 • FooPlugin as a direct link dependency of app (via Foo's usage re‐
4995 quirements).
4996 • FooExtras as a dependency of FooPlugin.
4998 • Foo as a dependency of FooPlugin and FooExtras.
5000 • Core as a dependency of FooPlugin, FooExtras, and Foo.
5002 Note that without the INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target
5004 property, Foo would be linked twice: once as a direct dependency of
5005 app, and once as a dependency of FooPlugin.
5006 Example: Opt-In Static Plugins
5008 In the above Example: Static Plugins, the app executable specifies that
5009 it links directly to Foo. In a real application, there might be an in‐
5010 termediate library:
5011 add_library(app_impl STATIC app_impl.cpp)
5013 target_link_libraries(app_impl PRIVATE Foo)
5014 add_executable(app main.cpp)
5016 target_link_libraries(app PRIVATE app_impl)
5017 In this case we do not want Foo's INTERFACE_LINK_LIBRARIES_DIRECT and
5019 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties to affect the
5020 direct dependencies of app_impl. To avoid this, we can revise the
5021 property values to make their effects opt-in:
5022 # An app that links Foo should link Foo's plugin directly.
5024 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
5025 "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
5026 )
5027 # An app does not need to link Foo directly because the plugin links it.
5029 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
5030 "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
5031 )
5032 Now, the app executable can opt-in to get Foo's plugin(s):
5034 set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
5036 The final link line for app will now link the libraries in the follow‐
5038 ing order:
5039 • FooPlugin as a direct link dependency of app (via Foo's usage re‐
5041 quirements).
5042 • app_impl as a direct link dependency of app.
5044 • FooExtras as a dependency of FooPlugin.
5046 • Foo as a dependency of app_impl, FooPlugin, and FooExtras.
5048 • Core as a dependency of FooPlugin, FooExtras, and Foo.
5050 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
5052 New in version 3.24.
5053 List of libraries that consumers of this library should not treat as
5056 direct link dependencies.
5057 This target property may be set to exclude items from a dependent tar‐
5059 get's final set of direct link dependencies. This property is pro‐
5060 cessed after the INTERFACE_LINK_LIBRARIES_DIRECT target property of all
5061 other dependencies of the dependent target, so exclusion from direct
5062 link dependence takes priority over inclusion.
5063 The initial set of a dependent target's direct link dependencies is
5065 specified by its LINK_LIBRARIES target property. Indirect link depen‐
5066 dencies are specified by the transitive closure of the direct link de‐
5067 pendencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency
5068 may specify additional direct link dependencies using the
5069 INTERFACE_LINK_LIBRARIES_DIRECT target property. The set of direct
5070 link dependencies is then filtered to exclude items named by any depen‐
5071 dency's INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.
5072 Excluding an item from a dependent target's direct link dependencies
5074 does not mean the dependent target won't link the item. The item may
5075 still be linked as an indirect link dependency via the
5076 INTERFACE_LINK_LIBRARIES property on other dependencies.
5077 The value of INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE may use generator
5079 expressions.
5080 NOTE:
5082 The INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property is in‐
5083 tended for advanced use cases such as injection of static plugins
5084 into a consuming executable. It should not be used as a substitute
5085 for organizing normal calls to target_link_libraries().
5086 See the INTERFACE_LINK_LIBRARIES_DIRECT target property documentation
5088 for more details and examples.
5089 INTERFACE_LINK_OPTIONS
5091 New in version 3.13.
5092 List of public link options requirements for a library.
5095 Targets may populate this property to publish the link options required
5097 to compile against the headers for the target. The
5098 target_link_options() command populates this property with values given
5099 to the PUBLIC and INTERFACE keywords. Projects may also get and set
5100 the property directly.
5101 When target dependencies are specified using target_link_libraries(),
5103 CMake will read this property from all target dependencies to determine
5104 the build properties of the consumer.
5105 Contents of INTERFACE_LINK_OPTIONS may use "generator expressions" with
5107 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5108 available expressions. See the cmake-buildsystem(7) -manual for more
5109 on defining buildsystem properties.
5110 INTERFACE_POSITION_INDEPENDENT_CODE
5112 Whether consumers need to create a position-independent target
5113 The INTERFACE_POSITION_INDEPENDENT_CODE property informs consumers of
5115 this target whether they must set their POSITION_INDEPENDENT_CODE prop‐
5116 erty to ON. If this property is set to ON, then the
5117 POSITION_INDEPENDENT_CODE property on all consumers will be set to ON.
5118 Similarly, if this property is set to OFF, then the
5119 POSITION_INDEPENDENT_CODE property on all consumers will be set to OFF.
5120 If this property is undefined, then consumers will determine their
5121 POSITION_INDEPENDENT_CODE property by other means. Consumers must en‐
5122 sure that the targets that they link to have a consistent requirement
5123 for their INTERFACE_POSITION_INDEPENDENT_CODE property.
5124 Contents of INTERFACE_POSITION_INDEPENDENT_CODE may use "generator ex‐
5126 pressions" with the syntax $<...>. See the
5127 cmake-generator-expressions(7) manual for available expressions. See
5128 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
5129 erties.
5130 INTERFACE_PRECOMPILE_HEADERS
5132 New in version 3.16.
5133 List of interface header files to precompile into consuming targets.
5136 Targets may populate this property to publish the header files for con‐
5138 suming targets to precompile. The target_precompile_headers() command
5139 populates this property with values given to the PUBLIC and INTERFACE
5140 keywords. Projects may also get and set the property directly. See
5141 the discussion in target_precompile_headers() for guidance on appropri‐
5142 ate use of this property for installed or exported targets.
5143 Contents of INTERFACE_PRECOMPILE_HEADERS may use "generator expres‐
5145 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
5146 manual for available expressions. See the cmake-buildsystem(7) manual
5147 for more on defining buildsystem properties.
5148 INTERFACE_SOURCES
5150 New in version 3.1.
5151 List of interface sources to compile into consuming targets.
5154 Targets may populate this property to publish the sources for consuming
5156 targets to compile. The target_sources() command populates this prop‐
5157 erty with values given to the PUBLIC and INTERFACE keywords. Projects
5158 may also get and set the property directly.
5159 When target dependencies are specified using target_link_libraries(),
5161 CMake will read this property from all target dependencies to determine
5162 the sources of the consumer.
5163 Contents of INTERFACE_SOURCES may use "generator expressions" with the
5165 syntax $<...>. See the cmake-generator-expressions(7) manual for
5166 available expressions. See the cmake-buildsystem(7) manual for more on
5167 defining buildsystem properties.
5168 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
5170 List of public system include directories for a library.
5171 Targets may populate this property to publish the include directories
5173 which contain system headers, and therefore should not result in com‐
5174 piler warnings. Additionally, system include directories are searched
5175 after normal include directories regardless of the order specified.
5176 When the target_include_directories() command is given the SYSTEM key‐
5178 word, it populates this property with values provided after the PUBLIC
5179 and INTERFACE keywords.
5180 Projects may also get and set the property directly, but must be aware
5182 that adding directories to this property does not make those directo‐
5183 ries used during compilation. Adding directories to this property
5184 marks directories as system directories which otherwise would be used
5185 in a non-system manner. This can appear similar to duplication, so
5186 prefer the high-level target_include_directories() command with the
5187 SYSTEM keyword and avoid setting the property directly.
5188 When target dependencies are specified using target_link_libraries(),
5190 CMake will read this property from all target dependencies to mark the
5191 same include directories as containing system headers.
5192 Contents of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES may use "generator ex‐
5194 pressions" with the syntax $<...>. See the
5195 cmake-generator-expressions(7) manual for available expressions. See
5196 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
5197 erties.
5198 INTERPROCEDURAL_OPTIMIZATION
5200 Enable interprocedural optimization for a target.
5201 If set to true, enables interprocedural optimizations if they are known
5203 to be supported by the compiler. Depending on value of policy CMP0069,
5204 the error will be reported or ignored, if interprocedural optimization
5205 is enabled but not supported.
5206 This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZATION
5208 variable if it is set when a target is created.
5209 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5211 Per-configuration interprocedural optimization for a target.
5212 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
5214 If set, this property overrides the generic property for the named con‐
5215 figuration.
5216 This property is initialized by the
5218 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> variable if it is set when
5219 a target is created.
5220 IOS_INSTALL_COMBINED
5222 New in version 3.5.
5223 Build a combined (device and simulator) target when installing.
5226 When this property is set to set to false (which is the default) then
5228 it will either be built with the device SDK or the simulator SDK de‐
5229 pending on the SDK set. But if this property is set to true then the
5230 target will at install time also be built for the corresponding SDK and
5231 combined into one library.
5232 NOTE:
5234 If a selected architecture is available for both: device SDK and
5235 simulator SDK it will be built for the SDK selected by
5236 CMAKE_OSX_SYSROOT and removed from the corresponding SDK.
5237 This feature requires at least Xcode version 6.
5239 ISPC_HEADER_DIRECTORY
5241 New in version 3.19.
5242 Specify relative output directory for ISPC headers provided by the tar‐
5245 get.
5246 If the target contains ISPC source files, this specifies the directory
5248 in which the generated headers will be placed. Relative paths are
5249 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR. When
5250 this property is not set, the headers will be placed a generator de‐
5251 fined build directory. If the variable CMAKE_ISPC_HEADER_DIRECTORY is
5252 set when a target is created its value is used to initialize this prop‐
5253 erty.
5254 ISPC_HEADER_SUFFIX
5256 New in version 3.19.2.
5257 Specify output suffix to be used for ISPC generated headers provided by
5260 the target.
5261 This property is initialized by the value of the
5263 CMAKE_ISPC_HEADER_SUFFIX variable if it is set when a target is cre‐
5264 ated.
5265 If the target contains ISPC source files, this specifies the header
5267 suffix to be used for the generated headers.
5268 The default value is _ispc.h.
5270 ISPC_INSTRUCTION_SETS
5272 New in version 3.19.
5273 List of instruction set architectures to generate code for.
5276 This property is initialized by the value of the
5278 CMAKE_ISPC_INSTRUCTION_SETS variable if it is set when a target is cre‐
5279 ated.
5280 The ISPC_INSTRUCTION_SETS target property must be used when generating
5282 for multiple instruction sets so that CMake can track what object files
5283 will be generated.
5284 Examples
5286 set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835)
5287 Generates code for avx2 and avx512skx target architectures.
5289 JOB_POOL_COMPILE
5291 Ninja only: Pool used for compiling.
5292 The number of parallel compile processes could be limited by defining
5294 pools with the global JOB_POOLS property and then specifying here the
5295 pool name.
5296 For instance:
5298 set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs)
5300 This property is initialized by the value of CMAKE_JOB_POOL_COMPILE.
5302 JOB_POOL_LINK
5304 Ninja only: Pool used for linking.
5305 The number of parallel link processes could be limited by defining
5307 pools with the global JOB_POOLS property and then specifying here the
5308 pool name.
5309 For instance:
5311 set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs)
5313 This property is initialized by the value of CMAKE_JOB_POOL_LINK.
5315 JOB_POOL_PRECOMPILE_HEADER
5317 New in version 3.17.
5318 Ninja only: Pool used for generating pre-compiled headers.
5321 The number of parallel compile processes could be limited by defining
5323 pools with the global JOB_POOLS property and then specifying here the
5324 pool name.
5325 For instance:
5327 set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs)
5329 This property is initialized by the value of
5331 CMAKE_JOB_POOL_PRECOMPILE_HEADER.
5332 If neither JOB_POOL_PRECOMPILE_HEADER nor
5334 CMAKE_JOB_POOL_PRECOMPILE_HEADER are set then JOB_POOL_COMPILE will be
5335 used for this task.
5336 LABELS
5338 Specify a list of text labels associated with a target.
5339 Target label semantics are currently unspecified.
5341 <LANG>_CLANG_TIDY
5343 New in version 3.6.
5344 This property is implemented only when <LANG> is C, CXX, OBJC or OB‐
5347 JCXX.
5348 Specify a semicolon-separated list containing a command line for the
5350 clang-tidy tool. The Makefile Generators and the Ninja generator will
5351 run this tool along with the compiler and report a warning if the tool
5352 reports any problems.
5353 The specified clang-tidy command line will be invoked with additional
5355 arguments specifying the source file and, after --, the full compiler
5356 command line.
5357 Changed in version 3.25: If the specified clang-tidy command line in‐
5359 cludes the -p option, it will be invoked without -- and the full com‐
5360 piler command line. clang-tidy will look up the source file in the
5361 specified compiler commands database.
5362 This property is initialized by the value of the
5365 CMAKE_<LANG>_CLANG_TIDY variable if it is set when a target is created.
5366 <LANG>_COMPILER_LAUNCHER
5368 New in version 3.4.
5369 This property is implemented only when <LANG> is C, CXX, Fortran, HIP,
5372 ISPC, OBJC, OBJCXX, or CUDA.
5373 Specify a semicolon-separated list containing a command line for a com‐
5375 piler launching tool. The Makefile Generators and the Ninja generator
5376 will run this tool and pass the compiler and its arguments to the tool.
5377 Some example tools are distcc and ccache.
5378 This property is initialized by the value of the
5380 CMAKE_<LANG>_COMPILER_LAUNCHER variable if it is set when a target is
5381 created.
5382 New in version 3.25: The property value may use generator expressions.
5384 <LANG>_CPPCHECK
5387 New in version 3.10.
5388 This property is supported only when <LANG> is C or CXX.
5391 Specify a semicolon-separated list containing a command line for the
5393 cppcheck static analysis tool. The Makefile Generators and the Ninja
5394 generator will run cppcheck along with the compiler and report any
5395 problems. If the command-line specifies the exit code options to cp‐
5396 pcheck then the build will fail if the tool returns non-zero.
5397 This property is initialized by the value of the CMAKE_<LANG>_CPPCHECK
5399 variable if it is set when a target is created.
5400 <LANG>_CPPLINT
5402 New in version 3.8.
5403 This property is supported only when <LANG> is C or CXX.
5406 Specify a semicolon-separated list containing a command line for the
5408 cpplint style checker. The Makefile Generators and the Ninja generator
5409 will run cpplint along with the compiler and report any problems.
5410 This property is initialized by the value of the CMAKE_<LANG>_CPPLINT
5412 variable if it is set when a target is created.
5413 <LANG>_EXTENSIONS
5415 The variations are:
5416 • C_EXTENSIONS
5418 • CXX_EXTENSIONS
5420 • CUDA_EXTENSIONS
5422 • HIP_EXTENSIONS
5424 • OBJC_EXTENSIONS
5426 • OBJCXX_EXTENSIONS
5428 These properties specify whether compiler-specific extensions are re‐
5430 quested.
5431 These properties are initialized by the value of the
5433 CMAKE_<LANG>_EXTENSIONS variable if it is set when a target is created
5434 and otherwise by the value of CMAKE_<LANG>_EXTENSIONS_DEFAULT (see
5435 CMP0128).
5436 For supported CMake versions see the respective pages. To control lan‐
5438 guage standard versions see <LANG>_STANDARD.
5439 See the cmake-compile-features(7) manual for information on compile
5441 features and a list of supported compilers.
5442 <LANG>_INCLUDE_WHAT_YOU_USE
5444 New in version 3.3.
5445 This property is implemented only when <LANG> is C or CXX.
5448 Specify a semicolon-separated list containing a command line for the
5450 include-what-you-use tool. The Makefile Generators and the Ninja gen‐
5451 erator will run this tool along with the compiler and report a warning
5452 if the tool reports any problems.
5453 This property is initialized by the value of the
5455 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE variable if it is set when a target
5456 is created.
5457 <LANG>_LINKER_LAUNCHER
5459 New in version 3.21.
5460 This property is implemented only when <LANG> is C, CXX, OBJC, or OB‐
5463 JCXX
5464 Specify a semicolon-separated list containing a command line for a
5466 linker launching tool. The Makefile Generators and the Ninja generator
5467 will run this tool and pass the linker and its arguments to the tool.
5468 This is useful for tools such as static analyzers.
5469 This property is initialized by the value of the
5471 CMAKE_<LANG>_LINKER_LAUNCHER variable if it is set when a target is
5472 created.
5473 <LANG>_STANDARD
5475 The variations are:
5476 • C_STANDARD
5478 • CXX_STANDARD
5480 • CUDA_STANDARD
5482 • HIP_STANDARD
5484 • OBJC_STANDARD
5486 • OBJCXX_STANDARD
5488 These properties specify language standard versions which are re‐
5490 quested. When a newer standard is specified than is supported by the
5491 compiler, then it will fallback to the latest supported standard. This
5492 "decay" behavior may be controlled with the <LANG>_STANDARD_REQUIRED
5493 target property.
5494 Note that the actual language standard used may be higher than that
5496 specified by <LANG>_STANDARD, regardless of the value of
5497 <LANG>_STANDARD_REQUIRED. In particular, transitive usage requirements
5498 or the use of compile features can raise the required language standard
5499 above what <LANG>_STANDARD specifies.
5500 These properties are initialized by the value of the
5502 CMAKE_<LANG>_STANDARD variable if it is set when a target is created.
5503 For supported values and CMake versions see the respective pages. To
5505 control compiler-specific extensions see <LANG>_EXTENSIONS.
5506 See the cmake-compile-features(7) manual for information on compile
5508 features and a list of supported compilers.
5509 <LANG>_STANDARD_REQUIRED
5511 The variations are:
5512 • C_STANDARD_REQUIRED
5514 • CXX_STANDARD_REQUIRED
5516 • CUDA_STANDARD_REQUIRED
5518 • HIP_STANDARD_REQUIRED
5520 • OBJC_STANDARD_REQUIRED
5522 • OBJCXX_STANDARD_REQUIRED
5524 These properties specify whether the value of <LANG>_STANDARD is a re‐
5526 quirement. When false or unset, the <LANG>_STANDARD target property is
5527 treated as optional and may "decay" to a previous standard if the re‐
5528 quested standard is not available. When <LANG>_STANDARD_REQUIRED is
5529 set to true, <LANG>_STANDARD becomes a hard requirement and a fatal er‐
5530 ror will be issued if that requirement cannot be met.
5531 Note that the actual language standard used may be higher than that
5533 specified by <LANG>_STANDARD, regardless of the value of <LANG>_STAN‐
5534 DARD_REQUIRED. In particular, transitive usage requirements or the use
5535 of compile features can raise the required language standard above what
5536 <LANG>_STANDARD specifies.
5537 These properties are initialized by the value of the
5539 CMAKE_<LANG>_STANDARD_REQUIRED variable if it is set when a target is
5540 created.
5541 See the cmake-compile-features(7) manual for information on compile
5543 features and a list of supported compilers.
5544 <LANG>_VISIBILITY_PRESET
5546 Value for symbol visibility compile flags
5547 The <LANG>_VISIBILITY_PRESET property determines the value passed in a
5549 visibility related compile option, such as -fvisibility= for <LANG>.
5550 This property affects compilation in sources of all types of targets
5551 (subject to policy CMP0063).
5552 This property is initialized by the value of the
5554 CMAKE_<LANG>_VISIBILITY_PRESET variable if it is set when a target is
5555 created.
5556 LIBRARY_OUTPUT_DIRECTORY
5558 Output directory in which to build LIBRARY target files.
5559 This property specifies the directory into which library target files
5561 should be built. The property value may use generator expressions.
5562 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
5563 fig) append a per-configuration subdirectory to the specified directory
5564 unless a generator expression is used.
5565 This property is initialized by the value of the
5567 CMAKE_LIBRARY_OUTPUT_DIRECTORY variable if it is set when a target is
5568 created.
5569 See also the LIBRARY_OUTPUT_DIRECTORY_<CONFIG> target property.
5571 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
5573 Per-configuration output directory for LIBRARY target files.
5574 This is a per-configuration version of the LIBRARY_OUTPUT_DIRECTORY
5576 target property, but multi-configuration generators (Visual Studio Gen‐
5577 erators, Xcode) do NOT append a per-configuration subdirectory to the
5578 specified directory. This property is initialized by the value of the
5579 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
5580 target is created.
5581 Contents of LIBRARY_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
5583 sions.
5584 LIBRARY_OUTPUT_NAME
5586 Output name for LIBRARY target files.
5587 This property specifies the base name for library target files. It
5589 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
5590 See also the LIBRARY_OUTPUT_NAME_<CONFIG> target property.
5592 LIBRARY_OUTPUT_NAME_<CONFIG>
5594 Per-configuration output name for LIBRARY target files.
5595 This is the configuration-specific version of the LIBRARY_OUTPUT_NAME
5597 target property.
5598 LINK_DEPENDS
5600 Additional files on which a target binary depends for linking.
5601 Specifies a semicolon-separated list of full-paths to files on which
5603 the link rule for this target depends. The target binary will be
5604 linked if any of the named files is newer than it.
5605 This property is supported only by Ninja and Makefile Generators. It
5607 is intended to specify dependencies on "linker scripts" for custom
5608 Makefile link rules.
5609 Contents of LINK_DEPENDS may use "generator expressions" with the syn‐
5611 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5612 able expressions. See the cmake-buildsystem(7) manual for more on
5613 defining buildsystem properties.
5614 LINK_DEPENDS_NO_SHARED
5616 Do not depend on linked shared library files.
5617 Set this property to true to tell CMake generators not to add
5619 file-level dependencies on the shared library files linked by this tar‐
5620 get. Modification to the shared libraries will not be sufficient to
5621 re-link this target. Logical target-level dependencies will not be af‐
5622 fected so the linked shared libraries will still be brought up to date
5623 before this target is built.
5624 This property is initialized by the value of the
5626 CMAKE_LINK_DEPENDS_NO_SHARED variable if it is set when a target is
5627 created.
5628 LINK_DIRECTORIES
5630 New in version 3.13.
5631 List of directories to use for the link step of shared library, module
5634 and executable targets.
5635 This property holds a semicolon-separated list of directories specified
5637 so far for its target. Use the target_link_directories() command to
5638 append more search directories.
5639 This property is initialized by the LINK_DIRECTORIES directory property
5641 when a target is created, and is used by the generators to set the
5642 search directories for the linker.
5643 Contents of LINK_DIRECTORIES may use "generator expressions" with the
5645 syntax $<...>. See the cmake-generator-expressions(7) manual for
5646 available expressions. See the cmake-buildsystem(7) manual for more on
5647 defining buildsystem properties.
5648 LINK_FLAGS
5650 Additional flags to use when linking this target if it is a shared li‐
5651 brary, module library, or an executable. Static libraries need to use
5652 STATIC_LIBRARY_OPTIONS or STATIC_LIBRARY_FLAGS properties.
5653 The LINK_FLAGS property, managed as a string, can be used to add extra
5655 flags to the link step of a target. LINK_FLAGS_<CONFIG> will add to
5656 the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
5657 RELWITHDEBINFO, ...
5658 NOTE:
5660 This property has been superseded by LINK_OPTIONS property.
5661 LINK_FLAGS_<CONFIG>
5663 Per-configuration linker flags for a SHARED library, MODULE or EXE‐
5664 CUTABLE target.
5665 This is the configuration-specific version of LINK_FLAGS.
5667 NOTE:
5669 This property has been superseded by LINK_OPTIONS property.
5670 LINK_INTERFACE_LIBRARIES
5672 List public interface libraries for a shared library or executable.
5673 By default linking to a shared library target transitively links to
5675 targets with which the library itself was linked. For an executable
5676 with exports (see the ENABLE_EXPORTS target property) no default tran‐
5677 sitive link dependencies are used. This property replaces the default
5678 transitive link dependencies with an explicit list. When the target is
5679 linked into another target using the target_link_libraries() command,
5680 the libraries listed (and recursively their link interface libraries)
5681 will be provided to the other target also. If the list is empty then
5682 no transitive link dependencies will be incorporated when this target
5683 is linked into another target even if the default set is non-empty.
5684 This property is initialized by the value of the
5685 CMAKE_LINK_INTERFACE_LIBRARIES variable if it is set when a target is
5686 created. This property is ignored for STATIC libraries.
5687 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
5689 policy CMP0022 is NEW.
5690 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
5692 Creating Relocatable Packages
5694 Note that it is not advisable to populate the LINK_INTERFACE_LIBRARIES
5695 of a target with absolute paths to dependencies. That would hard-code
5696 into installed packages the library file paths for dependencies as
5697 found on the machine the package was made on.
5698 See the Creating Relocatable Packages section of the cmake-packages(7)
5700 manual for discussion of additional care that must be taken when speci‐
5701 fying usage requirements while creating packages for redistribution.
5702 LINK_INTERFACE_LIBRARIES_<CONFIG>
5704 Per-configuration list of public interface libraries for a target.
5705 This is the configuration-specific version of LINK_INTERFACE_LIBRARIES.
5707 If set, this property completely overrides the generic property for the
5708 named configuration.
5709 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
5711 policy CMP0022 is NEW.
5712 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
5714 Creating Relocatable Packages
5716 Note that it is not advisable to populate the LINK_INTERFACE_LI‐
5717 BRARIES_<CONFIG> of a target with absolute paths to dependencies. That
5718 would hard-code into installed packages the library file paths for de‐
5719 pendencies as found on the machine the package was made on.
5720 See the Creating Relocatable Packages section of the cmake-packages(7)
5722 manual for discussion of additional care that must be taken when speci‐
5723 fying usage requirements while creating packages for redistribution.
5724 LINK_INTERFACE_MULTIPLICITY
5726 Repetition count for STATIC libraries with cyclic dependencies.
5727 When linking to a STATIC library target with cyclic dependencies the
5729 linker may need to scan more than once through the archives in the
5730 strongly connected component of the dependency graph. CMake by default
5731 constructs the link line so that the linker will scan through the com‐
5732 ponent at least twice. This property specifies the minimum number of
5733 scans if it is larger than the default. CMake uses the largest value
5734 specified by any target in a component.
5735 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
5737 Per-configuration repetition count for cycles of STATIC libraries.
5738 This is the configuration-specific version of
5740 LINK_INTERFACE_MULTIPLICITY. If set, this property completely over‐
5741 rides the generic property for the named configuration.
5742 LINK_LIBRARIES
5744 List of direct link dependencies.
5745 This property specifies the list of libraries or targets which will be
5747 used for linking. In addition to accepting values from the
5748 target_link_libraries() command, values may be set directly on any tar‐
5749 get using the set_property() command.
5750 The value of this property is used by the generators to construct the
5752 link rule for the target. The direct link dependencies are linked
5753 first, followed by indirect dependencies from the transitive closure of
5754 the direct dependencies' INTERFACE_LINK_LIBRARIES properties. See pol‐
5755 icy CMP0022.
5756 Contents of LINK_LIBRARIES may use generator expressions with the syn‐
5758 tax $<...>. Policy CMP0131 affects the behavior of the LINK_ONLY gen‐
5759 erator expression for this property.
5760 See the cmake-buildsystem(7) manual for more on defining buildsystem
5762 properties.
5763 NOTE:
5765 A call to target_link_libraries(<target> ...) may update this prop‐
5766 erty on <target>. If <target> was not created in the same directory
5767 as the call then target_link_libraries() will wrap each entry with
5768 the form ::@(directory-id);...;::@, where the ::@ is literal and the
5769 (directory-id) is unspecified. This tells the generators that the
5770 named libraries must be looked up in the scope of the caller rather
5771 than in the scope in which the <target> was created. Valid direc‐
5772 tory ids are stripped on export by the install(EXPORT) and export()
5773 commands.
5774 In advanced use cases, the list of direct link dependencies specified
5776 by this property may be updated by usage requirements from dependen‐
5777 cies. See the INTERFACE_LINK_LIBRARIES_DIRECT and
5778 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties.
5779 LINK_LIBRARIES_ONLY_TARGETS
5781 New in version 3.23.
5782 Enforce that link items that can be target names are actually existing
5785 targets.
5786 Set this property to a true value to enable additional checks on the
5788 contents of the LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES target
5789 properties, typically populated by target_link_libraries(). Checks are
5790 also applied to libraries added to a target through the
5791 INTERFACE_LINK_LIBRARIES_DIRECT properties of its dependencies. CMake
5792 will verify that link items that might be target names actually name
5793 existing targets. An item is considered a possible target name if:
5794 • it does not contain a / or \, and
5796 • it does not start in -, and
5798 • (for historical reasons) it does not start in $ or `.
5800 This property is initialized by the value of the
5802 CMAKE_LINK_LIBRARIES_ONLY_TARGETS variable when a non-imported target
5803 is created. The property may be explicitly enabled on an imported tar‐
5804 get to check its link interface.
5805 In the following example, CMake will halt with an error at configure
5807 time because miLib is not a target:
5808 set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON)
5810 add_library(myLib STATIC myLib.c)
5811 add_executable(myExe myExe.c)
5812 target_link_libraries(myExe PRIVATE miLib) # typo for myLib
5813 In order to link toolchain-provided libraries by name while still en‐
5815 forcing LINK_LIBRARIES_ONLY_TARGETS, use an imported Interface Library
5816 with the IMPORTED_LIBNAME target property:
5817 add_library(toolchain::m INTERFACE IMPORTED)
5819 set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m")
5820 target_link_libraries(myExe PRIVATE toolchain::m)
5821 See also policy CMP0028.
5823 NOTE:
5825 If INTERFACE_LINK_LIBRARIES contains generator expressions, its ac‐
5826 tual list of link items may depend on the type and properties of the
5827 consuming target. In such cases CMake may not always detect names
5828 of missing targets that only appear for specific consumers. A fu‐
5829 ture version of CMake with improved heuristics may start triggering
5830 errors on projects accepted by previous versions of CMake.
5831 LINK_LIBRARY_OVERRIDE
5833 New in version 3.24.
5834 Override the library features associated with libraries from
5837 LINK_LIBRARY generator expressions. This can be used to resolve incom‐
5838 patible library features that result from specifying different features
5839 for the same library in different LINK_LIBRARY generator expressions.
5840 This property supports overriding multiple libraries and features. It
5842 expects a semicolon-separated list, where each list item has the fol‐
5843 lowing form:
5844 feature[,link-item]*
5846 For each comma-separated link-item, any existing library feature asso‐
5848 ciated with it will be ignored for the target this property is set on.
5849 The item will instead be associated with the specified feature. Each
5850 link-item can be anything that would be accepted as part of a li‐
5851 brary-list in a LINK_LIBRARY generator expression.
5852 add_library(lib1 ...)
5854 add_library(lib2 ...)
5855 add_library(lib3 ...)
5856 target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
5858 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
5859 target_link_libraries(lib3 PRIVATE lib1 lib2)
5860 # lib1 is associated with both feature2 and no feature. Without any override,
5862 # this would result in a fatal error at generation time for lib3.
5863 # Define an override to resolve the incompatible feature associations.
5864 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
5865 # lib1 and external will now be associated with feature2 instead when linking lib3
5867 It is also possible to override any feature with the pre-defined DE‐
5869 FAULT library feature. This effectively discards any feature for that
5870 link item, for that target only (lib3 in this example):
5871 # When linking lib3, discard any library feature for lib1, and use feature2 for external
5873 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
5874 "DEFAULT,lib1"
5875 "feature2,external"
5876 )
5877 The above example also demonstrates how to specify different feature
5879 overrides for different link items. See the
5880 LINK_LIBRARY_OVERRIDE_<LIBRARY> target property for an alternative way
5881 of overriding library features for individual libraries, which may be
5882 simpler in some cases. If both properties are defined and specify an
5883 override for the same link item, LINK_LIBRARY_OVERRIDE_<LIBRARY> takes
5884 precedence over LINK_LIBRARY_OVERRIDE.
5885 Contents of LINK_LIBRARY_OVERRIDE may use generator expressions.
5887 For more information about library features, see the
5889 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and
5890 CMAKE_LINK_LIBRARY_USING_<FEATURE> variables.
5891 LINK_LIBRARY_OVERRIDE_<LIBRARY>
5893 New in version 3.24.
5894 Override the library feature associated with <LIBRARY> from
5897 LINK_LIBRARY generator expressions. This can be used to resolve incom‐
5898 patible library features that result from specifying different features
5899 for <LIBRARY> in different LINK_LIBRARY generator expressions.
5900 When set on a target, this property holds a single library feature
5902 name, which will be applied to <LIBRARY> when linking that target.
5903 add_library(lib1 ...)
5905 add_library(lib2 ...)
5906 add_library(lib3 ...)
5907 target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
5909 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
5910 target_link_libraries(lib3 PRIVATE lib1 lib2)
5911 # lib1 is associated with both feature2 and no feature. Without any override,
5913 # this would result in a fatal error at generation time for lib3.
5914 # Define an override to resolve the incompatible feature associations.
5915 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
5916 # lib1 will now be associated with feature2 instead when linking lib3
5918 It is also possible to override any feature with the pre-defined DE‐
5920 FAULT library feature. This effectively discards any feature for that
5921 link item, for that target only (lib3 in this example):
5922 # When linking lib3, discard any library feature for lib1
5924 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
5925 See the LINK_LIBRARY_OVERRIDE target property for an alternative way of
5927 overriding library features for multiple libraries at once. If both
5928 properties are defined and specify an override for the same link item,
5929 LINK_LIBRARY_OVERRIDE_<LIBRARY> takes precedence over
5930 LINK_LIBRARY_OVERRIDE.
5931 Contents of LINK_LIBRARY_OVERRIDE_<LIBRARY> may use generator expres‐
5933 sions.
5934 For more information about library features, see the
5936 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and
5937 CMAKE_LINK_LIBRARY_USING_<FEATURE> variables.
5938 LINK_OPTIONS
5940 New in version 3.13.
5941 List of options to use for the link step of shared library, module and
5944 executable targets as well as the device link step. Targets that are
5945 static libraries need to use the STATIC_LIBRARY_OPTIONS target prop‐
5946 erty.
5947 These options are used for both normal linking and device linking (see
5949 policy CMP0105). To control link options for normal and device link
5950 steps, $<HOST_LINK> and $<DEVICE_LINK> generator expressions can be
5951 used.
5952 This property holds a semicolon-separated list of options specified so
5954 far for its target. Use the target_link_options() command to append
5955 more options.
5956 This property is initialized by the LINK_OPTIONS directory property
5958 when a target is created, and is used by the generators to set the op‐
5959 tions for the compiler.
5960 Contents of LINK_OPTIONS may use "generator expressions" with the syn‐
5962 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5963 able expressions. See the cmake-buildsystem(7) manual for more on
5964 defining buildsystem properties.
5965 NOTE:
5967 This property must be used in preference to LINK_FLAGS property.
5968 Host And Device Specific Link Options
5970 New in version 3.18: When a device link step is involved, which is con‐
5971 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
5972 properties and policy CMP0105, the raw options will be delivered to the
5973 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
5974 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
5975 sion will be used only for the device link step. Options wrapped with
5976 $<HOST_LINK:...> generator expression will be used only for the host
5977 link step.
5978 Option De-duplication
5981 The final set of options used for a target is constructed by accumulat‐
5982 ing options from the current target and the usage requirements of its
5983 dependencies. The set of options is de-duplicated to avoid repetition.
5984 New in version 3.12: While beneficial for individual options, the
5986 de-duplication step can break up option groups. For example, -option A
5987 -option B becomes -option A B. One may specify a group of options us‐
5988 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
5989 is dropped, and the rest of the option string is parsed using the
5990 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
5991 "SHELL:-option B" becomes -option A -option B.
5992 Handling Compiler Driver Differences
5995 To pass options to the linker tool, each compiler driver has its own
5996 syntax. The LINKER: prefix and , separator can be used to specify, in
5997 a portable way, options to pass to the linker tool. LINKER: is replaced
5998 by the appropriate driver option and , by the appropriate driver sepa‐
5999 rator. The driver prefix and driver separator are given by the values
6000 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6001 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6002 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6004 Clang and -Wl,-z,defs for GNU GCC.
6005 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6007 sion.
6008 The LINKER: prefix supports, as an alternative syntax, specification of
6010 arguments using the SHELL: prefix and space as separator. The previous
6011 example then becomes "LINKER:SHELL:-z defs".
6012 NOTE:
6014 Specifying the SHELL: prefix anywhere other than at the beginning of
6015 the LINKER: prefix is not supported.
6016 LINK_SEARCH_END_STATIC
6018 End a link line such that static system libraries are used.
6019 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
6021 mine whether to use static or shared libraries for -lXXX options.
6022 CMake uses these options to set the link type for libraries whose full
6023 paths are not known or (in some cases) are in implicit link directories
6024 for the platform. By default CMake adds an option at the end of the
6025 library list (if necessary) to set the linker search type back to its
6026 starting type. This property switches the final linker search type to
6027 -Bstatic regardless of how it started.
6028 This property is initialized by the value of the variable
6030 CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created.
6031 See also LINK_SEARCH_START_STATIC.
6033 LINK_SEARCH_START_STATIC
6035 Assume the linker looks for static libraries by default.
6036 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
6038 mine whether to use static or shared libraries for -lXXX options.
6039 CMake uses these options to set the link type for libraries whose full
6040 paths are not known or (in some cases) are in implicit link directories
6041 for the platform. By default the linker search type is assumed to be
6042 -Bdynamic at the beginning of the library list. This property switches
6043 the assumption to -Bstatic. It is intended for use when linking an ex‐
6044 ecutable statically (e.g. with the GNU -static option).
6045 This property is initialized by the value of the variable
6047 CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is
6048 created.
6049 See also LINK_SEARCH_END_STATIC.
6051 LINK_WHAT_YOU_USE
6053 New in version 3.7.
6054 This is a boolean option that, when set to TRUE, will automatically run
6057 contents of variable CMAKE_LINK_WHAT_YOU_USE_CHECK on the target after
6058 it is linked. In addition, the linker flag specified by variable
6059 CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG will be passed to the target with
6060 the link command so that all libraries specified on the command line
6061 will be linked into the target. This will result in the link producing
6062 a list of libraries that provide no symbols used by this target but are
6063 being linked to it.
6064 NOTE:
6066 For now, it is only supported for ELF platforms and is only applica‐
6067 ble to executable and shared or module library targets. This prop‐
6068 erty will be ignored for any other targets and configurations.
6069 This property is initialized by the value of the
6071 CMAKE_LINK_WHAT_YOU_USE variable if it is set when a target is created.
6072 LINKER_LANGUAGE
6074 Specifies language whose compiler will invoke the linker.
6075 For executables, shared libraries, and modules, this sets the language
6077 whose compiler is used to link the target (such as "C" or "CXX"). A
6078 typical value for an executable is the language of the source file pro‐
6079 viding the program entry point (main). If not set, the language with
6080 the highest linker preference value is the default. Details of the
6081 linker preferences are considered internal, but some limited discussion
6082 can be found under the internal CMAKE_<LANG>_LINKER_PREFERENCE vari‐
6083 ables.
6084 If this property is not set by the user, it will be calculated at gen‐
6086 erate-time by CMake.
6087 LOCATION
6089 Read-only location of a target on disk.
6090 For an imported target, this read-only property returns the value of
6092 the LOCATION_<CONFIG> property for an unspecified configuration <CON‐
6093 FIG> provided by the target.
6094 For a non-imported target, this property is provided for compatibility
6096 with CMake 2.4 and below. It was meant to get the location of an exe‐
6097 cutable target's output file for use in add_custom_command(). The path
6098 may contain a build-system-specific portion that is replaced at build
6099 time with the configuration getting built (such as $(ConfigurationName)
6100 in VS). In CMake 2.6 and above add_custom_command() automatically rec‐
6101 ognizes a target name in its COMMAND and DEPENDS options and computes
6102 the target location. In CMake 2.8.4 and above add_custom_command()
6103 recognizes generator expressions to refer to target locations anywhere
6104 in the command. Therefore this property is not needed for creating
6105 custom commands.
6106 Do not set properties that affect the location of a target after read‐
6108 ing this property. These include properties whose names match (RUN‐
6109 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IM‐
6110 PLIB_)?(PREFIX|SUFFIX), or "LINKER_LANGUAGE". Failure to follow this
6111 rule is not diagnosed and leaves the location of the target undefined.
6112 LOCATION_<CONFIG>
6114 Read-only property providing a target location on disk.
6115 A read-only property that indicates where a target's main file is lo‐
6117 cated on disk for the configuration <CONFIG>. The property is defined
6118 only for library and executable targets. An imported target may pro‐
6119 vide a set of configurations different from that of the importing
6120 project. By default CMake looks for an exact-match but otherwise uses
6121 an arbitrary available configuration. Use the
6122 MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations
6123 explicitly.
6124 Do not set properties that affect the location of a target after read‐
6126 ing this property. These include properties whose names match (RUN‐
6127 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IM‐
6128 PLIB_)?(PREFIX|SUFFIX), or LINKER_LANGUAGE. Failure to follow this
6129 rule is not diagnosed and leaves the location of the target undefined.
6130 MACHO_COMPATIBILITY_VERSION
6132 New in version 3.17.
6133 What compatibility version number is this target for Mach-O binaries.
6136 For shared libraries on Mach-O systems (e.g. macOS, iOS) the MACHO_COM‐
6138 PATIBILITY_VERSION property corresponds to the compatibility version
6139 and MACHO_CURRENT_VERSION corresponds to the current version. These
6140 are both embedded in the shared library binary and can be checked with
6141 the otool -L <binary> command.
6142 It should be noted that the MACHO_CURRENT_VERSION and MACHO_COMPATIBIL‐
6144 ITY_VERSION properties do not affect the file names or version-related
6145 symlinks that CMake generates for the library. The VERSION and
6146 SOVERSION target properties still control the file and symlink names.
6147 The install_name is also still controlled by SOVERSION.
6148 When MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION are not
6150 given, VERSION and SOVERSION are used for the version details to be em‐
6151 bedded in the binaries respectively. The MACHO_CURRENT_VERSION and MA‐
6152 CHO_COMPATIBILITY_VERSION properties only need to be given if the
6153 project needs to decouple the file and symlink naming from the version
6154 details embedded in the binaries (e.g. to match libtool conventions).
6155 MACHO_CURRENT_VERSION
6157 New in version 3.17.
6158 What current version number is this target for Mach-O binaries.
6161 For shared libraries on Mach-O systems (e.g. macOS, iOS) the
6163 MACHO_COMPATIBILITY_VERSION property corresponds to the compatibility
6164 version and MACHO_CURRENT_VERSION corresponds to the current version.
6165 These are both embedded in the shared library binary and can be checked
6166 with the otool -L <binary> command.
6167 It should be noted that the MACHO_CURRENT_VERSION and
6169 MACHO_COMPATIBILITY_VERSION properties do not affect the file names or
6170 version-related symlinks that CMake generates for the library. The
6171 VERSION and SOVERSION target properties still control the file and sym‐
6172 link names. The install_name is also still controlled by SOVERSION.
6173 When MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION are not
6175 given, VERSION and SOVERSION are used for the version details to be em‐
6176 bedded in the binaries respectively. The MACHO_CURRENT_VERSION and
6177 MACHO_COMPATIBILITY_VERSION properties only need to be given if the
6178 project needs to decouple the file and symlink naming from the version
6179 details embedded in the binaries (e.g. to match libtool conventions).
6180 MACOSX_BUNDLE
6182 Build an executable as an Application Bundle on macOS or iOS.
6183 When this property is set to TRUE the executable when built on macOS or
6185 iOS will be created as an application bundle. This makes it a GUI exe‐
6186 cutable that can be launched from the Finder. See the
6187 MACOSX_BUNDLE_INFO_PLIST target property for information about creation
6188 of the Info.plist file for the application bundle. This property is
6189 initialized by the value of the variable CMAKE_MACOSX_BUNDLE if it is
6190 set when a target is created.
6191 MACOSX_BUNDLE_INFO_PLIST
6193 Specify a custom Info.plist template for a macOS and iOS Application
6194 Bundle.
6195 An executable target with MACOSX_BUNDLE enabled will be built as an ap‐
6197 plication bundle on macOS. By default its Info.plist file is created
6198 by configuring a template called MacOSXBundleInfo.plist.in located in
6199 the CMAKE_MODULE_PATH. This property specifies an alternative template
6200 file name which may be a full path.
6201 The following target properties may be set to specify content to be
6203 configured into the file:
6204 MACOSX_BUNDLE_BUNDLE_NAME
6206 Sets CFBundleName.
6207 MACOSX_BUNDLE_BUNDLE_VERSION
6209 Sets CFBundleVersion.
6210 MACOSX_BUNDLE_COPYRIGHT
6212 Sets NSHumanReadableCopyright.
6213 MACOSX_BUNDLE_GUI_IDENTIFIER
6215 Sets CFBundleIdentifier.
6216 MACOSX_BUNDLE_ICON_FILE
6218 Sets CFBundleIconFile.
6219 MACOSX_BUNDLE_INFO_STRING
6221 Sets CFBundleGetInfoString.
6222 MACOSX_BUNDLE_LONG_VERSION_STRING
6224 Sets CFBundleLongVersionString.
6225 MACOSX_BUNDLE_SHORT_VERSION_STRING
6227 Sets CFBundleShortVersionString.
6228 CMake variables of the same name may be set to affect all targets in a
6230 directory that do not have each specific property set. If a custom
6231 Info.plist is specified by this property it may of course hard-code all
6232 the settings instead of using the target properties.
6233 MACOSX_FRAMEWORK_INFO_PLIST
6235 Specify a custom Info.plist template for a macOS and iOS Framework.
6236 A library target with FRAMEWORK enabled will be built as a framework on
6238 macOS. By default its Info.plist file is created by configuring a tem‐
6239 plate called MacOSXFrameworkInfo.plist.in located in the
6240 CMAKE_MODULE_PATH. This property specifies an alternative template
6241 file name which may be a full path.
6242 The following target properties may be set to specify content to be
6244 configured into the file:
6245 MACOSX_FRAMEWORK_BUNDLE_VERSION
6247 Sets CFBundleVersion.
6248 MACOSX_FRAMEWORK_ICON_FILE
6250 Sets CFBundleIconFile.
6251 MACOSX_FRAMEWORK_IDENTIFIER
6253 Sets CFBundleIdentifier.
6254 MACOSX_FRAMEWORK_SHORT_VERSION_STRING
6256 Sets CFBundleShortVersionString.
6257 CMake variables of the same name may be set to affect all targets in a
6259 directory that do not have each specific property set. If a custom
6260 Info.plist is specified by this property it may of course hard-code all
6261 the settings instead of using the target properties.
6262 MACOSX_RPATH
6264 Whether this target on macOS or iOS is located at runtime using rpaths.
6265 When this property is set to TRUE, the directory portion of the in‐
6267 stall_name field of this shared library will be @rpath unless overrid‐
6268 den by INSTALL_NAME_DIR. This indicates the shared library is to be
6269 found at runtime using runtime paths (rpaths).
6270 This property is initialized by the value of the variable
6272 CMAKE_MACOSX_RPATH if it is set when a target is created.
6273 Runtime paths will also be embedded in binaries using this target and
6275 can be controlled by the INSTALL_RPATH target property on the target
6276 linking to this target.
6277 Policy CMP0042 was introduced to change the default value of MA‐
6279 COSX_RPATH to TRUE. This is because use of @rpath is a more flexible
6280 and powerful alternative to @executable_path and @loader_path.
6281 MANUALLY_ADDED_DEPENDENCIES
6283 New in version 3.8.
6284 Get manually added dependencies to other top-level targets.
6287 This read-only property can be used to query all dependencies that were
6289 added for this target with the add_dependencies() command.
6290 MAP_IMPORTED_CONFIG_<CONFIG>
6292 Map from project configuration to imported target's configuration.
6293 Set this to the list of configurations of an imported target that may
6295 be used for the current project's <CONFIG> configuration. Targets im‐
6296 ported from another project may not provide the same set of configura‐
6297 tion names available in the current project. Setting this property
6298 tells CMake what imported configurations are suitable for use when
6299 building the <CONFIG> configuration. The first configuration in the
6300 list found to be provided by the imported target (i.e. via
6301 IMPORTED_LOCATION_<CONFIG> for the mapped-to <CONFIG>) is selected. As
6302 a special case, an empty list element refers to the configuration-less
6303 imported target location (i.e. IMPORTED_LOCATION).
6304 If this property is set and no matching configurations are available,
6306 then the imported target is considered to be not found. This property
6307 is ignored for non-imported targets.
6308 This property is initialized by the value of the
6310 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable if it is set when a target
6311 is created.
6312 Example
6314 For example creating imported C++ library foo:
6315 add_library(foo STATIC IMPORTED)
6317 Use foo_debug path for Debug build type:
6319 set_property(
6321 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG
6322 )
6323 set_target_properties(foo PROPERTIES
6325 IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
6326 IMPORTED_LOCATION_DEBUG "${foo_debug}"
6327 )
6328 Use foo_release path for Release build type:
6330 set_property(
6332 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE
6333 )
6334 set_target_properties(foo PROPERTIES
6336 IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
6337 IMPORTED_LOCATION_RELEASE "${foo_release}"
6338 )
6339 Use Release version of library for MinSizeRel and RelWithDebInfo build
6341 types:
6342 set_target_properties(foo PROPERTIES
6344 MAP_IMPORTED_CONFIG_MINSIZEREL Release
6345 MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
6346 )
6347 MSVC_DEBUG_INFORMATION_FORMAT
6349 New in version 3.25.
6350 Select debug information format when targeting the MSVC ABI.
6353 The allowed values are:
6355 Embedded
6357 Compile with -Z7 or equivalent flag(s) to produce object files
6358 with full symbolic debugging information.
6359 ProgramDatabase
6361 Compile with -Zi or equivalent flag(s) to produce a program
6362 database that contains all the symbolic debugging information.
6363 EditAndContinue
6365 Compile with -ZI or equivalent flag(s) to produce a program
6366 database that supports the Edit and Continue feature.
6367 The value is ignored on compilers not targeting the MSVC ABI, but an
6369 unsupported value will be rejected as an error when using a compiler
6370 targeting the MSVC ABI.
6371 The value may also be the empty string (""), in which case no debug in‐
6373 formation format flag will be added explicitly by CMake.
6374 Use generator expressions to support per-configuration specification.
6376 For example, the code:
6377 add_executable(foo foo.c)
6379 set_property(TARGET foo PROPERTY
6380 MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
6381 selects for the target foo the program database debug information for‐
6383 mat for the Debug configuration.
6384 If this property is not set, CMake selects a debug information format
6386 using the default value $<$<CONFIG:Debug,RelWithDebInfo>:Program‐
6387 Database>, if supported by the compiler, and otherwise $<$<CONFIG:De‐
6388 bug,RelWithDebInfo>:Embedded>.
6389 NOTE:
6391 This property has effect only when policy CMP0141 is set to NEW
6392 prior to the first project() or enable_language() command that en‐
6393 ables a language using a compiler targeting the MSVC ABI.
6394 MSVC_RUNTIME_LIBRARY
6396 New in version 3.15.
6397 Select the MSVC runtime library for use by compilers targeting the MSVC
6400 ABI.
6401 The allowed values are:
6403 MultiThreaded
6405 Compile with -MT or equivalent flag(s) to use a multi-threaded
6406 statically-linked runtime library.
6407 MultiThreadedDLL
6409 Compile with -MD or equivalent flag(s) to use a multi-threaded
6410 dynamically-linked runtime library.
6411 MultiThreadedDebug
6413 Compile with -MTd or equivalent flag(s) to use a multi-threaded
6414 statically-linked runtime library.
6415 MultiThreadedDebugDLL
6417 Compile with -MDd or equivalent flag(s) to use a multi-threaded
6418 dynamically-linked runtime library.
6419 The value is ignored on compilers not targeting the MSVC ABI, but an
6421 unsupported value will be rejected as an error when using a compiler
6422 targeting the MSVC ABI.
6423 The value may also be the empty string ("") in which case no runtime
6425 library selection flag will be added explicitly by CMake. Note that
6426 with Visual Studio Generators the native build system may choose to add
6427 its own default runtime library selection flag.
6428 Use generator expressions to support per-configuration specification.
6430 For example, the code:
6431 add_executable(foo foo.c)
6433 set_property(TARGET foo PROPERTY
6434 MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
6435 selects for the target foo a multi-threaded statically-linked runtime
6437 library with or without debug information depending on the configura‐
6438 tion.
6439 The property is initialized from the value of the
6441 CMAKE_MSVC_RUNTIME_LIBRARY variable, if it is set. If the property is
6442 not set, then CMake uses the default value MultiThreaded$<$<CONFIG:De‐
6443 bug>:Debug>DLL to select a MSVC runtime library.
6444 NOTE:
6446 This property has effect only when policy CMP0091 is set to NEW
6447 prior to the first project() or enable_language() command that en‐
6448 ables a language using a compiler targeting the MSVC ABI.
6449 NAME
6451 Logical name for the target.
6452 Read-only logical name for the target as used by CMake.
6454 NO_SONAME
6456 Whether to set soname when linking a shared library.
6457 Enable this boolean property if a generated SHARED library should not
6459 have soname set. Default is to set soname on all shared libraries as
6460 long as the platform supports it. Generally, use this property only
6461 for leaf private libraries or plugins. If you use it on normal shared
6462 libraries which other targets link against, on some platforms a linker
6463 will insert a full path to the library (as specified at link time) into
6464 the dynamic section of the dependent binary. Therefore, once in‐
6465 stalled, dynamic loader may eventually fail to locate the library for
6466 the binary.
6467 NO_SYSTEM_FROM_IMPORTED
6469 Do not treat include directories from the interfaces of consumed
6470 Imported Targets as system directories.
6471 The contents of the INTERFACE_INCLUDE_DIRECTORIES target property are
6473 treated as system includes when the consumed target's SYSTEM property
6474 is set to true. By default, SYSTEM is true for imported targets and
6475 false for other target types. If the NO_SYSTEM_FROM_IMPORTED property
6476 is set to true on a consuming target, compilation of sources in that
6477 consuming target will not treat the contents of the
6478 INTERFACE_INCLUDE_DIRECTORIES of consumed imported targets as system
6479 includes, even if that imported target's SYSTEM property is false.
6480 Directories listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES property
6482 of consumed targets are not affected by NO_SYSTEM_FROM_IMPORTED. Those
6483 directories will always be treated as system include directories by
6484 consumers.
6485 This property is initialized by the value of the
6487 CMAKE_NO_SYSTEM_FROM_IMPORTED variable if it is set when a target is
6488 created.
6489 See the EXPORT_NO_SYSTEM target property to set this behavior on the
6491 target providing the include directories rather than the target consum‐
6492 ing them.
6493 OBJC_EXTENSIONS
6495 New in version 3.16.
6496 Boolean specifying whether compiler specific extensions are requested.
6499 This property specifies whether compiler specific extensions should be
6501 used. For some compilers, this results in adding a flag such as
6502 -std=gnu11 instead of -std=c11 to the compile line. This property is
6503 ON by default. The basic OBJC standard level is controlled by the
6504 OBJC_STANDARD target property.
6505 If the property is not set, and the project has set the C_EXTENSIONS,
6507 the value of C_EXTENSIONS is set for OBJC_EXTENSIONS.
6508 See the cmake-compile-features(7) manual for information on compile
6510 features and a list of supported compilers.
6511 This property is initialized by the value of the CMAKE_OBJC_EXTENSIONS
6513 variable if set when a target is created and otherwise by the value of
6514 CMAKE_OBJC_EXTENSIONS_DEFAULT (see CMP0128).
6515 OBJC_STANDARD
6517 New in version 3.16.
6518 The OBJC standard whose features are requested to build this target.
6521 This property specifies the OBJC standard whose features are requested
6523 to build this target. For some compilers, this results in adding a
6524 flag such as -std=gnu11 to the compile line.
6525 Supported values are:
6527 90 Objective C89/C90
6529 99 Objective C99
6531 11 Objective C11
6533 If the value requested does not result in a compile flag being added
6535 for the compiler in use, a previous standard flag will be added in‐
6536 stead. This means that using:
6537 set_property(TARGET tgt PROPERTY OBJC_STANDARD 11)
6539 with a compiler which does not support -std=gnu11 or an equivalent flag
6541 will not result in an error or warning, but will instead add the
6542 -std=gnu99 or -std=gnu90 flag if supported. This "decay" behavior may
6543 be controlled with the OBJC_STANDARD_REQUIRED target property. Addi‐
6544 tionally, the OBJC_EXTENSIONS target property may be used to control
6545 whether compiler-specific extensions are enabled on a per-target basis.
6546 If the property is not set, and the project has set the C_STANDARD, the
6548 value of C_STANDARD is set for OBJC_STANDARD.
6549 See the cmake-compile-features(7) manual for information on compile
6551 features and a list of supported compilers.
6552 This property is initialized by the value of the CMAKE_OBJC_STANDARD
6554 variable if it is set when a target is created.
6555 OBJC_STANDARD_REQUIRED
6557 New in version 3.16.
6558 Boolean describing whether the value of OBJC_STANDARD is a requirement.
6561 If this property is set to ON, then the value of the OBJC_STANDARD tar‐
6563 get property is treated as a requirement. If this property is OFF or
6564 unset, the OBJC_STANDARD target property is treated as optional and may
6565 "decay" to a previous standard if the requested is not available.
6566 If the property is not set, and the project has set the
6568 C_STANDARD_REQUIRED, the value of C_STANDARD_REQUIRED is set for
6569 OBJC_STANDARD_REQUIRED.
6570 See the cmake-compile-features(7) manual for information on compile
6572 features and a list of supported compilers.
6573 This property is initialized by the value of the
6575 CMAKE_OBJC_STANDARD_REQUIRED variable if it is set when a target is
6576 created.
6577 OBJCXX_EXTENSIONS
6579 New in version 3.16.
6580 Boolean specifying whether compiler specific extensions are requested.
6583 This property specifies whether compiler specific extensions should be
6585 used. For some compilers, this results in adding a flag such as
6586 -std=gnu++11 instead of -std=c++11 to the compile line. This property
6587 is ON by default. The basic ObjC++ standard level is controlled by the
6588 OBJCXX_STANDARD target property.
6589 See the cmake-compile-features(7) manual for information on compile
6591 features and a list of supported compilers.
6592 If the property is not set, and the project has set the CXX_EXTENSIONS,
6594 the value of CXX_EXTENSIONS is set for OBJCXX_EXTENSIONS.
6595 This property is initialized by the value of the
6597 CMAKE_OBJCXX_EXTENSIONS variable if set when a target is created and
6598 otherwise by the value of CMAKE_OBJCXX_EXTENSIONS_DEFAULT (see
6599 CMP0128).
6600 OBJCXX_STANDARD
6602 New in version 3.16.
6603 The ObjC++ standard whose features are requested to build this target.
6606 This property specifies the ObjC++ standard whose features are re‐
6608 quested to build this target. For some compilers, this results in
6609 adding a flag such as -std=gnu++11 to the compile line.
6610 Supported values are:
6612 98 Objective C++98
6614 11 Objective C++11
6616 14 Objective C++14
6618 17 Objective C++17
6620 20 Objective C++20
6622 23 New in version 3.20.
6624 Objective C++23
6627 26 New in version 3.25.
6629 Objective C++26. CMake 3.25 and later recognize 26 as a valid
6632 value, no version has support for any compiler.
6633 If the value requested does not result in a compile flag being added
6635 for the compiler in use, a previous standard flag will be added in‐
6636 stead. This means that using:
6637 set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11)
6639 with a compiler which does not support -std=gnu++11 or an equivalent
6641 flag will not result in an error or warning, but will instead add the
6642 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
6643 trolled with the OBJCXX_STANDARD_REQUIRED target property. Addition‐
6644 ally, the OBJCXX_EXTENSIONS target property may be used to control
6645 whether compiler-specific extensions are enabled on a per-target basis.
6646 If the property is not set, and the project has set the CXX_STANDARD,
6648 the value of CXX_STANDARD is set for OBJCXX_STANDARD.
6649 See the cmake-compile-features(7) manual for information on compile
6651 features and a list of supported compilers.
6652 This property is initialized by the value of the CMAKE_OBJCXX_STANDARD
6654 variable if it is set when a target is created.
6655 OBJCXX_STANDARD_REQUIRED
6657 New in version 3.16.
6658 Boolean describing whether the value of OBJCXX_STANDARD is a require‐
6661 ment.
6662 If this property is set to ON, then the value of the OBJCXX_STANDARD
6664 target property is treated as a requirement. If this property is OFF
6665 or unset, the OBJCXX_STANDARD target property is treated as optional
6666 and may "decay" to a previous standard if the requested is not avail‐
6667 able.
6668 If the property is not set, and the project has set the
6670 CXX_STANDARD_REQUIRED, the value of CXX_STANDARD_REQUIRED is set for
6671 OBJCXX_STANDARD_REQUIRED.
6672 See the cmake-compile-features(7) manual for information on compile
6674 features and a list of supported compilers.
6675 This property is initialized by the value of the
6677 CMAKE_OBJCXX_STANDARD_REQUIRED variable if it is set when a target is
6678 created.
6679 OPTIMIZE_DEPENDENCIES
6681 New in version 3.19.
6682 Activates dependency optimization of static and object libraries.
6685 When this property is set to true, some dependencies for a static or
6687 object library may be removed at generation time if they are not neces‐
6688 sary to build the library, since static and object libraries don't ac‐
6689 tually link against anything.
6690 If a static or object library has dependency optimization enabled, it
6692 first discards all dependencies. Then, it looks through all of the di‐
6693 rect and indirect dependencies that it initially had, and adds them
6694 back if they meet any of the following criteria:
6695 • The dependency was added to the library by add_dependencies().
6697 • The dependency was added to the library through a source file in the
6699 library generated by a custom command that uses the dependency.
6700 • The dependency has any PRE_BUILD, PRE_LINK, or POST_BUILD custom com‐
6702 mands associated with it.
6703 • The dependency contains any source files that were generated by a
6705 custom command.
6706 • The dependency contains any languages which produce side effects that
6708 are relevant to the library. Currently, all languages except C, C++,
6709 Objective-C, Objective-C++, assembly, and CUDA are assumed to produce
6710 side effects. However, side effects from one language are assumed
6711 not to be relevant to another (for example, a Fortran library is as‐
6712 sumed to not have any side effects that are relevant for a Swift li‐
6713 brary.)
6714 As an example, assume you have a static Fortran library which depends
6716 on a static C library, which in turn depends on a static Fortran li‐
6717 brary. The top-level Fortran library has optimization enabled, but the
6718 middle C library does not. If you build the top Fortran library, the
6719 bottom Fortran library will also build, but not the middle C library,
6720 since the C library does not have any side effects that are relevant
6721 for the Fortran library. However, if you build the middle C library,
6722 the bottom Fortran library will also build, even though it does not
6723 have any side effects that are relevant to the C library, since the C
6724 library does not have optimization enabled.
6725 This property is initialized by the value of the
6727 CMAKE_OPTIMIZE_DEPENDENCIES variable when the target is created.
6728 OSX_ARCHITECTURES
6730 Target specific architectures for macOS.
6731 The OSX_ARCHITECTURES property sets the target binary architecture for
6733 targets on macOS (-arch). This property is initialized by the value of
6734 the variable CMAKE_OSX_ARCHITECTURES if it is set when a target is cre‐
6735 ated. Use OSX_ARCHITECTURES_<CONFIG> to set the binary architectures
6736 on a per-configuration basis, where <CONFIG> is an upper-case name
6737 (e.g. OSX_ARCHITECTURES_DEBUG).
6738 OSX_ARCHITECTURES_<CONFIG>
6740 Per-configuration macOS and iOS binary architectures for a target.
6741 This property is the configuration-specific version of
6743 OSX_ARCHITECTURES.
6744 OUTPUT_NAME
6746 Output name for target files.
6747 This sets the base name for output files created for an executable or
6749 library target. If not set, the logical target name is used by default
6750 during generation. The value is not set by default during configura‐
6751 tion.
6752 Contents of OUTPUT_NAME and the variants listed below may use generator
6754 expressions.
6755 See also the variants:
6757 • OUTPUT_NAME_<CONFIG>
6759 • ARCHIVE_OUTPUT_NAME_<CONFIG>
6761 • ARCHIVE_OUTPUT_NAME
6763 • LIBRARY_OUTPUT_NAME_<CONFIG>
6765 • LIBRARY_OUTPUT_NAME
6767 • RUNTIME_OUTPUT_NAME_<CONFIG>
6769 • RUNTIME_OUTPUT_NAME
6771 OUTPUT_NAME_<CONFIG>
6773 Per-configuration target file base name.
6774 This is the configuration-specific version of the OUTPUT_NAME target
6776 property.
6777 PCH_INSTANTIATE_TEMPLATES
6779 New in version 3.19.
6780 When this property is set to true, the precompiled header compiler op‐
6783 tions will contain a flag to instantiate templates during the genera‐
6784 tion of the PCH if supported. This can significantly improve compile
6785 times. Supported in Clang since version 11.
6786 This property is initialized by the value of the
6788 CMAKE_PCH_INSTANTIATE_TEMPLATES variable if it is set when a target is
6789 created. If that variable is not set, the property defaults to ON.
6790 PCH_WARN_INVALID
6792 New in version 3.18.
6793 When this property is set to true, the precompile header compiler op‐
6796 tions will contain a compiler flag which should warn about invalid pre‐
6797 compiled headers e.g. -Winvalid-pch for GNU compiler.
6798 This property is initialized by the value of the CMAKE_PCH_WARN_INVALID
6800 variable if it is set when a target is created. If that variable is
6801 not set, the property defaults to ON.
6802 PDB_NAME
6804 Output name for the MS debug symbol .pdb file generated by the linker
6805 for an executable or shared library target.
6806 This property specifies the base name for the debug symbols file. If
6808 not set, the OUTPUT_NAME target property value or logical target name
6809 is used by default.
6810 NOTE:
6812 This property does not apply to STATIC library targets because no
6813 linker is invoked to produce them so they have no linker-generated
6814 .pdb file containing debug symbols.
6815 The linker-generated program database files are specified by the
6817 /pdb linker flag and are not the same as compiler-generated program
6818 database files specified by the /Fd compiler flag. Use the
6819 COMPILE_PDB_NAME property to specify the latter.
6820 PDB_NAME_<CONFIG>
6822 Per-configuration output name for the MS debug symbol .pdb file gener‐
6823 ated by the linker for an executable or shared library target.
6824 This is the configuration-specific version of PDB_NAME.
6826 NOTE:
6828 This property does not apply to STATIC library targets because no
6829 linker is invoked to produce them so they have no linker-generated
6830 .pdb file containing debug symbols.
6831 The linker-generated program database files are specified by the
6833 /pdb linker flag and are not the same as compiler-generated program
6834 database files specified by the /Fd compiler flag. Use the
6835 COMPILE_PDB_NAME_<CONFIG> property to specify the latter.
6836 PDB_OUTPUT_DIRECTORY
6838 Output directory for the MS debug symbols .pdb file generated by the
6839 linker for an executable or shared library target.
6840 This property specifies the directory into which the MS debug symbols
6842 will be placed by the linker. The property value may use generator ex‐
6843 pressions. Multi-configuration generators append a per-configuration
6844 subdirectory to the specified directory unless a generator expression
6845 is used.
6846 This property is initialized by the value of the
6848 CMAKE_PDB_OUTPUT_DIRECTORY variable if it is set when a target is cre‐
6849 ated.
6850 NOTE:
6852 This property does not apply to STATIC library targets because no
6853 linker is invoked to produce them so they have no linker-generated
6854 .pdb file containing debug symbols.
6855 The linker-generated program database files are specified by the
6857 /pdb linker flag and are not the same as compiler-generated program
6858 database files specified by the /Fd compiler flag. Use the
6859 COMPILE_PDB_OUTPUT_DIRECTORY property to specify the latter.
6860 PDB_OUTPUT_DIRECTORY_<CONFIG>
6862 Per-configuration output directory for the MS debug symbol .pdb file
6863 generated by the linker for an executable or shared library target.
6864 This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
6866 multi-configuration generators (Visual Studio Generators, Xcode) do NOT
6867 append a per-configuration subdirectory to the specified directory.
6868 This property is initialized by the value of the
6869 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a target
6870 is created.
6871 Contents of PDB_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
6873 sions.
6874 NOTE:
6876 This property does not apply to STATIC library targets because no
6877 linker is invoked to produce them so they have no linker-generated
6878 .pdb file containing debug symbols.
6879 The linker-generated program database files are specified by the
6881 /pdb linker flag and are not the same as compiler-generated program
6882 database files specified by the /Fd compiler flag. Use the
6883 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the lat‐
6884 ter.
6885 POSITION_INDEPENDENT_CODE
6887 Whether to create a position-independent target
6888 The POSITION_INDEPENDENT_CODE property determines whether position in‐
6890 dependent executables or shared libraries will be created. This prop‐
6891 erty is True by default for SHARED and MODULE library targets and False
6892 otherwise. This property is initialized by the value of the
6893 CMAKE_POSITION_INDEPENDENT_CODE variable if it is set when a target is
6894 created.
6895 NOTE:
6897 For executable targets, the link step is controlled by the CMP0083
6898 policy and the CheckPIESupported module.
6899 PRECOMPILE_HEADERS
6901 New in version 3.16.
6902 List of header files to precompile.
6905 This property holds a semicolon-separated list of header files to pre‐
6907 compile specified so far for its target. Use the
6908 target_precompile_headers() command to append more header files.
6909 This property supports generator expressions.
6911 PRECOMPILE_HEADERS_REUSE_FROM
6913 New in version 3.16.
6914 Target from which to reuse the precompiled headers build artifact.
6917 See the second signature of target_precompile_headers() command for
6919 more detailed information.
6920 PREFIX
6922 What comes before the library name.
6923 A target property that can be set to override the prefix (such as lib)
6925 on a library name.
6926 PRIVATE_HEADER
6928 Specify private header files in a FRAMEWORK shared library target.
6929 Shared library targets marked with the FRAMEWORK property generate
6931 frameworks on macOS, iOS and normal shared libraries on other plat‐
6932 forms. This property may be set to a list of header files to be placed
6933 in the PrivateHeaders directory inside the framework folder. On
6934 non-Apple platforms these headers may be installed using the PRI‐
6935 VATE_HEADER option to the install(TARGETS) command.
6936 PROJECT_LABEL
6938 Change the name of a target in an IDE.
6939 Can be used to change the name of the target in an IDE like Visual Stu‐
6941 dio.
6942 PUBLIC_HEADER
6944 Specify public header files in a FRAMEWORK shared library target.
6945 Shared library targets marked with the FRAMEWORK property generate
6947 frameworks on macOS, iOS and normal shared libraries on other plat‐
6948 forms. This property may be set to a list of header files to be placed
6949 in the Headers directory inside the framework folder. On non-Apple
6950 platforms these headers may be installed using the PUBLIC_HEADER option
6951 to the install(TARGETS) command.
6952 RESOURCE
6954 Specify resource files in a FRAMEWORK or BUNDLE.
6955 Target marked with the FRAMEWORK or BUNDLE property generate framework
6957 or application bundle (both macOS and iOS is supported) or normal
6958 shared libraries on other platforms. This property may be set to a
6959 list of files to be placed in the corresponding directory (eg. Re‐
6960 sources directory for macOS) inside the bundle. On non-Apple platforms
6961 these files may be installed using the RESOURCE option to the
6962 install(TARGETS) command.
6963 Following example of Application Bundle:
6965 add_executable(ExecutableTarget
6967 addDemo.c
6968 resourcefile.txt
6969 appresourcedir/appres.txt)
6970 target_link_libraries(ExecutableTarget heymath mul)
6972 set(RESOURCE_FILES
6974 resourcefile.txt
6975 appresourcedir/appres.txt)
6976 set_target_properties(ExecutableTarget PROPERTIES
6978 MACOSX_BUNDLE TRUE
6979 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget
6980 RESOURCE "${RESOURCE_FILES}")
6981 will produce flat structure for iOS systems:
6983 ExecutableTarget.app
6985 appres.txt
6986 ExecutableTarget
6987 Info.plist
6988 resourcefile.txt
6989 For macOS systems it will produce following directory structure:
6991 ExecutableTarget.app/
6993 Contents
6994 Info.plist
6995 MacOS
6996 ExecutableTarget
6997 Resources
6998 appres.txt
6999 resourcefile.txt
7000 For Linux, such CMake script produce following files:
7002 ExecutableTarget
7004 Resources
7005 appres.txt
7006 resourcefile.txt
7007 RULE_LAUNCH_COMPILE
7009 Specify a launcher for compile rules.
7010 NOTE:
7012 This property is intended for internal use by ctest(1). Projects
7013 and developers should use the <LANG>_COMPILER_LAUNCHER target prop‐
7014 erties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables
7015 instead.
7016 See the global property of the same name for details. This overrides
7018 the global and directory property for a target.
7019 RULE_LAUNCH_CUSTOM
7021 Specify a launcher for custom rules.
7022 See the global property of the same name for details. This overrides
7024 the global and directory property for a target.
7025 RULE_LAUNCH_LINK
7027 Specify a launcher for link rules.
7028 NOTE:
7030 This property is intended for internal use by ctest(1). Projects
7031 and developers should use the <LANG>_LINKER_LAUNCHER target proper‐
7032 ties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables in‐
7033 stead.
7034 See the global property of the same name for details. This overrides
7036 the global and directory property for a target.
7037 RUNTIME_OUTPUT_DIRECTORY
7039 Output directory in which to build RUNTIME target files.
7040 This property specifies the directory into which runtime target files
7042 should be built. The property value may use generator expressions.
7043 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
7044 fig) append a per-configuration subdirectory to the specified directory
7045 unless a generator expression is used.
7046 This property is initialized by the value of the
7048 CMAKE_RUNTIME_OUTPUT_DIRECTORY variable if it is set when a target is
7049 created.
7050 See also the RUNTIME_OUTPUT_DIRECTORY_<CONFIG> target property.
7052 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
7054 Per-configuration output directory for RUNTIME target files.
7055 This is a per-configuration version of the RUNTIME_OUTPUT_DIRECTORY
7057 target property, but multi-configuration generators (Visual Studio Gen‐
7058 erators, Xcode) do NOT append a per-configuration subdirectory to the
7059 specified directory. This property is initialized by the value of the
7060 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
7061 target is created.
7062 Contents of RUNTIME_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
7064 sions.
7065 RUNTIME_OUTPUT_NAME
7067 Output name for RUNTIME target files.
7068 This property specifies the base name for runtime target files. It
7070 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
7071 See also the RUNTIME_OUTPUT_NAME_<CONFIG> target property.
7073 RUNTIME_OUTPUT_NAME_<CONFIG>
7075 Per-configuration output name for RUNTIME target files.
7076 This is the configuration-specific version of the RUNTIME_OUTPUT_NAME
7078 target property.
7079 SKIP_BUILD_RPATH
7081 Should rpaths be used for the build tree.
7082 SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic gen‐
7084 eration of an rpath allowing the target to run from the build tree.
7085 This property is initialized by the value of the variable
7086 CMAKE_SKIP_BUILD_RPATH if it is set when a target is created.
7087 SOURCE_DIR
7089 New in version 3.4.
7090 This read-only property reports the value of the
7093 CMAKE_CURRENT_SOURCE_DIR variable in the directory in which the target
7094 was defined.
7095 SOURCES
7097 This specifies the list of paths to source files for the target. The
7098 following commands all set or add to the SOURCES target property and
7099 are the usual way to manipulate it:
7100 • add_executable()
7102 • add_library()
7104 • add_custom_target()
7106 • target_sources()
7108 Contents of SOURCES may use generator expressions. If a path starts
7110 with a generator expression, it is expected to evaluate to an absolute
7111 path. Not doing so is considered undefined behavior.
7112 Paths that are for files generated by the build will be treated as rel‐
7114 ative to the build directory of the target, if the path is not already
7115 specified as an absolute path. Note that whether a file is seen as
7116 generated may be affected by policy CMP0118.
7117 If a path does not start with a generator expression, is not an abso‐
7119 lute path and is not a generated file, it will be treated as relative
7120 to the location selected by the first of the following that matches:
7121 • If a file by the specified path exists relative to the target's
7123 source directory, use that file.
7124 • If policy CMP0115 is not set to NEW, try appending each known source
7126 file extension to the path and check if that exists relative to the
7127 target's source directory.
7128 • Repeat the above two steps, this time relative to the target's binary
7130 directory instead.
7131 Note that the above decisions are made at generation time, not build
7133 time.
7134 See the cmake-buildsystem(7) manual for more on defining buildsystem
7136 properties.
7137 SOVERSION
7139 What version number is this target.
7140 For shared libraries VERSION and SOVERSION can be used to specify the
7142 build version and API version respectively. When building or in‐
7143 stalling appropriate symlinks are created if the platform supports sym‐
7144 links and the linker supports so-names. If only one of both is speci‐
7145 fied the missing is assumed to have the same version number. SOVERSION
7146 is ignored if NO_SONAME property is set.
7147 Windows Versions
7149 For shared libraries and executables on Windows the VERSION attribute
7150 is parsed to extract a <major>.<minor> version number. These numbers
7151 are used as the image version of the binary.
7152 Mach-O Versions
7154 For shared libraries and executables on Mach-O systems (e.g. macOS,
7155 iOS), the SOVERSION property corresponds to the compatibility version
7156 and VERSION corresponds to the current version (unless Mach-O specific
7157 overrides are provided, as discussed below). See the FRAMEWORK target
7158 property for an example.
7159 For shared libraries, the MACHO_COMPATIBILITY_VERSION and
7161 MACHO_CURRENT_VERSION properties can be used to override the compati‐
7162 bility version and current version respectively. Note that SOVERSION
7163 will still be used to form the install_name and both SOVERSION and
7164 VERSION may also affect the file and symlink names.
7165 Versions of Mach-O binaries may be checked with the otool -L <binary>
7167 command.
7168 STATIC_LIBRARY_FLAGS
7170 Archiver (or MSVC librarian) flags for a static library target. Tar‐
7171 gets that are shared libraries, modules, or executables need to use the
7172 LINK_OPTIONS or LINK_FLAGS target properties.
7173 The STATIC_LIBRARY_FLAGS property, managed as a string, can be used to
7175 add extra flags to the link step of a static library target.
7176 STATIC_LIBRARY_FLAGS_<CONFIG> will add to the configuration <CONFIG>,
7177 for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO, ...
7178 NOTE:
7180 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
7181 erty.
7182 STATIC_LIBRARY_FLAGS_<CONFIG>
7184 Per-configuration archiver (or MSVC librarian) flags for a static li‐
7185 brary target.
7186 This is the configuration-specific version of STATIC_LIBRARY_FLAGS.
7188 NOTE:
7190 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
7191 erty.
7192 STATIC_LIBRARY_OPTIONS
7194 New in version 3.13.
7195 Archiver (or MSVC librarian) flags for a static library target. Tar‐
7198 gets that are shared libraries, modules, or executables need to use the
7199 LINK_OPTIONS target property.
7200 This property holds a semicolon-separated list of options specified so
7202 far for its target. Use set_target_properties() or set_property() com‐
7203 mands to set its content.
7204 Contents of STATIC_LIBRARY_OPTIONS may use "generator expressions" with
7206 the syntax $<...>. See the cmake-generator-expressions(7) manual for
7207 available expressions. See the cmake-buildsystem(7) manual for more on
7208 defining buildsystem properties.
7209 NOTE:
7211 This property must be used in preference to STATIC_LIBRARY_FLAGS
7212 property.
7213 Option De-duplication
7215 The final set of options used for a target is constructed by accumulat‐
7216 ing options from the current target and the usage requirements of its
7217 dependencies. The set of options is de-duplicated to avoid repetition.
7218 New in version 3.12: While beneficial for individual options, the
7220 de-duplication step can break up option groups. For example, -option A
7221 -option B becomes -option A B. One may specify a group of options us‐
7222 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
7223 is dropped, and the rest of the option string is parsed using the
7224 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
7225 "SHELL:-option B" becomes -option A -option B.
7226 SUFFIX
7229 What comes after the target name.
7230 A target property that can be set to override the suffix (such as .so
7232 or .exe) on the name of a library, module or executable.
7233 Swift_DEPENDENCIES_FILE
7235 New in version 3.15.
7236 This property sets the path for the Swift dependency file (swiftdep)
7239 for the target. If one is not specified, it will default to <TAR‐
7240 GET>.swiftdeps.
7241 Swift_LANGUAGE_VERSION
7243 New in version 3.16.
7244 This property sets the language version for the Swift sources in the
7247 target. If one is not specified, it will default to <CMAKE_Swift_LAN‐
7248 GUAGE_VERSION> if specified, otherwise it is the latest version sup‐
7249 ported by the compiler.
7250 Swift_MODULE_DIRECTORY
7252 New in version 3.15.
7253 Specify output directory for Swift modules provided by the target.
7256 If the target contains Swift source files, this specifies the directory
7258 in which the modules will be placed. When this property is not set,
7259 the modules will be placed in the build directory corresponding to the
7260 target's source directory. If the variable
7261 CMAKE_Swift_MODULE_DIRECTORY is set when a target is created its value
7262 is used to initialize this property.
7263 Swift_MODULE_NAME
7265 New in version 3.15.
7266 This property specifies the name of the Swift module. It is defaulted
7269 to the name of the target.
7270 SYSTEM
7272 New in version 3.25.
7273 Specifies that a target is a system target. This has the following ef‐
7276 fects:
7277 • Entries of INTERFACE_INCLUDE_DIRECTORIES are treated as system in‐
7279 clude directories when compiling consumers. Entries of
7280 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES are not affected, and will al‐
7281 ways be treated as system include directories.
7282 For imported targets, this property defaults to true, which means that
7284 their INTERFACE_INCLUDE_DIRECTORIES are treated as system directories
7285 by default. If their SYSTEM property is false, then their
7286 INTERFACE_INCLUDE_DIRECTORIES will not be treated as system. Use the
7287 EXPORT_NO_SYSTEM property to change how a target's SYSTEM property is
7288 set when it is installed.
7289 For non-imported targets, this target property is initialized from the
7291 SYSTEM directory property when the target is created.
7292 TYPE
7294 The type of the target.
7295 This read-only property can be used to test the type of the given tar‐
7297 get. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, SHARED_LIBRARY,
7298 OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal
7299 target types.
7300 UNITY_BUILD
7302 New in version 3.16.
7303 When this property is set to true, the target source files will be com‐
7306 bined into batches for faster compilation. This is done by creating a
7307 (set of) unity sources which #include the original sources, then com‐
7308 piling these unity sources instead of the originals. This is known as
7309 a Unity or Jumbo build.
7310 CMake provides different algorithms for selecting which sources are
7312 grouped together into a bucket. Algorithm selection is decided by the
7313 UNITY_BUILD_MODE target property, which has the following acceptable
7314 values:
7315 • BATCH When in this mode CMake determines which files are grouped to‐
7317 gether. The UNITY_BUILD_BATCH_SIZE property controls the upper limit
7318 on how many sources can be combined per unity source file.
7319 • GROUP When in this mode each target explicitly specifies how to group
7321 source files. Each source file that has the same UNITY_GROUP value
7322 will be grouped together. Any sources that don't have this property
7323 will be compiled individually. The UNITY_BUILD_BATCH_SIZE property is
7324 ignored when using this mode.
7325 If no explicit UNITY_BUILD_MODE has been specified, CMake will default
7327 to BATCH.
7328 Unity builds are not currently supported for all languages. CMake ver‐
7330 sion 3.25.2 supports combining C and CXX source files. For targets
7331 that mix source files from more than one language, CMake will separate
7332 the languages such that each generated unity source file only contains
7333 sources for a single language.
7334 This property is initialized by the value of the CMAKE_UNITY_BUILD
7336 variable when a target is created.
7337 NOTE:
7339 Projects should not directly set the UNITY_BUILD property or its as‐
7340 sociated CMAKE_UNITY_BUILD variable to true. Depending on the capa‐
7341 bilities of the build machine and compiler used, it might or might
7342 not be appropriate to enable unity builds. Therefore, this feature
7343 should be under developer control, which would normally be through
7344 the developer choosing whether or not to set the CMAKE_UNITY_BUILD
7345 variable on the cmake(1) command line or some other equivalent
7346 method. However, it IS recommended to set the UNITY_BUILD target
7347 property to false if it is known that enabling unity builds for the
7348 target can lead to problems.
7349 ODR (One definition rule) errors
7351 When multiple source files are included into one source file, as is
7352 done for unity builds, it can potentially lead to ODR errors. CMake
7353 provides a number of measures to help address such problems:
7354 • Any source file that has a non-empty COMPILE_OPTIONS,
7356 COMPILE_DEFINITIONS, COMPILE_FLAGS, or INCLUDE_DIRECTORIES source
7357 property will not be combined into a unity source.
7358 • Projects can prevent an individual source file from being combined
7360 into a unity source by setting its SKIP_UNITY_BUILD_INCLUSION source
7361 property to true. This can be a more effective way to prevent prob‐
7362 lems with specific files than disabling unity builds for an entire
7363 target.
7364 • Projects can set UNITY_BUILD_UNIQUE_ID to cause a valid C-identifier
7366 to be generated which is unique per file in a unity build. This can
7367 be used to avoid problems with anonymous namespaces in unity builds.
7368 • The UNITY_BUILD_CODE_BEFORE_INCLUDE and
7370 UNITY_BUILD_CODE_AFTER_INCLUDE target properties can be used to in‐
7371 ject code into the unity source files before and after every #include
7372 statement.
7373 • The order of source files added to the target via commands like
7375 add_library(), add_executable() or target_sources() will be preserved
7376 in the generated unity source files. This can be used to manually
7377 enforce a specific grouping based on the UNITY_BUILD_BATCH_SIZE tar‐
7378 get property.
7379 UNITY_BUILD_BATCH_SIZE
7381 New in version 3.16.
7382 Specifies the maximum number of source files that can be combined into
7385 any one unity source file when unity builds are enabled by the
7386 UNITY_BUILD target property. The original source files will be dis‐
7387 tributed across as many unity source files as necessary to honor this
7388 limit.
7389 The initial value for this property is taken from the
7391 CMAKE_UNITY_BUILD_BATCH_SIZE variable when the target is created. If
7392 that variable has not been set, the initial value will be 8.
7393 The batch size needs to be selected carefully. If set too high, the
7395 size of the combined source files could result in the compiler using
7396 excessive memory or hitting other similar limits. In extreme cases,
7397 this can even result in build failure. On the other hand, if the batch
7398 size is too low, there will be little gain in build performance.
7399 Although strongly discouraged, the batch size may be set to a value of
7401 0 to combine all the sources for the target into a single unity file,
7402 regardless of how many sources are involved. This runs the risk of
7403 creating an excessively large unity source file and negatively impact‐
7404 ing the build performance, so a value of 0 is not generally recom‐
7405 mended.
7406 UNITY_BUILD_CODE_AFTER_INCLUDE
7408 New in version 3.16.
7409 Code snippet which is included verbatim by the UNITY_BUILD feature just
7412 after every #include statement in the generated unity source files.
7413 For example:
7414 set(after [[
7416 #if defined(NOMINMAX)
7417 #undef NOMINMAX
7418 #endif
7419 ]])
7420 set_target_properties(myTarget PROPERTIES
7421 UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
7422 )
7423 See also UNITY_BUILD_CODE_BEFORE_INCLUDE.
7425 UNITY_BUILD_CODE_BEFORE_INCLUDE
7427 New in version 3.16.
7428 Code snippet which is included verbatim by the UNITY_BUILD feature just
7431 before every #include statement in the generated unity source files.
7432 For example:
7433 set(before [[
7435 #if !defined(NOMINMAX)
7436 #define NOMINMAX
7437 #endif
7438 ]])
7439 set_target_properties(myTarget PROPERTIES
7440 UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
7441 )
7442 See also UNITY_BUILD_CODE_AFTER_INCLUDE.
7444 UNITY_BUILD_MODE
7446 New in version 3.18.
7447 CMake provides different algorithms for selecting which sources are
7450 grouped together into a bucket. Selection is decided by this property,
7451 which has the following acceptable values:
7452 BATCH When in this mode CMake determines which files are grouped to‐
7454 gether. The UNITY_BUILD_BATCH_SIZE property controls the upper
7455 limit on how many sources can be combined per unity source file.
7456 Example usage:
7458 add_library(example_library
7460 source1.cxx
7461 source2.cxx
7462 source3.cxx
7463 source4.cxx)
7464 set_target_properties(example_library PROPERTIES
7466 UNITY_BUILD_MODE BATCH
7467 UNITY_BUILD_BATCH_SIZE 2
7468 )
7469 GROUP When in this mode each target explicitly specifies how to group
7471 source files. Each source file that has the same UNITY_GROUP
7472 value will be grouped together. Any sources that don't have this
7473 property will be compiled individually. The
7474 UNITY_BUILD_BATCH_SIZE property is ignored when using this mode.
7475 Example usage:
7477 add_library(example_library
7479 source1.cxx
7480 source2.cxx
7481 source3.cxx
7482 source4.cxx)
7483 set_target_properties(example_library PROPERTIES
7485 UNITY_BUILD_MODE GROUP
7486 )
7487 set_source_files_properties(source1.cxx source2.cxx source3.cxx
7489 PROPERTIES UNITY_GROUP "bucket1"
7490 )
7491 set_source_files_properties(source4.cxx
7492 PROPERTIES UNITY_GROUP "bucket2"
7493 )
7494 If no explicit UNITY_BUILD_MODE has been specified, CMake will default
7496 to BATCH.
7497 UNITY_BUILD_UNIQUE_ID
7499 New in version 3.20.
7500 The name of a valid C-identifier which is set to a unique per-file
7503 value during unity builds.
7504 When this property is populated and when UNITY_BUILD is true, the prop‐
7506 erty value is used to define a compiler definition of the specified
7507 name. The value of the defined symbol is unspecified, but it is unique
7508 per file path.
7509 Given:
7511 set_target_properties(myTarget PROPERTIES
7513 UNITY_BUILD "ON"
7514 UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID"
7515 )
7516 the MY_UNITY_ID symbol is defined to a unique per-file value.
7518 One known use case for this identifier is to disambiguate the variables
7520 in an anonymous namespace in a limited scope. Anonymous namespaces
7521 present a problem for unity builds because they are used to ensure that
7522 certain variables and declarations are scoped to a translation unit
7523 which is approximated by a single source file. When source files are
7524 combined in a unity build file, those variables in different files are
7525 combined in a single translation unit and the names clash. This prop‐
7526 erty can be used to avoid that with code like the following:
7527 // Needed for when unity builds are disabled
7529 #ifndef MY_UNITY_ID
7530 #define MY_UNITY_ID
7531 #endif
7532 namespace { namespace MY_UNITY_ID {
7534 // The name 'i' clashes (or could clash) with other
7535 // variables in other anonymous namespaces
7536 int i = 42;
7537 }}
7538 int use_var()
7540 {
7541 return MY_UNITY_ID::i;
7542 }
7543 The pseudonymous namespace is used within a truly anonymous namespace.
7545 On many platforms, this maintains the invariant that the symbols within
7546 do not get external linkage when performing a unity build.
7547 VERIFY_INTERFACE_HEADER_SETS
7549 New in version 3.24.
7550 Used to verify that all headers in a target's PUBLIC and INTERFACE
7553 header sets can be included on their own.
7554 When this property is set to true, and the target is an object library,
7556 static library, shared library, interface library, or executable with
7557 exports enabled, and the target has one or more PUBLIC or INTERFACE
7558 header sets, an object library target named <target_name>_verify_inter‐
7559 face_header_sets is created. This verification target has one source
7560 file per header in the PUBLIC and INTERFACE header sets. Each source
7561 file only includes its associated header file. The verification target
7562 links against the original target to get all of its usage requirements.
7563 The verification target has its EXCLUDE_FROM_ALL and
7564 DISABLE_PRECOMPILE_HEADERS properties set to true, and its AUTOMOC,
7565 AUTORCC, AUTOUIC, and UNITY_BUILD properties set to false.
7566 If the header's LANGUAGE property is set, the value of that property is
7568 used to determine the language with which to compile the header file.
7569 Otherwise, if the target has any C++ sources, the header is compiled as
7570 C++. Otherwise, if the target has any C sources, the header is com‐
7571 piled as C. Otherwise, if C++ is enabled globally, the header is com‐
7572 piled as C++. Otherwise, if C is enabled globally, the header is com‐
7573 piled as C. Otherwise, the header file is not compiled.
7574 If any verification targets are created, a top-level target called
7576 all_verify_interface_header_sets is created which depends on all veri‐
7577 fication targets.
7578 This property is initialized by the value of the
7580 CMAKE_VERIFY_INTERFACE_HEADER_SETS variable if it is set when a target
7581 is created.
7582 If the project wishes to control which header sets are verified by this
7584 property, it can set INTERFACE_HEADER_SETS_TO_VERIFY.
7585 VERSION
7587 What version number is this target.
7588 For shared libraries VERSION and SOVERSION can be used to specify the
7590 build version and API version respectively. When building or in‐
7591 stalling appropriate symlinks are created if the platform supports sym‐
7592 links and the linker supports so-names. If only one of both is speci‐
7593 fied the missing is assumed to have the same version number. For exe‐
7594 cutables VERSION can be used to specify the build version. When build‐
7595 ing or installing appropriate symlinks are created if the platform sup‐
7596 ports symlinks.
7597 Windows Versions
7599 For shared libraries and executables on Windows the VERSION attribute
7600 is parsed to extract a <major>.<minor> version number. These numbers
7601 are used as the image version of the binary.
7602 Mach-O Versions
7604 For shared libraries and executables on Mach-O systems (e.g. macOS,
7605 iOS), the SOVERSION property corresponds to the compatibility version
7606 and VERSION corresponds to the current version (unless Mach-O specific
7607 overrides are provided, as discussed below). See the FRAMEWORK target
7608 property for an example.
7609 For shared libraries, the MACHO_COMPATIBILITY_VERSION and
7611 MACHO_CURRENT_VERSION properties can be used to override the compati‐
7612 bility version and current version respectively. Note that SOVERSION
7613 will still be used to form the install_name and both SOVERSION and VER‐
7614 SION may also affect the file and symlink names.
7615 Versions of Mach-O binaries may be checked with the otool -L <binary>
7617 command.
7618 VISIBILITY_INLINES_HIDDEN
7620 Whether to add a compile flag to hide symbols of inline functions
7621 The VISIBILITY_INLINES_HIDDEN property determines whether a flag for
7623 hiding symbols for inline functions, such as -fvisibility-inlines-hid‐
7624 den, should be used when invoking the compiler. This property affects
7625 compilation in sources of all types of targets (subject to policy
7626 CMP0063).
7627 This property is initialized by the value of the
7629 CMAKE_VISIBILITY_INLINES_HIDDEN variable if it is set when a target is
7630 created.
7631 VS_CONFIGURATION_TYPE
7633 New in version 3.6.
7634 Visual Studio project configuration type.
7637 Sets the ConfigurationType attribute for a generated Visual Studio
7639 project. The property value may use generator expressions. If this
7640 property is set, it overrides the default setting that is based on the
7641 target type (e.g. StaticLibrary, Application, ...).
7642 Supported on Visual Studio Generators for VS 2010 and higher.
7644 VS_DEBUGGER_COMMAND
7646 New in version 3.12.
7647 Sets the local debugger command for Visual Studio C++ targets. The
7650 property value may use generator expressions. This is defined in <Lo‐
7651 calDebuggerCommand> in the Visual Studio project file.
7652 This property only works for Visual Studio 11 2012 and above; it is ig‐
7654 nored on other generators.
7655 VS_DEBUGGER_COMMAND_ARGUMENTS
7657 New in version 3.13.
7658 Sets the local debugger command line arguments for Visual Studio C++
7661 targets. The property value may use generator expressions. This is
7662 defined in <LocalDebuggerCommandArguments> in the Visual Studio project
7663 file.
7664 This property only works for Visual Studio 11 2012 and above; it is ig‐
7666 nored on other generators.
7667 VS_DEBUGGER_ENVIRONMENT
7669 New in version 3.13.
7670 Sets the local debugger environment for Visual Studio C++ targets. The
7673 property value may use generator expressions. This is defined in <Lo‐
7674 calDebuggerEnvironment> in the Visual Studio project file.
7675 This property only works for Visual Studio 11 2012 and above; it is ig‐
7677 nored on other generators.
7678 VS_DEBUGGER_WORKING_DIRECTORY
7680 New in version 3.8.
7681 Sets the local debugger working directory for Visual Studio C++ tar‐
7684 gets. The property value may use generator expressions. This is de‐
7685 fined in <LocalDebuggerWorkingDirectory> in the Visual Studio project
7686 file.
7687 This property only works for Visual Studio 11 2012 and above; it is ig‐
7689 nored on other generators.
7690 VS_DESKTOP_EXTENSIONS_VERSION
7692 New in version 3.4.
7693 Visual Studio Windows 10 Desktop Extensions Version
7696 Specifies the version of the Desktop Extensions that should be included
7698 in the target. For example 10.0.10240.0. If the value is not specified,
7699 the Desktop Extensions will not be included. To use the same version of
7700 the extensions as the Windows 10 SDK that is being used, you can use
7701 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
7702 VS_DOTNET_DOCUMENTATION_FILE
7704 New in version 3.17.
7705 Visual Studio managed project .NET documentation output
7708 Sets the target XML documentation file output.
7710 VS_DOTNET_REFERENCE_<refname>
7712 New in version 3.8.
7713 Visual Studio managed project .NET reference with name <refname> and
7716 hint path.
7717 Adds one .NET reference to generated Visual Studio project. The refer‐
7719 ence will have the name <refname> and will point to the assembly given
7720 as value of the property.
7721 See also VS_DOTNET_REFERENCES and VS_DOTNET_REFERENCES_COPY_LOCAL
7723 VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>
7725 New in version 3.10.
7726 Defines an XML property <tagname> for a .NET reference <refname>.
7729 Reference properties can be set for .NET references which are defined
7731 by the target properties VS_DOTNET_REFERENCES,
7732 VS_DOTNET_REFERENCE_<refname> and also for project references to other
7733 C# targets which are established by target_link_libraries().
7734 This property is only applicable to C# targets and Visual Studio gener‐
7736 ators 2010 and later.
7737 VS_DOTNET_REFERENCES
7739 Visual Studio managed project .NET references
7740 Adds one or more semicolon-delimited .NET references to a generated
7742 Visual Studio project. For example, "System;System.Windows.Forms".
7743 VS_DOTNET_REFERENCES_COPY_LOCAL
7745 New in version 3.8.
7746 Sets the Copy Local property for all .NET hint references in the target
7749 Boolean property to enable/disable copying of .NET hint references to
7751 output directory. The default is ON.
7752 VS_DOTNET_STARTUP_OBJECT
7754 New in version 3.24.
7755 Sets the startup object property in Visual Studio .NET targets. The
7758 property value defines a full qualified class name (including package
7759 name), for example: MyCompany.Package.MyStarterClass.
7760 If the property is unset, Visual Studio uses the first matching static
7762 void Main(string[]) function signature by default. When more than one
7763 Main() method is available in the current project, the property becomes
7764 mandatory for building the project.
7765 This property only works for Visual Studio 11 2012 and above; it is ig‐
7767 nored on other generators.
7768 set_property(TARGET ${TARGET_NAME} PROPERTY
7770 VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")
7771 VS_DOTNET_TARGET_FRAMEWORK_VERSION
7773 Specify the .NET target framework version.
7774 Used to specify the .NET target framework version for C++/CLI. For ex‐
7776 ample, "v4.5".
7777 This property is deprecated and should not be used anymore. Use
7779 DOTNET_TARGET_FRAMEWORK or DOTNET_TARGET_FRAMEWORK_VERSION instead.
7780 VS_DPI_AWARE
7782 New in version 3.16.
7783 Set the Manifest Tool -> Input and Output -> DPI Awareness in the Vis‐
7786 ual Studio target project properties.
7787 Valid values are PerMonitor, ON, or OFF.
7789 For example:
7791 add_executable(myproject myproject.cpp)
7793 set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor")
7794 VS_GLOBAL_KEYWORD
7796 Visual Studio project keyword for VS 10 (2010) and newer.
7797 Sets the "keyword" attribute for a generated Visual Studio project.
7799 Defaults to "Win32Proj". You may wish to override this value with
7800 "ManagedCProj", for example, in a Visual Studio managed C++ unit test
7801 project.
7802 Use the VS_KEYWORD target property to set the keyword for Visual Studio
7804 9 (2008) and older.
7805 VS_GLOBAL_PROJECT_TYPES
7807 Visual Studio project type(s).
7808 Can be set to one or more UUIDs recognized by Visual Studio to indicate
7810 the type of project. This value is copied verbatim into the generated
7811 project file. Example for a managed C++ unit testing project:
7812 {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}
7814 UUIDs are semicolon-delimited.
7816 VS_GLOBAL_ROOTNAMESPACE
7818 Visual Studio project root namespace.
7819 Sets the "RootNamespace" attribute for a generated Visual Studio
7821 project. The attribute will be generated only if this is set.
7822 VS_GLOBAL_<variable>
7824 Visual Studio project-specific global variable.
7825 Tell the Visual Studio generator to set the global variable '<vari‐
7827 able>' to a given value in the generated Visual Studio project. Ig‐
7828 nored on other generators. Qt integration works better if
7829 VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For ex‐
7830 ample, "4.7.3"
7831 VS_IOT_EXTENSIONS_VERSION
7833 New in version 3.4.
7834 Visual Studio Windows 10 IoT Extensions Version
7837 Specifies the version of the IoT Extensions that should be included in
7839 the target. For example 10.0.10240.0. If the value is not specified,
7840 the IoT Extensions will not be included. To use the same version of the
7841 extensions as the Windows 10 SDK that is being used, you can use the
7842 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
7843 VS_IOT_STARTUP_TASK
7845 New in version 3.4.
7846 Visual Studio Windows 10 IoT Continuous Background Task
7849 Specifies that the target should be compiled as a Continuous Background
7851 Task library.
7852 VS_JUST_MY_CODE_DEBUGGING
7854 New in version 3.15.
7855 Enable Just My Code with Visual Studio debugger.
7858 Supported on Visual Studio Generators for VS 2010 and higher, Makefile
7860 Generators and the Ninja generators.
7861 This property is initialized by the CMAKE_VS_JUST_MY_CODE_DEBUGGING
7863 variable if it is set when a target is created.
7864 VS_KEYWORD
7866 Visual Studio project keyword for VS 9 (2008) and older.
7867 Can be set to change the visual studio keyword, for example Qt integra‐
7869 tion works better if this is set to Qt4VSv1.0.
7870 Use the VS_GLOBAL_KEYWORD target property to set the keyword for Visual
7872 Studio 11 (2012) and newer.
7873 VS_MOBILE_EXTENSIONS_VERSION
7875 New in version 3.4.
7876 Visual Studio Windows 10 Mobile Extensions Version
7879 Specifies the version of the Mobile Extensions that should be included
7881 in the target. For example 10.0.10240.0. If the value is not specified,
7882 the Mobile Extensions will not be included. To use the same version of
7883 the extensions as the Windows 10 SDK that is being used, you can use
7884 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
7885 VS_NO_COMPILE_BATCHING
7887 New in version 3.24.
7888 Turn off compile batching for the target. Usually MSBuild calls the
7891 compiler with multiple c/cpp files and compiler starts subprocesses for
7892 each file to make the build parallel. If you want compiler to be in‐
7893 voked with one file at a time set VS_NO_COMPILE_BATCHING to ON. If this
7894 flag is set MSBuild will call compiler with one c/cpp file at a time.
7895 Useful when you want to use tool that replaces the compiler, for exam‐
7896 ple some build caching tool.
7897 This property is initialized by the CMAKE_VS_NO_COMPILE_BATCHING vari‐
7899 able if it is set when a target is created.
7900 Example
7902 This shows setting the property for the target foo.
7903 add_library(foo SHARED foo.cpp)
7905 set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)
7906 VS_NO_SOLUTION_DEPLOY
7908 New in version 3.15.
7909 Specify that the target should not be marked for deployment to a Win‐
7912 dows CE or Windows Phone device in the generated Visual Studio solu‐
7913 tion.
7914 Be default, all EXE and shared library (DLL) targets are marked to de‐
7916 ploy to the target device in the generated Visual Studio solution.
7917 Generator expressions are supported.
7919 There are reasons one might want to exclude a target / generated
7921 project from deployment:
7922 • The library or executable may not be necessary in the primary de‐
7924 ploy/debug scenario, and excluding from deployment saves time in the
7925 develop/download/debug cycle.
7926 • There may be insufficient space on the target device to accommodate
7928 all of the build products.
7929 • Visual Studio 2013 requires a target device IP address be entered for
7931 each target marked for deployment. For large numbers of targets,
7932 this can be tedious. NOTE: Visual Studio will deploy all project de‐
7933 pendencies of a project tagged for deployment to the IP address con‐
7934 figured for that project even if those dependencies are not tagged
7935 for deployment.
7936 Example 1
7938 This shows setting the variable for the target foo.
7939 add_library(foo SHARED foo.cpp)
7941 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON)
7942 Example 2
7944 This shows setting the variable for the Release configuration only.
7945 add_library(foo SHARED foo.cpp)
7947 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>")
7948 VS_PACKAGE_REFERENCES
7950 New in version 3.15.
7951 Visual Studio package references for nuget.
7954 Adds one or more semicolon-delimited package references to a generated
7956 Visual Studio project. The version of the package will be underscore
7957 delimited. For example, boost_1.7.0;nunit_3.12.*.
7958 set_property(TARGET ${TARGET_NAME} PROPERTY
7960 VS_PACKAGE_REFERENCES "boost_1.7.0")
7961 VS_PLATFORM_TOOLSET
7963 New in version 3.18.
7964 Overrides the platform toolset used to build a target.
7967 Only supported when the compiler used by the given toolset is the same
7969 as the compiler used to build the whole source tree.
7970 This is especially useful to create driver projects with the toolsets
7972 "WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0".
7973 VS_PROJECT_IMPORT
7975 New in version 3.15.
7976 Visual Studio managed project imports
7979 Adds to a generated Visual Studio project one or more semicolon-delim‐
7981 ited paths to .props files needed when building projects from some
7982 NuGet packages. For example, my_packages_path/MyPack‐
7983 age.1.0.0/build/MyPackage.props.
7984 VS_SCC_AUXPATH
7986 Visual Studio Source Code Control Aux Path.
7987 Can be set to change the visual studio source code control auxpath
7989 property.
7990 VS_SCC_LOCALPATH
7992 Visual Studio Source Code Control Local Path.
7993 Can be set to change the visual studio source code control local path
7995 property.
7996 VS_SCC_PROJECTNAME
7998 Visual Studio Source Code Control Project.
7999 Can be set to change the visual studio source code control project name
8001 property.
8002 VS_SCC_PROVIDER
8004 Visual Studio Source Code Control Provider.
8005 Can be set to change the visual studio source code control provider
8007 property.
8008 VS_SDK_REFERENCES
8010 New in version 3.7.
8011 Visual Studio project SDK references. Specify a semicolon-separated
8014 list of SDK references to be added to a generated Visual Studio
8015 project, e.g. Microsoft.AdMediatorWindows81, Version=1.0.
8016 VS_SOLUTION_DEPLOY
8018 New in version 3.18.
8019 Specify that the target should be marked for deployment when not tar‐
8022 geting Windows CE, Windows Phone or a Windows Store application.
8023 If the target platform doesn't support deployment, this property won't
8025 have any effect.
8026 Generator expressions are supported.
8028 Examples
8030 Always deploy target foo:
8031 add_executable(foo SHARED foo.cpp)
8033 set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)
8034 Deploy target foo for all configurations except Release:
8036 add_executable(foo SHARED foo.cpp)
8038 set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")
8039 VS_SOURCE_SETTINGS_<tool>
8041 New in version 3.18.
8042 Set any item metadata on all non-built files that use <tool>.
8045 Takes a list of Key=Value pairs. Tells the Visual Studio generator to
8047 set Key to Value as item metadata on all non-built files that use
8048 <tool>.
8049 For example:
8051 set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")
8053 will set Key to Value and Key2 to Value2 for all non-built files that
8055 use FXCompile.
8056 Generator expressions are supported.
8058 VS_USER_PROPS
8060 New in version 3.8.
8061 Sets the user props file to be included in the visual studio C++
8064 project file. The standard path is $(UserRootDir)\\Micro‐
8065 soft.Cpp.$(Platform).user.props, which is in most cases the same as
8066 %LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Micro‐
8067 soft.Cpp.Win32.user.props or %LOCALAPPDATA%\\Microsoft\\MS‐
8068 Build\\v4.0\\Microsoft.Cpp.x64.user.props.
8069 The *.user.props files can be used for Visual Studio wide configuration
8071 which is independent from cmake.
8072 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
8074 New in version 3.4.
8075 Visual Studio Windows Target Platform Minimum Version
8078 For Windows 10. Specifies the minimum version of the OS that is being
8080 targeted. For example 10.0.10240.0. If the value is not specified, the
8081 value of CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION will be used on Win‐
8082 dowsStore projects otherwise the target platform minimum version will
8083 not be specified for the project.
8084 VS_WINRT_COMPONENT
8086 New in version 3.1.
8087 Mark a target as a Windows Runtime component for the Visual Studio gen‐
8090 erator. Compile the target with C++/CX language extensions for Windows
8091 Runtime. For SHARED and MODULE libraries, this also defines the
8092 _WINRT_DLL preprocessor macro.
8093 NOTE:
8095 Currently this is implemented only by Visual Studio generators.
8096 Support may be added to other generators in the future.
8097 VS_WINRT_EXTENSIONS
8099 Deprecated. Use VS_WINRT_COMPONENT instead. This property was an ex‐
8100 perimental partial implementation of that one.
8101 VS_WINRT_REFERENCES
8103 Visual Studio project Windows Runtime Metadata references
8104 Adds one or more semicolon-delimited WinRT references to a generated
8106 Visual Studio project. For example, "Windows;Windows.UI.Core".
8107 WATCOM_RUNTIME_LIBRARY
8109 New in version 3.24.
8110 Select the Watcom runtime library for use by compilers targeting the
8113 Watcom ABI.
8114 The allowed values are:
8116 SingleThreaded
8118 Compile without additional flags to use a single-threaded stati‐
8119 cally-linked runtime library.
8120 SingleThreadedDLL
8122 Compile with -br or equivalent flag(s) to use a single-threaded
8123 dynamically-linked runtime library. This is not available for
8124 Linux targets.
8125 MultiThreaded
8127 Compile with -bm or equivalent flag(s) to use a multi-threaded
8128 statically-linked runtime library.
8129 MultiThreadedDLL
8131 Compile with -bm -br or equivalent flag(s) to use a
8132 multi-threaded dynamically-linked runtime library. This is not
8133 available for Linux targets.
8134 The value is ignored on non-Watcom compilers but an unsupported value
8136 will be rejected as an error when using a compiler targeting the Watcom
8137 ABI.
8138 The value may also be the empty string ("") in which case no runtime
8140 library selection flag will be added explicitly by CMake.
8141 Use generator expressions to support per-configuration specification.
8143 For example, the code:
8145 add_executable(foo foo.c)
8147 set_property(TARGET foo PROPERTY
8148 WATCOM_RUNTIME_LIBRARY "MultiThreaded")
8149 selects for the target foo a multi-threaded statically-linked runtime
8151 library.
8152 If this property is not set then CMake uses the default value Multi‐
8154 ThreadedDLL on Windows and SingleThreaded on other platforms to select
8155 a Watcom runtime library.
8156 NOTE:
8158 This property has effect only when policy CMP0136 is set to NEW
8159 prior to the first project() or enable_language() command that en‐
8160 ables a language using a compiler targeting the Watcom ABI.
8161 WIN32_EXECUTABLE
8163 Build an executable with a WinMain entry point on windows.
8164 When this property is set to true the executable when linked on Windows
8166 will be created with a WinMain() entry point instead of just main().
8167 This makes it a GUI executable instead of a console application. See
8168 the CMAKE_MFC_FLAG variable documentation to configure use of the Mi‐
8169 crosoft Foundation Classes (MFC) for WinMain executables. This prop‐
8170 erty is initialized by the value of the CMAKE_WIN32_EXECUTABLE variable
8171 if it is set when a target is created.
8172 This property supports generator expressions, except if the target is
8174 managed (contains C# code.)
8175 WINDOWS_EXPORT_ALL_SYMBOLS
8177 New in version 3.4.
8178 This property is implemented only for MS-compatible tools on Windows.
8181 Enable this boolean property to automatically create a module defini‐
8183 tion (.def) file with all global symbols found in the input .obj files
8184 for a SHARED library (or executable with ENABLE_EXPORTS) on Windows.
8185 The module definition file will be passed to the linker causing all
8186 symbols to be exported from the .dll. For global data symbols, __de‐
8187 clspec(dllimport) must still be used when compiling against the code in
8188 the .dll. All other function symbols will be automatically exported
8189 and imported by callers. This simplifies porting projects to Windows
8190 by reducing the need for explicit dllexport markup, even in C++
8191 classes.
8192 When this property is enabled, zero or more .def files may also be
8194 specified as source files of the target. The exports named by these
8195 files will be merged with those detected from the object files to gen‐
8196 erate a single module definition file to be passed to the linker. This
8197 can be used to export symbols from a .dll that are not in any of its
8198 object files but are added by the linker from dependencies (e.g.
8199 msvcrt.lib).
8200 This property is initialized by the value of the
8202 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS variable if it is set when a target is
8203 created.
8204 XCODE_ATTRIBUTE_<an-attribute>
8206 Set Xcode target attributes directly.
8207 Tell the Xcode generator to set <an-attribute> to a given value in the
8209 generated Xcode project. Ignored on other generators.
8210 This offers low-level control over the generated Xcode project file.
8212 It is meant as a last resort for specifying settings that CMake does
8213 not otherwise have a way to control. Although this can override a set‐
8214 ting CMake normally produces on its own, doing so bypasses CMake's
8215 model of the project and can break things.
8216 See the CMAKE_XCODE_ATTRIBUTE_<an-attribute> variable to set attributes
8218 on all targets in a directory tree.
8219 Contents of XCODE_ATTRIBUTE_<an-attribute> may use "generator expres‐
8221 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
8222 manual for available expressions. See the cmake-buildsystem(7) manual
8223 for more on defining buildsystem properties.
8224 XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY
8226 New in version 3.20.
8227 Tell the Xcode generator to perform code signing for all the frameworks
8230 and libraries that are embedded using the XCODE_EMBED_FRAMEWORKS prop‐
8231 erty.
8232 New in version 3.21.
8234 This property was generalized to other types of embedded items. See
8237 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY for the more general form.
8238 XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY
8240 New in version 3.20.
8241 Tell the Xcode generator to remove headers from all the frameworks that
8244 are embedded using the XCODE_EMBED_FRAMEWORKS property.
8245 New in version 3.21.
8247 This property was generalized to other types of embedded items. See
8250 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY for the more general form.
8251 XCODE_EMBED_<type>
8253 New in version 3.20.
8254 Tell the Xcode generator to embed the specified list of items into the
8257 target bundle. <type> specifies the embed build phase to use. See the
8258 Xcode documentation for the base location of each <type>.
8259 The supported values for <type> are:
8261 FRAMEWORKS
8263 The specified items will be added to the Embed Frameworks build
8264 phase. The items can be CMake target names or paths to frame‐
8265 works or libraries.
8266 APP_EXTENSIONS
8268 New in version 3.21.
8269 The specified items will be added to the Embed App Extensions
8272 build phase. They must be CMake target names.
8273 PLUGINS
8275 New in version 3.23.
8276 The specified items will be added to the Embed PlugIns build
8279 phase. They must be CMake target names.
8280 See also XCODE_EMBED_<type>_PATH,
8282 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY and
8283 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY.
8284 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY
8286 New in version 3.20.
8287 Boolean property used only by the Xcode generator. It specifies
8290 whether to perform code signing for the items that are embedded using
8291 the XCODE_EMBED_<type> property.
8292 The supported values for <type> are:
8294 FRAMEWORKS
8296 APP_EXTENSIONS
8298 New in version 3.21.
8299 PLUGINS
8302 New in version 3.23.
8303 If a XCODE_EMBED_<type>_CODE_SIGN_ON_COPY property is not defined on
8306 the target, no code signing on copy will be performed for that <type>.
8307 XCODE_EMBED_<type>_PATH
8309 New in version 3.20.
8310 This property is used only by the Xcode generator. When defined, it
8313 specifies the relative path to use when embedding the items specified
8314 by XCODE_EMBED_<type>. The path is relative to the base location of
8315 the Embed XXX build phase associated with <type>. See the Xcode docu‐
8316 mentation for the base location of each <type>.
8317 The supported values for <type> are:
8319 FRAMEWORKS
8321 APP_EXTENSIONS
8323 New in version 3.21.
8324 PLUGINS
8327 New in version 3.23.
8328 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY
8331 New in version 3.20.
8332 Boolean property used only by the Xcode generator. It specifies
8335 whether to remove headers from all the frameworks that are embedded us‐
8336 ing the XCODE_EMBED_<type> property.
8337 The supported values for <type> are:
8339 FRAMEWORKS
8341 If the XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY property is
8342 not defined, headers will not be removed on copy by default.
8343 APP_EXTENSIONS
8345 New in version 3.21.
8346 If the XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY prop‐
8349 erty is not defined, headers WILL be removed on copy by default.
8350 PLUGINS
8352 New in version 3.23.
8353 XCODE_EXPLICIT_FILE_TYPE
8356 New in version 3.8.
8357 Set the Xcode explicitFileType attribute on its reference to a target.
8360 CMake computes a default based on target type but can be told explic‐
8361 itly with this property.
8362 See also XCODE_PRODUCT_TYPE.
8364 XCODE_GENERATE_SCHEME
8366 New in version 3.15.
8367 If enabled, the Xcode generator will generate schema files. These are
8370 useful to invoke analyze, archive, build-for-testing and test actions
8371 from the command line.
8372 This property is initialized by the value of the variable
8374 CMAKE_XCODE_GENERATE_SCHEME if it is set when a target is created.
8375 The following target properties overwrite the default of the corre‐
8377 sponding settings on the "Diagnostic" tab for each schema file. Each
8378 of those is initialized by the respective CMAKE_ variable at target
8379 creation time.
8380 • XCODE_SCHEME_ADDRESS_SANITIZER
8382 • XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
8384 • XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
8386 • XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
8388 • XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
8390 • XCODE_SCHEME_GUARD_MALLOC
8392 • XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
8394 • XCODE_SCHEME_MALLOC_GUARD_EDGES
8396 • XCODE_SCHEME_MALLOC_SCRIBBLE
8398 • XCODE_SCHEME_MALLOC_STACK
8400 • XCODE_SCHEME_THREAD_SANITIZER
8402 • XCODE_SCHEME_THREAD_SANITIZER_STOP
8404 • XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
8406 • XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
8408 • XCODE_SCHEME_LAUNCH_CONFIGURATION
8410 • XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
8412 • XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
8414 • XCODE_SCHEME_ZOMBIE_OBJECTS
8416 The following target properties will be applied on the "Info", "Argu‐
8418 ments", and "Options" tab:
8419 • XCODE_SCHEME_ARGUMENTS
8421 • XCODE_SCHEME_DEBUG_AS_ROOT
8423 • XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
8425 • XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
8427 • XCODE_SCHEME_ENVIRONMENT
8429 • XCODE_SCHEME_EXECUTABLE
8431 • XCODE_SCHEME_LAUNCH_MODE
8433 • XCODE_SCHEME_WORKING_DIRECTORY
8435 XCODE_LINK_BUILD_PHASE_MODE
8437 New in version 3.19.
8438 When using the Xcode generator, libraries to be linked will be speci‐
8441 fied in the Xcode project file using either the "Link Binary With Li‐
8442 braries" build phase or directly as linker flags. The former allows
8443 Xcode to manage build paths, which may be necessary when creating Xcode
8444 archives because it may use different build paths to a regular build.
8445 This property controls usage of "Link Binary With Libraries" build
8447 phase for a target that is an app bundle, executable, shared library,
8448 shared framework or a module library.
8449 Possible values are:
8451 • NONE The libraries will be linked by specifying the linker flags di‐
8453 rectly.
8454 • BUILT_ONLY The "Link Binary With Libraries" build phase will be used
8456 to link to another target under the following conditions:
8457 • The target to be linked to is a regular non-imported, non-interface
8459 library target.
8460 • The output directory of the target being built has not been changed
8462 from its default (see RUNTIME_OUTPUT_DIRECTORY and
8463 LIBRARY_OUTPUT_DIRECTORY).
8464 • KNOWN_LOCATION The "Link Binary With Libraries" build phase will be
8466 used to link to another target under the same conditions as with
8467 BUILT_ONLY and also:
8468 • Imported library targets except those of type UNKNOWN.
8470 • Any non-target library specified directly with a path.
8472 For all other cases, the libraries will be linked by specifying the
8474 linker flags directly.
8475 WARNING:
8477 Libraries linked using "Link Binary With Libraries" are linked after
8478 the ones linked through regular linker flags. This order should be
8479 taken into account when different static libraries contain symbols
8480 with the same name, as the former ones will take precedence over the
8481 latter.
8482 WARNING:
8484 If two or more directories contain libraries with identical file
8485 names and some libraries are linked from those directories, the li‐
8486 brary search path lookup will end up linking libraries from the
8487 first directory. This is a known limitation of Xcode.
8488 This property is initialized by the value of the
8490 CMAKE_XCODE_LINK_BUILD_PHASE_MODE variable if it is set when a target
8491 is created.
8492 XCODE_PRODUCT_TYPE
8494 New in version 3.8.
8495 Set the Xcode productType attribute on its reference to a target.
8498 CMake computes a default based on target type but can be told explic‐
8499 itly with this property.
8500 See also XCODE_EXPLICIT_FILE_TYPE.
8502 XCODE_SCHEME_ADDRESS_SANITIZER
8504 New in version 3.13.
8505 Whether to enable Address Sanitizer in the Diagnostics section of the
8508 generated Xcode scheme.
8509 This property is initialized by the value of the variable
8511 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER if it is set when a target is cre‐
8512 ated.
8513 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8515 to see all Xcode schema related properties.
8516 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
8518 New in version 3.13.
8519 Whether to enable Detect use of stack after return in the Diagnostics
8522 section of the generated Xcode scheme.
8523 This property is initialized by the value of the variable
8525 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN if it is set when
8526 a target is created.
8527 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8529 to see all Xcode schema related properties.
8530 XCODE_SCHEME_ARGUMENTS
8532 New in version 3.13.
8533 Specify command line arguments that should be added to the Arguments
8536 section of the generated Xcode scheme.
8537 If set to a list of arguments those will be added to the scheme.
8539 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8541 to see all Xcode schema related properties.
8542 XCODE_SCHEME_DEBUG_AS_ROOT
8544 New in version 3.15.
8545 Whether to debug the target as 'root'.
8548 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8550 to see all Xcode schema related properties.
8551 XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
8553 New in version 3.16.
8554 Whether to enable Allow debugging when using document Versions Browser
8557 in the Options section of the generated Xcode scheme.
8558 This property is initialized by the value of the variable
8560 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING if it is set when a target
8561 is created.
8562 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8564 to see all Xcode schema related properties.
8565 XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
8567 New in version 3.13.
8568 Whether to disable the Main Thread Checker in the Diagnostics section
8571 of the generated Xcode scheme.
8572 This property is initialized by the value of the variable
8574 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER if it is set when a tar‐
8575 get is created.
8576 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8578 to see all Xcode schema related properties.
8579 XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
8581 New in version 3.13.
8582 Whether to enable Dynamic Library Loads in the Diagnostics section of
8585 the generated Xcode scheme.
8586 This property is initialized by the value of the variable
8588 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS if it is set when a target is
8589 created.
8590 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8592 to see all Xcode schema related properties.
8593 XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
8595 New in version 3.13.
8596 Whether to enable Dynamic Linker API usage in the Diagnostics section
8599 of the generated Xcode scheme.
8600 This property is initialized by the value of the variable
8602 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE if it is set when a target
8603 is created.
8604 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8606 to see all Xcode schema related properties.
8607 XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
8609 New in version 3.25.
8610 Property value for Metal: API Validation in the Options section of the
8613 generated Xcode scheme.
8614 This property is initialized by the value of the variable
8616 CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION if it is set when a target
8617 is created.
8618 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8620 to see all Xcode schema related properties.
8621 XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
8623 New in version 3.23.
8624 Property value for GPU Frame Capture in the Options section of the gen‐
8627 erated Xcode scheme. Example values are Metal and Disabled.
8628 This property is initialized by the value of the variable
8630 CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE if it is set when a
8631 target is created.
8632 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8634 to see all Xcode schema related properties.
8635 XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
8637 New in version 3.25.
8638 Property value for Metal: Shader Validation in the Options section of
8641 the generated Xcode scheme.
8642 This property is initialized by the value of the variable
8644 CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION if it is set when a
8645 target is created.
8646 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8648 to see all Xcode schema related properties.
8649 XCODE_SCHEME_ENVIRONMENT
8651 New in version 3.13.
8652 Specify environment variables that should be added to the Arguments
8655 section of the generated Xcode scheme.
8656 If set to a list of environment variables and values of the form MY‐
8658 VAR=value those environment variables will be added to the scheme.
8659 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8661 to see all Xcode schema related properties.
8662 XCODE_SCHEME_EXECUTABLE
8664 New in version 3.13.
8665 Specify path to executable in the Info section of the generated Xcode
8668 scheme. If not set the schema generator will select the current target
8669 if it is actually executable.
8670 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8672 to see all Xcode schema related properties.
8673 XCODE_SCHEME_GUARD_MALLOC
8675 New in version 3.13.
8676 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
8679 ated Xcode scheme.
8680 This property is initialized by the value of the variable
8682 CMAKE_XCODE_SCHEME_GUARD_MALLOC if it is set when a target is created.
8683 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8685 to see all Xcode schema related properties.
8686 XCODE_SCHEME_LAUNCH_CONFIGURATION
8688 New in version 3.25.
8689 Set the build configuration to run the target.
8692 This property is initialized by the value of the variable
8694 CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION if it is set when a target is
8695 created.
8696 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8698 to see all Xcode schema related properties.
8699 XCODE_SCHEME_LAUNCH_MODE
8701 New in version 3.25.
8702 Property value for Launch in the Info section of the generated Xcode
8705 scheme.
8706 Possible values are:
8708 AUTO Launch automatically. This is the default.
8710 WAIT Wait for the executable to be launched.
8712 This property is initialized by the value of the variable
8714 CMAKE_XCODE_SCHEME_LAUNCH_MODE if it is set when a target is created.
8715 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8717 to see all Xcode schema related properties.
8718 XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
8720 New in version 3.13.
8721 Whether to enable the Main Thread Checker option Pause on issues in the
8724 Diagnostics section of the generated Xcode scheme.
8725 This property is initialized by the value of the variable
8727 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP if it is set when a target
8728 is created.
8729 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8731 to see all Xcode schema related properties.
8732 XCODE_SCHEME_MALLOC_GUARD_EDGES
8734 New in version 3.13.
8735 Whether to enable Malloc Guard Edges in the Diagnostics section of the
8738 generated Xcode scheme.
8739 This property is initialized by the value of the variable
8741 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES if it is set when a target is
8742 created.
8743 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8745 to see all Xcode schema related properties.
8746 XCODE_SCHEME_MALLOC_SCRIBBLE
8748 New in version 3.13.
8749 Whether to enable Malloc Scribble in the Diagnostics section of the
8752 generated Xcode scheme.
8753 This property is initialized by the value of the variable
8755 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE if it is set when a target is cre‐
8756 ated.
8757 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8759 to see all Xcode schema related properties.
8760 XCODE_SCHEME_MALLOC_STACK
8762 New in version 3.13.
8763 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
8766 ated Xcode scheme.
8767 This property is initialized by the value of the variable
8769 CMAKE_XCODE_SCHEME_MALLOC_STACK if it is set when a target is created.
8770 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8772 to see all Xcode schema related properties.
8773 XCODE_SCHEME_THREAD_SANITIZER
8775 New in version 3.13.
8776 Whether to enable Thread Sanitizer in the Diagnostics section of the
8779 generated Xcode scheme.
8780 This property is initialized by the value of the variable
8782 CMAKE_XCODE_SCHEME_THREAD_SANITIZER if it is set when a target is cre‐
8783 ated.
8784 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8786 to see all Xcode schema related properties.
8787 XCODE_SCHEME_THREAD_SANITIZER_STOP
8789 New in version 3.13.
8790 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
8793 section of the generated Xcode scheme.
8794 This property is initialized by the value of the variable
8796 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP if it is set when a target is
8797 created.
8798 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8800 to see all Xcode schema related properties.
8801 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
8803 New in version 3.13.
8804 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
8807 tion of the generated Xcode scheme.
8808 This property is initialized by the value of the variable
8810 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER if it is set when a
8811 target is created.
8812 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8814 to see all Xcode schema related properties.
8815 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
8817 New in version 3.13.
8818 Whether to enable Undefined Behavior Sanitizer option Pause on issues
8821 in the Diagnostics section of the generated Xcode scheme.
8822 This property is initialized by the value of the variable
8824 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP if it is set when
8825 a target is created.
8826 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8828 to see all Xcode schema related properties.
8829 XCODE_SCHEME_WORKING_DIRECTORY
8831 New in version 3.17.
8832 Specify the Working Directory of the Run and Profile actions in the
8835 generated Xcode scheme. In case the value contains generator expres‐
8836 sions those are evaluated.
8837 This property is initialized by the value of the variable
8839 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY if it is set when a target is cre‐
8840 ated.
8841 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8843 to see all Xcode schema related properties.
8844 XCODE_SCHEME_ZOMBIE_OBJECTS
8846 New in version 3.13.
8847 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
8850 erated Xcode scheme.
8851 This property is initialized by the value of the variable
8853 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS if it is set when a target is cre‐
8854 ated.
8855 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8857 to see all Xcode schema related properties.
8858 XCODE_XCCONFIG
8860 New in version 3.24.
8861 If set, the Xcode generator will register the specified file as a tar‐
8864 get-level XCConfig file. For global XCConfig files see the
8865 CMAKE_XCODE_XCCONFIG variable.
8866 This feature is intended to ease migration from native Xcode projects
8868 to CMake projects.
8869 Contents of XCODE_XCCONFIG may use generator expressions.
8871 XCTEST
8873 New in version 3.3.
8874 This target is a XCTest CFBundle on the Mac.
8877 This property will usually get set via the xctest_add_bundle() macro in
8879 FindXCTest module.
8880 If a module library target has this property set to true it will be
8882 built as a CFBundle when built on the Mac. It will have the directory
8883 structure required for a CFBundle.
8884 This property depends on BUNDLE to be effective.
8886
8888 ATTACHED_FILES
8889 Attach a list of files to a dashboard submission.
8890 Set this property to a list of files that will be encoded and submitted
8892 to the dashboard as an addition to the test result.
8893 ATTACHED_FILES_ON_FAIL
8895 Attach a list of files to a dashboard submission if the test fails.
8896 Same as ATTACHED_FILES, but these files will only be included if the
8898 test does not pass.
8899 COST
8901 This property describes the cost of a test. When parallel testing is
8902 enabled, tests in the test set will be run in descending order of cost.
8903 Projects can explicitly define the cost of a test by setting this prop‐
8904 erty to a floating point value.
8905 When the cost of a test is not defined by the project, ctest will ini‐
8907 tially use a default cost of 0. It computes a weighted average of the
8908 cost each time a test is run and uses that as an improved estimate of
8909 the cost for the next run. The more a test is re-run in the same build
8910 directory, the more representative the cost should become.
8911 DEPENDS
8913 Specifies that this test should only be run after the specified list of
8914 tests.
8915 Set this to a list of tests that must finish before this test is run.
8917 The results of those tests are not considered, the dependency relation‐
8918 ship is purely for order of execution (i.e. it is really just a run af‐
8919 ter relationship). Consider using test fixtures with setup tests if a
8920 dependency with successful completion is required (see
8921 FIXTURES_REQUIRED).
8922 Examples
8924 add_test(NAME baseTest1 ...)
8925 add_test(NAME baseTest2 ...)
8926 add_test(NAME dependsTest12 ...)
8927 set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2")
8929 # dependsTest12 runs after baseTest1 and baseTest2, even if they fail
8930 DISABLED
8932 New in version 3.9.
8933 If set to True, the test will be skipped and its status will be 'Not
8936 Run'. A DISABLED test will not be counted in the total number of tests
8937 and its completion status will be reported to CDash as Disabled.
8938 A DISABLED test does not participate in test fixture dependency resolu‐
8940 tion. If a DISABLED test has fixture requirements defined in its
8941 FIXTURES_REQUIRED property, it will not cause setup or cleanup tests
8942 for those fixtures to be added to the test set.
8943 If a test with the FIXTURES_SETUP property set is DISABLED, the fixture
8945 behavior will be as though that setup test was passing and any test
8946 case requiring that fixture will still run.
8947 ENVIRONMENT
8949 Specify environment variables that should be defined for running a
8950 test.
8951 Set to a semicolon-separated list list of environment variables and
8953 values of the form MYVAR=value. Those environment variables will be
8954 defined while running the test. The environment changes from this
8955 property do not affect other tests.
8956 ENVIRONMENT_MODIFICATION
8958 New in version 3.22.
8959 Specify environment variables that should be modified for running a
8962 test. Note that the operations performed by this property are performed
8963 after the ENVIRONMENT property is already applied.
8964 Set to a semicolon-separated list of environment variables and values
8966 of the form MYVAR=OP:VALUE, where MYVAR is the case-sensitive name of
8967 an environment variable to be modified. Entries are considered in the
8968 order specified in the property's value. The OP may be one of:
8969 • reset: Reset to the unmodified value, ignoring all modifications
8971 to MYVAR prior to this entry. Note that this will reset the vari‐
8972 able to the value set by ENVIRONMENT, if it was set, and otherwise
8973 to its state from the rest of the CTest execution.
8974 • set: Replaces the current value of MYVAR with VALUE.
8976 • unset: Unsets the current value of MYVAR.
8978 • string_append: Appends singular VALUE to the current value of MY‐
8980 VAR.
8981 • string_prepend: Prepends singular VALUE to the current value of
8983 MYVAR.
8984 • path_list_append: Appends singular VALUE to the current value of
8986 MYVAR using the host platform's path list separator (; on Windows
8987 and : elsewhere).
8988 • path_list_prepend: Prepends singular VALUE to the current value of
8990 MYVAR using the host platform's path list separator (; on Windows
8991 and : elsewhere).
8992 • cmake_list_append: Appends singular VALUE to the current value of
8994 MYVAR using ; as the separator.
8995 • cmake_list_prepend: Prepends singular VALUE to the current value
8997 of MYVAR using ; as the separator.
8998 Unrecognized OP values will result in the test failing before it is ex‐
9000 ecuted. This is so that future operations may be added without changing
9001 valid behavior of existing tests.
9002 The environment changes from this property do not affect other tests.
9004 FAIL_REGULAR_EXPRESSION
9006 If the output matches this regular expression the test will fail, re‐
9007 gardless of the process exit code.
9008 If set, if the output matches one of specified regular expressions, the
9010 test will fail. Example:
9011 set_tests_properties(mytest PROPERTIES
9013 FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
9014 )
9015 FAIL_REGULAR_EXPRESSION expects a list of regular expressions.
9017 See also the PASS_REGULAR_EXPRESSION and SKIP_REGULAR_EXPRESSION test
9019 properties.
9020 FIXTURES_CLEANUP
9022 New in version 3.7.
9023 Specifies a list of fixtures for which the test is to be treated as a
9026 cleanup test. These fixture names are distinct from test case names and
9027 are not required to have any similarity to the names of tests associ‐
9028 ated with them.
9029 Fixture cleanup tests are ordinary tests with all of the usual test
9031 functionality. Setting the FIXTURES_CLEANUP property for a test has two
9032 primary effects:
9033 • CTest will ensure the test executes after all other tests which list
9035 any of the fixtures in its FIXTURES_REQUIRED property.
9036 • If CTest is asked to run only a subset of tests (e.g. using regular
9038 expressions or the --rerun-failed option) and the cleanup test is not
9039 in the set of tests to run, it will automatically be added if any
9040 tests in the set require any fixture listed in FIXTURES_CLEANUP.
9041 A cleanup test can have multiple fixtures listed in its FIX‐
9043 TURES_CLEANUP property. It will execute only once for the whole CTest
9044 run, not once for each fixture. A fixture can also have more than one
9045 cleanup test defined. If there are multiple cleanup tests for a fix‐
9046 ture, projects can control their order with the usual DEPENDS test
9047 property if necessary.
9048 A cleanup test is allowed to require other fixtures, but not any fix‐
9050 ture listed in its FIXTURES_CLEANUP property. For example:
9051 # Ok: Dependent fixture is different to cleanup
9053 set_tests_properties(cleanupFoo PROPERTIES
9054 FIXTURES_CLEANUP Foo
9055 FIXTURES_REQUIRED Bar
9056 )
9057 # Error: cannot require same fixture as cleanup
9059 set_tests_properties(cleanupFoo PROPERTIES
9060 FIXTURES_CLEANUP Foo
9061 FIXTURES_REQUIRED Foo
9062 )
9063 Cleanup tests will execute even if setup or regular tests for that fix‐
9065 ture fail or are skipped.
9066 See FIXTURES_REQUIRED for a more complete discussion of how to use test
9068 fixtures.
9069 FIXTURES_REQUIRED
9071 New in version 3.7.
9072 Specifies a list of fixtures the test requires. Fixture names are case
9075 sensitive and they are not required to have any similarity to test
9076 names.
9077 Fixtures are a way to attach setup and cleanup tasks to a set of tests.
9079 If a test requires a given fixture, then all tests marked as setup
9080 tasks for that fixture will be executed first (once for the whole set
9081 of tests, not once per test requiring the fixture). After all tests re‐
9082 quiring a particular fixture have completed, CTest will ensure all
9083 tests marked as cleanup tasks for that fixture are then executed. Tests
9084 are marked as setup tasks with the FIXTURES_SETUP property and as
9085 cleanup tasks with the FIXTURES_CLEANUP property. If any of a fixture's
9086 setup tests fail, all tests listing that fixture in their FIXTURES_RE‐
9087 QUIRED property will not be executed. The cleanup tests for the fixture
9088 will always be executed, even if some setup tests fail.
9089 When CTest is asked to execute only a subset of tests (e.g. by the use
9091 of regular expressions or when run with the --rerun-failed command line
9092 option), it will automatically add any setup or cleanup tests for fix‐
9093 tures required by any of the tests that are in the execution set. This
9094 behavior can be overridden with the -FS, -FC and -FA command line op‐
9095 tions to ctest(1) if desired.
9096 Since setup and cleanup tasks are also tests, they can have an ordering
9098 specified by the DEPENDS test property just like any other tests. This
9099 can be exploited to implement setup or cleanup using multiple tests for
9100 a single fixture to modularise setup or cleanup logic.
9101 The concept of a fixture is different to that of a resource specified
9103 by RESOURCE_LOCK, but they may be used together. A fixture defines a
9104 set of tests which share setup and cleanup requirements, whereas a re‐
9105 source lock has the effect of ensuring a particular set of tests do not
9106 run in parallel. Some situations may need both, such as setting up a
9107 database, serializing test access to that database and deleting the
9108 database again at the end. For such cases, tests would populate both
9109 FIXTURES_REQUIRED and RESOURCE_LOCK to combine the two behaviors. Names
9110 used for RESOURCE_LOCK have no relationship with names of fixtures, so
9111 note that a resource lock does not imply a fixture and vice versa.
9112 Consider the following example which represents a database test sce‐
9114 nario similar to that mentioned above:
9115 add_test(NAME testsDone COMMAND emailResults)
9117 add_test(NAME fooOnly COMMAND testFoo)
9118 add_test(NAME dbOnly COMMAND testDb)
9119 add_test(NAME dbWithFoo COMMAND testDbWithFoo)
9120 add_test(NAME createDB COMMAND initDB)
9121 add_test(NAME setupUsers COMMAND userCreation)
9122 add_test(NAME cleanupDB COMMAND deleteDB)
9123 add_test(NAME cleanupFoo COMMAND removeFoos)
9124 set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)
9126 set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB)
9128 set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB)
9129 set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB)
9130 set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo)
9131 set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo")
9132 set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo)
9134 set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB)
9135 set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo")
9136 set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
9138 PROPERTIES RESOURCE_LOCK DbAccess)
9139 Key points from this example:
9141 • Two fixtures are defined: DB and Foo. Tests can require a single fix‐
9143 ture as fooOnly and dbOnly do, or they can depend on multiple fix‐
9144 tures like dbWithFoo does.
9145 • A DEPENDS relationship is set up to ensure setupUsers happens after
9147 createDB, both of which are setup tests for the DB fixture and will
9148 therefore be executed before the dbOnly and dbWithFoo tests automati‐
9149 cally.
9150 • No explicit DEPENDS relationships were needed to make the setup tests
9152 run before or the cleanup tests run after the regular tests.
9153 • The Foo fixture has no setup tests defined, only a single cleanup
9155 test.
9156 • testsDone is a cleanup test for both the DB and Foo fixtures. There‐
9158 fore, it will only execute once regular tests for both fixtures have
9159 finished (i.e. after fooOnly, dbOnly and dbWithFoo). No DEPENDS rela‐
9160 tionship was specified for testsDone, so it is free to run before,
9161 after or concurrently with other cleanup tests for either fixture.
9162 • The setup and cleanup tests never list the fixtures they are for in
9164 their own FIXTURES_REQUIRED property, as that would result in a de‐
9165 pendency on themselves and be considered an error.
9166 FIXTURES_SETUP
9168 New in version 3.7.
9169 Specifies a list of fixtures for which the test is to be treated as a
9172 setup test. These fixture names are distinct from test case names and
9173 are not required to have any similarity to the names of tests associ‐
9174 ated with them.
9175 Fixture setup tests are ordinary tests with all of the usual test func‐
9177 tionality. Setting the FIXTURES_SETUP property for a test has two pri‐
9178 mary effects:
9179 • CTest will ensure the test executes before any other test which lists
9181 the fixture name(s) in its FIXTURES_REQUIRED property.
9182 • If CTest is asked to run only a subset of tests (e.g. using regular
9184 expressions or the --rerun-failed option) and the setup test is not
9185 in the set of tests to run, it will automatically be added if any
9186 tests in the set require any fixture listed in FIXTURES_SETUP.
9187 A setup test can have multiple fixtures listed in its FIXTURES_SETUP
9189 property. It will execute only once for the whole CTest run, not once
9190 for each fixture. A fixture can also have more than one setup test de‐
9191 fined. If there are multiple setup tests for a fixture, projects can
9192 control their order with the usual DEPENDS test property if necessary.
9193 A setup test is allowed to require other fixtures, but not any fixture
9195 listed in its FIXTURES_SETUP property. For example:
9196 # Ok: dependent fixture is different to setup
9198 set_tests_properties(setupFoo PROPERTIES
9199 FIXTURES_SETUP Foo
9200 FIXTURES_REQUIRED Bar
9201 )
9202 # Error: cannot require same fixture as setup
9204 set_tests_properties(setupFoo PROPERTIES
9205 FIXTURES_SETUP Foo
9206 FIXTURES_REQUIRED Foo
9207 )
9208 If any of a fixture's setup tests fail, none of the tests listing that
9210 fixture in its FIXTURES_REQUIRED property will be run. Cleanup tests
9211 will, however, still be executed.
9212 See FIXTURES_REQUIRED for a more complete discussion of how to use test
9214 fixtures.
9215 LABELS
9217 Specify a list of text labels associated with a test. The labels are
9218 reported in both the ctest output summary and in dashboard submissions.
9219 They can also be used to filter the set of tests to be executed (see
9220 the ctest -L and ctest -LE options).
9221 See Additional Labels for adding labels to a test dynamically during
9223 test execution.
9224 MEASUREMENT
9226 Specify a CDASH measurement and value to be reported for a test.
9227 If set to a name then that name will be reported to CDASH as a named
9229 measurement with a value of 1. You may also specify a value by setting
9230 MEASUREMENT to measurement=value.
9231 PASS_REGULAR_EXPRESSION
9233 The output must match this regular expression for the test to pass.
9234 The process exit code is ignored.
9235 If set, the test output will be checked against the specified regular
9237 expressions and at least one of the regular expressions has to match,
9238 otherwise the test will fail. Example:
9239 set_tests_properties(mytest PROPERTIES
9241 PASS_REGULAR_EXPRESSION "TestPassed;All ok"
9242 )
9243 PASS_REGULAR_EXPRESSION expects a list of regular expressions.
9245 See also the FAIL_REGULAR_EXPRESSION and SKIP_REGULAR_EXPRESSION test
9247 properties.
9248 PROCESSOR_AFFINITY
9250 New in version 3.12.
9251 Set to a true value to ask CTest to launch the test process with CPU
9254 affinity for a fixed set of processors. If enabled and supported for
9255 the current platform, CTest will choose a set of processors to place in
9256 the CPU affinity mask when launching the test process. The number of
9257 processors in the set is determined by the PROCESSORS test property or
9258 the number of processors available to CTest, whichever is smaller. The
9259 set of processors chosen will be disjoint from the processors assigned
9260 to other concurrently running tests that also have the PROCESSOR_AFFIN‐
9261 ITY property enabled.
9262 PROCESSORS
9264 Set to specify how many process slots this test requires. If not set,
9265 the default is 1 processor.
9266 Denotes the number of processors that this test will require. This is
9268 typically used for MPI tests, and should be used in conjunction with
9269 the ctest_test() PARALLEL_LEVEL option.
9270 This will also be used to display a weighted test timing result in la‐
9272 bel and subproject summaries in the command line output of ctest(1).
9273 The wall clock time for the test run will be multiplied by this prop‐
9274 erty to give a better idea of how much cpu resource CTest allocated for
9275 the test.
9276 See also the PROCESSOR_AFFINITY test property.
9278 REQUIRED_FILES
9280 List of files required to run the test. The filenames are relative to
9281 the test WORKING_DIRECTORY unless an absolute path is specified.
9282 If set to a list of files, the test will not be run unless all of the
9284 files exist.
9285 Examples
9287 Suppose that test.txt is created by test baseTest and none.txt does not
9288 exist:
9289 add_test(NAME baseTest ...) # Assumed to create test.txt
9291 add_test(NAME fileTest ...)
9292 # The following ensures that if baseTest is successful, test.txt will
9294 # have been created before fileTest is run
9295 set_tests_properties(fileTest PROPERTIES
9296 DEPENDS baseTest
9297 REQUIRED_FILES test.txt
9298 )
9299 add_test(NAME notRunTest ...)
9301 # The following makes notRunTest depend on two files. Nothing creates
9303 # the none.txt file, so notRunTest will fail with status "Not Run".
9304 set_tests_properties(notRunTest PROPERTIES
9305 REQUIRED_FILES "test.txt;none.txt"
9306 )
9307 The above example demonstrates how REQUIRED_FILES works, but it is not
9309 the most robust way to implement test ordering with failure detection.
9310 For that, test fixtures are a better alternative (see
9311 FIXTURES_REQUIRED).
9312 RESOURCE_GROUPS
9314 New in version 3.16.
9315 Specify resources required by a test, grouped in a way that is meaning‐
9318 ful to the test. See resource allocation for more information on how
9319 this property integrates into the CTest resource allocation feature.
9320 The RESOURCE_GROUPS property is a semicolon-separated list of group de‐
9322 scriptions. Each entry consists of an optional number of groups using
9323 the description followed by a series of resource requirements for those
9324 groups. These requirements (and the number of groups) are separated by
9325 commas. The resource requirements consist of the name of a resource
9326 type, followed by a colon, followed by an unsigned integer specifying
9327 the number of slots required on one resource of the given type.
9328 The RESOURCE_GROUPS property tells CTest what resources a test expects
9330 to use grouped in a way meaningful to the test. The test itself must
9331 read the environment variables to determine which resources have been
9332 allocated to each group. For example, each group may correspond to a
9333 process the test will spawn when executed.
9334 Consider the following example:
9336 add_test(NAME MyTest COMMAND MyExe)
9338 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
9339 "2,gpus:2"
9340 "gpus:4,crypto_chips:2")
9341 In this example, there are two group descriptions (implicitly separated
9343 by a semicolon.) The content of the first description is 2,gpus:2. This
9344 description specifies 2 groups, each of which requires 2 slots from a
9345 single GPU. The content of the second description is
9346 gpus:4,crypto_chips:2. This description does not specify a group count,
9347 so a default of 1 is assumed. This single group requires 4 slots from
9348 a single GPU and 2 slots from a single cryptography chip. In total, 3
9349 resource groups are specified for this test, each with its own unique
9350 requirements.
9351 Note that the number of slots following the resource type specifies
9353 slots from a single instance of the resource. If the resource group can
9354 tolerate receiving slots from different instances of the same resource,
9355 it can indicate this by splitting the specification into multiple re‐
9356 quirements of one slot. For example:
9357 add_test(NAME MyTest COMMAND MyExe)
9359 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
9360 "gpus:1,gpus:1,gpus:1,gpus:1")
9361 In this case, the single resource group indicates that it needs four
9363 GPU slots, all of which may come from separate GPUs (though they don't
9364 have to; CTest may still assign slots from the same GPU.)
9365 When CTest sets the environment variables for a test, it assigns a
9367 group number based on the group description, starting at 0 on the left
9368 and the number of groups minus 1 on the right. For example, in the ex‐
9369 ample above, the two groups in the first description would have IDs of
9370 0 and 1, and the single group in the second description would have an
9371 ID of 2.
9372 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
9374 purposes, but they are distinct and orthogonal. Resources specified by
9375 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
9376 RESOURCE_LOCK is a simpler property that is used for locking one global
9377 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
9378 tiple tests to simultaneously use multiple resources of the same type,
9379 specifying their requirements in a fine-grained manner.
9380 RESOURCE_LOCK
9382 Specify a list of resources that are locked by this test.
9383 If multiple tests specify the same resource lock, they are guaranteed
9385 not to run concurrently.
9386 See also FIXTURES_REQUIRED if the resource requires any setup or
9388 cleanup steps.
9389 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
9391 purposes, but they are distinct and orthogonal. Resources specified by
9392 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
9393 RESOURCE_LOCK is a simpler property that is used for locking one global
9394 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
9395 tiple tests to simultaneously use multiple resources of the same type,
9396 specifying their requirements in a fine-grained manner.
9397 RUN_SERIAL
9399 Do not run this test in parallel with any other test.
9400 Use this option in conjunction with the ctest_test PARALLEL_LEVEL op‐
9402 tion to specify that this test should not be run in parallel with any
9403 other tests.
9404 SKIP_REGULAR_EXPRESSION
9406 New in version 3.16.
9407 If the output matches this regular expression the test will be marked
9410 as skipped.
9411 If set, if the output matches one of specified regular expressions, the
9413 test will be marked as skipped. Example:
9414 set_property(TEST mytest PROPERTY
9416 SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped"
9417 )
9418 SKIP_REGULAR_EXPRESSION expects a list of regular expressions.
9420 See also the SKIP_RETURN_CODE, PASS_REGULAR_EXPRESSION, and
9422 FAIL_REGULAR_EXPRESSION test properties.
9423 SKIP_RETURN_CODE
9425 Return code to mark a test as skipped.
9426 Sometimes only a test itself can determine if all requirements for the
9428 test are met. If such a situation should not be considered a hard fail‐
9429 ure a return code of the process can be specified that will mark the
9430 test as Not Run if it is encountered. Valid values are in the range of
9431 0 to 255, inclusive.
9432 See also the SKIP_REGULAR_EXPRESSION property.
9434 TIMEOUT
9436 How many seconds to allow for this test.
9437 This property if set will limit a test to not take more than the speci‐
9439 fied number of seconds to run. If it exceeds that the test process
9440 will be killed and ctest will move to the next test. This setting
9441 takes precedence over CTEST_TEST_TIMEOUT.
9442 TIMEOUT_AFTER_MATCH
9444 New in version 3.6.
9445 Change a test's timeout duration after a matching line is encountered
9448 in its output.
9449 Usage
9451 add_test(mytest ...)
9452 set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}")
9453 Description
9455 Allow a test seconds to complete after regex is encountered in its out‐
9456 put.
9457 When the test outputs a line that matches regex its start time is reset
9459 to the current time and its timeout duration is changed to seconds.
9460 Prior to this, the timeout duration is determined by the TIMEOUT prop‐
9461 erty or the CTEST_TEST_TIMEOUT variable if either of these are set.
9462 Because the test's start time is reset, its execution time will not in‐
9463 clude any time that was spent waiting for the matching output.
9464 TIMEOUT_AFTER_MATCH is useful for avoiding spurious timeouts when your
9466 test must wait for some system resource to become available before it
9467 can execute. Set TIMEOUT to a longer duration that accounts for re‐
9468 source acquisition and use TIMEOUT_AFTER_MATCH to control how long the
9469 actual test is allowed to run.
9470 If the required resource can be controlled by CTest you should use
9472 RESOURCE_LOCK instead of TIMEOUT_AFTER_MATCH. This property should be
9473 used when only the test itself can determine when its required re‐
9474 sources are available.
9475 WILL_FAIL
9477 If set to true, this will invert the pass/fail flag of the test.
9478 This property can be used for tests that are expected to fail and re‐
9480 turn a non zero return code.
9481 WORKING_DIRECTORY
9483 The directory from which the test executable will be called.
9484 If this is not set, the test will be run with the working directory set
9486 to the binary directory associated with where the test was created
9487 (i.e. the CMAKE_CURRENT_BINARY_DIR for where add_test() was called).
9488
9490 ABSTRACT
9491 Is this source file an abstract class.
9492 A property on a source file that indicates if the source file repre‐
9494 sents a class that is abstract. This only makes sense for languages
9495 that have a notion of an abstract class and it is only used by some
9496 tools that wrap classes into other languages.
9497 AUTORCC_OPTIONS
9499 Additional options for rcc when using AUTORCC
9500 This property holds additional command line options which will be used
9502 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
9503 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
9504 By default it is empty.
9506 The options set on the .qrc source file may override AUTORCC_OPTIONS
9508 set on the target.
9509 EXAMPLE
9511 # ...
9512 set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9")
9513 # ...
9514 AUTOUIC_OPTIONS
9516 Additional options for uic when using AUTOUIC
9517 This property holds additional command line options which will be used
9519 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
9520 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
9521 By default it is empty.
9523 The options set on the .ui source file may override AUTOUIC_OPTIONS set
9525 on the target.
9526 EXAMPLE
9528 # ...
9529 set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection")
9530 # ...
9531 COMPILE_DEFINITIONS
9533 Preprocessor definitions for compiling a source file.
9534 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
9536 list of preprocessor definitions using the syntax VAR or VAR=value.
9537 Function-style definitions are not supported. CMake will automatically
9538 escape the value correctly for the native build system (note that CMake
9539 language syntax may require escapes to specify some values). This
9540 property may be set on a per-configuration basis using the name COM‐
9541 PILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case name (ex.
9542 COMPILE_DEFINITIONS_DEBUG).
9543 CMake will automatically drop some definitions that are not supported
9545 by the native build tool. Xcode does not support per-configuration
9546 definitions on source files.
9547 Disclaimer: Most native build tools have poor support for escaping cer‐
9549 tain values. CMake has work-arounds for many cases but some values may
9550 just not be possible to pass correctly. If a value does not seem to be
9551 escaped correctly, do not attempt to work-around the problem by adding
9552 escape sequences to the value. Your work-around may break in a future
9553 version of CMake that has improved escape support. Instead consider
9554 defining the macro in a (configured) header file. Then report the lim‐
9555 itation. Known limitations include:
9556 # - broken almost everywhere
9558 ; - broken in VS IDE 7.0 and Borland Makefiles
9559 , - broken in VS IDE
9560 % - broken in some cases in NMake
9561 & | - broken in some cases on MinGW
9562 ^ < > \" - broken in most Make tools on Windows
9563 CMake does not reject these values outright because they do work in
9565 some cases. Use with caution.
9566 Contents of COMPILE_DEFINITIONS may use cmake-generator-expressions(7)
9568 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9569 for available expressions. However, Xcode does not support per-config
9570 per-source settings, so expressions that depend on the build configura‐
9571 tion are not allowed with that generator.
9572 Generator expressions should be preferred instead of setting the alter‐
9574 native per-configuration property.
9575 COMPILE_FLAGS
9577 Additional flags to be added when compiling this source file.
9578 The COMPILE_FLAGS property, managed as a string, sets additional com‐
9580 piler flags used that will be added to the list of compile flags when
9581 this source file builds. The flags will be added after target-wide
9582 flags (except in some cases not supported by the Visual Studio 9 2008
9583 generator).
9584 Use COMPILE_DEFINITIONS to pass additional preprocessor definitions.
9586 Contents of COMPILE_FLAGS may use "generator expressions" with the syn‐
9588 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
9589 able expressions. However, Xcode does not support per-config
9590 per-source settings, so expressions that depend on the build configura‐
9591 tion are not allowed with that generator.
9592 NOTE:
9594 This property has been superseded by the COMPILE_OPTIONS property.
9595 COMPILE_OPTIONS
9597 New in version 3.11.
9598 List of additional options to pass to the compiler.
9601 This property holds a semicolon-separated list of options and will be
9603 added to the list of compile flags when this source file builds. The
9604 options will be added after target-wide options (except in some cases
9605 not supported by the Visual Studio 9 2008 generator).
9606 Contents of COMPILE_OPTIONS may use "generator expressions" with the
9608 syntax $<...>. See the cmake-generator-expressions(7) manual for
9609 available expressions. However, Xcode does not support per-config
9610 per-source settings, so expressions that depend on the build configura‐
9611 tion are not allowed with that generator.
9612 Usage example:
9614 set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer")
9616 Related properties:
9618 • Prefer this property over COMPILE_FLAGS.
9620 • Use COMPILE_DEFINITIONS to pass additional preprocessor definitions.
9622 • Use INCLUDE_DIRECTORIES to pass additional include directories.
9624 Related commands:
9626 • add_compile_options() for directory-wide settings
9628 • target_compile_options() for target-specific settings
9630 EXTERNAL_OBJECT
9632 If set to true then this is an object file.
9633 If this property is set to True then the source file is really an ob‐
9635 ject file and should not be compiled. It will still be linked into the
9636 target though.
9637 Fortran_FORMAT
9639 Set to FIXED or FREE to indicate the Fortran source layout.
9640 This property tells CMake whether a given Fortran source file uses
9642 fixed-format or free-format. CMake will pass the corresponding format
9643 flag to the compiler. Consider using the target-wide Fortran_FORMAT
9644 property if all source files in a target share the same format.
9645 NOTE:
9647 For some compilers, NAG, PGI and Solaris Studio, setting this to OFF
9648 will have no effect.
9649 Fortran_PREPROCESS
9651 New in version 3.18.
9652 Control whether the Fortran source file should be unconditionally pre‐
9655 processed.
9656 If unset or empty, rely on the compiler to determine whether the file
9658 should be preprocessed. If explicitly set to OFF then the file does not
9659 need to be preprocessed. If explicitly set to ON, then the file does
9660 need to be preprocessed as part of the compilation step.
9661 When using the Ninja generator, all source files are first preprocessed
9663 in order to generate module dependency information. Setting this prop‐
9664 erty to OFF will make Ninja skip this step.
9665 Consider using the target-wide Fortran_PREPROCESS property if all
9667 source files in a target need to be preprocessed.
9668 GENERATED
9670 Is this source file generated as part of the build or CMake process.
9671 Changed in version 3.20: The GENERATED source file property is now vis‐
9673 ible in all directories.
9674 Tells the internal CMake engine that a source file is generated by an
9677 outside process such as another build step, or the execution of CMake
9678 itself. This information is then used to exempt the file from any ex‐
9679 istence or validity checks.
9680 Any file that is
9682 • created by the execution of commands such as add_custom_command() and
9684 file(GENERATE)
9685 • listed as one of the BYPRODUCTS of an add_custom_command() or
9687 add_custom_target() command, or
9688 • created by a CMake AUTOGEN operation such as AUTOMOC, AUTORCC, or
9690 AUTOUIC
9691 will be marked with the GENERATED property.
9693 When a generated file created as the OUTPUT of an add_custom_command()
9695 command is explicitly listed as a source file for any target in the
9696 same directory scope (which usually means the same CMakeLists.txt
9697 file), CMake will automatically create a dependency to make sure the
9698 file is generated before building that target.
9699 The Makefile Generators will remove GENERATED files during make clean.
9701 Generated sources may be hidden in some IDE tools, while in others they
9703 might be shown. For the special case of sources generated by CMake's
9704 AUTOMOC, AUTORCC or AUTOUIC functionality, the AUTOGEN_SOURCE_GROUP,
9705 AUTOMOC_SOURCE_GROUP, AUTORCC_SOURCE_GROUP and AUTOUIC_SOURCE_GROUP
9706 target properties may influence where the generated sources are grouped
9707 in the project's file lists.
9708 NOTE:
9710 Starting with CMake 3.20 the GENERATED source file property can be
9711 set and retrieved from any directory scope. It is an all-or-nothing
9712 property. It also can no longer be removed or unset if it was set
9713 to TRUE. Policy CMP0118 was introduced to allow supporting the OLD
9714 behavior for some time.
9715 HEADER_FILE_ONLY
9717 Is this source file only a header file.
9718 A property on a source file that indicates if the source file is a
9720 header file with no associated implementation. This is set automati‐
9721 cally based on the file extension and is used by CMake to determine if
9722 certain dependency information should be computed.
9723 By setting this property to ON, you can disable compilation of the
9725 given source file, even if it should be compiled because it is part of
9726 the library's/executable's sources.
9727 This is useful if you have some source files which you somehow
9729 pre-process, and then add these pre-processed sources via add_library()
9730 or add_executable(). Normally, in IDE, there would be no reference of
9731 the original sources, only of these pre-processed sources. So by set‐
9732 ting this property for all the original source files to ON, and then
9733 either calling add_library() or add_executable() while passing both the
9734 pre-processed sources and the original sources, or by using
9735 target_sources() to add original source files will do exactly what
9736 would one expect, i.e. the original source files would be visible in
9737 IDE, and will not be built.
9738 INCLUDE_DIRECTORIES
9740 New in version 3.11.
9741 List of preprocessor include file search directories.
9744 This property holds a semicolon-separated list of paths and will be
9746 added to the list of include directories when this source file builds.
9747 These directories will take precedence over directories defined at tar‐
9748 get level except for Xcode generator due to technical limitations.
9749 Relative paths should not be added to this property directly.
9751 Contents of INCLUDE_DIRECTORIES may use "generator expressions" with
9753 the syntax $<...>. See the cmake-generator-expressions(7) manual for
9754 available expressions. However, Xcode does not support per-config
9755 per-source settings, so expressions that depend on the build configura‐
9756 tion are not allowed with that generator.
9757 KEEP_EXTENSION
9759 Make the output file have the same extension as the source file.
9760 If this property is set then the file extension of the output file will
9762 be the same as that of the source file. Normally the output file ex‐
9763 tension is computed based on the language of the source file, for exam‐
9764 ple .cxx will go to a .o extension.
9765 LABELS
9767 Specify a list of text labels associated with a source file.
9768 This property has meaning only when the source file is listed in a tar‐
9770 get whose LABELS property is also set. No other semantics are cur‐
9771 rently specified.
9772 LANGUAGE
9774 Specify the programming language in which a source file is written.
9775 A property that can be set to indicate what programming language the
9777 source file is. If it is not set the language is determined based on
9778 the file extension. Typical values are CXX (i.e. C++), C, CSharp,
9779 CUDA, Fortran, HIP, ISPC, and ASM. Setting this property for a file
9780 means this file will be compiled, unless HEADER_FILE_ONLY is set.
9781 Changed in version 3.20: Setting this property causes the source file
9783 to be compiled as the specified language, using explicit flags if pos‐
9784 sible. Previously it only caused the specified language's compiler to
9785 be used. See policy CMP0119.
9786 LOCATION
9789 The full path to a source file.
9790 A read only property on a SOURCE FILE that contains the full path to
9792 the source file.
9793 MACOSX_PACKAGE_LOCATION
9795 Place a source file inside a Application Bundle (MACOSX_BUNDLE), Core
9796 Foundation Bundle (BUNDLE), or Framework Bundle (FRAMEWORK). It is ap‐
9797 plicable for macOS and iOS.
9798 Executable targets with the MACOSX_BUNDLE property set are built as
9800 macOS or iOS application bundles on Apple platforms. Shared library
9801 targets with the FRAMEWORK property set are built as macOS or iOS
9802 frameworks on Apple platforms. Module library targets with the BUNDLE
9803 property set are built as macOS CFBundle bundles on Apple platforms.
9804 Source files listed in the target with this property set will be copied
9805 to a directory inside the bundle or framework content folder specified
9806 by the property value. For macOS Application Bundles the content
9807 folder is <name>.app/Contents. For macOS Frameworks the content folder
9808 is <name>.framework/Versions/<version>. For macOS CFBundles the con‐
9809 tent folder is <name>.bundle/Contents (unless the extension is
9810 changed). See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target
9811 properties for specifying files meant for Headers, PrivateHeaders, or
9812 Resources directories.
9813 If the specified location is equal to Resources, the resulting location
9815 will be the same as if the RESOURCE property had been used. If the
9816 specified location is a sub-folder of Resources, it will be placed into
9817 the respective sub-folder. Note: For iOS Apple uses a flat bundle lay‐
9818 out where no Resources folder exist. Therefore CMake strips the Re‐
9819 sources folder name from the specified location.
9820 OBJECT_DEPENDS
9822 Additional files on which a compiled object file depends.
9823 Specifies a semicolon-separated list of full-paths to files on which
9825 any object files compiled from this source file depend. On Makefile
9826 Generators and the Ninja generator an object file will be recompiled if
9827 any of the named files is newer than it. Visual Studio Generators and
9828 the Xcode generator cannot implement such compilation dependencies.
9829 This property need not be used to specify the dependency of a source
9831 file on a generated header file that it includes. Although the prop‐
9832 erty was originally introduced for this purpose, it is no longer neces‐
9833 sary. If the generated header file is created by a custom command in
9834 the same target as the source file, the automatic dependency scanning
9835 process will recognize the dependency. If the generated header file is
9836 created by another target, an inter-target dependency should be created
9837 with the add_dependencies() command (if one does not already exist due
9838 to linking relationships).
9839 OBJECT_OUTPUTS
9841 Additional outputs for a Ninja or Makefile Generators rule.
9842 Additional outputs created by compilation of this source file. If any
9844 of these outputs is missing the object will be recompiled. This is
9845 supported only on the Ninja and Makefile Generators and will be ignored
9846 on other generators.
9847 This property supports generator expressions.
9849 SKIP_AUTOGEN
9851 New in version 3.8.
9852 Exclude the source file from AUTOMOC, AUTOUIC and AUTORCC processing
9855 (for Qt projects).
9856 For finer exclusion control see SKIP_AUTOMOC, SKIP_AUTOUIC and
9858 SKIP_AUTORCC.
9859 EXAMPLE
9861 # ...
9862 set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
9863 # ...
9864 SKIP_AUTOMOC
9866 New in version 3.8.
9867 Exclude the source file from AUTOMOC processing (for Qt projects).
9870 For broader exclusion control see SKIP_AUTOGEN.
9872 EXAMPLE
9874 # ...
9875 set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
9876 # ...
9877 SKIP_AUTORCC
9879 New in version 3.8.
9880 Exclude the source file from AUTORCC processing (for Qt projects).
9883 For broader exclusion control see SKIP_AUTOGEN.
9885 EXAMPLE
9887 # ...
9888 set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
9889 # ...
9890 SKIP_AUTOUIC
9892 New in version 3.8.
9893 Exclude the source file from AUTOUIC processing (for Qt projects).
9896 SKIP_AUTOUIC can be set on C++ header and source files and on .ui
9898 files.
9899 For broader exclusion control see SKIP_AUTOGEN.
9901 EXAMPLE
9903 # ...
9904 set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
9905 set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON)
9906 set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON)
9907 # ...
9908 SKIP_PRECOMPILE_HEADERS
9910 New in version 3.16.
9911 Is this source file skipped by PRECOMPILE_HEADERS feature.
9914 This property helps with build problems that one would run into when
9916 using the PRECOMPILE_HEADERS feature.
9917 One example would be the usage of Objective-C (*.m) files, and Objec‐
9919 tive-C++ (*.mm) files, which lead to compilation failure because they
9920 are treated (in case of Ninja / Makefile generator) as C, and CXX re‐
9921 spectively. The precompile headers are not compatible between lan‐
9922 guages.
9923 SKIP_UNITY_BUILD_INCLUSION
9925 New in version 3.16.
9926 Setting this property to true ensures the source file will be skipped
9929 by unity builds when its associated target has its UNITY_BUILD property
9930 set to true. The source file will instead be compiled on its own in
9931 the same way as it would with unity builds disabled.
9932 This property helps with "ODR (One definition rule)" problems where
9934 combining a particular source file with others might lead to build er‐
9935 rors or other unintended side effects.
9936 Swift_DEPENDENCIES_FILE
9938 New in version 3.15.
9939 This property sets the path for the Swift dependency file (swiftdeps)
9942 for the source. If one is not specified, it will default to <OB‐
9943 JECT>.swiftdeps.
9944 Swift_DIAGNOSTICS_FILE
9946 New in version 3.15.
9947 This property controls where the Swift diagnostics are serialized.
9950 SYMBOLIC
9952 Is this just a name for a rule.
9953 If SYMBOLIC (boolean) is set to True the build system will be informed
9955 that the source file is not actually created on disk but instead used
9956 as a symbolic name for a build rule.
9957 UNITY_GROUP
9959 New in version 3.18.
9960 This property controls which bucket the source will be part of when the
9963 UNITY_BUILD_MODE is set to GROUP.
9964 VS_COPY_TO_OUT_DIR
9966 New in version 3.8.
9967 Sets the <CopyToOutputDirectory> tag for a source file in a Visual Stu‐
9970 dio project file. Valid values are Never, Always and PreserveNewest.
9971 VS_CSHARP_<tagname>
9973 New in version 3.8.
9974 Visual Studio and CSharp source-file-specific configuration.
9977 Tell the Visual Studio generators to set the source file tag <tagname>
9979 to a given value in the generated Visual Studio CSharp project. Ignored
9980 on other generators and languages. This property can be used to define
9981 dependencies between source files or set any other Visual Studio spe‐
9982 cific parameters.
9983 Example usage:
9985 set_source_files_properties(<filename>
9987 PROPERTIES
9988 VS_CSHARP_DependentUpon <other file>
9989 VS_CSHARP_SubType "Form")
9990 VS_DEPLOYMENT_CONTENT
9992 New in version 3.1.
9993 Mark a source file as content for deployment with a Windows Phone or
9996 Windows Store application when built with a Visual Studio generators.
9997 The value must evaluate to either 1 or 0 and may use generator expres‐
9998 sions to make the choice based on the build configuration. The .vcx‐
9999 proj file entry for the source file will be marked either Deployment‐
10000 Content or ExcludedFromBuild for values 1 and 0, respectively.
10001 VS_DEPLOYMENT_LOCATION
10003 New in version 3.1.
10004 Specifies the deployment location for a content source file with a Win‐
10007 dows Phone or Windows Store application when built with a Visual Studio
10008 generators. This property is only applicable when using
10009 VS_DEPLOYMENT_CONTENT. The value represent the path relative to the
10010 app package and applies to all configurations.
10011 VS_INCLUDE_IN_VSIX
10013 New in version 3.8.
10014 Boolean property to specify if the file should be included within a
10017 VSIX (Visual Studio Integration Extension) extension package. This is
10018 needed for development of Visual Studio extensions.
10019 VS_RESOURCE_GENERATOR
10021 New in version 3.8.
10022 This property allows to specify the resource generator to be used on
10025 this file. It defaults to PublicResXFileCodeGenerator if not set.
10026 This property only applies to C# projects.
10028 VS_SETTINGS
10030 New in version 3.18.
10031 Set any item metadata on a file.
10034 New in version 3.22: This property is honored for all source file
10036 types. Previously it worked only for non-built files.
10037 Takes a list of Key=Value pairs. Tells the Visual Studio generator to
10040 set Key to Value as item metadata on the file.
10041 For example:
10043 set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2")
10045 will set Key to Value and Key2 to Value2 on the file.hlsl item as meta‐
10047 data.
10048 Generator expressions are supported.
10050 VS_SHADER_DISABLE_OPTIMIZATIONS
10052 New in version 3.11.
10053 Disable compiler optimizations for an .hlsl source file. This adds the
10056 -Od flag to the command line for the FxCompiler tool. Specify the
10057 value true for this property to disable compiler optimizations.
10058 VS_SHADER_ENABLE_DEBUG
10060 New in version 3.11.
10061 Enable debugging information for an .hlsl source file. This adds the
10064 -Zi flag to the command line for the FxCompiler tool. Specify the
10065 value true to generate debugging information for the compiled shader.
10066 VS_SHADER_ENTRYPOINT
10068 New in version 3.1.
10069 Specifies the name of the entry point for the shader of a .hlsl source
10072 file.
10073 VS_SHADER_FLAGS
10075 New in version 3.2.
10076 Set additional Visual Studio shader flags of a .hlsl source file.
10079 VS_SHADER_MODEL
10081 New in version 3.1.
10082 Specifies the shader model of a .hlsl source file. Some shader types
10085 can only be used with recent shader models
10086 VS_SHADER_OBJECT_FILE_NAME
10088 New in version 3.12.
10089 Specifies a file name for the compiled shader object file for an .hlsl
10092 source file. This adds the -Fo flag to the command line for the FxCom‐
10093 piler tool.
10094 VS_SHADER_OUTPUT_HEADER_FILE
10096 New in version 3.10.
10097 Set filename for output header file containing object code of a .hlsl
10100 source file.
10101 VS_SHADER_TYPE
10103 New in version 3.1.
10104 Set the Visual Studio shader type of a .hlsl source file.
10107 VS_SHADER_VARIABLE_NAME
10109 New in version 3.10.
10110 Set name of variable in header file containing object code of a .hlsl
10113 source file.
10114 VS_TOOL_OVERRIDE
10116 New in version 3.7.
10117 Override the default Visual Studio tool that will be applied to the
10120 source file with a new tool not based on the extension of the file.
10121 VS_XAML_TYPE
10123 New in version 3.3.
10124 Mark a Extensible Application Markup Language (XAML) source file as a
10127 different type than the default Page. The most common usage would be
10128 to set the default App.xaml file as ApplicationDefinition.
10129 WRAP_EXCLUDE
10131 Exclude this source file from any code wrapping techniques.
10132 Some packages can wrap source files into alternate languages to provide
10134 additional functionality.
10135 For example, C++ code can be wrapped into Java or Python, using SWIG.
10137 If WRAP_EXCLUDE is set to True, that indicates that this source file
10138 should not be wrapped.
10139 XCODE_EXPLICIT_FILE_TYPE
10141 New in version 3.1.
10142 Set the Xcode explicitFileType attribute on its reference to a source
10145 file. CMake computes a default based on file extension but can be told
10146 explicitly with this property.
10147 See also XCODE_LAST_KNOWN_FILE_TYPE.
10149 XCODE_FILE_ATTRIBUTES
10151 New in version 3.7.
10152 Add values to the Xcode ATTRIBUTES setting on its reference to a source
10155 file. Among other things, this can be used to set the role on a .mig
10156 file:
10157 set_source_files_properties(defs.mig
10159 PROPERTIES
10160 XCODE_FILE_ATTRIBUTES "Client;Server"
10161 )
10162 XCODE_LAST_KNOWN_FILE_TYPE
10164 New in version 3.1.
10165 Set the Xcode lastKnownFileType attribute on its reference to a source
10168 file. CMake computes a default based on file extension but can be told
10169 explicitly with this property.
10170 See also XCODE_EXPLICIT_FILE_TYPE, which is preferred over this prop‐
10172 erty if set.
10173
10175 ADVANCED
10176 True if entry should be hidden by default in GUIs.
10177 This is a boolean value indicating whether the entry is considered in‐
10179 teresting only for advanced configuration. The mark_as_advanced() com‐
10180 mand modifies this property.
10181 HELPSTRING
10183 Help associated with entry in GUIs.
10184 This string summarizes the purpose of an entry to help users set it
10186 through a CMake GUI.
10187 MODIFIED
10189 Internal management property. Do not set or get.
10190 This is an internal cache entry property managed by CMake to track in‐
10192 teractive user modification of entries. Ignore it.
10193 STRINGS
10195 Enumerate possible STRING entry values for GUI selection.
10196 For cache entries with type STRING, this enumerates a set of values.
10198 CMake GUIs may use this to provide a selection widget instead of a
10199 generic string entry field. This is for convenience only. CMake does
10200 not enforce that the value matches one of those listed.
10201 TYPE
10203 Widget type for entry in GUIs.
10204 Cache entry values are always strings, but CMake GUIs present widgets
10206 to help users set values. The GUIs use this property as a hint to de‐
10207 termine the widget type. Valid TYPE values are:
10208 BOOL = Boolean ON/OFF value.
10210 PATH = Path to a directory.
10211 FILEPATH = Path to a file.
10212 STRING = Generic string value.
10213 INTERNAL = Do not present in GUI at all.
10214 STATIC = Value managed by CMake, do not change.
10215 UNINITIALIZED = Type not yet specified.
10216 Generally the TYPE of a cache entry should be set by the command which
10218 creates it ( set(), option(), find_library(), etc.).
10219 VALUE
10221 Value of a cache entry.
10222 This property maps to the actual value of a cache entry. Setting this
10224 property always sets the value without checking, so use with care.
10225
10227 CPACK_DESKTOP_SHORTCUTS
10228 New in version 3.3.
10229 Species a list of shortcut names that should be created on the Desktop
10232 for this file.
10233 The property is currently only supported by the CPack WIX Generator.
10235 CPACK_NEVER_OVERWRITE
10237 New in version 3.1.
10238 Request that this file not be overwritten on install or reinstall.
10241 The property is currently only supported by the CPack WIX Generator.
10243 CPACK_PERMANENT
10245 New in version 3.1.
10246 Request that this file not be removed on uninstall.
10249 The property is currently only supported by the CPack WIX Generator.
10251 CPACK_START_MENU_SHORTCUTS
10253 New in version 3.3.
10254 Species a list of shortcut names that should be created in the Start
10257 Menu for this file.
10258 The property is currently only supported by the CPack WIX Generator.
10260 CPACK_STARTUP_SHORTCUTS
10262 New in version 3.3.
10263 Species a list of shortcut names that should be created in the Startup
10266 folder for this file.
10267 The property is currently only supported by the CPack WIX Generator.
10269 CPACK_WIX_ACL
10271 New in version 3.1.
10272 Specifies access permissions for files or directories installed by a
10275 WiX installer.
10276 The property can contain multiple list entries, each of which has to
10278 match the following format.
10279 <user>[@<domain>]=<permission>[,<permission>]
10281 <user> and <domain> specify the windows user and domain for which the
10283 <Permission> element should be generated.
10284 <permission> is any of the YesNoType attributes listed here:
10286 http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html
10288 The property is currently only supported by the CPack WIX Generator.
10290
10292 ADDITIONAL_MAKE_CLEAN_FILES
10293 Deprecated since version 3.15: Use ADDITIONAL_CLEAN_FILES instead.
10294 Additional files to remove during the clean stage.
10297 A ;-list of files that will be removed as a part of the make clean tar‐
10299 get.
10300 Arguments to ADDITIONAL_MAKE_CLEAN_FILES may use generator expressions.
10302 This property only works for the Makefile generators. It is ignored on
10304 other generators.
10305 COMPILE_DEFINITIONS_<CONFIG>
10307 Ignored. See CMake Policy CMP0043.
10308 Per-configuration preprocessor definitions in a directory.
10310 This is the configuration-specific version of COMPILE_DEFINITIONS where
10312 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
10313 This property will be initialized in each directory by its value in the
10315 directory's parent.
10316 Contents of COMPILE_DEFINITIONS_<CONFIG> may use "generator expres‐
10318 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10319 manual for available expressions. See the cmake-buildsystem(7) manual
10320 for more on defining buildsystem properties.
10321 Generator expressions should be preferred instead of setting this prop‐
10323 erty.
10324 TEST_INCLUDE_FILE
10326 Deprecated. Use TEST_INCLUDE_FILES instead.
10327 A cmake file that will be included when ctest is run.
10329 If you specify TEST_INCLUDE_FILE, that file will be included and pro‐
10331 cessed when ctest is run on the directory.
10332
10334 COMPILE_DEFINITIONS_<CONFIG>
10335 Ignored. See CMake Policy CMP0043.
10336 Per-configuration preprocessor definitions on a target.
10338 This is the configuration-specific version of COMPILE_DEFINITIONS where
10340 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
10341 Contents of COMPILE_DEFINITIONS_<CONFIG> may use "generator expres‐
10343 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10344 manual for available expressions. See the cmake-buildsystem(7) manual
10345 for more on defining buildsystem properties.
10346 Generator expressions should be preferred instead of setting this prop‐
10348 erty.
10349 POST_INSTALL_SCRIPT
10351 Deprecated install support.
10352 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
10354 way to specify CMake scripts to run before and after installing a tar‐
10355 get. They are used only when the old INSTALL_TARGETS command is used
10356 to install the target. Use the install() command instead.
10357 PRE_INSTALL_SCRIPT
10359 Deprecated install support.
10360 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
10362 way to specify CMake scripts to run before and after installing a tar‐
10363 get. They are used only when the old INSTALL_TARGETS command is used
10364 to install the target. Use the install() command instead.
10365
10367 COMPILE_DEFINITIONS_<CONFIG>
10368 Ignored. See CMake Policy CMP0043.
10369 Per-configuration preprocessor definitions on a source file.
10371 This is the configuration-specific version of COMPILE_DEFINITIONS.
10373 Note that Xcode does not support per-configuration source file flags so
10374 this property will be ignored by the Xcode generator.
10375
10377 2000-2023 Kitware, Inc. and Contributors
103783.25.2 Jan 19, 2023 CMAKE-PROPERTIES(7)