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(). AUTO‐
36 GEN_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 Controls whether to use the FOLDER target property to organize targets
757 into folders. The value of USE_FOLDERS at the end of the top level
758 CMakeLists.txt file is what determines the behavior.
759 Changed in version 3.26: CMake treats this property as ON by default.
761 See policy CMP0143.
762 Not all CMake generators support recording folder details for targets.
765 The Xcode and Visual Studio generators are examples of generators that
766 do. Similarly, not all IDEs support presenting targets using folder
767 hierarchies, even if the CMake generator used provides the necessary
768 information.
769 XCODE_EMIT_EFFECTIVE_PLATFORM_NAME
771 New in version 3.8.
772 Control emission of EFFECTIVE_PLATFORM_NAME by the Xcode generator.
775 It is required for building the same target with multiple SDKs. A com‐
777 mon use case is the parallel use of iphoneos and iphonesimulator SDKs.
778 Three different states possible that control when the Xcode generator
780 emits the EFFECTIVE_PLATFORM_NAME variable:
781 • If set to ON it will always be emitted
783 • If set to OFF it will never be emitted
785 • If unset (the default) it will only be emitted when the project was
787 configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
788 of the simulators.
789 NOTE:
791 When this behavior is enable for generated Xcode projects, the EF‐
792 FECTIVE_PLATFORM_NAME variable will leak into Generator expressions
793 like TARGET_FILE and will render those mostly unusable.
794
796 ADDITIONAL_CLEAN_FILES
797 New in version 3.15.
798 A ;-list of files or directories that will be removed as a part of the
801 global clean target. It is useful for specifying generated files or
802 directories that are used by multiple targets or by CMake itself, or
803 that are generated in ways which cannot be captured as outputs or
804 byproducts of custom commands.
805 If an additional clean file is specific to a single target only, then
807 the ADDITIONAL_CLEAN_FILES target property would usually be a better
808 choice than this directory property.
809 Relative paths are allowed and are interpreted relative to the current
811 binary directory.
812 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
814 This property only works for the Ninja and the Makefile generators. It
816 is ignored by other generators.
817 BINARY_DIR
819 New in version 3.7.
820 This read-only directory property reports absolute path to the binary
823 directory corresponding to the source on which it is read.
824 BUILDSYSTEM_TARGETS
826 New in version 3.7.
827 This read-only directory property contains a semicolon-separated list
830 of buildsystem targets added in the directory by calls to the
831 add_library(), add_executable(), and add_custom_target() commands. The
832 list does not include any Imported Targets or Alias Targets, but does
833 include Interface Libraries. Each entry in the list is the logical
834 name of a target, suitable to pass to the get_property() command TARGET
835 option.
836 See also the IMPORTED_TARGETS directory property.
838 CACHE_VARIABLES
840 List of cache variables available in the current directory.
841 This read-only property specifies the list of CMake cache variables
843 currently defined. It is intended for debugging purposes.
844 CLEAN_NO_CUSTOM
846 Set to true to tell Makefile Generators not to remove the outputs of
847 custom commands for this directory during the make clean operation.
848 This is ignored on other generators because it is not possible to im‐
849 plement.
850 CMAKE_CONFIGURE_DEPENDS
852 Tell CMake about additional input files to the configuration process.
853 If any named file is modified the build system will re-run CMake to
854 re-configure the file and generate the build system again.
855 Specify files as a semicolon-separated list of paths. Relative paths
857 are interpreted as relative to the current source directory.
858 COMPILE_DEFINITIONS
860 Preprocessor definitions for compiling a directory's sources.
861 This property specifies the list of options given so far to the
863 add_compile_definitions() (or add_definitions()) command.
864 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
866 list of preprocessor definitions using the syntax VAR or VAR=value.
867 Function-style definitions are not supported. CMake will automatically
868 escape the value correctly for the native build system (note that CMake
869 language syntax may require escapes to specify some values).
870 This property will be initialized in each directory by its value in the
872 directory's parent.
873 CMake will automatically drop some definitions that are not supported
875 by the native build tool.
876 New in version 3.26: Any leading -D on an item will be removed.
878 Disclaimer: Most native build tools have poor support for escaping cer‐
881 tain values. CMake has work-arounds for many cases but some values may
882 just not be possible to pass correctly. If a value does not seem to be
883 escaped correctly, do not attempt to work-around the problem by adding
884 escape sequences to the value. Your work-around may break in a future
885 version of CMake that has improved escape support. Instead consider
886 defining the macro in a (configured) header file. Then report the lim‐
887 itation. Known limitations include:
888 # - broken almost everywhere
890 ; - broken in VS IDE 7.0 and Borland Makefiles
891 , - broken in VS IDE
892 % - broken in some cases in NMake
893 & | - broken in some cases on MinGW
894 ^ < > \" - broken in most Make tools on Windows
895 CMake does not reject these values outright because they do work in
897 some cases. Use with caution.
898 Contents of COMPILE_DEFINITIONS may use "generator expressions" with
900 the syntax $<...>. See the cmake-generator-expressions(7) manual for
901 available expressions. See the cmake-buildsystem(7) manual for more on
902 defining buildsystem properties.
903 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
905 specify per-configuration definitions. Generator expressions should be
906 preferred instead of setting the alternative property.
907 COMPILE_OPTIONS
909 List of options to pass to the compiler.
910 This property holds a semicolon-separated list of options given so far
912 to the add_compile_options() command.
913 This property is used to initialize the COMPILE_OPTIONS target property
915 when a target is created, which is used by the generators to set the
916 options for the compiler.
917 Contents of COMPILE_OPTIONS may use "generator expressions" with the
919 syntax $<...>. See the cmake-generator-expressions(7) manual for
920 available expressions. See the cmake-buildsystem(7) manual for more on
921 defining buildsystem properties.
922 DEFINITIONS
924 For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead.
925 This read-only property specifies the list of flags given so far to the
927 add_definitions() command. It is intended for debugging purposes. Use
928 the COMPILE_DEFINITIONS directory property instead.
929 This built-in read-only property does not exist if policy CMP0059 is
931 set to NEW.
932 EXCLUDE_FROM_ALL
934 Set this directory property to a true value on a subdirectory to ex‐
935 clude its targets from the "all" target of its ancestors. If excluded,
936 running e.g. make in the parent directory will not build targets the
937 subdirectory by default. This does not affect the "all" target of the
938 subdirectory itself. Running e.g. make inside the subdirectory will
939 still build its targets.
940 If the EXCLUDE_FROM_ALL target property is set on a target then its
942 value determines whether the target is included in the "all" target of
943 this directory and its ancestors.
944 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
946 Specify #include line transforms for dependencies in a directory.
947 This property specifies rules to transform macro-like #include lines
949 during implicit dependency scanning of C and C++ source files. The
950 list of rules must be semicolon-separated with each entry of the form
951 A_MACRO(%)=value-with-% (the % must be literal). During dependency
952 scanning occurrences of A_MACRO(...) on #include lines will be replaced
953 by the value given with the macro argument substituted for %. For ex‐
954 ample, the entry
955 MYDIR(%)=<mydir/%>
957 will convert lines of the form
959 #include MYDIR(myheader.h)
961 to
963 #include <mydir/myheader.h>
965 allowing the dependency to be followed.
967 This property applies to sources in all targets within a directory.
969 The property value is initialized in each directory by its value in the
970 directory's parent.
971 IMPORTED_TARGETS
973 New in version 3.21.
974 This read-only directory property contains a semicolon-separated list
977 of Imported Targets added in the directory by calls to the
978 add_library() and add_executable() commands. Each entry in the list is
979 the logical name of a target, suitable to pass to the get_property()
980 command TARGET option when called in the same directory.
981 See also the BUILDSYSTEM_TARGETS directory property.
983 INCLUDE_DIRECTORIES
985 List of preprocessor include file search directories.
986 This property specifies the list of directories given so far to the
988 include_directories() command.
989 This property is used to populate the INCLUDE_DIRECTORIES target prop‐
991 erty, which is used by the generators to set the include directories
992 for the compiler.
993 In addition to accepting values from that command, values may be set
995 directly on any directory using the set_property() command, and can be
996 set on the current directory using the set_directory_properties() com‐
997 mand. A directory gets its initial value from its parent directory if
998 it has one. The initial value of the INCLUDE_DIRECTORIES target prop‐
999 erty comes from the value of this property. Both directory and target
1000 property values are adjusted by calls to the include_directories() com‐
1001 mand. Calls to set_property() or set_directory_properties(), however,
1002 will update the directory property value without updating target prop‐
1003 erty values. Therefore direct property updates must be made before
1004 calls to add_executable() or add_library() for targets they are meant
1005 to affect.
1006 The target property values are used by the generators to set the in‐
1008 clude paths for the compiler.
1009 Contents of INCLUDE_DIRECTORIES may use "generator expressions" with
1011 the syntax $<...>. See the cmake-generator-expressions(7) manual for
1012 available expressions. See the cmake-buildsystem(7) manual for more on
1013 defining buildsystem properties.
1014 INCLUDE_REGULAR_EXPRESSION
1016 Include file scanning regular expression.
1017 This property specifies the regular expression used during dependency
1019 scanning to match include files that should be followed. See the
1020 include_regular_expression() command for a high-level interface to set
1021 this property.
1022 LABELS
1024 New in version 3.10.
1025 Specify a list of text labels associated with a directory and all of
1028 its subdirectories. This is equivalent to setting the LABELS target
1029 property and the LABELS test property on all targets and tests in the
1030 current directory and subdirectories. Note: Launchers must enabled to
1031 propagate labels to targets.
1032 The CMAKE_DIRECTORY_LABELS variable can be used to initialize this
1034 property.
1035 The list is reported in dashboard submissions.
1037 LINK_DIRECTORIES
1039 List of linker search directories.
1040 This property holds a semicolon-separated list of directories and is
1042 typically populated using the link_directories() command. It gets its
1043 initial value from its parent directory, if it has one.
1044 The directory property is used to initialize the LINK_DIRECTORIES tar‐
1046 get property when a target is created. That target property is used by
1047 the generators to set the library search directories for the linker.
1048 Contents of LINK_DIRECTORIES may use "generator expressions" with the
1050 syntax $<...>. See the cmake-generator-expressions(7) manual for
1051 available expressions. See the cmake-buildsystem(7) manual for more on
1052 defining buildsystem properties.
1053 LINK_OPTIONS
1055 New in version 3.13.
1056 List of options to use for the link step of shared library, module and
1059 executable targets as well as the device link step.
1060 This property holds a semicolon-separated list of options given so far
1062 to the add_link_options() command.
1063 This property is used to initialize the LINK_OPTIONS target property
1065 when a target is created, which is used by the generators to set the
1066 options for the compiler.
1067 Contents of LINK_OPTIONS may use "generator expressions" with the syn‐
1069 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
1070 able expressions. See the cmake-buildsystem(7) manual for more on
1071 defining buildsystem properties.
1072 LISTFILE_STACK
1074 The current stack of listfiles being processed.
1075 This property is mainly useful when trying to debug errors in your
1077 CMake scripts. It returns a list of what list files are currently be‐
1078 ing processed, in order. So if one listfile does an include() command
1079 then that is effectively pushing the included listfile onto the stack.
1080 MACROS
1082 List of macro commands available in the current directory.
1083 This read-only property specifies the list of CMake macros currently
1085 defined. It is intended for debugging purposes. See the macro() com‐
1086 mand.
1087 PARENT_DIRECTORY
1089 Source directory that added current subdirectory.
1090 This read-only property specifies the source directory that added the
1092 current source directory as a subdirectory of the build. In the
1093 top-level directory the value is the empty-string.
1094 RULE_LAUNCH_COMPILE
1096 Specify a launcher for compile rules.
1097 NOTE:
1099 This property is intended for internal use by ctest(1). Projects
1100 and developers should use the <LANG>_COMPILER_LAUNCHER target prop‐
1101 erties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables
1102 instead.
1103 See the global property of the same name for details. This overrides
1105 the global property for a directory.
1106 RULE_LAUNCH_CUSTOM
1108 Specify a launcher for custom rules.
1109 See the global property of the same name for details. This overrides
1111 the global property for a directory.
1112 RULE_LAUNCH_LINK
1114 Specify a launcher for link rules.
1115 NOTE:
1117 This property is intended for internal use by ctest(1). Projects
1118 and developers should use the <LANG>_LINKER_LAUNCHER target proper‐
1119 ties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables in‐
1120 stead.
1121 See the global property of the same name for details. This overrides
1123 the global property for a directory.
1124 SOURCE_DIR
1126 New in version 3.7.
1127 This read-only directory property reports absolute path to the source
1130 directory on which it is read.
1131 SUBDIRECTORIES
1133 New in version 3.7.
1134 This read-only directory property contains a semicolon-separated list
1137 of subdirectories processed so far by the add_subdirectory() or
1138 subdirs() commands. Each entry is the absolute path to the source di‐
1139 rectory (containing the CMakeLists.txt file). This is suitable to pass
1140 to the get_property() command DIRECTORY option.
1141 NOTE:
1143 The subdirs() command does not process its arguments until after the
1144 calling directory is fully processed. Therefore looking up this
1145 property in the current directory will not see them.
1146 SYSTEM
1148 New in version 3.25.
1149 This directory property is used to initialize the SYSTEM target prop‐
1152 erty for non-imported targets created in that directory. It is set to
1153 true by add_subdirectory() and FetchContent_Declare() when the SYSTEM
1154 option is given as an argument to those commands.
1155 TESTS
1157 New in version 3.12.
1158 List of tests.
1161 This read-only property holds a semicolon-separated list of tests de‐
1163 fined so far, in the current directory, by the add_test() command.
1164 TEST_INCLUDE_FILES
1166 New in version 3.10.
1167 A list of cmake files that will be included when ctest is run.
1170 If you specify TEST_INCLUDE_FILES, those files will be included and
1172 processed when ctest is run on the directory.
1173 VARIABLES
1175 List of variables defined in the current directory.
1176 This read-only property specifies the list of CMake variables currently
1178 defined. It is intended for debugging purposes.
1179 VS_GLOBAL_SECTION_POST_<section>
1181 Specify a postSolution global section in Visual Studio.
1182 Setting a property like this generates an entry of the following form
1184 in the solution file:
1185 GlobalSection(<section>) = postSolution
1187 <contents based on property value>
1188 EndGlobalSection
1189 The property must be set to a semicolon-separated list of key=value
1191 pairs. Each such pair will be transformed into an entry in the solu‐
1192 tion global section. Whitespace around key and value is ignored. List
1193 elements which do not contain an equal sign are skipped.
1194 This property only works for Visual Studio 9 and above; it is ignored
1196 on other generators. The property only applies when set on a directory
1197 whose CMakeLists.txt contains a project() command.
1198 Note that CMake generates postSolution sections ExtensibilityGlobals
1200 and ExtensibilityAddIns by default. If you set the corresponding prop‐
1201 erty, it will override the default section. For example, setting
1202 VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default
1203 contents of the ExtensibilityGlobals section, while keeping Extensibil‐
1204 ityAddIns on its default. However, CMake will always add a Solu‐
1205 tionGuid to the ExtensibilityGlobals section if it is not specified ex‐
1206 plicitly.
1207 VS_GLOBAL_SECTION_PRE_<section>
1209 Specify a preSolution global section in Visual Studio.
1210 Setting a property like this generates an entry of the following form
1212 in the solution file:
1213 GlobalSection(<section>) = preSolution
1215 <contents based on property value>
1216 EndGlobalSection
1217 The property must be set to a semicolon-separated list of key=value
1219 pairs. Each such pair will be transformed into an entry in the solu‐
1220 tion global section. Whitespace around key and value is ignored. List
1221 elements which do not contain an equal sign are skipped.
1222 This property only works for Visual Studio 9 and above; it is ignored
1224 on other generators. The property only applies when set on a directory
1225 whose CMakeLists.txt contains a project() command.
1226 VS_STARTUP_PROJECT
1228 New in version 3.6.
1229 Specify the default startup project in a Visual Studio solution.
1232 The Visual Studio Generators create a .sln file for each directory
1234 whose CMakeLists.txt file calls the project() command. Set this prop‐
1235 erty in the same directory as a project() command call (e.g. in the
1236 top-level CMakeLists.txt file) to specify the default startup project
1237 for the corresponding solution file.
1238 The property must be set to the name of an existing target. This will
1240 cause that project to be listed first in the generated solution file
1241 causing Visual Studio to make it the startup project if the solution
1242 has never been opened before.
1243 If this property is not specified, then the ALL_BUILD project will be
1245 the default.
1246
1248 ADDITIONAL_CLEAN_FILES
1249 New in version 3.15.
1250 A ;-list of files or directories that will be removed as a part of the
1253 global clean target. It can be used to specify files and directories
1254 that are generated as part of building the target or that are directly
1255 associated with the target in some way (e.g. created as a result of
1256 running the target).
1257 For custom targets, if such files can be captured as outputs or byprod‐
1259 ucts instead, then that should be preferred over adding them to this
1260 property. If an additional clean file is used by multiple targets or
1261 isn't target-specific, then the ADDITIONAL_CLEAN_FILES directory prop‐
1262 erty may be the more appropriate property to use.
1263 Relative paths are allowed and are interpreted relative to the current
1265 binary directory.
1266 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
1268 This property only works for the Ninja and the Makefile generators. It
1270 is ignored by other generators.
1271 AIX_EXPORT_ALL_SYMBOLS
1273 New in version 3.17.
1274 On AIX, CMake automatically exports all symbols from shared libraries,
1277 and from executables with the ENABLE_EXPORTS target property set. Ex‐
1278 plicitly disable this boolean property to suppress the behavior and ex‐
1279 port no symbols by default. In this case it is expected that the
1280 project will use other means to export some symbols.
1281 This property is initialized by the value of the
1283 CMAKE_AIX_EXPORT_ALL_SYMBOLS variable if it is set when a target is
1284 created.
1285 ALIAS_GLOBAL
1287 New in version 3.18.
1288 Read-only property indicating of whether an ALIAS target is globally
1291 visible.
1292 The boolean value of this property is TRUE for aliases to IMPORTED tar‐
1294 gets created with the GLOBAL options to add_executable() or
1295 add_library(), FALSE otherwise. It is undefined for targets built
1296 within the project.
1297 NOTE:
1299 Promoting an IMPORTED target from LOCAL to GLOBAL scope by changing
1300 the value or IMPORTED_GLOBAL target property do not change the scope
1301 of local aliases.
1302 ALIASED_TARGET
1304 Name of target aliased by this target.
1305 If this is an Alias Target, this property contains the name of the tar‐
1307 get aliased.
1308 ANDROID_ANT_ADDITIONAL_OPTIONS
1310 New in version 3.4.
1311 Set the additional options for Android Ant build system. This is a
1314 string value containing all command line options for the Ant build.
1315 This property is initialized by the value of the
1316 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS variable if it is set when a tar‐
1317 get is created.
1318 ANDROID_API
1320 New in version 3.1.
1321 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1324 Edition, this property sets the Android target API version (e.g. 15).
1325 The version number must be a positive decimal integer. This property
1326 is initialized by the value of the CMAKE_ANDROID_API variable if it is
1327 set when a target is created.
1328 ANDROID_API_MIN
1330 New in version 3.2.
1331 Set the Android MIN API version (e.g. 9). The version number must be a
1334 positive decimal integer. This property is initialized by the value of
1335 the CMAKE_ANDROID_API_MIN variable if it is set when a target is cre‐
1336 ated. Native code builds using this API version.
1337 ANDROID_ARCH
1339 New in version 3.4.
1340 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1343 Edition, this property sets the Android target architecture.
1344 This is a string property that could be set to the one of the following
1346 values:
1347 • armv7-a: "ARMv7-A (armv7-a)"
1349 • armv7-a-hard: "ARMv7-A, hard-float ABI (armv7-a)"
1351 • arm64-v8a: "ARMv8-A, 64bit (arm64-v8a)"
1353 • x86: "x86 (x86)"
1355 • x86_64: "x86_64 (x86_64)"
1357 This property is initialized by the value of the CMAKE_ANDROID_ARCH
1359 variable if it is set when a target is created.
1360 ANDROID_ASSETS_DIRECTORIES
1362 New in version 3.4.
1363 Set the Android assets directories to copy into the main assets folder
1366 before build. This a string property that contains the directory paths
1367 separated by semicolon. This property is initialized by the value of
1368 the CMAKE_ANDROID_ASSETS_DIRECTORIES variable if it is set when a tar‐
1369 get is created.
1370 ANDROID_GUI
1372 New in version 3.1.
1373 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1376 Edition, this property specifies whether to build an executable as an
1377 application package on Android.
1378 When this property is set to true the executable when built for Android
1380 will be created as an application package. This property is initial‐
1381 ized by the value of the CMAKE_ANDROID_GUI variable if it is set when a
1382 target is created.
1383 Add the AndroidManifest.xml source file explicitly to the target
1385 add_executable() command invocation to specify the root directory of
1386 the application package source.
1387 ANDROID_JAR_DEPENDENCIES
1389 New in version 3.4.
1390 Set the Android property that specifies JAR dependencies. This is a
1393 string value property. This property is initialized by the value of the
1394 CMAKE_ANDROID_JAR_DEPENDENCIES variable if it is set when a target is
1395 created.
1396 ANDROID_JAR_DIRECTORIES
1398 New in version 3.4.
1399 Set the Android property that specifies directories to search for the
1402 JAR libraries.
1403 This a string property that contains the directory paths separated by
1405 semicolons. This property is initialized by the value of the
1406 CMAKE_ANDROID_JAR_DIRECTORIES variable if it is set when a target is
1407 created.
1408 Contents of ANDROID_JAR_DIRECTORIES may use "generator expressions"
1410 with the syntax $<...>. See the cmake-generator-expressions(7) manual
1411 for available expressions.
1412 ANDROID_JAVA_SOURCE_DIR
1414 New in version 3.4.
1415 Set the Android property that defines the Java source code root direc‐
1418 tories. This a string property that contains the directory paths sepa‐
1419 rated by semicolon. This property is initialized by the value of the
1420 CMAKE_ANDROID_JAVA_SOURCE_DIR variable if it is set when a target is
1421 created.
1422 ANDROID_NATIVE_LIB_DEPENDENCIES
1424 New in version 3.4.
1425 Set the Android property that specifies the .so dependencies. This is
1428 a string property.
1429 This property is initialized by the value of the
1431 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES variable if it is set when a tar‐
1432 get is created.
1433 Contents of ANDROID_NATIVE_LIB_DEPENDENCIES may use "generator expres‐
1435 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
1436 manual for available expressions.
1437 ANDROID_NATIVE_LIB_DIRECTORIES
1439 New in version 3.4.
1440 Set the Android property that specifies directories to search for the
1443 .so libraries.
1444 This a string property that contains the directory paths separated by
1446 semicolons.
1447 This property is initialized by the value of the
1449 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES variable if it is set when a tar‐
1450 get is created.
1451 Contents of ANDROID_NATIVE_LIB_DIRECTORIES may use "generator expres‐
1453 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
1454 manual for available expressions.
1455 ANDROID_PROCESS_MAX
1457 New in version 3.4.
1458 Set the Android property that defines the maximum number of a parallel
1461 Android NDK compiler processes (e.g. 4). This property is initialized
1462 by the value of the CMAKE_ANDROID_PROCESS_MAX variable if it is set
1463 when a target is created.
1464 ANDROID_PROGUARD
1466 New in version 3.4.
1467 When this property is set to true that enables the ProGuard tool to
1470 shrink, optimize, and obfuscate the code by removing unused code and
1471 renaming classes, fields, and methods with semantically obscure names.
1472 This property is initialized by the value of the CMAKE_ANDROID_PROGUARD
1473 variable if it is set when a target is created.
1474 ANDROID_PROGUARD_CONFIG_PATH
1476 New in version 3.4.
1477 Set the Android property that specifies the location of the ProGuard
1480 config file. Leave empty to use the default one. This a string prop‐
1481 erty that contains the path to ProGuard config file. This property is
1482 initialized by the value of the CMAKE_ANDROID_PROGUARD_CONFIG_PATH
1483 variable if it is set when a target is created.
1484 ANDROID_SECURE_PROPS_PATH
1486 New in version 3.4.
1487 Set the Android property that states the location of the secure proper‐
1490 ties file. This is a string property that contains the file path.
1491 This property is initialized by the value of the
1492 CMAKE_ANDROID_SECURE_PROPS_PATH variable if it is set when a target is
1493 created.
1494 ANDROID_SKIP_ANT_STEP
1496 New in version 3.4.
1497 Set the Android property that defines whether or not to skip the Ant
1500 build step. This is a boolean property initialized by the value of the
1501 CMAKE_ANDROID_SKIP_ANT_STEP variable if it is set when a target is cre‐
1502 ated.
1503 ANDROID_STL_TYPE
1505 New in version 3.4.
1506 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1509 Edition, this property specifies the type of STL support for the
1510 project. This is a string property that could set to the one of the
1511 following values:
1512 none No C++ Support
1514 system Minimal C++ without STL
1516 gabi++_static
1518 GAbi++ Static
1519 gabi++_shared
1521 GAbi++ Shared
1522 gnustl_static
1524 GNU libstdc++ Static
1525 gnustl_shared
1527 GNU libstdc++ Shared
1528 stlport_static
1530 STLport Static
1531 stlport_shared
1533 STLport Shared
1534 This property is initialized by the value of the CMAKE_ANDROID_STL_TYPE
1536 variable if it is set when a target is created.
1537 ARCHIVE_OUTPUT_DIRECTORY
1539 Output directory in which to build ARCHIVE target files.
1540 This property specifies the directory into which archive target files
1542 should be built. The property value may use generator expressions.
1543 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
1544 fig) append a per-configuration subdirectory to the specified directory
1545 unless a generator expression is used.
1546 This property is initialized by the value of the
1548 CMAKE_ARCHIVE_OUTPUT_DIRECTORY variable if it is set when a target is
1549 created.
1550 NOTE:
1552 On macOS, this property will be ignored for the linker import files
1553 (e.g. .tbd files, see ENABLE_EXPORTS property for details) when:
1554 • The FRAMEWORK is set, because the framework layout cannot be
1556 changed.
1557 • The Xcode generator is used, due to the limitations and con‐
1559 straints of the Xcode tool.
1560 In both cases, the linker import files will be generated in the same
1562 directory as the shared library.
1563 See also the ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> target property.
1565 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
1567 Per-configuration output directory for ARCHIVE target files.
1568 This is a per-configuration version of the ARCHIVE_OUTPUT_DIRECTORY
1570 target property, but multi-configuration generators (VS, Xcode) do NOT
1571 append a per-configuration subdirectory to the specified directory.
1572 This property is initialized by the value of the
1573 CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
1574 target is created.
1575 Contents of ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
1577 sions.
1578 ARCHIVE_OUTPUT_NAME
1580 Output name for ARCHIVE target files.
1581 This property specifies the base name for archive target files. It
1583 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
1584 NOTE:
1586 On macOS, this property will be ignored for the linker import files
1587 (e.g. .tbd files, see ENABLE_EXPORTS property for details) when:
1588 • The FRAMEWORK is set, because the framework layout cannot be
1590 changed.
1591 • The Xcode generator is used, due to the limitations and con‐
1593 straints of the Xcode tool.
1594 In both cases, the linker import files will be generated with the
1596 same name as the shared library.
1597 See also the ARCHIVE_OUTPUT_NAME_<CONFIG> target property.
1599 ARCHIVE_OUTPUT_NAME_<CONFIG>
1601 Per-configuration output name for ARCHIVE target files.
1602 This is the configuration-specific version of the ARCHIVE_OUTPUT_NAME
1604 target property.
1605 AUTOGEN_BUILD_DIR
1607 New in version 3.9.
1608 Directory where AUTOMOC, AUTOUIC and AUTORCC generate files for the
1611 target.
1612 The directory is created on demand and automatically added to the
1614 ADDITIONAL_CLEAN_FILES target property.
1615 When unset or empty the directory <dir>/<target-name>_autogen is used
1617 where <dir> is CMAKE_CURRENT_BINARY_DIR and <target-name> is NAME.
1618 By default AUTOGEN_BUILD_DIR is unset.
1620 See the cmake-qt(7) manual for more information on using CMake with Qt.
1622 AUTOGEN_ORIGIN_DEPENDS
1624 New in version 3.14.
1625 Switch for forwarding origin target dependencies to the corresponding
1628 _autogen target.
1629 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1631 sponding _autogen target which generates moc and uic files. As this
1632 _autogen target is created at generate-time, it is not possible to de‐
1633 fine dependencies of it using e.g. add_dependencies(). Instead the
1634 AUTOGEN_ORIGIN_DEPENDS target property decides whether the origin tar‐
1635 get dependencies should be forwarded to the _autogen target or not.
1636 By default AUTOGEN_ORIGIN_DEPENDS is initialized from
1638 CMAKE_AUTOGEN_ORIGIN_DEPENDS which is ON by default.
1639 In total the dependencies of the _autogen target are composed from
1641 • forwarded origin target dependencies (enabled by default via AUTO‐
1643 GEN_ORIGIN_DEPENDS)
1644 • additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1646 See the cmake-qt(7) manual for more information on using CMake with Qt.
1648 Note
1650 Disabling AUTOGEN_ORIGIN_DEPENDS is useful to avoid building of origin
1651 target dependencies when building the _autogen target only. This is
1652 especially interesting when a global autogen target is enabled.
1653 When the _autogen target doesn't require all the origin target's depen‐
1655 dencies, and AUTOGEN_ORIGIN_DEPENDS is disabled, it might be necessary
1656 to extend AUTOGEN_TARGET_DEPENDS to add missing dependencies.
1657 AUTOGEN_PARALLEL
1659 New in version 3.11.
1660 Number of parallel moc or uic processes to start when using AUTOMOC and
1663 AUTOUIC.
1664 The custom <origin>_autogen target starts a number of threads of which
1666 each one parses a source file and on demand starts a moc or uic
1667 process. AUTOGEN_PARALLEL controls how many parallel threads (and
1668 therefore moc or uic processes) are started.
1669 • An empty (or unset) value or the string AUTO sets the number of
1671 threads/processes to the number of physical CPUs on the host system.
1672 • A positive non zero integer value sets the exact thread/process
1674 count.
1675 • Otherwise a single thread/process is started.
1677 By default AUTOGEN_PARALLEL is initialized from CMAKE_AUTOGEN_PARALLEL.
1679 See the cmake-qt(7) manual for more information on using CMake with Qt.
1681 AUTOGEN_TARGET_DEPENDS
1683 Additional target dependencies of the corresponding _autogen target.
1684 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1686 sponding _autogen target which generates moc and uic files. As this
1687 _autogen target is created at generate-time, it is not possible to de‐
1688 fine dependencies of it using e.g. add_dependencies(). Instead the
1689 AUTOGEN_TARGET_DEPENDS target property can be set to a ;-list of addi‐
1690 tional dependencies for the _autogen target. Dependencies can be tar‐
1691 get names or file names.
1692 In total the dependencies of the _autogen target are composed from
1694 • forwarded origin target dependencies (enabled by default via
1696 AUTOGEN_ORIGIN_DEPENDS)
1697 • additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1699 See the cmake-qt(7) manual for more information on using CMake with Qt.
1701 Use cases
1703 If AUTOMOC or AUTOUIC depends on a file that is either
1704 • a GENERATED non C++ file (e.g. a GENERATED .json or .ui file) or
1706 • a GENERATED C++ file that isn't recognized by AUTOMOC and AUTOUIC be‐
1708 cause it's skipped by SKIP_AUTOMOC, SKIP_AUTOUIC, SKIP_AUTOGEN or
1709 CMP0071 or
1710 • a file that isn't in the origin target's sources
1712 it must be added to AUTOGEN_TARGET_DEPENDS.
1714 AUTOGEN_USE_SYSTEM_INCLUDE
1716 New in version 3.27.
1717 AUTOGEN_USE_SYSTEM_INCLUDE is a boolean property that can be set on a
1720 target to indicate that the autogen target include directory should be
1721 added as a system include directory or normal include directory to the
1722 target.
1723 If this property is not set, the autogen target include directory is
1725 added as a system include directory by default. See policy CMP0151.
1726 See the cmake-qt(7) manual for more information on using CMake with Qt.
1728 This property is initialized by the CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
1730 variable if it is set when a target is created.
1731 AUTOMOC
1733 Should the target be processed with auto-moc (for Qt projects).
1734 AUTOMOC is a boolean specifying whether CMake will handle the Qt moc
1736 preprocessor automatically, i.e. without having to use commands like
1737 QT4_WRAP_CPP(), QT5_WRAP_CPP(), etc. Currently, Qt versions 4 to 6 are
1738 supported.
1739 This property is initialized by the value of the CMAKE_AUTOMOC variable
1741 if it is set when a target is created.
1742 When this property is set ON, CMake will scan the header and source
1744 files at build time and invoke moc accordingly.
1745 Header file processing
1747 At configuration time, a list of header files that should be scanned by
1748 AUTOMOC is computed from the target's sources.
1749 • All header files in the target's sources are added to the scan list.
1751 • For all C++ source files <source_base>.<source_extension> in the tar‐
1753 get's sources, CMake searches for
1754 • a regular header with the same base name (<source_base>.<header_ex‐
1756 tention>) and
1757 • a private header with the same base name and a _p suffix
1759 (<source_base>_p.<header_extention>)
1760 and adds these to the scan list.
1762 At build time, CMake scans each unknown or modified header file from
1764 the list and searches for
1765 • a Qt macro from AUTOMOC_MACRO_NAMES,
1767 • additional file dependencies from the FILE argument of a
1769 Q_PLUGIN_METADATA macro and
1770 • additional file dependencies detected by filters defined in
1772 AUTOMOC_DEPEND_FILTERS.
1773 If a Qt macro is found, then the header will be compiled by the moc to
1775 the output file moc_<base_name>.cpp. The complete output file path is
1776 described in the section Output file location.
1777 The header will be moc compiled again if a file from the additional
1779 file dependencies changes.
1780 Header moc output files moc_<base_name>.cpp can be included in source
1782 files. In the section Including header moc files in sources there is
1783 more information on that topic.
1784 Source file processing
1786 At build time, CMake scans each unknown or modified C++ source file
1787 from the target's sources for
1788 • a Qt macro from AUTOMOC_MACRO_NAMES,
1790 • includes of header moc files (see Including header moc files in
1792 sources),
1793 • additional file dependencies from the FILE argument of a
1795 Q_PLUGIN_METADATA macro and
1796 • additional file dependencies detected by filters defined in
1798 AUTOMOC_DEPEND_FILTERS.
1799 If a Qt macro is found, then the C++ source file <base>.<source_exten‐
1801 sion> is expected to as well contain an include statement
1802 #include <<base>.moc> // or
1804 #include "<base>.moc"
1805 The source file then will be compiled by the moc to the output file
1807 <base>.moc. A description of the complete output file path is in sec‐
1808 tion Output file location.
1809 The source will be moc compiled again if a file from the additional
1811 file dependencies changes.
1812 Including header moc files in sources
1814 A source file can include the moc output file of a header
1815 <header_base>.<header_extension> by using an include statement of the
1816 form
1817 #include <moc_<header_base>.cpp> // or
1819 #include "moc_<header_base>.cpp"
1820 If the moc output file of a header is included by a source, it will be
1822 generated in a different location than if it was not included. This is
1823 described in the section Output file location.
1824 Output file location
1826 Included moc output files
1827 moc output files that are included by a source file will be generated
1828 in
1829 • <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
1831 • <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
1833 tors.
1834 Where <AUTOGEN_BUILD_DIR> is the value of the target property
1836 AUTOGEN_BUILD_DIR.
1837 The include directory is automatically added to the target's
1839 INCLUDE_DIRECTORIES.
1840 Not included moc output files
1842 moc output files that are not included in a source file will be gener‐
1843 ated in
1844 • <AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM> for single configuration
1846 generators or in,
1847 • <AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM> for multi
1849 configuration generators.
1850 Where <SOURCE_DIR_CHECKSUM> is a checksum computed from the relative
1852 parent directory path of the moc input file. This scheme allows to
1853 have moc input files with the same name in different directories.
1854 All not included moc output files will be included automatically by the
1856 CMake generated file
1857 • <AUTOGEN_BUILD_DIR>/mocs_compilation.cpp, or
1859 • <AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp,
1861 which is added to the target's sources.
1863 Qt version detection
1865 AUTOMOC enabled targets need to know the Qt major and minor version
1866 they're working with. The major version usually is provided by the IN‐
1867 TERFACE_QT_MAJOR_VERSION property of the Qt[456]Core library, that the
1868 target links to. To find the minor version, CMake builds a list of
1869 available Qt versions from
1870 • Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR variables (usually
1872 set by find_package(Qt6...))
1873 • Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR directory properties
1875 • Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR variables (usually
1877 set by find_package(Qt5...))
1878 • Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR directory properties
1880 • QT_VERSION_MAJOR and QT_VERSION_MINOR variables (usually set by
1882 find_package(Qt4...))
1883 • QT_VERSION_MAJOR and QT_VERSION_MINOR directory properties
1885 in the context of the add_executable() or add_library() call.
1887 Assumed INTERFACE_QT_MAJOR_VERSION is a valid number, the first entry
1889 in the list with a matching major version is taken. If no matching ma‐
1890 jor version was found, an error is generated. If INTERFACE_QT_MA‐
1891 JOR_VERSION is not a valid number, the first entry in the list is
1892 taken.
1893 A find_package(Qt[456]...) call sets the QT/Qt[56]Core_VERSION_MA‐
1895 JOR/MINOR variables. If the call is in a different context than the
1896 add_executable() or add_library() call, e.g. in a function, then the
1897 version variables might not be available to the AUTOMOC enabled target.
1898 In that case the version variables can be forwarded from the find_pack‐
1899 age(Qt[456]...) calling context to the add_executable() or
1900 add_library() calling context as directory properties. The following
1901 Qt5 example demonstrates the procedure.
1902 function (add_qt5_client)
1904 find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets)
1905 ...
1906 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1907 PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}")
1908 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1909 PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}")
1910 ...
1911 endfunction ()
1912 ...
1913 add_qt5_client()
1914 add_executable(myTarget main.cpp)
1915 target_link_libraries(myTarget Qt5::QtWidgets)
1916 set_property(TARGET myTarget PROPERTY AUTOMOC ON)
1917 Modifiers
1919 AUTOMOC_EXECUTABLE: The moc executable will be detected automatically,
1920 but can be forced to a certain binary using this target property.
1921 AUTOMOC_MOC_OPTIONS: Additional command line options for moc can be set
1923 in this target property.
1924 AUTOMOC_MACRO_NAMES: This list of Qt macro names can be extended to
1926 search for additional macros in headers and sources.
1927 AUTOMOC_DEPEND_FILTERS: moc dependency file names can be extracted from
1929 headers or sources by defining file name filters in this target prop‐
1930 erty.
1931 AUTOMOC_COMPILER_PREDEFINES: Compiler pre definitions for moc are writ‐
1933 ten to the moc_predefs.h file. The generation of this file can be en‐
1934 abled or disabled in this target property.
1935 SKIP_AUTOMOC: Sources and headers can be excluded from AUTOMOC process‐
1937 ing by setting this source file property.
1938 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
1940 AUTORCC processing by setting this source file property.
1941 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
1943 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
1944 AUTOGEN_TARGETS_FOLDER: This global property can be used to group AUTO‐
1946 MOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
1947 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
1949 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
1950 project, will be generated when this variable is ON.
1951 AUTOGEN_PARALLEL: This target property controls the number of moc or
1953 uic processes to start in parallel during builds.
1954 See the cmake-qt(7) manual for more information on using CMake with Qt.
1956 AUTOMOC_COMPILER_PREDEFINES
1958 New in version 3.10.
1959 Boolean value used by AUTOMOC to determine if the compiler pre defini‐
1962 tions file moc_predefs.h should be generated.
1963 CMake generates a moc_predefs.h file with compiler pre definitions from
1965 the output of the command defined in
1966 CMAKE_CXX_COMPILER_PREDEFINES_COMMAND when
1967 • AUTOMOC is enabled,
1969 • AUTOMOC_COMPILER_PREDEFINES is enabled,
1971 • CMAKE_CXX_COMPILER_PREDEFINES_COMMAND isn't empty and
1973 • the Qt version is greater or equal 5.8.
1975 The moc_predefs.h file, which is generated in AUTOGEN_BUILD_DIR, is
1977 passed to moc as the argument to the --include option.
1978 By default AUTOMOC_COMPILER_PREDEFINES is initialized from
1980 CMAKE_AUTOMOC_COMPILER_PREDEFINES, which is ON by default.
1981 See the cmake-qt(7) manual for more information on using CMake with Qt.
1983 AUTOMOC_DEPEND_FILTERS
1985 New in version 3.9.
1986 Filter definitions used by AUTOMOC to extract file names from a source
1989 file that are registered as additional dependencies for the moc file of
1990 the source file.
1991 Filters are defined as KEYWORD;REGULAR_EXPRESSION pairs. First the file
1993 content is searched for KEYWORD. If it is found at least once, then
1994 file names are extracted by successively searching for REGULAR_EXPRES‐
1995 SION and taking the first match group.
1996 The file name found in the first match group is searched for
1998 • first in the vicinity of the source file
2000 • and afterwards in the target's INCLUDE_DIRECTORIES.
2002 If any of the extracted files changes, then the moc file for the source
2004 file gets rebuilt even when the source file itself doesn't change.
2005 If any of the extracted files is GENERATED or if it is not in the tar‐
2007 get's sources, then it might be necessary to add it to the _autogen
2008 target dependencies. See AUTOGEN_TARGET_DEPENDS for reference.
2009 By default AUTOMOC_DEPEND_FILTERS is initialized from
2011 CMAKE_AUTOMOC_DEPEND_FILTERS, which is empty by default.
2012 From Qt 5.15.0 on this variable is ignored as moc is able to output the
2014 correct dependencies.
2015 See the cmake-qt(7) manual for more information on using CMake with Qt.
2017 Example 1
2019 A header file my_class.hpp uses a custom macro JSON_FILE_MACRO which is
2020 defined in an other header macros.hpp. We want the moc file of
2021 my_class.hpp to depend on the file name argument of JSON_FILE_MACRO:
2022 // my_class.hpp
2024 class My_Class : public QObject
2025 {
2026 Q_OBJECT
2027 JSON_FILE_MACRO ( "info.json" )
2028 ...
2029 };
2030 In CMakeLists.txt we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS like
2032 this:
2033 list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
2035 "JSON_FILE_MACRO"
2036 "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
2037 )
2038 We assume info.json is a plain (not GENERATED) file that is listed in
2040 the target's source. Therefore we do not need to add it to
2041 AUTOGEN_TARGET_DEPENDS.
2042 Example 2
2044 In the target my_target a header file complex_class.hpp uses a custom
2045 macro JSON_BASED_CLASS which is defined in an other header macros.hpp:
2046 // macros.hpp
2048 ...
2049 #define JSON_BASED_CLASS(name, json) \
2050 class name : public QObject \
2051 { \
2052 Q_OBJECT \
2053 Q_PLUGIN_METADATA(IID "demo" FILE json) \
2054 name() {} \
2055 };
2056 ...
2057 // complex_class.hpp
2059 #pragma once
2060 JSON_BASED_CLASS(Complex_Class, "meta.json")
2061 // end of file
2062 Since complex_class.hpp doesn't contain a Q_OBJECT macro it would be
2064 ignored by AUTOMOC. We change this by adding JSON_BASED_CLASS to
2065 CMAKE_AUTOMOC_MACRO_NAMES:
2066 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")
2068 We want the moc file of complex_class.hpp to depend on meta.json. So
2070 we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS:
2071 list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
2073 "JSON_BASED_CLASS"
2074 "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
2075 )
2076 Additionally we assume meta.json is GENERATED which is why we have to
2078 add it to AUTOGEN_TARGET_DEPENDS:
2079 set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")
2081 AUTOMOC_EXECUTABLE
2083 New in version 3.14.
2084 AUTOMOC_EXECUTABLE is file path pointing to the moc executable to use
2087 for AUTOMOC enabled files. Setting this property will make CMake skip
2088 the automatic detection of the moc binary as well as the sanity-tests
2089 normally run to ensure that the binary is available and working as ex‐
2090 pected.
2091 Usually this property does not need to be set. Only consider this prop‐
2093 erty if auto-detection of moc can not work -- e.g. because you are
2094 building the moc binary as part of your project.
2095 See the cmake-qt(7) manual for more information on using CMake with Qt.
2097 AUTOMOC_MACRO_NAMES
2099 New in version 3.10.
2100 A semicolon-separated list of macro names used by AUTOMOC to determine
2103 if a C++ file needs to be processed by moc.
2104 This property is only used if the AUTOMOC property is ON for this tar‐
2106 get.
2107 When running AUTOMOC, CMake searches for the strings listed in AUTO‐
2109 MOC_MACRO_NAMES in C++ source and header files. If any of the strings
2110 is found
2111 • as the first non space string on a new line or
2113 • as the first non space string after a { on a new line,
2115 then the file will be processed by moc.
2117 By default AUTOMOC_MACRO_NAMES is initialized from
2119 CMAKE_AUTOMOC_MACRO_NAMES.
2120 See also the INTERFACE_AUTOMOC_MACRO_NAMES target property.
2122 See the cmake-qt(7) manual for more information on using CMake with Qt.
2124 Example
2126 In this case the Q_OBJECT macro is hidden inside another macro called
2127 CUSTOM_MACRO. To let CMake know that source files that contain CUS‐
2128 TOM_MACRO need to be moc processed, we call:
2129 set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
2131 AUTOMOC_MOC_OPTIONS
2133 Additional options for moc when using AUTOMOC
2134 This property is only used if the AUTOMOC property is ON for this tar‐
2136 get. In this case, it holds additional command line options which will
2137 be used when moc is executed during the build, i.e. it is equivalent
2138 to the optional OPTIONS argument of the qt4_wrap_cpp() macro.
2139 This property is initialized by the value of the
2141 CMAKE_AUTOMOC_MOC_OPTIONS variable if it is set when a target is cre‐
2142 ated, or an empty string otherwise.
2143 See the cmake-qt(7) manual for more information on using CMake with Qt.
2145 EXAMPLE
2147 In this example, the moc tool is invoked with the -D_EXTRA_DEFINE op‐
2148 tion when generating the moc file for object.cpp.
2149 CMakeLists.txt
2151 add_executable(mocOptions object.cpp main.cpp)
2153 set_property(TARGET mocOptions PROPERTY AUTOMOC ON)
2154 target_compile_options(mocOptions PRIVATE "-D_EXTRA_DEFINE")
2155 set_property(TARGET mocOptions PROPERTY AUTOMOC_MOC_OPTIONS "-D_EXTRA_DEFINE")
2156 target_link_libraries(mocOptions Qt6::Core)
2157 object.hpp
2159 #ifndef Object_HPP
2161 #define Object_HPP
2162 #include <QObject>
2164 #ifdef _EXTRA_DEFINE
2166 class Object : public QObject
2167 {
2168 Q_OBJECT
2169 public:
2170 Object();
2172 };
2174 #endif
2175 #endif
2177 AUTOMOC_PATH_PREFIX
2179 New in version 3.16.
2180 When this property is ON, CMake will generate the -p path prefix option
2183 for moc on AUTOMOC enabled Qt targets.
2184 To generate the path prefix, CMake tests if the header compiled by moc
2186 is in any of the target include directories. If so, CMake will compute
2187 the relative path accordingly. If the header is not in the include di‐
2188 rectories, CMake will omit the -p path prefix option. moc usually gen‐
2189 erates a relative include path in that case.
2190 AUTOMOC_PATH_PREFIX is initialized from the variable
2192 CMAKE_AUTOMOC_PATH_PREFIX, which is OFF by default.
2193 See the cmake-qt(7) manual for more information on using CMake with Qt.
2195 Reproducible builds
2197 For reproducible builds it is recommended to keep headers that are moc
2198 compiled in one of the target include directories and set AUTO‐
2199 MOC_PATH_PREFIX to ON. This ensures that:
2200 • moc output files are identical on different build setups,
2202 • moc output files will compile correctly when the source and/or build
2204 directory is a symbolic link.
2205 AUTORCC
2207 Should the target be processed with auto-rcc (for Qt projects).
2208 AUTORCC is a boolean specifying whether CMake will handle the Qt rcc
2210 code generator automatically, i.e. without having to use commands like
2211 QT4_ADD_RESOURCES(), QT5_ADD_RESOURCES(), etc. Currently, Qt versions
2212 4 to 6 are supported.
2213 When this property is ON, CMake will handle .qrc files added as target
2215 sources at build time and invoke rcc accordingly. This property is
2216 initialized by the value of the CMAKE_AUTORCC variable if it is set
2217 when a target is created.
2218 By default AUTORCC is processed by a custom command. If the .qrc file
2220 is GENERATED, a custom target is used instead.
2221 When there are multiple .qrc files with the same name, CMake will gen‐
2223 erate unspecified unique output file names for rcc. Therefore, if
2224 Q_INIT_RESOURCE() or Q_CLEANUP_RESOURCE() need to be used, the .qrc
2225 file name must be unique.
2226 Modifiers
2228 AUTORCC_EXECUTABLE: The rcc executable will be detected automatically,
2229 but can be forced to a certain binary by setting this target property.
2230 AUTORCC_OPTIONS: Additional command line options for rcc can be set via
2232 this target property. The corresponding AUTORCC_OPTIONS source file
2233 property can be used to specify options to be applied only to a spe‐
2234 cific .qrc file.
2235 SKIP_AUTORCC: .qrc files can be excluded from AUTORCC processing by
2237 setting this source file property.
2238 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
2240 AUTORCC processing by setting this source file property.
2241 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
2243 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
2244 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
2246 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
2247 CMAKE_GLOBAL_AUTORCC_TARGET: A global autorcc target that depends on
2249 all AUTORCC targets in the project will be generated when this variable
2250 is ON.
2251 See the cmake-qt(7) manual for more information on using CMake with Qt.
2253 AUTORCC_EXECUTABLE
2255 New in version 3.14.
2256 AUTORCC_EXECUTABLE is file path pointing to the rcc executable to use
2259 for AUTORCC enabled files. Setting this property will make CMake skip
2260 the automatic detection of the rcc binary as well as the sanity-tests
2261 normally run to ensure that the binary is available and working as ex‐
2262 pected.
2263 Usually this property does not need to be set. Only consider this prop‐
2265 erty if auto-detection of rcc can not work -- e.g. because you are
2266 building the rcc binary as part of your project.
2267 See the cmake-qt(7) manual for more information on using CMake with Qt.
2269 AUTORCC_OPTIONS
2271 Additional options for rcc when using AUTORCC
2272 This property holds additional command line options which will be used
2274 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
2275 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
2276 This property is initialized by the value of the CMAKE_AUTORCC_OPTIONS
2278 variable if it is set when a target is created, or an empty string oth‐
2279 erwise.
2280 The options set on the target may be overridden by AUTORCC_OPTIONS set
2282 on the .qrc source file.
2283 See the cmake-qt(7) manual for more information on using CMake with Qt.
2285 EXAMPLE
2287 # ...
2288 set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9")
2289 # ...
2290 AUTOUIC
2292 Should the target be processed with auto-uic (for Qt projects).
2293 AUTOUIC is a boolean specifying whether CMake will handle the Qt uic
2295 code generator automatically, i.e. without having to use commands like
2296 QT4_WRAP_UI(), QT5_WRAP_UI(), etc. Currently, Qt versions 4 to 6 are
2297 supported.
2298 This property is initialized by the value of the CMAKE_AUTOUIC variable
2300 if it is set when a target is created.
2301 When this property is ON, CMake will scan the header and source files
2303 at build time and invoke uic accordingly.
2304 Header and source file processing
2306 At build time, CMake scans each header and source file from the tar‐
2307 get's sources for include statements of the form
2308 #include "ui_<ui_base>.h"
2310 Once such an include statement is found in a file, CMake searches for
2312 the uic input file <ui_base>.ui
2313 • in the vicinity of the file and
2315 • in the AUTOUIC_SEARCH_PATHS of the target.
2317 If the <ui_base>.ui file was found, uic is called on it to generate
2319 ui_<ui_base>.h in the directory
2320 • <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
2322 • <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
2324 tors.
2325 Where <AUTOGEN_BUILD_DIR> is the value of the target property
2327 AUTOGEN_BUILD_DIR.
2328 The include directory is automatically added to the target's
2330 INCLUDE_DIRECTORIES.
2331 Modifiers
2333 AUTOUIC_EXECUTABLE: The uic executable will be detected automatically,
2334 but can be forced to a certain binary using this target property.
2335 AUTOUIC_OPTIONS: Additional command line options for uic can be set via
2337 this target property. The corresponding AUTOUIC_OPTIONS source file
2338 property can be used to specify options to be applied only to a spe‐
2339 cific <base_name>.ui file.
2340 SKIP_AUTOUIC: Source files can be excluded from AUTOUIC processing by
2342 setting this source file property.
2343 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
2345 AUTORCC processing by setting this source file property.
2346 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
2348 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
2349 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
2351 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
2352 project, will be generated when this variable is ON.
2353 AUTOGEN_PARALLEL: This target property controls the number of moc or
2355 uic processes to start in parallel during builds.
2356 See the cmake-qt(7) manual for more information on using CMake with Qt.
2358 AUTOUIC_EXECUTABLE
2360 New in version 3.14.
2361 AUTOUIC_EXECUTABLE is file path pointing to the uic executable to use
2364 for AUTOUIC enabled files. Setting this property will make CMake skip
2365 the automatic detection of the uic binary as well as the sanity-tests
2366 normally run to ensure that the binary is available and working as ex‐
2367 pected.
2368 Usually this property does not need to be set. Only consider this prop‐
2370 erty if auto-detection of uic can not work -- e.g. because you are
2371 building the uic binary as part of your project.
2372 See the cmake-qt(7) manual for more information on using CMake with Qt.
2374 AUTOUIC_OPTIONS
2376 Additional options for uic when using AUTOUIC
2377 This property holds additional command line options which will be used
2379 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
2380 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
2381 This property is initialized by the value of the CMAKE_AUTOUIC_OPTIONS
2383 variable if it is set when a target is created, or an empty string oth‐
2384 erwise.
2385 The options set on the target may be overridden by AUTOUIC_OPTIONS set
2387 on the .ui source file.
2388 This property may use "generator expressions" with the syntax $<...>.
2390 See the cmake-generator-expressions(7) manual for available expres‐
2391 sions.
2392 See the cmake-qt(7) manual for more information on using CMake with Qt.
2394 EXAMPLE
2396 # ...
2397 set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection")
2398 # ...
2399 AUTOUIC_SEARCH_PATHS
2401 New in version 3.9.
2402 Search path list used by AUTOUIC to find included .ui files.
2405 This property is initialized by the value of the
2407 CMAKE_AUTOUIC_SEARCH_PATHS variable if it is set when a target is cre‐
2408 ated. Otherwise it is empty.
2409 See the cmake-qt(7) manual for more information on using CMake with Qt.
2411 BINARY_DIR
2413 New in version 3.4.
2414 This read-only property reports the value of the
2417 CMAKE_CURRENT_BINARY_DIR variable in the directory in which the target
2418 was defined.
2419 BUILD_RPATH
2421 New in version 3.8.
2422 A semicolon-separated list specifying runtime path (RPATH) entries to
2425 add to binaries linked in the build tree (for platforms that support
2426 it). By default, CMake sets the runtime path of binaries in the build
2427 tree to contain search paths it knows are needed to find the shared li‐
2428 braries they link. Projects may set BUILD_RPATH to specify additional
2429 search paths.
2430 The build-tree runtime path will not be used for binaries in the in‐
2432 stall tree. It will be replaced with the install-tree runtime path
2433 during the installation step. See also the INSTALL_RPATH target prop‐
2434 erty.
2435 This property is initialized by the value of the variable
2437 CMAKE_BUILD_RPATH if it is set when a target is created.
2438 This property supports generator expressions.
2440 Other settings that affect the build-tree runtime path include:
2442 • The CMAKE_SKIP_RPATH variable completely disables runtime paths in
2444 both the build tree and install tree.
2445 • The SKIP_BUILD_RPATH target property disables setting any runtime
2447 path in the build tree.
2448 • The BUILD_RPATH_USE_ORIGIN target property causes the automati‐
2450 cally-generated runtime path to use entries relative to $ORIGIN.
2451 • The BUILD_WITH_INSTALL_RPATH target property causes binaries in the
2453 build tree to be built with the install-tree runtime path.
2454 BUILD_RPATH_USE_ORIGIN
2456 New in version 3.14.
2457 Whether to use relative paths for the build RPATH.
2460 This property is initialized by the value of the variable
2462 CMAKE_BUILD_RPATH_USE_ORIGIN.
2463 On platforms that support runtime paths (RPATH) with the $ORIGIN token,
2465 setting this property to TRUE enables relative paths in the build RPATH
2466 for executables and shared libraries that point to shared libraries in
2467 the same build tree.
2468 Normally the build RPATH of a binary contains absolute paths to the di‐
2470 rectory of each shared library it links to. The RPATH entries for di‐
2471 rectories contained within the build tree can be made relative to en‐
2472 able relocatable builds and to help achieve reproducible builds by
2473 omitting the build directory from the build environment.
2474 This property has no effect on platforms that do not support the $ORI‐
2476 GIN token in RPATH, or when the CMAKE_SKIP_RPATH variable is set. The
2477 runtime path set through the BUILD_RPATH target property is also unaf‐
2478 fected by this property.
2479 BUILD_WITH_INSTALL_NAME_DIR
2481 New in version 3.9.
2482 BUILD_WITH_INSTALL_NAME_DIR is a boolean specifying whether the macOS
2485 install_name of a target in the build tree uses the directory given by
2486 INSTALL_NAME_DIR. This setting only applies to targets on macOS.
2487 This property is initialized by the value of the variable
2489 CMAKE_BUILD_WITH_INSTALL_NAME_DIR if it is set when a target is cre‐
2490 ated.
2491 If this property is not set and policy CMP0068 is not NEW, the value of
2493 BUILD_WITH_INSTALL_RPATH is used in its place.
2494 BUILD_WITH_INSTALL_RPATH
2496 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
2497 target in the build tree with the INSTALL_RPATH. This takes precedence
2498 over SKIP_BUILD_RPATH and avoids the need for relinking before instal‐
2499 lation.
2500 This property is initialized by the value of the
2502 CMAKE_BUILD_WITH_INSTALL_RPATH variable if it is set when a target is
2503 created.
2504 If policy CMP0068 is not NEW, this property also controls use of
2506 INSTALL_NAME_DIR in the build tree on macOS. Either way, the
2507 BUILD_WITH_INSTALL_NAME_DIR target property takes precedence.
2508 BUNDLE
2510 This target is a CFBundle on the macOS.
2511 If a module library target has this property set to true it will be
2513 built as a CFBundle when built on the mac. It will have the directory
2514 structure required for a CFBundle and will be suitable to be used for
2515 creating Browser Plugins or other application resources.
2516 BUNDLE_EXTENSION
2518 The file extension used to name a BUNDLE, a FRAMEWORK, or a
2519 MACOSX_BUNDLE target on the macOS and iOS.
2520 The default value is bundle, framework, or app for the respective tar‐
2522 get types.
2523 C_EXTENSIONS
2525 New in version 3.1.
2526 Boolean specifying whether compiler specific extensions are requested.
2529 This property specifies whether compiler specific extensions should be
2531 used. For some compilers, this results in adding a flag such as
2532 -std=gnu11 instead of -std=c11 to the compile line. This property is
2533 ON by default. The basic C standard level is controlled by the
2534 C_STANDARD target property.
2535 See the cmake-compile-features(7) manual for information on compile
2537 features and a list of supported compilers.
2538 This property is initialized by the value of the CMAKE_C_EXTENSIONS
2540 variable if set when a target is created and otherwise by the value of
2541 CMAKE_C_EXTENSIONS_DEFAULT (see CMP0128).
2542 C_STANDARD
2544 New in version 3.1.
2545 The C standard whose features are requested to build this target.
2548 This property specifies the C standard whose features are requested to
2550 build this target. For some compilers, this results in adding a flag
2551 such as -std=gnu11 to the compile line. For compilers that have no no‐
2552 tion of a C standard level, such as Microsoft Visual C++ before VS
2553 16.7, this property has no effect.
2554 Supported values are:
2556 90 C89/C90
2558 99 C99
2560 11 C11
2562 17 New in version 3.21.
2564 C17
2567 23 New in version 3.21.
2569 C23
2572 If the value requested does not result in a compile flag being added
2574 for the compiler in use, a previous standard flag will be added in‐
2575 stead. This means that using:
2576 set_property(TARGET tgt PROPERTY C_STANDARD 11)
2578 with a compiler which does not support -std=gnu11 or an equivalent flag
2580 will not result in an error or warning, but will instead add the
2581 -std=gnu99 or -std=gnu90 flag if supported. This "decay" behavior may
2582 be controlled with the C_STANDARD_REQUIRED target property. Addition‐
2583 ally, the C_EXTENSIONS target property may be used to control whether
2584 compiler-specific extensions are enabled on a per-target basis.
2585 See the cmake-compile-features(7) manual for information on compile
2587 features and a list of supported compilers.
2588 This property is initialized by the value of the CMAKE_C_STANDARD vari‐
2590 able if it is set when a target is created.
2591 C_STANDARD_REQUIRED
2593 New in version 3.1.
2594 Boolean describing whether the value of C_STANDARD is a requirement.
2597 If this property is set to ON, then the value of the C_STANDARD target
2599 property is treated as a requirement. If this property is OFF or un‐
2600 set, the C_STANDARD target property is treated as optional and may "de‐
2601 cay" to a previous standard if the requested is not available. For
2602 compilers that have no notion of a C standard level, such as Microsoft
2603 Visual C++ before VS 16.7, this property has no effect.
2604 See the cmake-compile-features(7) manual for information on compile
2606 features and a list of supported compilers.
2607 This property is initialized by the value of the
2609 CMAKE_C_STANDARD_REQUIRED variable if it is set when a target is cre‐
2610 ated.
2611 COMMON_LANGUAGE_RUNTIME
2613 New in version 3.12.
2614 By setting this target property, the target is configured to build with
2617 C++/CLI support.
2618 The Visual Studio generator defines the clr parameter depending on the
2620 value of the COMMON_LANGUAGE_RUNTIME target property:
2621 Not Set (default)
2623 Native C++.
2624 "" (set but empty)
2626 Mixed unmanaged/managed C++ using .NET Framework.
2627 netcore
2629 New in version 3.26.
2630 Mixed unmanaged/managed C++ using .NET Core.
2633 This required VS 2019's v142 toolset or higher.
2635 pure
2637 Managed C++.
2638 safe
2640 Managed C++.
2641 This property is only evaluated Visual Studio Generators for VS 2010
2643 and above.
2644 To be able to build managed C++ targets with VS 2017 and above the com‐
2646 ponent C++/CLI support must be installed, which may not be done by de‐
2647 fault.
2648 See also IMPORTED_COMMON_LANGUAGE_RUNTIME
2650 COMPATIBLE_INTERFACE_BOOL
2652 Properties which must be compatible with their link interface
2653 The COMPATIBLE_INTERFACE_BOOL property may contain a list of properties
2655 for this target which must be consistent when evaluated as a boolean
2656 with the INTERFACE variant of the property in all linked dependees.
2657 For example, if a property FOO appears in the list, then for each de‐
2658 pendee, the INTERFACE_FOO property content in all of its dependencies
2659 must be consistent with each other, and with the FOO property in the
2660 depender.
2661 Consistency in this sense has the meaning that if the property is set,
2663 then it must have the same boolean value as all others, and if the
2664 property is not set, then it is ignored.
2665 Note that for each dependee, the set of properties specified in this
2667 property must not intersect with the set specified in any of the other
2668 Compatible Interface Properties.
2669 COMPATIBLE_INTERFACE_NUMBER_MAX
2671 Properties whose maximum value from the link interface will be used.
2672 The COMPATIBLE_INTERFACE_NUMBER_MAX property may contain a list of
2674 properties for this target whose maximum value may be read at generate
2675 time when evaluated in the INTERFACE variant of the property in all
2676 linked dependees. For example, if a property FOO appears in the list,
2677 then for each dependee, the INTERFACE_FOO property content in all of
2678 its dependencies will be compared with each other and with the FOO
2679 property in the depender. When reading the FOO property at generate
2680 time, the maximum value will be returned. If the property is not set,
2681 then it is ignored.
2682 Note that for each dependee, the set of properties specified in this
2684 property must not intersect with the set specified in any of the other
2685 Compatible Interface Properties.
2686 COMPATIBLE_INTERFACE_NUMBER_MIN
2688 Properties whose maximum value from the link interface will be used.
2689 The COMPATIBLE_INTERFACE_NUMBER_MIN property may contain a list of
2691 properties for this target whose minimum value may be read at generate
2692 time when evaluated in the INTERFACE variant of the property of all
2693 linked dependees. For example, if a property FOO appears in the list,
2694 then for each dependee, the INTERFACE_FOO property content in all of
2695 its dependencies will be compared with each other and with the FOO
2696 property in the depender. When reading the FOO property at generate
2697 time, the minimum value will be returned. If the property is not set,
2698 then it is ignored.
2699 Note that for each dependee, the set of properties specified in this
2701 property must not intersect with the set specified in any of the other
2702 Compatible Interface Properties.
2703 COMPATIBLE_INTERFACE_STRING
2705 Properties which must be string-compatible with their link interface
2706 The COMPATIBLE_INTERFACE_STRING property may contain a list of proper‐
2708 ties for this target which must be the same when evaluated as a string
2709 in the INTERFACE variant of the property all linked dependees. For ex‐
2710 ample, if a property FOO appears in the list, then for each dependee,
2711 the INTERFACE_FOO property content in all of its dependencies must be
2712 equal with each other, and with the FOO property in the depender. If
2713 the property is not set, then it is ignored.
2714 Note that for each dependee, the set of properties specified in this
2716 property must not intersect with the set specified in any of the other
2717 Compatible Interface Properties.
2718 COMPILE_DEFINITIONS
2720 Preprocessor definitions for compiling a target's sources.
2721 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
2723 list of preprocessor definitions using the syntax VAR or VAR=value.
2724 Function-style definitions are not supported. CMake will automatically
2725 escape the value correctly for the native build system (note that CMake
2726 language syntax may require escapes to specify some values).
2727 CMake will automatically drop some definitions that are not supported
2729 by the native build tool.
2730 New in version 3.26: Any leading -D on an item will be removed.
2732 Disclaimer: Most native build tools have poor support for escaping cer‐
2735 tain values. CMake has work-arounds for many cases but some values may
2736 just not be possible to pass correctly. If a value does not seem to be
2737 escaped correctly, do not attempt to work-around the problem by adding
2738 escape sequences to the value. Your work-around may break in a future
2739 version of CMake that has improved escape support. Instead consider
2740 defining the macro in a (configured) header file. Then report the lim‐
2741 itation. Known limitations include:
2742 # - broken almost everywhere
2744 ; - broken in VS IDE 7.0 and Borland Makefiles
2745 , - broken in VS IDE
2746 % - broken in some cases in NMake
2747 & | - broken in some cases on MinGW
2748 ^ < > \" - broken in most Make tools on Windows
2749 CMake does not reject these values outright because they do work in
2751 some cases. Use with caution.
2752 Contents of COMPILE_DEFINITIONS may use "generator expressions" with
2754 the syntax $<...>. See the cmake-generator-expressions(7) manual for
2755 available expressions. See the cmake-buildsystem(7) manual for more on
2756 defining buildsystem properties.
2757 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
2759 specify per-configuration definitions. Generator expressions should be
2760 preferred instead of setting the alternative property.
2761 COMPILE_FEATURES
2763 New in version 3.1.
2764 Compiler features enabled for this target.
2767 The list of features in this property are a subset of the features
2769 listed in the CMAKE_C_COMPILE_FEATURES, CMAKE_CUDA_COMPILE_FEATURES,
2770 and CMAKE_CXX_COMPILE_FEATURES variables.
2771 Contents of COMPILE_FEATURES may use "generator expressions" with the
2773 syntax $<...>. See the cmake-generator-expressions(7) manual for
2774 available expressions. See the cmake-compile-features(7) manual for
2775 information on compile features and a list of supported compilers.
2776 COMPILE_FLAGS
2778 Additional flags to use when compiling this target's sources.
2779 The COMPILE_FLAGS property sets additional compiler flags used to build
2781 sources within the target. Use COMPILE_DEFINITIONS to pass additional
2782 preprocessor definitions.
2783 This property is deprecated. Use the COMPILE_OPTIONS property or the
2785 target_compile_options() command instead.
2786 COMPILE_OPTIONS
2788 List of options to pass to the compiler.
2789 This property holds a semicolon-separated list of options specified so
2791 far for its target. Use the target_compile_options() command to append
2792 more options. The options will be added after flags in the
2793 CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> variables, but be‐
2794 fore those propagated from dependencies by the
2795 INTERFACE_COMPILE_OPTIONS property.
2796 This property adds compile options for all languages in a target. Use
2798 the COMPILE_LANGUAGE generator expression to specify per-language com‐
2799 pile options.
2800 This property is initialized by the COMPILE_OPTIONS directory property
2802 when a target is created, and is used by the generators to set the op‐
2803 tions for the compiler.
2804 Contents of COMPILE_OPTIONS may use "generator expressions" with the
2806 syntax $<...>. See the cmake-generator-expressions(7) manual for
2807 available expressions. See the cmake-buildsystem(7) manual for more on
2808 defining buildsystem properties.
2809 Option De-duplication
2811 The final set of options used for a target is constructed by accumulat‐
2812 ing options from the current target and the usage requirements of its
2813 dependencies. The set of options is de-duplicated to avoid repetition.
2814 New in version 3.12: While beneficial for individual options, the
2816 de-duplication step can break up option groups. For example, -option A
2817 -option B becomes -option A B. One may specify a group of options us‐
2818 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
2819 is dropped, and the rest of the option string is parsed using the
2820 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
2821 "SHELL:-option B" becomes -option A -option B.
2822 COMPILE_PDB_NAME
2825 New in version 3.1.
2826 Output name for the MS debug symbol .pdb file generated by the compiler
2829 while building source files.
2830 This property specifies the base name for the debug symbols file. If
2832 not set, the default is unspecified.
2833 NOTE:
2835 The compiler-generated program database files are specified by the
2836 /Fd compiler flag and are not the same as linker-generated program
2837 database files specified by the /pdb linker flag. Use the PDB_NAME
2838 property to specify the latter.
2839 COMPILE_PDB_NAME_<CONFIG>
2841 New in version 3.1.
2842 Per-configuration output name for the MS debug symbol .pdb file gener‐
2845 ated by the compiler while building source files.
2846 This is the configuration-specific version of COMPILE_PDB_NAME.
2848 NOTE:
2850 The compiler-generated program database files are specified by the
2851 /Fd compiler flag and are not the same as linker-generated program
2852 database files specified by the /pdb linker flag. Use the
2853 PDB_NAME_<CONFIG> property to specify the latter.
2854 COMPILE_PDB_OUTPUT_DIRECTORY
2856 New in version 3.1.
2857 Output directory for the MS debug symbol .pdb file generated by the
2860 compiler while building source files.
2861 This property specifies the directory into which the MS debug symbols
2863 will be placed by the compiler. This property is initialized by the
2864 value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY variable if it is set
2865 when a target is created.
2866 NOTE:
2868 The compiler-generated program database files are specified by the
2869 /Fd compiler flag and are not the same as linker-generated program
2870 database files specified by the /pdb linker flag. Use the
2871 PDB_OUTPUT_DIRECTORY property to specify the latter.
2872 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
2874 New in version 3.1.
2875 Per-configuration output directory for the MS debug symbol .pdb file
2878 generated by the compiler while building source files.
2879 This is a per-configuration version of COMPILE_PDB_OUTPUT_DIRECTORY,
2881 but multi-configuration generators (Visual Studio, Xcode) do NOT append
2882 a per-configuration subdirectory to the specified directory. This
2883 property is initialized by the value of the
2884 CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when
2885 a target is created.
2886 NOTE:
2888 The compiler-generated program database files are specified by the
2889 /Fd compiler flag and are not the same as linker-generated program
2890 database files specified by the /pdb linker flag. Use the
2891 PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the latter.
2892 COMPILE_WARNING_AS_ERROR
2894 New in version 3.24.
2895 Specify whether to treat warnings on compile as errors. If enabled,
2898 adds a flag to treat warnings on compile as errors. If the cmake
2899 --compile-no-warning-as-error option is given on the cmake(1) command
2900 line, this property is ignored.
2901 This property is not implemented for all compilers. It is silently ig‐
2903 nored if there is no implementation for the compiler being used. The
2904 currently implemented compiler IDs are:
2905 • GNU
2907 • Clang
2909 • AppleClang
2911 • Fujitsu
2913 • FujitsuClang
2915 • IBMClang
2917 • Intel
2919 • IntelLLVM
2921 • LCC
2923 • MSVC
2925 • NVHPC
2927 • NVIDIA (CUDA)
2929 • QCC
2931 • SunPro
2933 • Tasking
2935 • TI
2937 • VisualAge
2939 • XL
2941 • XLClang
2943 This property is initialized by the value of the variable
2945 CMAKE_COMPILE_WARNING_AS_ERROR if it is set when a target is created.
2946 <CONFIG>_OUTPUT_NAME
2948 Old per-configuration target file base name. Use OUTPUT_NAME_<CONFIG>
2949 instead.
2950 This is a configuration-specific version of the OUTPUT_NAME target
2952 property.
2953 <CONFIG>_POSTFIX
2955 Postfix to append to the target file name for configuration <CONFIG>.
2956 When building with configuration <CONFIG> the value of this property is
2958 appended to the target file name built on disk. For non-executable
2959 targets, this property is initialized by the value of the
2960 CMAKE_<CONFIG>_POSTFIX variable if it is set when a target is created.
2961 This property is ignored on macOS for Frameworks and App Bundles.
2962 For macOS see also the FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target
2964 property.
2965 CROSSCOMPILING_EMULATOR
2967 New in version 3.3.
2968 Use the given emulator to run executables created when crosscompiling.
2971 This command will be added as a prefix to add_test(),
2972 add_custom_command(), and add_custom_target() commands for built target
2973 system executables.
2974 New in version 3.15: If this property contains a semicolon-separated
2976 list, then the first value is the command and remaining values are its
2977 arguments.
2978 This property is initialized by the value of the
2981 CMAKE_CROSSCOMPILING_EMULATOR variable if it is set when a target is
2982 created.
2983 CUDA_ARCHITECTURES
2985 New in version 3.18.
2986 List of architectures to generate device code for.
2989 An architecture can be suffixed by either -real or -virtual to specify
2991 the kind of architecture to generate code for. If no suffix is given
2992 then code is generated for both real and virtual architectures.
2993 A non-empty false value (e.g. OFF) disables adding architectures. This
2995 is intended to support packagers and rare cases where full control over
2996 the passed flags is required.
2997 This property is initialized by the value of the
2999 CMAKE_CUDA_ARCHITECTURES variable if it is set when a target is cre‐
3000 ated.
3001 The CUDA_ARCHITECTURES target property must be set to a non-empty value
3003 on targets that compile CUDA sources, or it is an error. See policy
3004 CMP0104.
3005 The CUDA_ARCHITECTURES may be set to one of the following special val‐
3007 ues:
3008 all New in version 3.23.
3010 Compile for all supported major and minor real architectures,
3013 and the highest major virtual architecture.
3014 all-major
3016 New in version 3.23.
3017 Compile for all supported major real architectures, and the
3020 highest major virtual architecture.
3021 native New in version 3.24.
3023 Compile for the architecture(s) of the host's GPU(s).
3026 Examples
3028 set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72")
3029 Generates code for real and virtual architectures 30, 50 and 72.
3031 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
3033 Generates code for real architecture 70 and virtual architecture 72.
3035 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)
3037 CMake will not pass any architecture flags to the compiler.
3039 CUDA_CUBIN_COMPILATION
3041 New in version 3.27.
3042 Compile CUDA sources to .cubin files instead of .obj files within
3045 Object Libraries.
3046 For example:
3048 add_library(mycubin OBJECT a.cu b.cu)
3050 set_property(TARGET mycubin PROPERTY CUDA_CUBIN_COMPILATION ON)
3051 CUDA_EXTENSIONS
3053 New in version 3.8.
3054 Boolean specifying whether compiler specific extensions are requested.
3057 This property specifies whether compiler specific extensions should be
3059 used. For some compilers, this results in adding a flag such as
3060 -std=gnu++11 instead of -std=c++11 to the compile line. This property
3061 is ON by default. The basic CUDA/C++ standard level is controlled by
3062 the CUDA_STANDARD target property.
3063 See the cmake-compile-features(7) manual for information on compile
3065 features and a list of supported compilers.
3066 This property is initialized by the value of the CMAKE_CUDA_EXTENSIONS
3068 variable if set when a target is created and otherwise by the value of
3069 CMAKE_CUDA_EXTENSIONS_DEFAULT (see CMP0128).
3070 CUDA_FATBIN_COMPILATION
3072 New in version 3.27.
3073 Compile CUDA sources to .fatbin files instead of .obj files within
3076 Object Libraries.
3077 For example:
3079 add_library(myfbins OBJECT a.cu b.cu)
3081 set_property(TARGET myfbins PROPERTY CUDA_FATBIN_COMPILATION ON)
3082 CUDA_OPTIX_COMPILATION
3084 New in version 3.27.
3085 Compile CUDA sources to .optixir files instead of .obj files within
3088 Object Libraries.
3089 For example:
3091 add_library(myoptix OBJECT a.cu b.cu)
3093 set_property(TARGET myoptix PROPERTY CUDA_OPTIX_COMPILATION ON)
3094 CUDA_PTX_COMPILATION
3096 New in version 3.9.
3097 Compile CUDA sources to .ptx files instead of .obj files within Object
3100 Libraries.
3101 For example:
3103 add_library(myptx OBJECT a.cu b.cu)
3105 set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)
3106 CUDA_RESOLVE_DEVICE_SYMBOLS
3108 New in version 3.9.
3109 CUDA only: Enables device linking for the specific library target where
3112 required.
3113 If set, this will tell the required compilers to enable device linking
3115 on the library target. Device linking is an additional link step re‐
3116 quired by some CUDA compilers when CUDA_SEPARABLE_COMPILATION is en‐
3117 abled. Normally device linking is deferred until a shared library or
3118 executable is generated, allowing for multiple static libraries to re‐
3119 solve device symbols at the same time when they are used by a shared
3120 library or executable.
3121 If this property or CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS is unset, static
3123 libraries are treated as if it is disabled while shared, module, and
3124 executable targets behave as if it is on.
3125 If CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS has been defined, this property is
3127 initialized to the value the variable and overriding the default behav‐
3128 ior.
3129 Note that device linking is not supported for Object Libraries.
3131 For instance:
3133 set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
3135 CUDA_RUNTIME_LIBRARY
3137 New in version 3.17.
3138 Select the CUDA runtime library for use by compilers targeting the CUDA
3141 language.
3142 The allowed case insensitive values are:
3144 None Link with -cudart=none or equivalent flag(s) to use no CUDA run‐
3146 time library.
3147 Shared Link with -cudart=shared or equivalent flag(s) to use a dynami‐
3149 cally-linked CUDA runtime library.
3150 Static Link with -cudart=static or equivalent flag(s) to use a stati‐
3152 cally-linked CUDA runtime library.
3153 Contents of CUDA_RUNTIME_LIBRARY may use generator expressions.
3155 If that property is not set then CMake uses an appropriate default
3157 value based on the compiler to select the CUDA runtime library.
3158 NOTE:
3160 This property has effect only when the CUDA language is enabled. To
3161 control the CUDA runtime linking when only using the CUDA SDK with
3162 the C or C++ language we recommend using the FindCUDAToolkit module.
3163 CUDA_SEPARABLE_COMPILATION
3165 New in version 3.8.
3166 CUDA only: Enables separate compilation of device code
3169 If set this will enable separable compilation for all CUDA files for
3171 the given target.
3172 For instance:
3174 set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)
3176 This property is initialized by the value of the
3178 CMAKE_CUDA_SEPARABLE_COMPILATION variable if it is set when a target is
3179 created.
3180 CUDA_STANDARD
3182 New in version 3.8.
3183 The CUDA/C++ standard whose features are requested to build this tar‐
3186 get.
3187 This property specifies the CUDA/C++ standard whose features are re‐
3189 quested to build this target. For some compilers, this results in
3190 adding a flag such as -std=gnu++11 to the compile line.
3191 Supported values are:
3193 98 CUDA C++98. Note that this maps to the same as 03 internally.
3195 03 CUDA C++03
3197 11 CUDA C++11
3199 14 CUDA C++14. While CMake 3.8 and later recognize 14 as a valid
3201 value, CMake 3.9 was the first version to include support for
3202 any compiler.
3203 17 CUDA C++17. While CMake 3.8 and later recognize 17 as a valid
3205 value, CMake 3.18 was the first version to include support for
3206 any compiler.
3207 20 New in version 3.12.
3209 CUDA C++20. While CMake 3.12 and later recognize 20 as a valid
3212 value, CMake 3.18 was the first version to include support for
3213 any compiler.
3214 23 New in version 3.20.
3216 CUDA C++23
3219 26 New in version 3.25.
3221 CUDA C++26. CMake 3.25 and later recognize 26 as a valid value,
3224 no version has support for any compiler.
3225 If the value requested does not result in a compile flag being added
3227 for the compiler in use, a previous standard flag will be added in‐
3228 stead. This means that using:
3229 set_property(TARGET tgt PROPERTY CUDA_STANDARD 11)
3231 with a compiler which does not support -std=gnu++11 or an equivalent
3233 flag will not result in an error or warning, but will instead add the
3234 -std=gnu++03 flag if supported. This "decay" behavior may be con‐
3235 trolled with the CUDA_STANDARD_REQUIRED target property. Additionally,
3236 the CUDA_EXTENSIONS target property may be used to control whether com‐
3237 piler-specific extensions are enabled on a per-target basis.
3238 See the cmake-compile-features(7) manual for information on compile
3240 features and a list of supported compilers.
3241 This property is initialized by the value of the CMAKE_CUDA_STANDARD
3243 variable if it is set when a target is created.
3244 CUDA_STANDARD_REQUIRED
3246 New in version 3.8.
3247 Boolean describing whether the value of CUDA_STANDARD is a requirement.
3250 If this property is set to ON, then the value of the CUDA_STANDARD tar‐
3252 get property is treated as a requirement. If this property is OFF or
3253 unset, the CUDA_STANDARD target property is treated as optional and may
3254 "decay" to a previous standard if the requested is not available. For
3255 compilers that have no notion of a standard level, such as MSVC 1800
3256 (Visual Studio 2013) and lower, this has no effect.
3257 See the cmake-compile-features(7) manual for information on compile
3259 features and a list of supported compilers.
3260 This property is initialized by the value of the
3262 CMAKE_CUDA_STANDARD_REQUIRED variable if it is set when a target is
3263 created.
3264 CXX_EXTENSIONS
3266 New in version 3.1.
3267 Boolean specifying whether compiler specific extensions are requested.
3270 This property specifies whether compiler specific extensions should be
3272 used. For some compilers, this results in adding a flag such as
3273 -std=gnu++11 instead of -std=c++11 to the compile line. This property
3274 is ON by default. The basic C++ standard level is controlled by the
3275 CXX_STANDARD target property.
3276 See the cmake-compile-features(7) manual for information on compile
3278 features and a list of supported compilers.
3279 This property is initialized by the value of the CMAKE_CXX_EXTENSIONS
3281 variable if set when a target is created and otherwise by the value of
3282 CMAKE_CXX_EXTENSIONS_DEFAULT (see CMP0128).
3283 CXX_MODULE_DIRS
3285 New in version 3.25.
3286 NOTE:
3289 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3290 Semicolon-separated list of base directories of the target's default
3292 C++ module set (i.e. the file set with name and type CXX_MODULES). The
3293 property supports generator expressions.
3294 This property is normally only set by target_sources(FILE_SET) rather
3296 than being manipulated directly.
3297 See CXX_MODULE_DIRS_<NAME> for the list of base directories in other
3299 C++ module sets.
3300 CXX_MODULE_DIRS_<NAME>
3302 New in version 3.25.
3303 NOTE:
3306 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3307 Semicolon-separated list of base directories of the target's <NAME> C++
3309 module set, which has the set type CXX_MODULES. The property supports
3310 generator expressions.
3311 This property is normally only set by target_sources(FILE_SET) rather
3313 than being manipulated directly.
3314 See CXX_MODULE_DIRS for the list of base directories in the default C++
3316 module set. See CXX_MODULE_SETS for the file set names of all C++ mod‐
3317 ule sets.
3318 CXX_MODULE_SET
3320 New in version 3.25.
3321 NOTE:
3324 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3325 Semicolon-separated list of files in the target's default C++ module
3327 set, (i.e. the file set with name and type CXX_MODULES). If any of the
3328 paths are relative, they are computed relative to the target's source
3329 directory. The property supports generator expressions.
3330 This property is normally only set by target_sources(FILE_SET) rather
3332 than being manipulated directly.
3333 See CXX_MODULE_SET_<NAME> for the list of files in other C++ module
3335 sets.
3336 CXX_MODULE_SET_<NAME>
3338 New in version 3.25.
3339 NOTE:
3342 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3343 Semicolon-separated list of files in the target's <NAME> C++ module
3345 set, which has the set type CXX_MODULES. If any of the paths are rela‐
3346 tive, they are computed relative to the target's source directory. The
3347 property supports generator expressions.
3348 This property is normally only set by target_sources(FILE_SET) rather
3350 than being manipulated directly.
3351 See CXX_MODULE_SET for the list of files in the default C++ module set.
3353 See CXX_MODULE_SETS for the file set names of all C++ module sets.
3354 CXX_MODULE_SETS
3356 New in version 3.25.
3357 NOTE:
3360 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
3361 Read-only list of the target's PRIVATE and PUBLIC C++ module sets (i.e.
3363 all file sets with the type CXX_MODULES). Files listed in these file
3364 sets are treated as source files for the purpose of IDE integration.
3365 C++ module sets may be defined using the target_sources() command
3367 FILE_SET option with type CXX_MODULES.
3368 See also CXX_MODULE_SET_<NAME>, CXX_MODULE_SET and
3370 INTERFACE_CXX_MODULE_SETS.
3371 CXX_SCAN_FOR_MODULES
3373 New in version 3.26.
3374 CXX_SCAN_FOR_MODULES is a boolean specifying whether CMake will scan
3377 C++ sources in the target for module dependencies. See also the
3378 CXX_SCAN_FOR_MODULES for per-source settings which, if set, overrides
3379 the target-wide settings.
3380 This property is initialized by the value of the
3382 CMAKE_CXX_SCAN_FOR_MODULES variable if it is set when a target is cre‐
3383 ated.
3384 When this property is set ON or unset, CMake will scan the target's CXX
3386 sources at build time and add module dependency information to the com‐
3387 pile line as necessary. When this property is set OFF, CMake will not
3388 scan the target's CXX sources at build time.
3389 Note that scanning is only performed if C++20 or higher is enabled for
3391 the target. Scanning for modules in the target's sources belonging to
3392 file sets of type CXX_MODULES is always performed.
3393 NOTE:
3395 This setting is meaningful only when experimental support for C++
3396 modules has been enabled by the CMAKE_EXPERIMENTAL_CXX_MOD‐
3397 ULE_CMAKE_API gate.
3398 CXX_STANDARD
3400 New in version 3.1.
3401 The C++ standard whose features are requested to build this target.
3404 This property specifies the C++ standard whose features are requested
3406 to build this target. For some compilers, this results in adding a
3407 flag such as -std=gnu++11 to the compile line. For compilers that have
3408 no notion of a standard level, such as Microsoft Visual C++ before 2015
3409 Update 3, this has no effect.
3410 Supported values are:
3412 98 C++98
3414 11 C++11
3416 14 C++14
3418 17 New in version 3.8.
3420 C++17
3423 20 New in version 3.12.
3425 C++20
3428 23 New in version 3.20.
3430 C++23
3433 26 New in version 3.25.
3435 C++26. CMake 3.25 and later recognize 26 as a valid value, no
3438 version has support for any compiler.
3439 If the value requested does not result in a compile flag being added
3441 for the compiler in use, a previous standard flag will be added in‐
3442 stead. This means that using:
3443 set_property(TARGET tgt PROPERTY CXX_STANDARD 11)
3445 with a compiler which does not support -std=gnu++11 or an equivalent
3447 flag will not result in an error or warning, but will instead add the
3448 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
3449 trolled with the CXX_STANDARD_REQUIRED target property. Additionally,
3450 the CXX_EXTENSIONS target property may be used to control whether com‐
3451 piler-specific extensions are enabled on a per-target basis.
3452 See the cmake-compile-features(7) manual for information on compile
3454 features and a list of supported compilers.
3455 This property is initialized by the value of the CMAKE_CXX_STANDARD
3457 variable if it is set when a target is created.
3458 CXX_STANDARD_REQUIRED
3460 New in version 3.1.
3461 Boolean describing whether the value of CXX_STANDARD is a requirement.
3464 If this property is set to ON, then the value of the CXX_STANDARD tar‐
3466 get property is treated as a requirement. If this property is OFF or
3467 unset, the CXX_STANDARD target property is treated as optional and may
3468 "decay" to a previous standard if the requested is not available. For
3469 compilers that have no notion of a standard level, such as MSVC 1800
3470 (Visual Studio 2013) and lower, this has no effect.
3471 See the cmake-compile-features(7) manual for information on compile
3473 features and a list of supported compilers.
3474 This property is initialized by the value of the
3476 CMAKE_CXX_STANDARD_REQUIRED variable if it is set when a target is cre‐
3477 ated.
3478 DEBUG_POSTFIX
3480 See target property <CONFIG>_POSTFIX.
3481 This property is a special case of the more-general <CONFIG>_POSTFIX
3483 property for the DEBUG configuration.
3484 DEFINE_SYMBOL
3486 Define a symbol when compiling this target's sources.
3487 DEFINE_SYMBOL sets the name of the preprocessor symbol defined when
3489 compiling sources in a shared library. If not set here then it is set
3490 to target_EXPORTS by default (with some substitutions if the target is
3491 not a valid C identifier). This is useful for headers to know whether
3492 they are being included from inside their library or outside to prop‐
3493 erly setup dllexport/dllimport decorations on Windows.
3494 On POSIX platforms, this can optionally be used to control the visibil‐
3496 ity of symbols.
3497 CMake provides support for such decorations with the
3499 GenerateExportHeader module.
3500 DEPLOYMENT_ADDITIONAL_FILES
3502 New in version 3.13.
3503 Set the WinCE project AdditionalFiles in DeploymentTool in .vcproj
3506 files generated by the Visual Studio 9 2008 generator. This is useful
3507 when you want to debug on remote WinCE device. Specify additional
3508 files that will be copied to the device. For example:
3509 set_property(TARGET ${TARGET} PROPERTY
3511 DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0"
3512 "german.lng|local_folder|remote_folder|0")
3513 produces:
3515 <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... />
3517 DEPLOYMENT_REMOTE_DIRECTORY
3519 New in version 3.6.
3520 Set the WinCE project RemoteDirectory in DeploymentTool and RemoteExe‐
3523 cutable in DebuggerTool in .vcproj files generated by the Visual Studio
3524 9 2008 generator. This is useful when you want to debug on remote
3525 WinCE device. For example:
3526 set_property(TARGET ${TARGET} PROPERTY
3528 DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage")
3529 produces:
3531 <DeploymentTool RemoteDirectory="\FlashStorage" ... />
3533 <DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... />
3534 DEPRECATION
3536 New in version 3.17.
3537 Deprecation message from imported target's developer.
3540 DEPRECATION is the message regarding a deprecation status to be dis‐
3542 played to downstream users of a target.
3543 The message is formatted as follows:
3545 • Lines that do not start in whitespace are wrapped as paragraph text.
3547 • Lines that start in whitespace are preserved as preformatted text.
3549 DISABLE_PRECOMPILE_HEADERS
3551 New in version 3.16.
3552 Disables the precompilation of header files specified by
3555 PRECOMPILE_HEADERS property.
3556 If the property is not set, CMake will use the value provided by
3558 CMAKE_DISABLE_PRECOMPILE_HEADERS.
3559 DLL_NAME_WITH_SOVERSION
3561 New in version 3.27.
3562 This property control whether the SOVERSION target property are added
3565 to the filename of generated DLL filenames for the Windows platform,
3566 which is selected when the WIN32 variable is set.
3567 The value of the listed property is appended to the basename of the
3569 runtime component of the shared library target as -<SOVERSION>.
3570 Please note that setting this property has no effect if versioned file‐
3572 names are globally disabled with the CMAKE_PLATFORM_NO_VERSIONED_SONAME
3573 variable.
3574 DOTNET_SDK
3576 New in version 3.23.
3577 Specify the .NET SDK for C# projects. For example: Microsoft.NET.Sdk.
3580 This property tells Visual Studio Generators for VS 2019 and above to
3582 generate a .NET SDK-style project using the specified SDK. The prop‐
3583 erty is meaningful only to these generators, and only in C# targets.
3584 It is ignored for C++ projects, even if they are managed (e.g. using
3585 COMMON_LANGUAGE_RUNTIME).
3586 This property must be a non-empty string to generate .NET SDK-style
3588 projects. CMake does not perform any validations for the value of the
3589 property.
3590 This property may be initialized for all targets using the
3592 CMAKE_DOTNET_SDK variable.
3593 NOTE:
3595 The Visual Studio Generators in this version of CMake have not yet
3596 learned to support add_custom_command() in .NET SDK-style projects.
3597 It is currently an error to attach a custom command to a target with
3598 the DOTNET_SDK property set.
3599 DOTNET_TARGET_FRAMEWORK
3601 New in version 3.17.
3602 Specify the .NET target framework.
3605 Used to specify the .NET target framework for C++/CLI and C#. For ex‐
3607 ample: netcoreapp2.1.
3608 This property is only evaluated for Visual Studio Generators VS 2010
3610 and above.
3611 Can be initialized for all targets using the variable
3613 CMAKE_DOTNET_TARGET_FRAMEWORK.
3614 DOTNET_TARGET_FRAMEWORK_VERSION
3616 New in version 3.12.
3617 Specify the .NET target framework version.
3620 Used to specify the .NET target framework version for C++/CLI and C#.
3622 For example: v4.5.
3623 This property is only evaluated for Visual Studio Generators VS 2010
3625 and above.
3626 To initialize this variable for all targets set
3628 CMAKE_DOTNET_TARGET_FRAMEWORK or CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.
3629 If both are set, the latter is ignored.
3630 EchoString
3632 A message to be displayed when the target is built.
3633 A message to display on some generators (such as Makefile Generators)
3635 when the target is built.
3636 ENABLE_EXPORTS
3638 Specify whether an executable or a shared library exports symbols.
3639 Normally an executable does not export any symbols because it is the
3641 final program. It is possible for an executable to export symbols to
3642 be used by loadable modules. When this property is set to true CMake
3643 will allow other targets to "link" to the executable with the
3644 target_link_libraries() command. On all platforms a target-level de‐
3645 pendency on the executable is created for targets that link to it.
3646 Handling of the executable on the link lines of the loadable modules
3647 varies by platform:
3648 • On Windows-based systems (including Cygwin) an "import library" is
3650 created along with the executable to list the exported symbols.
3651 Loadable modules link to the import library to get the symbols.
3652 • On macOS, loadable modules link to the executable itself using the
3654 -bundle_loader flag.
3655 • On AIX, a linker "import file" is created along with the executable
3657 to list the exported symbols for import when linking other targets.
3658 Loadable modules link to the import file to get the symbols.
3659 • On other platforms, loadable modules are simply linked without refer‐
3661 encing the executable since the dynamic loader will automatically
3662 bind symbols when the module is loaded.
3663 This property is initialized by the value of the
3665 CMAKE_EXECUTABLE_ENABLE_EXPORTS variable, if it is set when an exe‐
3666 cutable target is created. If CMAKE_EXECUTABLE_ENABLE_EXPORTS is not
3667 set, the CMAKE_ENABLE_EXPORTS variable is used to initialize the prop‐
3668 erty instead for backward compatibility reasons. See below for alter‐
3669 native initialization behavior for shared library targets.
3670 New in version 3.27: On Apple platforms, to link with a shared library
3672 (either a bare library or a framework), a linker import file can be
3673 used instead of the actual shared library. These linker import files
3674 are also known as text-based stubs, and they have a .tbd file exten‐
3675 sion.
3676 The generation of these linker import files, as well as their consump‐
3678 tion, is controlled by this property. When this property is set to true
3679 on a shared library target, CMake will generate a .tbd file for the li‐
3680 brary. Other targets that link to the shared library target will then
3681 use this .tbd file when linking rather than linking to the shared li‐
3682 brary binary.
3683 NOTE:
3685 For backward compatibility reasons, this property will be ignored if
3686 the XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS target property or the
3687 CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS variable is set to
3688 false.
3689 For shared library targets, this property is initialized by the value
3691 of the CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS variable, if it is set when
3692 the target is created.
3693 EXCLUDE_FROM_ALL
3696 Set this target property to a true (or false) value to exclude (or in‐
3697 clude) the target from the "all" target of the containing directory and
3698 its ancestors. If excluded, running e.g. make in the containing direc‐
3699 tory or its ancestors will not build the target by default.
3700 If this target property is not set then the target will be included in
3702 the "all" target of the containing directory. Furthermore, it will be
3703 included in the "all" target of its ancestor directories unless the
3704 EXCLUDE_FROM_ALL directory property is set.
3705 With EXCLUDE_FROM_ALL set to false or not set at all, the target will
3707 be brought up to date as part of doing a make install or its equivalent
3708 for the CMake generator being used.
3709 If a target has EXCLUDE_FROM_ALL set to true, it may still be listed in
3711 an install(TARGETS) command, but the user is responsible for ensuring
3712 that the target's build artifacts are not missing or outdated when an
3713 install is performed.
3714 This property may use "generator expressions" with the syntax $<...>.
3716 See the cmake-generator-expressions(7) manual for available expres‐
3717 sions.
3718 Only the "Ninja Multi-Config" generator supports a property value that
3720 varies by configuration. For all other generators the value of this
3721 property must be the same for all configurations.
3722 EXCLUDE_FROM_DEFAULT_BUILD
3724 Exclude target from Build Solution.
3725 This property is only used by Visual Studio generators. When set to
3727 TRUE, the target will not be built when you press Build Solution.
3728 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
3730 Per-configuration version of target exclusion from Build Solution.
3731 This is the configuration-specific version of
3733 EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD
3734 is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes
3735 precedence in configurations for which it has a value.
3736 EXPORT_COMPILE_COMMANDS
3738 New in version 3.20.
3739 Enable/Disable output of compile commands during generation for a tar‐
3742 get.
3743 This property is initialized by the value of the variable
3745 CMAKE_EXPORT_COMPILE_COMMANDS if it is set when a target is created.
3746 EXPORT_NAME
3748 Exported name for target files.
3749 This sets the name for the IMPORTED target generated by the
3751 install(EXPORT) and export() commands. If not set, the logical target
3752 name is used by default.
3753 EXPORT_NO_SYSTEM
3755 New in version 3.25.
3756 This property affects the behavior of the install(EXPORT) and export()
3759 commands when they install or export the target respectively. When EX‐
3760 PORT_NO_SYSTEM is set to true, those commands generate an imported tar‐
3761 get with SYSTEM property set to false.
3762 See the NO_SYSTEM_FROM_IMPORTED target property to set this behavior on
3764 the target consuming the include directories rather than the one pro‐
3765 viding them.
3766 EXPORT_PROPERTIES
3768 New in version 3.12.
3769 List additional properties to export for a target.
3772 This property contains a list of property names that should be exported
3774 by the install(EXPORT) and export() commands. By default only a lim‐
3775 ited number of properties are exported. This property can be used to
3776 additionally export other properties as well.
3777 Properties starting with INTERFACE_ or IMPORTED_ are not allowed as
3779 they are reserved for internal CMake use.
3780 Properties containing generator expressions are also not allowed.
3782 NOTE:
3784 Since CMake 3.19, Interface Libraries may have arbitrary target
3785 properties. If a project exports an interface library with custom
3786 properties, the resulting package may not work with dependents con‐
3787 figured by older versions of CMake that reject the custom proper‐
3788 ties.
3789 FOLDER
3791 For IDEs that present targets using a folder hierarchy, this property
3792 specifies the name of the folder to place the target under. To nest
3793 folders, use FOLDER values such as GUI/Dialogs with / characters sepa‐
3794 rating folder levels. Targets with no FOLDER property will appear as
3795 top level entities. Targets with the same FOLDER property value will
3796 appear in the same folder as siblings.
3797 Only some CMake generators honor the FOLDER property (e.g. Xcode or any
3799 of the Visual Studio generators). Those generators that don't will
3800 simply ignore it.
3801 This property is initialized by the value of the variable CMAKE_FOLDER
3803 if it is set when a target is created.
3804 The global property USE_FOLDERS must be set to true, otherwise the
3806 FOLDER property is ignored.
3807 Fortran_BUILDING_INSTRINSIC_MODULES
3809 New in version 3.22.
3810 Instructs the CMake Fortran preprocessor that the target is building
3813 Fortran intrinsics for building a Fortran compiler.
3814 This property is off by default and should be turned only on projects
3816 that build a Fortran compiler. It should not be turned on for projects
3817 that use a Fortran compiler.
3818 Turning this property on will correctly add dependencies for building
3820 Fortran intrinsic modules whereas turning the property off will ignore
3821 Fortran intrinsic modules in the dependency graph as they are supplied
3822 by the compiler itself.
3823 Fortran_FORMAT
3825 Set to FIXED or FREE to indicate the Fortran source layout.
3826 This property tells CMake whether the Fortran source files in a target
3828 use fixed-format or free-format. CMake will pass the corresponding
3829 format flag to the compiler. Use the source-specific Fortran_FORMAT
3830 property to change the format of a specific source file. If the vari‐
3831 able CMAKE_Fortran_FORMAT is set when a target is created its value is
3832 used to initialize this property.
3833 Fortran_MODULE_DIRECTORY
3835 Specify output directory for Fortran modules provided by the target.
3836 If the target contains Fortran source files that provide modules and
3838 the compiler supports a module output directory this specifies the di‐
3839 rectory in which the modules will be placed. When this property is not
3840 set the modules will be placed in the build directory corresponding to
3841 the target's source directory. If the variable
3842 CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its
3843 value is used to initialize this property.
3844 When using one of the Visual Studio Generators with the Intel Fortran
3846 plugin installed in Visual Studio, a subdirectory named after the con‐
3847 figuration will be appended to the path where modules are created. For
3848 example, if Fortran_MODULE_DIRECTORY is set to C:/some/path, modules
3849 will end up in C:/some/path/Debug (or C:/some/path/Release etc.) when
3850 an Intel Fortran .vfproj file is generated, and in C:/some/path when
3851 any other generator is used.
3852 Note that some compilers will automatically search the module output
3854 directory for modules USEd during compilation but others will not. If
3855 your sources USE modules their location must be specified by
3856 INCLUDE_DIRECTORIES regardless of this property.
3857 Fortran_PREPROCESS
3859 New in version 3.18.
3860 Control whether the Fortran source file should be unconditionally pre‐
3863 processed.
3864 If unset or empty, rely on the compiler to determine whether the file
3866 should be preprocessed. If explicitly set to OFF then the file does not
3867 need to be preprocessed. If explicitly set to ON, then the file does
3868 need to be preprocessed as part of the compilation step.
3869 When using the Ninja generator, all source files are first preprocessed
3871 in order to generate module dependency information. Setting this prop‐
3872 erty to OFF will make Ninja skip this step.
3873 Use the source-specific Fortran_PREPROCESS property if a single file
3875 needs to be preprocessed. If the variable CMAKE_Fortran_PREPROCESS is
3876 set when a target is created its value is used to initialize this prop‐
3877 erty.
3878 NOTE:
3880 For some compilers, NAG, PGI and Solaris Studio, setting this to OFF
3881 will have no effect.
3882 FRAMEWORK
3884 Build SHARED or STATIC library as Framework Bundle on the macOS and
3885 iOS.
3886 If such a library target has this property set to TRUE it will be built
3888 as a framework when built on the macOS and iOS. It will have the di‐
3889 rectory structure required for a framework and will be suitable to be
3890 used with the -framework option. This property is initialized by the
3891 value of the CMAKE_FRAMEWORK variable if it is set when a target is
3892 created.
3893 To customize Info.plist file in the framework, use
3895 MACOSX_FRAMEWORK_INFO_PLIST target property.
3896 For macOS see also the FRAMEWORK_VERSION target property.
3898 Example of creation dynamicFramework:
3900 add_library(dynamicFramework SHARED
3902 dynamicFramework.c
3903 dynamicFramework.h
3904 )
3905 set_target_properties(dynamicFramework PROPERTIES
3906 FRAMEWORK TRUE
3907 FRAMEWORK_VERSION C
3908 MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework
3909 MACOSX_FRAMEWORK_INFO_PLIST Info.plist
3910 # "current version" in semantic format in Mach-O binary file
3911 VERSION 16.4.0
3912 # "compatibility version" in semantic format in Mach-O binary file
3913 SOVERSION 1.0.0
3914 PUBLIC_HEADER dynamicFramework.h
3915 XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer"
3916 )
3917 FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
3919 New in version 3.18.
3920 Postfix to append to the framework file name for configuration <CON‐
3923 FIG>, when using a multi-config generator (like Xcode and Ninja
3924 Multi-Config).
3925 When building with configuration <CONFIG> the value of this property is
3927 appended to the framework file name built on disk.
3928 For example, given a framework called my_fw, a value of _debug for the
3930 FRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG property, and Debug;Release in
3931 CMAKE_CONFIGURATION_TYPES, the following relevant files would be cre‐
3932 ated for the Debug and Release configurations:
3933 • Release/my_fw.framework/my_fw
3935 • Release/my_fw.framework/Versions/A/my_fw
3937 • Debug/my_fw.framework/my_fw_debug
3939 • Debug/my_fw.framework/Versions/A/my_fw_debug
3941 For framework targets, this property is initialized by the value of the
3943 CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> variable if it is set
3944 when a target is created.
3945 This property is ignored for non-framework targets, and when using sin‐
3947 gle config generators.
3948 FRAMEWORK_VERSION
3950 New in version 3.4.
3951 Version of a framework created using the FRAMEWORK target property
3954 (e.g. A).
3955 This property only affects macOS, as iOS doesn't have versioned direc‐
3957 tory structure.
3958 GENERATOR_FILE_NAME
3960 Generator's file for this target.
3961 An internal property used by some generators to record the name of the
3963 project or dsp file associated with this target. Note that at config‐
3964 ure time, this property is only set for targets created by
3965 include_external_msproject().
3966 GHS_INTEGRITY_APP
3968 New in version 3.14.
3969 ON / OFF boolean to determine if an executable target should be treated
3972 as an Integrity Application.
3973 If no value is set and if a .int file is added as a source file to the
3975 executable target it will be treated as an Integrity Application.
3976 Supported on Green Hills MULTI.
3978 GHS_NO_SOURCE_GROUP_FILE
3980 New in version 3.14.
3981 ON / OFF boolean to control if the project file for a target should be
3984 one single file or multiple files.
3985 The default behavior or when the property is OFF is to generate a
3987 project file for the target and then a sub-project file for each source
3988 group.
3989 When this property is ON or if CMAKE_GHS_NO_SOURCE_GROUP_FILE is ON
3991 then only a single project file is generated for the target.
3992 Supported on Green Hills MULTI.
3994 GNUtoMS
3996 Convert GNU import library (.dll.a) to MS format (.lib).
3997 When linking a shared library or executable that exports symbols using
3999 GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert
4000 the import library (.dll.a) from GNU to MS format (.lib). Both import
4001 libraries will be installed by install(TARGETS) and exported by
4002 install(EXPORT) and export() to be linked by applications with either
4003 GNU- or MS-compatible tools.
4004 If the variable CMAKE_GNUtoMS is set when a target is created its value
4006 is used to initialize this property. The variable must be set prior to
4007 the first command that enables a language such as project() or
4008 enable_language(). CMake provides the variable as an option to the
4009 user automatically when configuring on Windows with GNU tools.
4010 HAS_CXX
4012 Link the target using the C++ linker tool (obsolete).
4013 This is equivalent to setting the LINKER_LANGUAGE property to CXX.
4015 HEADER_DIRS
4017 New in version 3.23.
4018 Semicolon-separated list of base directories of the target's default
4021 header set (i.e. the file set with name and type HEADERS). The property
4022 supports generator expressions.
4023 This property is normally only set by target_sources(FILE_SET) rather
4025 than being manipulated directly.
4026 See HEADER_DIRS_<NAME> for the list of base directories in other header
4028 sets.
4029 HEADER_DIRS_<NAME>
4031 New in version 3.23.
4032 Semicolon-separated list of base directories of the target's <NAME>
4035 header set, which has the set type HEADERS. The property supports
4036 generator expressions.
4037 This property is normally only set by target_sources(FILE_SET) rather
4039 than being manipulated directly.
4040 See HEADER_DIRS for the list of base directories in the default header
4042 set. See HEADER_SETS for the file set names of all header sets.
4043 HEADER_SET
4045 New in version 3.23.
4046 Semicolon-separated list of files in the target's default header set,
4049 (i.e. the file set with name and type HEADERS). If any of the paths are
4050 relative, they are computed relative to the target's source directory.
4051 The property supports generator expressions.
4052 This property is normally only set by target_sources(FILE_SET) rather
4054 than being manipulated directly.
4055 See HEADER_SET_<NAME> for the list of files in other header sets.
4057 HEADER_SET_<NAME>
4059 New in version 3.23.
4060 Semicolon-separated list of files in the target's <NAME> header set,
4063 which has the set type HEADERS. If any of the paths are relative, they
4064 are computed relative to the target's source directory. The property
4065 supports generator expressions.
4066 This property is normally only set by target_sources(FILE_SET) rather
4068 than being manipulated directly.
4069 See HEADER_SET for the list of files in the default header set. See
4071 HEADER_SETS for the file set names of all header sets.
4072 HEADER_SETS
4074 New in version 3.23.
4075 Read-only list of the target's PRIVATE and PUBLIC header sets (i.e.
4078 all file sets with the type HEADERS). Files listed in these file sets
4079 are treated as source files for the purpose of IDE integration. The
4080 files also have their HEADER_FILE_ONLY property set to TRUE.
4081 Header sets may be defined using the target_sources() command FILE_SET
4083 option with type HEADERS.
4084 See also HEADER_SET_<NAME>, HEADER_SET and INTERFACE_HEADER_SETS.
4086 HIP_ARCHITECTURES
4088 New in version 3.21.
4089 List of AMD GPU architectures to generate device code for.
4092 A non-empty false value (e.g. OFF) disables adding architectures. This
4094 is intended to support packagers and rare cases where full control over
4095 the passed flags is required.
4096 This property is initialized by the value of the
4098 CMAKE_HIP_ARCHITECTURES variable if it is set when a target is created.
4099 The HIP compilation model has two modes: whole and separable. Whole
4101 compilation generates device code at compile time. Separable compila‐
4102 tion generates device code at link time. Therefore the HIP_ARCHITEC‐
4103 TURES target property should be set on targets that compile or link
4104 with any HIP sources.
4105 Examples
4107 set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900)
4108 Generates code for both gfx801 and gfx900.
4110 HIP_EXTENSIONS
4112 New in version 3.21.
4113 Boolean specifying whether compiler specific extensions are requested.
4116 This property specifies whether compiler specific extensions should be
4118 used. For some compilers, this results in adding a flag such as
4119 -std=gnu++11 instead of -std=c++11 to the compile line. This property
4120 is ON by default. The basic HIP/C++ standard level is controlled by the
4121 HIP_STANDARD target property.
4122 See the cmake-compile-features(7) manual for information on compile
4124 features and a list of supported compilers.
4125 This property is initialized by the value of the CMAKE_HIP_EXTENSIONS
4127 variable if set when a target is created and otherwise by the value of
4128 CMAKE_HIP_EXTENSIONS_DEFAULT (see CMP0128).
4129 HIP_STANDARD
4131 New in version 3.21.
4132 The HIP/C++ standard requested to build this target.
4135 Supported values are:
4137 98 HIP C++98
4139 11 HIP C++11
4141 14 HIP C++14
4143 17 HIP C++17
4145 20 HIP C++20
4147 23 HIP C++23
4149 26 New in version 3.25.
4151 HIP C++26. CMake 3.25 and later recognize 26 as a valid value,
4154 no version has support for any compiler.
4155 If the value requested does not result in a compile flag being added
4157 for the compiler in use, a previous standard flag will be added in‐
4158 stead. This means that using:
4159 set_property(TARGET tgt PROPERTY HIP_STANDARD 11)
4161 with a compiler which does not support -std=gnu++11 or an equivalent
4163 flag will not result in an error or warning, but will instead add the
4164 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
4165 trolled with the HIP_STANDARD_REQUIRED target property. Additionally,
4166 the HIP_EXTENSIONS target property may be used to control whether com‐
4167 piler-specific extensions are enabled on a per-target basis.
4168 See the cmake-compile-features(7) manual for information on compile
4170 features and a list of supported compilers.
4171 This property is initialized by the value of the CMAKE_HIP_STANDARD
4173 variable if it is set when a target is created.
4174 HIP_STANDARD_REQUIRED
4176 New in version 3.21.
4177 Boolean describing whether the value of HIP_STANDARD is a requirement.
4180 If this property is set to ON, then the value of the HIP_STANDARD tar‐
4182 get property is treated as a requirement. If this property is OFF or
4183 unset, the HIP_STANDARD target property is treated as optional and may
4184 "decay" to a previous standard if the requested is not available.
4185 See the cmake-compile-features(7) manual for information on compile
4187 features and a list of supported compilers.
4188 This property is initialized by the value of the
4190 CMAKE_HIP_STANDARD_REQUIRED variable if it is set when a target is cre‐
4191 ated.
4192 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
4194 Specify #include line transforms for dependencies in a target.
4195 This property specifies rules to transform macro-like #include lines
4197 during implicit dependency scanning of C and C++ source files. The
4198 list of rules must be semicolon-separated with each entry of the form
4199 A_MACRO(%)=value-with-% (the % must be literal). During dependency
4200 scanning occurrences of A_MACRO(...) on #include lines will be replaced
4201 by the value given with the macro argument substituted for %. For ex‐
4202 ample, the entry
4203 MYDIR(%)=<mydir/%>
4205 will convert lines of the form
4207 #include MYDIR(myheader.h)
4209 to
4211 #include <mydir/myheader.h>
4213 allowing the dependency to be followed.
4215 This property applies to sources in the target on which it is set.
4217 IMPORTED
4219 Read-only indication of whether a target is IMPORTED.
4220 The boolean value of this property is True for targets created with the
4222 IMPORTED option to add_executable() or add_library(). It is False for
4223 targets built within the project.
4224 IMPORTED_COMMON_LANGUAGE_RUNTIME
4226 New in version 3.12.
4227 Property to define if the target uses C++/CLI.
4230 Ignored for non-imported targets.
4232 See also the COMMON_LANGUAGE_RUNTIME target property.
4234 IMPORTED_CONFIGURATIONS
4236 Configurations provided for an imported target.
4237 Set this to the list of configuration names available for an imported
4239 target. For each configuration named, the imported target's artifacts
4240 must be specified in other target properties:
4241 • IMPORTED_LOCATION_<CONFIG>, or
4243 • IMPORTED_IMPLIB_<CONFIG> (on DLL platforms, on AIX for Executables or
4245 on Apple for Shared Libraries), or
4246 • IMPORTED_OBJECTS_<CONFIG> (for Object Libraries), or
4248 • IMPORTED_LIBNAME_<CONFIG> (for Interface Libraries).
4250 The configuration names correspond to those defined in the project from
4252 which the target is imported. If the importing project uses a differ‐
4253 ent set of configurations, the names may be mapped using the
4254 MAP_IMPORTED_CONFIG_<CONFIG> target property.
4255 The IMPORTED_CONFIGURATIONS property is ignored for non-imported tar‐
4257 gets.
4258 IMPORTED_GLOBAL
4260 New in version 3.11.
4261 Indication of whether an IMPORTED target is globally visible.
4264 The boolean value of this property is True for targets created with the
4266 IMPORTED GLOBAL options to add_executable() or add_library(). It is al‐
4267 ways False for targets built within the project.
4268 For targets created with the IMPORTED option to add_executable() or
4270 add_library() but without the additional option GLOBAL this is False,
4271 too. However, setting this property for such a locally IMPORTED target
4272 to True promotes that target to global scope. This promotion can only
4273 be done in the same directory where that IMPORTED target was created in
4274 the first place.
4275 NOTE:
4277 Once an imported target has been made global, it cannot be changed
4278 back to non-global. Therefore, if a project sets this property, it
4279 may only provide a value of True. CMake will issue an error if the
4280 project tries to set the property to a non-True value, even if the
4281 value was already False.
4282 NOTE:
4284 Local ALIAS targets created before promoting an IMPORTED target from
4285 LOCAL to GLOBAL, keep their initial scope (see ALIAS_GLOBAL target
4286 property).
4287 IMPORTED_IMPLIB
4289 Full path to the import library for an IMPORTED target.
4290 This property may be set:
4292 • On DLL platforms, to the location of the .lib part of the DLL.
4294 • On AIX, to an import file (e.g. .imp) created for executables that
4296 export symbols (see the ENABLE_EXPORTS target property).
4297 • On macOS, to an import file (e.g. .tbd) created for shared libraries
4299 (see the ENABLE_EXPORTS target property). For frameworks this is the
4300 location of the .tbd file symlink just inside the framework folder.
4301 The IMPORTED_IMPLIB target property may be overridden for a given con‐
4303 figuration <CONFIG> by the configuration-specific
4304 IMPORTED_IMPLIB_<CONFIG> target property. Furthermore, the
4305 MAP_IMPORTED_CONFIG_<CONFIG> target property may be used to map between
4306 a project's configurations and those of an imported target. If none of
4307 these is set then the name of any other configuration listed in the
4308 IMPORTED_CONFIGURATIONS target property may be selected and its
4309 IMPORTED_IMPLIB_<CONFIG> value used.
4310 This property is ignored for non-imported targets.
4312 IMPORTED_IMPLIB_<CONFIG>
4314 <CONFIG>-specific version of IMPORTED_IMPLIB property.
4315 Configuration names correspond to those provided by the project from
4317 which the target is imported.
4318 IMPORTED_LIBNAME
4320 New in version 3.8.
4321 Specify the link library name for an imported Interface Library.
4324 An interface library builds no library file itself but does specify us‐
4326 age requirements for its consumers. The IMPORTED_LIBNAME property may
4327 be set to specify a single library name to be placed on the link line
4328 in place of the interface library target name as a requirement for us‐
4329 ing the interface.
4330 This property is intended for use in naming libraries provided by a
4332 platform SDK for which the full path to a library file may not be
4333 known. The value may be a plain library name such as foo but may not
4334 be a path (e.g. /usr/lib/libfoo.so) or a flag (e.g. -Wl,...). The name
4335 is never treated as a library target name even if it happens to name
4336 one.
4337 The IMPORTED_LIBNAME property is allowed only on imported Interface Li‐
4339 braries and is rejected on targets of other types (for which the
4340 IMPORTED_LOCATION target property may be used).
4341 IMPORTED_LIBNAME_<CONFIG>
4343 New in version 3.8.
4344 <CONFIG>-specific version of IMPORTED_LIBNAME property.
4347 Configuration names correspond to those provided by the project from
4349 which the target is imported.
4350 IMPORTED_LINK_DEPENDENT_LIBRARIES
4352 Dependent shared libraries of an imported shared library.
4353 Shared libraries may be linked to other shared libraries as part of
4355 their implementation. On some platforms the linker searches for the
4356 dependent libraries of shared libraries they are including in the link.
4357 Set this property to the list of dependent shared libraries of an im‐
4358 ported library. The list should be disjoint from the list of interface
4359 libraries in the INTERFACE_LINK_LIBRARIES property. On platforms re‐
4360 quiring dependent shared libraries to be found at link time CMake uses
4361 this list to add appropriate files or paths to the link command line.
4362 Ignored for non-imported targets.
4363 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
4365 <CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
4366 Configuration names correspond to those provided by the project from
4368 which the target is imported. If set, this property completely over‐
4369 rides the generic property for the named configuration.
4370 IMPORTED_LINK_INTERFACE_LANGUAGES
4372 Languages compiled into an IMPORTED static library.
4373 Set this to the list of languages of source files compiled to produce a
4375 STATIC IMPORTED library (such as C or CXX). CMake accounts for these
4376 languages when computing how to link a target to the imported library.
4377 For example, when a C executable links to an imported C++ static li‐
4378 brary CMake chooses the C++ linker to satisfy language runtime depen‐
4379 dencies of the static library.
4380 This property is ignored for targets that are not STATIC libraries.
4382 This property is ignored for non-imported targets.
4383 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
4385 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.
4386 Configuration names correspond to those provided by the project from
4388 which the target is imported. If set, this property completely over‐
4389 rides the generic property for the named configuration.
4390 IMPORTED_LINK_INTERFACE_LIBRARIES
4392 Transitive link interface of an IMPORTED target.
4393 Set this to the list of libraries whose interface is included when an
4395 IMPORTED library target is linked to another target. The libraries
4396 will be included on the link line for the target. Unlike the
4397 LINK_INTERFACE_LIBRARIES property, this property applies to all im‐
4398 ported target types, including STATIC libraries. This property is ig‐
4399 nored for non-imported targets.
4400 This property is ignored if the target also has a non-empty
4402 INTERFACE_LINK_LIBRARIES property.
4403 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
4405 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
4407 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.
4408 Configuration names correspond to those provided by the project from
4410 which the target is imported. If set, this property completely over‐
4411 rides the generic property for the named configuration.
4412 This property is ignored if the target also has a non-empty
4414 INTERFACE_LINK_LIBRARIES property.
4415 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
4417 IMPORTED_LINK_INTERFACE_MULTIPLICITY
4419 Repetition count for cycles of IMPORTED static libraries.
4420 This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
4422 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
4424 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY.
4425 If set, this property completely overrides the generic property for the
4427 named configuration.
4428 IMPORTED_LOCATION
4430 Full path to the main file on disk for an IMPORTED target.
4431 Set this to the location of an IMPORTED target file on disk. For exe‐
4433 cutables this is the location of the executable file. For STATIC li‐
4434 braries and modules this is the location of the library or module. For
4435 SHARED libraries on non-DLL platforms this is the location of the
4436 shared library. For application bundles on macOS this is the location
4437 of the executable file inside Contents/MacOS within the bundle folder.
4438 For frameworks on macOS this is the location of the library file sym‐
4439 link just inside the framework folder. For DLLs this is the location
4440 of the .dll part of the library. For UNKNOWN libraries this is the lo‐
4441 cation of the file to be linked. Ignored for non-imported targets.
4442 The IMPORTED_LOCATION target property may be overridden for a given
4444 configuration <CONFIG> by the configuration-specific
4445 IMPORTED_LOCATION_<CONFIG> target property. Furthermore, the
4446 MAP_IMPORTED_CONFIG_<CONFIG> target property may be used to map between
4447 a project's configurations and those of an imported target. If none of
4448 these is set then the name of any other configuration listed in the
4449 IMPORTED_CONFIGURATIONS target property may be selected and its
4450 IMPORTED_LOCATION_<CONFIG> value used.
4451 To get the location of an imported target read one of the LOCATION or
4453 LOCATION_<CONFIG> properties.
4454 For platforms with import libraries (e.g. Windows, AIX or macOS) see
4456 also IMPORTED_IMPLIB.
4457 IMPORTED_LOCATION_<CONFIG>
4459 <CONFIG>-specific version of IMPORTED_LOCATION property.
4460 Configuration names correspond to those provided by the project from
4462 which the target is imported.
4463 IMPORTED_NO_SONAME
4465 Specifies that an IMPORTED shared library target has no soname.
4466 Set this property to true for an imported shared library file that has
4468 no soname field. CMake may adjust generated link commands for some
4469 platforms to prevent the linker from using the path to the library in
4470 place of its missing soname. Ignored for non-imported targets.
4471 IMPORTED_NO_SONAME_<CONFIG>
4473 <CONFIG>-specific version of IMPORTED_NO_SONAME property.
4474 Configuration names correspond to those provided by the project from
4476 which the target is imported.
4477 IMPORTED_NO_SYSTEM
4479 New in version 3.23.
4480 Deprecated since version 3.25: IMPORTED_NO_SYSTEM is deprecated. Please
4483 use the following alternatives instead:
4484 • Set SYSTEM to false if you don't want a target's include directories
4486 to be treated as system directories when compiling consumers.
4487 • Set EXPORT_NO_SYSTEM to true if you don't want the include directo‐
4489 ries of the imported target generated by install(EXPORT) and export()
4490 commands to be treated as system directories when compiling con‐
4491 sumers.
4492 Setting IMPORTED_NO_SYSTEM to true on an imported target specifies that
4495 it is not a system target. This has the following effects:
4496 • Entries of INTERFACE_INCLUDE_DIRECTORIES are not treated as system
4498 include directories when compiling consumers (regardless of the value
4499 of the consumed target's SYSTEM property), as they would be by de‐
4500 fault. Entries of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES are not af‐
4501 fected, and will always be treated as system include directories.
4502 • On Apple platforms, when the target is a framework, it will not be
4504 treated as system.
4505 This property can also be enabled on a non-imported target. Doing so
4507 does not affect the build system, but does tell the install(EXPORT) and
4508 export() commands to enable it on the imported targets they generate.
4509 See the NO_SYSTEM_FROM_IMPORTED target property to set this behavior on
4511 the target consuming the include directories rather than the one pro‐
4512 viding them.
4513 IMPORTED_OBJECTS
4515 New in version 3.9.
4516 A semicolon-separated list of absolute paths to the object files on
4519 disk for an imported object library.
4520 Ignored for non-imported targets.
4522 Projects may skip IMPORTED_OBJECTS if the configuration-specific prop‐
4524 erty IMPORTED_OBJECTS_<CONFIG> is set instead, except in situations as
4525 noted in the section below.
4526 Xcode Generator Considerations
4528 New in version 3.20.
4529 For Apple platforms, a project may be built for more than one architec‐
4532 ture. This is controlled by the CMAKE_OSX_ARCHITECTURES variable. For
4533 all but the Xcode generator, CMake invokes compilers once per source
4534 file and passes multiple -arch flags, leading to a single object file
4535 which will be a universal binary. Such object files work well when
4536 listed in the IMPORTED_OBJECTS of a separate CMake build, even for the
4537 Xcode generator. But producing such object files with the Xcode gener‐
4538 ator is more difficult, since it invokes the compiler once per archi‐
4539 tecture for each source file. Unlike the other generators, it does not
4540 generate universal object file binaries.
4541 A further complication with the Xcode generator is that when targeting
4543 device platforms (iOS, tvOS or watchOS), the Xcode generator has the
4544 ability to use either the device or simulator SDK without needing CMake
4545 to be re-run. The SDK can be selected at build time. But since some
4546 architectures can be supported by both the device and the simulator
4547 SDKs (e.g. arm64 with Xcode 12 or later), not all combinations can be
4548 represented in a single universal binary. The only solution in this
4549 case is to have multiple object files.
4550 IMPORTED_OBJECTS doesn't support generator expressions, so every file
4552 it lists needs to be valid for every architecture and SDK. If incorpo‐
4553 rating object files that are not universal binaries, the path and/or
4554 file name of each object file has to somehow encapsulate the different
4555 architectures and SDKs. With the Xcode generator, Xcode variables of
4556 the form $(...) can be used to represent these aspects and Xcode will
4557 substitute the appropriate values at build time. CMake doesn't inter‐
4558 pret these variables and embeds them unchanged in the Xcode project
4559 file. $(CURRENT_ARCH) can be used to represent the architecture, while
4560 $(EFFECTIVE_PLATFORM_NAME) can be used to differentiate between SDKs.
4561 The following shows one example of how these two variables can be used
4563 to refer to an object file whose location depends on both the SDK and
4564 the architecture:
4565 add_library(someObjs OBJECT IMPORTED)
4567 set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
4569 # Quotes are required because of the ()
4570 "/path/to/somewhere/objects$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o"
4571 )
4572 # Example paths:
4574 # /path/to/somewhere/objects-iphoneos/arm64/func.o
4575 # /path/to/somewhere/objects-iphonesimulator/x86_64/func.o
4576 In some cases, you may want to have configuration-specific object files
4578 as well. The $(CONFIGURATION) Xcode variable is often used for this
4579 and can be used in conjunction with the others mentioned above:
4580 add_library(someObjs OBJECT IMPORTED)
4582 set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
4583 "/path/to/somewhere/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o"
4584 )
4585 # Example paths:
4587 # /path/to/somewhere/Release-iphoneos/arm64/func.o
4588 # /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o
4589 When any Xcode variable is used, CMake is not able to fully evaluate
4591 the path(s) at configure time. One consequence of this is that the
4592 configuration-specific IMPORTED_OBJECTS_<CONFIG> properties cannot be
4593 used, since CMake cannot determine whether an object file exists at a
4594 particular <CONFIG> location. The IMPORTED_OBJECTS property must be
4595 used for these situations and the configuration-specific aspects of the
4596 path should be handled by the $(CONFIGURATION) Xcode variable.
4597 IMPORTED_OBJECTS_<CONFIG>
4599 New in version 3.9.
4600 <CONFIG>-specific version of IMPORTED_OBJECTS property.
4603 Configuration names correspond to those provided by the project from
4605 which the target is imported.
4606 Xcode Generator Considerations
4608 Do not use this <CONFIG>-specific property if you need to use Xcode
4609 variables like $(CURRENT_ARCH) or $(EFFECTIVE_PLATFORM_NAME) in the
4610 value. The <CONFIG>-specific properties will be ignored in such cases
4611 because CMake cannot determine whether a file exists at the configura‐
4612 tion-specific path at configuration time. For such cases, use
4613 IMPORTED_OBJECTS instead.
4614 IMPORTED_SONAME
4616 The soname of an IMPORTED target of shared library type.
4617 Set this to the soname embedded in an imported shared library. This is
4619 meaningful only on platforms supporting the feature. Ignored for
4620 non-imported targets.
4621 IMPORTED_SONAME_<CONFIG>
4623 <CONFIG>-specific version of IMPORTED_SONAME property.
4624 Configuration names correspond to those provided by the project from
4626 which the target is imported.
4627 IMPORT_PREFIX
4629 What comes before the import library name.
4630 Similar to the target property PREFIX, but used for import libraries
4632 (typically corresponding to a DLL) instead of regular libraries. A
4633 target property that can be set to override the prefix (such as lib) on
4634 an import library name.
4635 IMPORT_SUFFIX
4637 What comes after the import library name.
4638 Similar to the target property SUFFIX, but used for import libraries
4640 (typically corresponding to a DLL) instead of regular libraries. A
4641 target property that can be set to override the suffix (such as .lib)
4642 on an import library name.
4643 INCLUDE_DIRECTORIES
4645 List of preprocessor include file search directories.
4646 This property specifies the list of directories given so far to the
4648 target_include_directories() command. In addition to accepting values
4649 from that command, values may be set directly on any target using the
4650 set_property() command. A target gets its initial value for this prop‐
4651 erty from the value of the INCLUDE_DIRECTORIES directory property.
4652 Both directory and target property values are adjusted by calls to the
4653 include_directories() command.
4654 The value of this property is used by the generators to set the include
4656 paths for the compiler.
4657 Relative paths should not be added to this property directly. Use one
4659 of the commands above instead to handle relative paths.
4660 Contents of INCLUDE_DIRECTORIES may use cmake-generator-expressions(7)
4662 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4663 for available expressions. See the cmake-buildsystem(7) manual for
4664 more on defining buildsystem properties.
4665 INSTALL_NAME_DIR
4667 Directory name for installed targets on Apple platforms.
4668 INSTALL_NAME_DIR is a string specifying the directory portion of the
4670 "install_name" field of shared libraries on Apple platforms for in‐
4671 stalled targets. When not set, the default directory used is deter‐
4672 mined by MACOSX_RPATH. If the BUILD_WITH_INSTALL_NAME_DIR property is
4673 set, this will be used already in the build tree. Policies CMP0068 and
4674 CMP0042 are also relevant.
4675 This property is initialized by the value of the variable
4677 CMAKE_INSTALL_NAME_DIR if it is set when a target is created.
4678 This property supports generator expressions. In particular, the
4680 $<INSTALL_PREFIX> generator expression can be used to set the directory
4681 relative to the install-time prefix.
4682 On platforms that support runtime paths (RPATH), refer to the
4684 INSTALL_RPATH target property. Under Windows, the TARGET_RUNTIME_DLLS
4685 generator expression is related.
4686 INSTALL_REMOVE_ENVIRONMENT_RPATH
4688 New in version 3.16.
4689 Controls whether toolchain-defined rpaths should be removed during in‐
4692 stallation.
4693 When a target is being installed, CMake may need to rewrite its rpath
4695 information. This occurs when the install rpath (as specified by the
4696 INSTALL_RPATH target property) has different contents to the rpath that
4697 the target was built with. Some toolchains insert their own rpath con‐
4698 tents into the binary as part of the build. By default, CMake will
4699 preserve those extra inserted contents in the install rpath. For those
4700 scenarios where such toolchain-inserted entries need to be discarded
4701 during install, set the INSTALL_REMOVE_ENVIRONMENT_RPATH target prop‐
4702 erty to true.
4703 This property is initialized by the value of
4705 CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH when the target is created.
4706 INSTALL_RPATH
4708 The rpath to use for installed targets.
4709 By default, the install rpath is empty. It can be set using this prop‐
4711 erty, which is a semicolon-separated list specifying the rpath to use
4712 in installed targets (for platforms that support it). This property is
4713 initialized by the value of the variable CMAKE_INSTALL_RPATH if it is
4714 set when a target is created. Beside setting the install rpath manu‐
4715 ally, using the INSTALL_RPATH_USE_LINK_PATH target property it can also
4716 be generated automatically by CMake.
4717 Normally CMake uses the build tree for the RPATH when building executa‐
4719 bles etc on systems that use RPATH, see the BUILD_RPATH target prop‐
4720 erty. When the software is installed the targets are edited (or re‐
4721 linked) by CMake (see CMAKE_NO_BUILTIN_CHRPATH) to have the install
4722 RPATH. This editing during installation can be avoided via the
4723 BUILD_WITH_INSTALL_RPATH target property.
4724 For handling toolchain-dependent RPATH entries the
4726 INSTALL_REMOVE_ENVIRONMENT_RPATH can be used. Runtime paths can be
4727 disabled completely via the CMAKE_SKIP_RPATH variable.
4728 Because the rpath may contain ${ORIGIN}, which coincides with CMake
4730 syntax, the contents of INSTALL_RPATH are properly escaped in the
4731 cmake_install.cmake script (see policy CMP0095.)
4732 This property supports generator expressions.
4734 On Apple platforms, refer to the INSTALL_NAME_DIR target property. Un‐
4736 der Windows, the TARGET_RUNTIME_DLLS generator expression is related.
4737 INSTALL_RPATH_USE_LINK_PATH
4739 Add paths to linker search and installed rpath.
4740 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to TRUE will ap‐
4742 pend to the runtime search path (rpath) of installed binaries any di‐
4743 rectories outside the project that are in the linker search path or
4744 contain linked library files. The directories are appended after the
4745 value of the INSTALL_RPATH target property.
4746 This property is initialized by the value of the variable
4748 CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a target is cre‐
4749 ated.
4750 INTERFACE_AUTOMOC_MACRO_NAMES
4752 New in version 3.27.
4753 A semicolon-separated list of macro names for AUTOMOC to be propagated
4756 to consumers.
4757 When a target with AUTOMOC enabled links to a library that sets INTER‐
4759 FACE_AUTOMOC_MACRO_NAMES, the target inherits the listed macro names
4760 and merges them with those specified in its own AUTOMOC_MACRO_NAMES
4761 property. The target will then automatically generate MOC files for
4762 source files that contain the inherited macro names too, not just the
4763 macro names specified in its own AUTOMOC_MACRO_NAMES property.
4764 By default INTERFACE_AUTOMOC_MACRO_NAMES is empty.
4766 See the cmake-qt(7) manual for more information on using CMake with Qt.
4768 Example 1
4770 In this example, myapp inherits the macro names STATIC_LIB_1 and
4771 STATIC_LIB_2 from static_lib. The moc tool will then automatically be
4772 run on any of the myapp sources which contain STATIC_LIB_1 or
4773 STATIC_LIB_2.
4774 set(AUTOMOC ON)
4776 add_executable(myapp main.cpp)
4777 target_link_libraries(myapp PRIVATE static_lib)
4778 add_library(static_lib STATIC static.cpp)
4780 set_property(TARGET static_lib PROPERTY
4781 INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LIB_1;STATIC_LIB_2"
4782 )
4783 Example 2
4785 In this example, the INTERFACE_AUTOMOC_MACRO_NAMES target property of
4786 the various *_deep_lib libraries will propagate to shared_lib,
4787 static_lib and interface_lib. Because the linking relationships are
4788 specified as PUBLIC and INTERFACE, those macro names will also further
4789 propagate transitively up to app.
4790 set(AUTOMOC ON)
4792 add_library(shared_deep_lib SHARED deep_lib.cpp)
4794 add_library(static_deep_lib STATIC deep_lib.cpp)
4795 add_library(interface_deep_lib INTERFACE)
4796 set_property(TARGET shared_deep_lib PROPERTY
4798 INTERFACE_AUTOMOC_MACRO_NAMES "SHARED_LINK_LIB"
4799 )
4800 set_property(TARGET static_deep_lib PROPERTY
4801 INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LINK_LIB"
4802 )
4803 set_property(TARGET interface_deep_lib PROPERTY
4804 INTERFACE_AUTOMOC_MACRO_NAMES "INTERFACE_LINK_LIB"
4805 )
4806 add_library(shared_lib SHARED lib.cpp)
4808 add_library(static_lib STATIC lib.cpp)
4809 add_library(interface_lib INTERFACE)
4810 # PUBLIC and INTERFACE here ensure the macro names propagate to any
4812 # consumers of shared_lib, static_lib or interface_lib too
4813 target_link_libraries(shared_lib PUBLIC shared_deep_lib)
4814 target_link_libraries(static_lib PUBLIC static_deep_lib)
4815 target_link_libraries(interface_lib INTERFACE interface_deep_lib)
4816 # This consumer will receive all three of the above custom macro names as
4818 # transitive usage requirements
4819 add_executable(app main.cpp)
4820 target_link_libraries(app PRIVATE shared_lib static_lib interface_lib)
4821 In the above:
4823 • shared_lib sources will be processed by moc if they contain
4825 SHARED_LINK_LIB.
4826 • static_lib sources will be processed by moc if they contain
4828 STATIC_LINK_LIB.
4829 • app sources will be processed by moc if they contain SHARED_LINK_LIB,
4831 STATIC_LINK_LIB or INTERFACE_LINK_LIB.
4832 INTERFACE_AUTOUIC_OPTIONS
4834 List of interface options to pass to uic.
4835 Targets may populate this property to publish the options required to
4837 use when invoking uic. Consuming targets can add entries to their own
4838 AUTOUIC_OPTIONS property such as $<TARGET_PROPERTY:foo,INTER‐
4839 FACE_AUTOUIC_OPTIONS> to use the uic options specified in the interface
4840 of foo. This is done automatically by the target_link_libraries() com‐
4841 mand.
4842 This property supports generator expressions. See the
4844 cmake-generator-expressions(7) manual for available expressions.
4845 INTERFACE_COMPILE_DEFINITIONS
4847 List of public compile definitions requirements for a library.
4848 Targets may populate this property to publish the compile definitions
4850 required to compile against the headers for the target. The
4851 target_compile_definitions() command populates this property with val‐
4852 ues given to the PUBLIC and INTERFACE keywords. Projects may also get
4853 and set the property directly.
4854 When target dependencies are specified using target_link_libraries(),
4856 CMake will read this property from all target dependencies to determine
4857 the build properties of the consumer.
4858 Contents of INTERFACE_COMPILE_DEFINITIONS may use "generator expres‐
4860 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
4861 manual for available expressions. See the cmake-buildsystem(7) -manual
4862 for more on defining buildsystem properties.
4863 INTERFACE_COMPILE_FEATURES
4865 New in version 3.1.
4866 List of public compile features requirements for a library.
4869 Targets may populate this property to publish the compile features re‐
4871 quired to compile against the headers for the target. The
4872 target_compile_features() command populates this property with values
4873 given to the PUBLIC and INTERFACE keywords. Projects may also get and
4874 set the property directly.
4875 When target dependencies are specified using target_link_libraries(),
4877 CMake will read this property from all target dependencies to determine
4878 the build properties of the consumer.
4879 Contents of INTERFACE_COMPILE_FEATURES may use "generator expressions"
4881 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4882 for available expressions. See the cmake-buildsystem(7) -manual for
4883 more on defining buildsystem properties.
4884 See the cmake-compile-features(7) manual for information on compile
4886 features and a list of supported compilers.
4887 INTERFACE_COMPILE_OPTIONS
4889 List of public compile options requirements for a library.
4890 Targets may populate this property to publish the compile options re‐
4892 quired to compile against the headers for the target. The
4893 target_compile_options() command populates this property with values
4894 given to the PUBLIC and INTERFACE keywords. Projects may also get and
4895 set the property directly.
4896 When target dependencies are specified using target_link_libraries(),
4898 CMake will read this property from all target dependencies to determine
4899 the build properties of the consumer.
4900 Contents of INTERFACE_COMPILE_OPTIONS may use "generator expressions"
4902 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4903 for available expressions. See the cmake-buildsystem(7) -manual for
4904 more on defining buildsystem properties.
4905 INTERFACE_CXX_MODULE_SETS
4907 New in version 3.25.
4908 NOTE:
4911 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
4912 Read-only list of the target's PUBLIC C++ module sets (i.e. all file
4914 sets with the type CXX_MODULES). Files listed in these C++ module sets
4915 can be installed with install(TARGETS) and exported with
4916 install(EXPORT) and export().
4917 C++ module sets may be defined using the target_sources() command
4919 FILE_SET option with type CXX_MODULES.
4920 See also CXX_MODULE_SETS.
4922 INTERFACE_HEADER_SETS
4924 New in version 3.23.
4925 Read-only list of the target's INTERFACE and PUBLIC header sets (i.e.
4928 all file sets with the type HEADERS). Files listed in these header sets
4929 can be installed with install(TARGETS) and exported with
4930 install(EXPORT) and export().
4931 Header sets may be defined using the target_sources() command FILE_SET
4933 option with type HEADERS.
4934 See also HEADER_SETS.
4936 INTERFACE_HEADER_SETS_TO_VERIFY
4938 New in version 3.24.
4939 Used to specify which PUBLIC and INTERFACE header sets of a target
4942 should be verified.
4943 This property contains a semicolon-separated list of header sets which
4945 should be verified if VERIFY_INTERFACE_HEADER_SETS is set to TRUE. If
4946 the list is empty, all PUBLIC and INTERFACE header sets are verified.
4947 (If the project does not want to verify any header sets on the target,
4948 simply set VERIFY_INTERFACE_HEADER_SETS to FALSE.)
4949 INTERFACE_INCLUDE_DIRECTORIES
4951 List of public include directories requirements for a library.
4952 Targets may populate this property to publish the include directories
4954 required to compile against the headers for the target. The
4955 target_include_directories() command populates this property with val‐
4956 ues given to the PUBLIC and INTERFACE keywords. Projects may also get
4957 and set the property directly.
4958 When target dependencies are specified using target_link_libraries(),
4960 CMake will read this property from all target dependencies to determine
4961 the build properties of the consumer.
4962 Contents of INTERFACE_INCLUDE_DIRECTORIES may use "generator expres‐
4964 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
4965 manual for available expressions. See the cmake-buildsystem(7) -manual
4966 for more on defining buildsystem properties.
4967 Include directories usage requirements commonly differ between the
4969 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
4970 TERFACE generator expressions can be used to describe separate usage
4971 requirements based on the usage location. Relative paths are allowed
4972 within the INSTALL_INTERFACE expression and are interpreted relative to
4973 the installation prefix. For example:
4974 target_include_directories(mylib INTERFACE
4976 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
4977 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
4978 )
4979 Creating Relocatable Packages
4981 Note that it is not advisable to populate the INSTALL_INTERFACE of the
4982 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
4983 include directories of dependencies. That would hard-code into in‐
4984 stalled packages the include directory paths for dependencies as found
4985 on the machine the package was made on.
4986 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
4988 suitable for specifying the required include directories for headers
4989 provided with the target itself, not those provided by the transitive
4990 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
4991 Those dependencies should themselves be targets that specify their own
4992 header locations in INTERFACE_INCLUDE_DIRECTORIES.
4993 See the Creating Relocatable Packages section of the cmake-packages(7)
4995 manual for discussion of additional care that must be taken when speci‐
4996 fying usage requirements while creating packages for redistribution.
4997 INTERFACE_LINK_DEPENDS
4999 New in version 3.13.
5000 Additional public interface files on which a target binary depends for
5003 linking.
5004 This property is supported only by Ninja and Makefile Generators. It
5006 is intended to specify dependencies on "linker scripts" for custom
5007 Makefile link rules.
5008 When target dependencies are specified using target_link_libraries(),
5010 CMake will read this property from all target dependencies to determine
5011 the build properties of the consumer.
5012 Contents of INTERFACE_LINK_DEPENDS may use "generator expressions" with
5014 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5015 available expressions. See the cmake-buildsystem(7) -manual for more
5016 on defining buildsystem properties.
5017 Link dependency files usage requirements commonly differ between the
5019 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
5020 TERFACE generator expressions can be used to describe separate usage
5021 requirements based on the usage location. Relative paths are allowed
5022 within the INSTALL_INTERFACE expression and are interpreted relative to
5023 the installation prefix. For example:
5024 set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS
5026 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript>
5027 $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript
5028 )
5029 INTERFACE_LINK_DIRECTORIES
5031 New in version 3.13.
5032 List of public link directories requirements for a library.
5035 Targets may populate this property to publish the link directories re‐
5037 quired to compile against the headers for the target. The
5038 target_link_directories() command populates this property with values
5039 given to the PUBLIC and INTERFACE keywords. Projects may also get and
5040 set the property directly.
5041 When target dependencies are specified using target_link_libraries(),
5043 CMake will read this property from all target dependencies to determine
5044 the build properties of the consumer.
5045 Contents of INTERFACE_LINK_DIRECTORIES may use "generator expressions"
5047 with the syntax $<...>. See the cmake-generator-expressions(7) manual
5048 for available expressions. See the cmake-buildsystem(7) -manual for
5049 more on defining buildsystem properties.
5050 INTERFACE_LINK_LIBRARIES
5052 List public interface libraries for a library.
5053 This property contains the list of transitive link dependencies. When
5055 the target is linked into another target using the
5056 target_link_libraries() command, the libraries listed (and recursively
5057 their link interface libraries) will be provided to the other target
5058 also. This property is overridden by the LINK_INTERFACE_LIBRARIES or
5059 LINK_INTERFACE_LIBRARIES_<CONFIG> property if policy CMP0022 is OLD or
5060 unset.
5061 The value of this property is used by the generators when constructing
5063 the link rule for a dependent target. A dependent target's direct link
5064 dependencies, specified by its LINK_LIBRARIES target property, are
5065 linked first, followed by indirect dependencies from the transitive
5066 closure of the direct dependencies' INTERFACE_LINK_LIBRARIES proper‐
5067 ties. See policy CMP0022.
5068 Contents of INTERFACE_LINK_LIBRARIES may use "generator expressions"
5070 with the syntax $<...>. See the cmake-generator-expressions(7) manual
5071 for available expressions. See the cmake-buildsystem(7) manual for
5072 more on defining buildsystem properties.
5073 NOTE:
5075 A call to target_link_libraries(<target> ...) may update this prop‐
5076 erty on <target>. If <target> was not created in the same directory
5077 as the call then target_link_libraries() will wrap each entry with
5078 the form ::@(directory-id);...;::@, where the ::@ is literal and the
5079 (directory-id) is unspecified. This tells the generators that the
5080 named libraries must be looked up in the scope of the caller rather
5081 than in the scope in which the <target> was created. Valid direc‐
5082 tory ids are stripped on export by the install(EXPORT) and export()
5083 commands.
5084 INTERFACE_LINK_LIBRARIES adds transitive link dependencies for a tar‐
5086 get's dependents. In advanced use cases, one may update the direct
5087 link dependencies of a target's dependents by using the
5088 INTERFACE_LINK_LIBRARIES_DIRECT and
5089 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties.
5090 Creating Relocatable Packages
5092 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
5093 of a target with absolute paths to dependencies. That would hard-code
5094 into installed packages the library file paths for dependencies as
5095 found on the machine the package was made on.
5096 See the Creating Relocatable Packages section of the cmake-packages(7)
5098 manual for discussion of additional care that must be taken when speci‐
5099 fying usage requirements while creating packages for redistribution.
5100 INTERFACE_LINK_LIBRARIES_DIRECT
5102 New in version 3.24.
5103 List of libraries that consumers of this library should treat as direct
5106 link dependencies.
5107 This target property may be set to include items in a dependent tar‐
5109 get's final set of direct link dependencies. See the
5110 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property to exclude
5111 items.
5112 The initial set of a dependent target's direct link dependencies is
5114 specified by its LINK_LIBRARIES target property. Indirect link depen‐
5115 dencies are specified by the transitive closure of the direct link de‐
5116 pendencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency
5117 may specify additional direct link dependencies using the INTER‐
5118 FACE_LINK_LIBRARIES_DIRECT target property. The set of direct link de‐
5119 pendencies is then filtered to exclude items named by any dependency's
5120 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.
5121 The value of INTERFACE_LINK_LIBRARIES_DIRECT may use generator expres‐
5123 sions.
5124 NOTE:
5126 The INTERFACE_LINK_LIBRARIES_DIRECT target property is intended for
5127 advanced use cases such as injection of static plugins into a con‐
5128 suming executable. It should not be used as a substitute for orga‐
5129 nizing normal calls to target_link_libraries().
5130 Direct Link Dependencies as Usage Requirements
5132 The INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DI‐
5133 RECT_EXCLUDE target properties are usage requirements. Their effects
5134 propagate to dependent targets transitively, and can therefore affect
5135 the direct link dependencies of every target in a chain of dependent
5136 libraries. Whenever some library target X links to another library
5137 target Y whose direct or transitive usage requirements contain INTER‐
5138 FACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE,
5139 the properties may affect X's list of direct link dependencies:
5140 • If X is a shared library or executable, its dependencies are linked.
5142 They also affect the usage requirements with which X's sources are
5143 compiled.
5144 • If X is a static library or object library, it does not actually
5146 link, so its dependencies at most affect the usage requirements with
5147 which X's sources are compiled.
5148 The properties may also affect the list of direct link dependencies on
5150 X's dependents:
5151 • If X links Y publicly:
5153 target_link_libraries(X PUBLIC Y)
5155 then Y is placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage re‐
5157 quirements, including INTERFACE_LINK_LIBRARIES_DIRECT, INTER‐
5158 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the usage requirements de‐
5159 clared by the direct link dependencies they add, are propagated to
5160 X's dependents.
5161 • If X is a static library or object library, and links Y privately:
5163 target_link_libraries(X PRIVATE Y)
5165 then $<LINK_ONLY:Y> is placed in X's INTERFACE_LINK_LIBRARIES. Y's
5167 linking requirements, including INTERFACE_LINK_LIBRARIES_DIRECT, IN‐
5168 TERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the transitive link depen‐
5169 dencies declared by the direct link dependencies they add, are propa‐
5170 gated to X's dependents. However, Y's non-linking usage requirements
5171 are blocked by the LINK_ONLY generator expression, and are not propa‐
5172 gated to X's dependents.
5173 • If X is a shared library or executable, and links Y privately:
5175 target_link_libraries(X PRIVATE Y)
5177 then Y is not placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage
5179 requirements, even INTERFACE_LINK_LIBRARIES_DIRECT and INTER‐
5180 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE, are not propagated to X's depen‐
5181 dents.
5182 • In all cases, the content of X's INTERFACE_LINK_LIBRARIES is not af‐
5184 fected by Y's INTERFACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LI‐
5185 BRARIES_DIRECT_EXCLUDE.
5186 One may limit the effects of INTERFACE_LINK_LIBRARIES_DIRECT and INTER‐
5188 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE to a subset of dependent targets by
5189 using the TARGET_PROPERTY generator expression. For example, to limit
5190 the effects to executable targets, use an entry of the form:
5191 "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
5193 Similarly, to limit the effects to specific targets, use an entry of
5195 the form:
5196 "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
5198 This entry will only affect targets that set their USE_IT target prop‐
5200 erty to a true value.
5201 Direct Link Dependency Ordering
5203 The list of direct link dependencies for a target is computed from an
5204 initial ordered list in its LINK_LIBRARIES target property. For each
5205 item, additional direct link dependencies are discovered from its di‐
5206 rect and transitive INTERFACE_LINK_LIBRARIES_DIRECT usage requirements.
5207 Each discovered item is injected before the item that specified it.
5208 However, a discovered item is added at most once, and only if it did
5209 not appear anywhere in the initial list. This gives LINK_LIBRARIES
5210 control over ordering of those direct link dependencies that it explic‐
5211 itly specifies.
5212 Once all direct link dependencies have been collected, items named by
5214 all of their INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE usage requirements
5215 are removed from the final list. This does not affect the order of the
5216 items that remain.
5217 Example: Static Plugins
5219 Consider a static library Foo that provides a static plugin FooPlugin
5220 to consuming application executables, where the implementation of the
5221 plugin depends on Foo and other things. In this case, the application
5222 should link to FooPlugin directly, before Foo. However, the applica‐
5223 tion author only knows about Foo. We can express this as follows:
5224 # Core library used by other components.
5226 add_library(Core STATIC core.cpp)
5227 # Foo is a static library for use by applications.
5229 # Implementation of Foo depends on Core.
5230 add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
5231 target_link_libraries(Foo PRIVATE Core)
5232 # Extra parts of Foo for use by its static plugins.
5234 # Implementation of Foo's extra parts depends on both Core and Foo.
5235 add_library(FooExtras STATIC foo_extras.cpp)
5236 target_link_libraries(FooExtras PRIVATE Core Foo)
5237 # The Foo library has an associated static plugin
5239 # that should be linked into the final executable.
5240 # Implementation of the plugin depends on Core, Foo, and FooExtras.
5241 add_library(FooPlugin STATIC foo_plugin.cpp)
5242 target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
5243 # An app that links Foo should link Foo's plugin directly.
5245 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
5246 # An app does not need to link Foo directly because the plugin links it.
5248 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
5249 An application app only needs to specify that it links to Foo:
5251 add_executable(app main.cpp)
5253 target_link_libraries(app PRIVATE Foo)
5254 The INTERFACE_LINK_LIBRARIES_DIRECT target property on Foo tells CMake
5256 to pretend that app also links directly to FooPlugin. The INTER‐
5257 FACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property on Foo tells CMake
5258 to pretend that app did not link directly to Foo. Instead, Foo will be
5259 linked as a dependency of FooPlugin. The final link line for app will
5260 link the libraries in the following order:
5261 • FooPlugin as a direct link dependency of app (via Foo's usage re‐
5263 quirements).
5264 • FooExtras as a dependency of FooPlugin.
5266 • Foo as a dependency of FooPlugin and FooExtras.
5268 • Core as a dependency of FooPlugin, FooExtras, and Foo.
5270 Note that without the INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target
5272 property, Foo would be linked twice: once as a direct dependency of
5273 app, and once as a dependency of FooPlugin.
5274 Example: Opt-In Static Plugins
5276 In the above Example: Static Plugins, the app executable specifies that
5277 it links directly to Foo. In a real application, there might be an in‐
5278 termediate library:
5279 add_library(app_impl STATIC app_impl.cpp)
5281 target_link_libraries(app_impl PRIVATE Foo)
5282 add_executable(app main.cpp)
5284 target_link_libraries(app PRIVATE app_impl)
5285 In this case we do not want Foo's INTERFACE_LINK_LIBRARIES_DIRECT and
5287 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties to affect the
5288 direct dependencies of app_impl. To avoid this, we can revise the
5289 property values to make their effects opt-in:
5290 # An app that links Foo should link Foo's plugin directly.
5292 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
5293 "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
5294 )
5295 # An app does not need to link Foo directly because the plugin links it.
5297 set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
5298 "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
5299 )
5300 Now, the app executable can opt-in to get Foo's plugin(s):
5302 set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
5304 The final link line for app will now link the libraries in the follow‐
5306 ing order:
5307 • FooPlugin as a direct link dependency of app (via Foo's usage re‐
5309 quirements).
5310 • app_impl as a direct link dependency of app.
5312 • FooExtras as a dependency of FooPlugin.
5314 • Foo as a dependency of app_impl, FooPlugin, and FooExtras.
5316 • Core as a dependency of FooPlugin, FooExtras, and Foo.
5318 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
5320 New in version 3.24.
5321 List of libraries that consumers of this library should not treat as
5324 direct link dependencies.
5325 This target property may be set to exclude items from a dependent tar‐
5327 get's final set of direct link dependencies. This property is pro‐
5328 cessed after the INTERFACE_LINK_LIBRARIES_DIRECT target property of all
5329 other dependencies of the dependent target, so exclusion from direct
5330 link dependence takes priority over inclusion.
5331 The initial set of a dependent target's direct link dependencies is
5333 specified by its LINK_LIBRARIES target property. Indirect link depen‐
5334 dencies are specified by the transitive closure of the direct link de‐
5335 pendencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency
5336 may specify additional direct link dependencies using the
5337 INTERFACE_LINK_LIBRARIES_DIRECT target property. The set of direct
5338 link dependencies is then filtered to exclude items named by any depen‐
5339 dency's INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.
5340 Excluding an item from a dependent target's direct link dependencies
5342 does not mean the dependent target won't link the item. The item may
5343 still be linked as an indirect link dependency via the
5344 INTERFACE_LINK_LIBRARIES property on other dependencies.
5345 The value of INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE may use generator
5347 expressions.
5348 NOTE:
5350 The INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property is in‐
5351 tended for advanced use cases such as injection of static plugins
5352 into a consuming executable. It should not be used as a substitute
5353 for organizing normal calls to target_link_libraries().
5354 See the INTERFACE_LINK_LIBRARIES_DIRECT target property documentation
5356 for more details and examples.
5357 INTERFACE_LINK_OPTIONS
5359 New in version 3.13.
5360 List of public link options requirements for a library.
5363 Targets may populate this property to publish the link options required
5365 to compile against the headers for the target. The
5366 target_link_options() command populates this property with values given
5367 to the PUBLIC and INTERFACE keywords. Projects may also get and set
5368 the property directly.
5369 When target dependencies are specified using target_link_libraries(),
5371 CMake will read this property from all target dependencies to determine
5372 the build properties of the consumer.
5373 Contents of INTERFACE_LINK_OPTIONS may use "generator expressions" with
5375 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5376 available expressions. See the cmake-buildsystem(7) -manual for more
5377 on defining buildsystem properties.
5378 INTERFACE_POSITION_INDEPENDENT_CODE
5380 Whether consumers need to create a position-independent target
5381 The INTERFACE_POSITION_INDEPENDENT_CODE property informs consumers of
5383 this target whether they must set their POSITION_INDEPENDENT_CODE prop‐
5384 erty to ON. If this property is set to ON, then the
5385 POSITION_INDEPENDENT_CODE property on all consumers will be set to ON.
5386 Similarly, if this property is set to OFF, then the
5387 POSITION_INDEPENDENT_CODE property on all consumers will be set to OFF.
5388 If this property is undefined, then consumers will determine their
5389 POSITION_INDEPENDENT_CODE property by other means. Consumers must en‐
5390 sure that the targets that they link to have a consistent requirement
5391 for their INTERFACE_POSITION_INDEPENDENT_CODE property.
5392 Contents of INTERFACE_POSITION_INDEPENDENT_CODE may use "generator ex‐
5394 pressions" with the syntax $<...>. See the
5395 cmake-generator-expressions(7) manual for available expressions. See
5396 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
5397 erties.
5398 INTERFACE_PRECOMPILE_HEADERS
5400 New in version 3.16.
5401 List of interface header files to precompile into consuming targets.
5404 Targets may populate this property to publish the header files for con‐
5406 suming targets to precompile. The target_precompile_headers() command
5407 populates this property with values given to the PUBLIC and INTERFACE
5408 keywords. Projects may also get and set the property directly. See
5409 the discussion in target_precompile_headers() for guidance on appropri‐
5410 ate use of this property for installed or exported targets.
5411 Contents of INTERFACE_PRECOMPILE_HEADERS may use "generator expres‐
5413 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
5414 manual for available expressions. See the cmake-buildsystem(7) manual
5415 for more on defining buildsystem properties.
5416 INTERFACE_SOURCES
5418 New in version 3.1.
5419 List of interface sources to compile into consuming targets.
5422 Targets may populate this property to publish the sources for consuming
5424 targets to compile. The target_sources() command populates this prop‐
5425 erty with values given to the PUBLIC and INTERFACE keywords. Projects
5426 may also get and set the property directly.
5427 When target dependencies are specified using target_link_libraries(),
5429 CMake will read this property from all target dependencies to determine
5430 the sources of the consumer.
5431 Contents of INTERFACE_SOURCES may use "generator expressions" with the
5433 syntax $<...>. See the cmake-generator-expressions(7) manual for
5434 available expressions. See the cmake-buildsystem(7) manual for more on
5435 defining buildsystem properties.
5436 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
5438 List of public system include directories for a library.
5439 Targets may populate this property to publish the include directories
5441 which contain system headers, and therefore should not result in com‐
5442 piler warnings. Additionally, system include directories are searched
5443 after normal include directories regardless of the order specified.
5444 When the target_include_directories() command is given the SYSTEM key‐
5446 word, it populates this property with values provided after the PUBLIC
5447 and INTERFACE keywords.
5448 Projects may also get and set the property directly, but must be aware
5450 that adding directories to this property does not make those directo‐
5451 ries used during compilation. Adding directories to this property
5452 marks directories as system directories which otherwise would be used
5453 in a non-system manner. This can appear similar to duplication, so
5454 prefer the high-level target_include_directories() command with the
5455 SYSTEM keyword and avoid setting the property directly.
5456 When target dependencies are specified using target_link_libraries(),
5458 CMake will read this property from all target dependencies to mark the
5459 same include directories as containing system headers.
5460 Contents of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES may use "generator ex‐
5462 pressions" with the syntax $<...>. See the
5463 cmake-generator-expressions(7) manual for available expressions. See
5464 the cmake-buildsystem(7) manual for more on defining buildsystem prop‐
5465 erties.
5466 INTERPROCEDURAL_OPTIMIZATION
5468 Enable interprocedural optimization for a target.
5469 If set to true, enables interprocedural optimizations if they are known
5471 to be supported by the compiler. Depending on value of policy CMP0069,
5472 the error will be reported or ignored, if interprocedural optimization
5473 is enabled but not supported.
5474 This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZATION
5476 variable if it is set when a target is created.
5477 There is also the per-configuration
5479 INTERPROCEDURAL_OPTIMIZATION_<CONFIG> target property, which overrides
5480 INTERPROCEDURAL_OPTIMIZATION if it is set.
5481 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5483 Per-configuration interprocedural optimization for a target.
5484 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
5486 If set, this property overrides the generic property for the named con‐
5487 figuration.
5488 This property is initialized by the
5490 CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> variable if it is set when
5491 a target is created.
5492 IOS_INSTALL_COMBINED
5494 New in version 3.5.
5495 Build a combined (device and simulator) target when installing.
5498 When this property is set to set to false (which is the default) then
5500 it will either be built with the device SDK or the simulator SDK de‐
5501 pending on the SDK set. But if this property is set to true then the
5502 target will at install time also be built for the corresponding SDK and
5503 combined into one library.
5504 NOTE:
5506 If a selected architecture is available for both: device SDK and
5507 simulator SDK it will be built for the SDK selected by
5508 CMAKE_OSX_SYSROOT and removed from the corresponding SDK.
5509 This feature requires at least Xcode version 6.
5511 ISPC_HEADER_DIRECTORY
5513 New in version 3.19.
5514 Specify relative output directory for ISPC headers provided by the tar‐
5517 get.
5518 If the target contains ISPC source files, this specifies the directory
5520 in which the generated headers will be placed. Relative paths are
5521 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR. When
5522 this property is not set, the headers will be placed a generator de‐
5523 fined build directory. If the variable CMAKE_ISPC_HEADER_DIRECTORY is
5524 set when a target is created its value is used to initialize this prop‐
5525 erty.
5526 ISPC_HEADER_SUFFIX
5528 New in version 3.19.2.
5529 Specify output suffix to be used for ISPC generated headers provided by
5532 the target.
5533 This property is initialized by the value of the
5535 CMAKE_ISPC_HEADER_SUFFIX variable if it is set when a target is cre‐
5536 ated.
5537 If the target contains ISPC source files, this specifies the header
5539 suffix to be used for the generated headers.
5540 The default value is _ispc.h.
5542 ISPC_INSTRUCTION_SETS
5544 New in version 3.19.
5545 List of instruction set architectures to generate code for.
5548 This property is initialized by the value of the
5550 CMAKE_ISPC_INSTRUCTION_SETS variable if it is set when a target is cre‐
5551 ated.
5552 The ISPC_INSTRUCTION_SETS target property must be used when generating
5554 for multiple instruction sets so that CMake can track what object files
5555 will be generated.
5556 Examples
5558 set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835)
5559 Generates code for avx2 and avx512skx target architectures.
5561 JOB_POOL_COMPILE
5563 Ninja only: Pool used for compiling.
5564 The number of parallel compile processes could be limited by defining
5566 pools with the global JOB_POOLS property and then specifying here the
5567 pool name.
5568 For instance:
5570 set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs)
5572 This property is initialized by the value of CMAKE_JOB_POOL_COMPILE.
5574 JOB_POOL_LINK
5576 Ninja only: Pool used for linking.
5577 The number of parallel link processes could be limited by defining
5579 pools with the global JOB_POOLS property and then specifying here the
5580 pool name.
5581 For instance:
5583 set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs)
5585 This property is initialized by the value of CMAKE_JOB_POOL_LINK.
5587 JOB_POOL_PRECOMPILE_HEADER
5589 New in version 3.17.
5590 Ninja only: Pool used for generating pre-compiled headers.
5593 The number of parallel compile processes could be limited by defining
5595 pools with the global JOB_POOLS property and then specifying here the
5596 pool name.
5597 For instance:
5599 set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs)
5601 This property is initialized by the value of
5603 CMAKE_JOB_POOL_PRECOMPILE_HEADER.
5604 If neither JOB_POOL_PRECOMPILE_HEADER nor
5606 CMAKE_JOB_POOL_PRECOMPILE_HEADER are set then JOB_POOL_COMPILE will be
5607 used for this task.
5608 LABELS
5610 Specify a list of text labels associated with a target.
5611 Target label semantics are currently unspecified.
5613 <LANG>_CLANG_TIDY
5615 New in version 3.6.
5616 This property is implemented only when <LANG> is C, CXX, OBJC or OB‐
5619 JCXX.
5620 Specify a semicolon-separated list containing a command line for the
5622 clang-tidy tool. The Makefile Generators and the Ninja generator will
5623 run this tool along with the compiler and report a warning if the tool
5624 reports any problems.
5625 The specified clang-tidy command line will be invoked with additional
5627 arguments specifying the source file and, after --, the full compiler
5628 command line.
5629 Changed in version 3.25: If the specified clang-tidy command line in‐
5631 cludes the -p option, it will be invoked without -- and the full com‐
5632 piler command line. clang-tidy will look up the source file in the
5633 specified compiler commands database.
5634 This property is initialized by the value of the
5637 CMAKE_<LANG>_CLANG_TIDY variable if it is set when a target is created.
5638 New in version 3.27: This property supports generator expressions.
5640 New in version 3.27: SKIP_LINTING can be set on individual source files
5643 to exclude them from the linting tools defined by <LANG>_CPPLINT,
5644 <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and <LANG>_INCLUDE_WHAT_YOU_USE.
5645 When SKIP_LINTING is set to true on a source file, those tools will not
5646 be run on that specific file.
5647 <LANG>_CLANG_TIDY_EXPORT_FIXES_DIR
5650 New in version 3.26.
5651 This property is implemented only when <LANG> is C, CXX, OBJC or OB‐
5654 JCXX, and only has an effect when <LANG>_CLANG_TIDY is set.
5655 Specify a directory for the clang-tidy tool to put .yaml files contain‐
5657 ing its suggested changes in. This can be used for automated mass
5658 refactoring by clang-tidy. Each object file that gets compiled will
5659 have a corresponding .yaml file in this directory. After the build is
5660 completed, you can run clang-apply-replacements on this directory to
5661 simultaneously apply all suggested changes to the code base. If this
5662 property is not an absolute directory, it is assumed to be relative to
5663 the target's binary directory. This property should be preferred over
5664 adding an --export-fixes or --fix argument directly to the
5665 <LANG>_CLANG_TIDY property.
5666 When this property is set, CMake takes ownership of the specified di‐
5668 rectory, and may create, modify, or delete files and directories within
5669 the directory at any time during configure or build time. Users should
5670 use a dedicated directory for exporting clang-tidy fixes to avoid hav‐
5671 ing files deleted or overwritten by CMake. Users should not create,
5672 modify, or delete files in this directory.
5673 This property is initialized by the value of the
5675 CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR variable if it is set when a
5676 target is created.
5677 <LANG>_COMPILER_LAUNCHER
5679 New in version 3.4.
5680 This property is implemented only when <LANG> is C, CXX, Fortran, HIP,
5683 ISPC, OBJC, OBJCXX, or CUDA.
5684 Specify a semicolon-separated list containing a command line for a com‐
5686 piler launching tool. The Makefile Generators and the Ninja generator
5687 will run this tool and pass the compiler and its arguments to the tool.
5688 Some example tools are distcc and ccache.
5689 This property is initialized by the value of the
5691 CMAKE_<LANG>_COMPILER_LAUNCHER variable if it is set when a target is
5692 created.
5693 New in version 3.25: The property value may use generator expressions.
5695 <LANG>_CPPCHECK
5698 New in version 3.10.
5699 This property is supported only when <LANG> is C or CXX.
5702 Specify a semicolon-separated list containing a command line for the
5704 cppcheck static analysis tool. The Makefile Generators and the Ninja
5705 generator will run cppcheck along with the compiler and report any
5706 problems. If the command-line specifies the exit code options to cp‐
5707 pcheck then the build will fail if the tool returns non-zero.
5708 This property is initialized by the value of the CMAKE_<LANG>_CPPCHECK
5710 variable if it is set when a target is created.
5711 New in version 3.27: This property supports generator expressions.
5713 New in version 3.27: SKIP_LINTING can be set on individual source files
5716 to exclude them from the linting tools defined by <LANG>_CPPLINT,
5717 <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and <LANG>_INCLUDE_WHAT_YOU_USE.
5718 When SKIP_LINTING is set to true on a source file, those tools will not
5719 be run on that specific file.
5720 <LANG>_CPPLINT
5723 New in version 3.8.
5724 This property is supported only when <LANG> is C or CXX.
5727 Specify a semicolon-separated list containing a command line for the
5729 cpplint style checker. The Makefile Generators and the Ninja generator
5730 will run cpplint along with the compiler and report any problems.
5731 This property is initialized by the value of the CMAKE_<LANG>_CPPLINT
5733 variable if it is set when a target is created.
5734 New in version 3.27: This property supports generator expressions.
5736 New in version 3.27: SKIP_LINTING can be set on individual source files
5739 to exclude them from the linting tools defined by <LANG>_CPPLINT,
5740 <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and <LANG>_INCLUDE_WHAT_YOU_USE.
5741 When SKIP_LINTING is set to true on a source file, those tools will not
5742 be run on that specific file.
5743 <LANG>_EXTENSIONS
5746 The variations are:
5747 • C_EXTENSIONS
5749 • CXX_EXTENSIONS
5751 • CUDA_EXTENSIONS
5753 • HIP_EXTENSIONS
5755 • OBJC_EXTENSIONS
5757 • OBJCXX_EXTENSIONS
5759 These properties specify whether compiler-specific extensions are re‐
5761 quested.
5762 These properties are initialized by the value of the
5764 CMAKE_<LANG>_EXTENSIONS variable if it is set when a target is created
5765 and otherwise by the value of CMAKE_<LANG>_EXTENSIONS_DEFAULT (see
5766 CMP0128).
5767 For supported CMake versions see the respective pages. To control lan‐
5769 guage standard versions see <LANG>_STANDARD.
5770 See the cmake-compile-features(7) manual for information on compile
5772 features and a list of supported compilers.
5773 <LANG>_INCLUDE_WHAT_YOU_USE
5775 New in version 3.3.
5776 This property is implemented only when <LANG> is C or CXX.
5779 Specify a semicolon-separated list containing a command line for the
5781 include-what-you-use tool. The Makefile Generators and the Ninja gen‐
5782 erator will run this tool along with the compiler and report a warning
5783 if the tool reports any problems.
5784 This property is initialized by the value of the
5786 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE variable if it is set when a target
5787 is created.
5788 New in version 3.27: This property supports generator expressions.
5790 New in version 3.27: SKIP_LINTING can be set on individual source files
5793 to exclude them from the linting tools defined by <LANG>_CPPLINT,
5794 <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and <LANG>_INCLUDE_WHAT_YOU_USE.
5795 When SKIP_LINTING is set to true on a source file, those tools will not
5796 be run on that specific file.
5797 <LANG>_LINKER_LAUNCHER
5800 New in version 3.21.
5801 This property is implemented only when <LANG> is C, CXX, OBJC, or OB‐
5804 JCXX
5805 Specify a semicolon-separated list containing a command line for a
5807 linker launching tool. The Makefile Generators and the Ninja generator
5808 will run this tool and pass the linker and its arguments to the tool.
5809 This is useful for tools such as static analyzers.
5810 This property is initialized by the value of the
5812 CMAKE_<LANG>_LINKER_LAUNCHER variable if it is set when a target is
5813 created.
5814 New in version 3.27: The property value may use generator expressions.
5816 <LANG>_STANDARD
5819 The variations are:
5820 • C_STANDARD
5822 • CXX_STANDARD
5824 • CUDA_STANDARD
5826 • HIP_STANDARD
5828 • OBJC_STANDARD
5830 • OBJCXX_STANDARD
5832 These properties specify language standard versions which are re‐
5834 quested. When a newer standard is specified than is supported by the
5835 compiler, then it will fallback to the latest supported standard. This
5836 "decay" behavior may be controlled with the <LANG>_STANDARD_REQUIRED
5837 target property.
5838 Note that the actual language standard used may be higher than that
5840 specified by <LANG>_STANDARD, regardless of the value of
5841 <LANG>_STANDARD_REQUIRED. In particular, transitive usage requirements
5842 or the use of compile features can raise the required language standard
5843 above what <LANG>_STANDARD specifies.
5844 These properties are initialized by the value of the
5846 CMAKE_<LANG>_STANDARD variable if it is set when a target is created.
5847 For supported values and CMake versions see the respective pages. To
5849 control compiler-specific extensions see <LANG>_EXTENSIONS.
5850 See the cmake-compile-features(7) manual for information on compile
5852 features and a list of supported compilers.
5853 <LANG>_STANDARD_REQUIRED
5855 The variations are:
5856 • C_STANDARD_REQUIRED
5858 • CXX_STANDARD_REQUIRED
5860 • CUDA_STANDARD_REQUIRED
5862 • HIP_STANDARD_REQUIRED
5864 • OBJC_STANDARD_REQUIRED
5866 • OBJCXX_STANDARD_REQUIRED
5868 These properties specify whether the value of <LANG>_STANDARD is a re‐
5870 quirement. When false or unset, the <LANG>_STANDARD target property is
5871 treated as optional and may "decay" to a previous standard if the re‐
5872 quested standard is not available. When <LANG>_STANDARD_REQUIRED is
5873 set to true, <LANG>_STANDARD becomes a hard requirement and a fatal er‐
5874 ror will be issued if that requirement cannot be met.
5875 Note that the actual language standard used may be higher than that
5877 specified by <LANG>_STANDARD, regardless of the value of <LANG>_STAN‐
5878 DARD_REQUIRED. In particular, transitive usage requirements or the use
5879 of compile features can raise the required language standard above what
5880 <LANG>_STANDARD specifies.
5881 These properties are initialized by the value of the
5883 CMAKE_<LANG>_STANDARD_REQUIRED variable if it is set when a target is
5884 created.
5885 See the cmake-compile-features(7) manual for information on compile
5887 features and a list of supported compilers.
5888 <LANG>_VISIBILITY_PRESET
5890 Value for symbol visibility compile flags
5891 The <LANG>_VISIBILITY_PRESET property determines the value passed in a
5893 visibility related compile option, such as -fvisibility= for <LANG>.
5894 This property affects compilation in sources of all types of targets
5895 (subject to policy CMP0063).
5896 This property is initialized by the value of the
5898 CMAKE_<LANG>_VISIBILITY_PRESET variable if it is set when a target is
5899 created.
5900 LIBRARY_OUTPUT_DIRECTORY
5902 Output directory in which to build LIBRARY target files.
5903 This property specifies the directory into which library target files
5905 should be built. The property value may use generator expressions.
5906 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
5907 fig) append a per-configuration subdirectory to the specified directory
5908 unless a generator expression is used.
5909 This property is initialized by the value of the
5911 CMAKE_LIBRARY_OUTPUT_DIRECTORY variable if it is set when a target is
5912 created.
5913 See also the LIBRARY_OUTPUT_DIRECTORY_<CONFIG> target property.
5915 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
5917 Per-configuration output directory for LIBRARY target files.
5918 This is a per-configuration version of the LIBRARY_OUTPUT_DIRECTORY
5920 target property, but multi-configuration generators (Visual Studio Gen‐
5921 erators, Xcode) do NOT append a per-configuration subdirectory to the
5922 specified directory. This property is initialized by the value of the
5923 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
5924 target is created.
5925 Contents of LIBRARY_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
5927 sions.
5928 LIBRARY_OUTPUT_NAME
5930 Output name for LIBRARY target files.
5931 This property specifies the base name for library target files. It
5933 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
5934 See also the LIBRARY_OUTPUT_NAME_<CONFIG> target property.
5936 LIBRARY_OUTPUT_NAME_<CONFIG>
5938 Per-configuration output name for LIBRARY target files.
5939 This is the configuration-specific version of the LIBRARY_OUTPUT_NAME
5941 target property.
5942 LINK_DEPENDS
5944 Additional files on which a target binary depends for linking.
5945 Specifies a semicolon-separated list of full-paths to files on which
5947 the link rule for this target depends. The target binary will be
5948 linked if any of the named files is newer than it.
5949 This property is supported only by Ninja and Makefile Generators. It
5951 is intended to specify dependencies on "linker scripts" for custom
5952 Makefile link rules.
5953 Contents of LINK_DEPENDS may use "generator expressions" with the syn‐
5955 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5956 able expressions. See the cmake-buildsystem(7) manual for more on
5957 defining buildsystem properties.
5958 LINK_DEPENDS_NO_SHARED
5960 Do not depend on linked shared library files.
5961 Set this property to true to tell CMake generators not to add
5963 file-level dependencies on the shared library files linked by this tar‐
5964 get. Modification to the shared libraries will not be sufficient to
5965 re-link this target. Logical target-level dependencies will not be af‐
5966 fected so the linked shared libraries will still be brought up to date
5967 before this target is built.
5968 This property is initialized by the value of the
5970 CMAKE_LINK_DEPENDS_NO_SHARED variable if it is set when a target is
5971 created.
5972 LINK_DIRECTORIES
5974 New in version 3.13.
5975 List of directories to use for the link step of shared library, module
5978 and executable targets.
5979 This property holds a semicolon-separated list of directories specified
5981 so far for its target. Use the target_link_directories() command to
5982 append more search directories.
5983 This property is initialized by the LINK_DIRECTORIES directory property
5985 when a target is created, and is used by the generators to set the
5986 search directories for the linker.
5987 Contents of LINK_DIRECTORIES may use "generator expressions" with the
5989 syntax $<...>. See the cmake-generator-expressions(7) manual for
5990 available expressions. See the cmake-buildsystem(7) manual for more on
5991 defining buildsystem properties.
5992 LINK_FLAGS
5994 Additional flags to use when linking this target if it is a shared li‐
5995 brary, module library, or an executable. Static libraries need to use
5996 STATIC_LIBRARY_OPTIONS or STATIC_LIBRARY_FLAGS properties.
5997 The LINK_FLAGS property, managed as a string, can be used to add extra
5999 flags to the link step of a target. LINK_FLAGS_<CONFIG> will add to
6000 the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
6001 RELWITHDEBINFO, ...
6002 NOTE:
6004 This property has been superseded by LINK_OPTIONS property.
6005 LINK_FLAGS_<CONFIG>
6007 Per-configuration linker flags for a SHARED library, MODULE or EXE‐
6008 CUTABLE target.
6009 This is the configuration-specific version of LINK_FLAGS.
6011 NOTE:
6013 This property has been superseded by LINK_OPTIONS property.
6014 LINK_INTERFACE_LIBRARIES
6016 List public interface libraries for a shared library or executable.
6017 By default linking to a shared library target transitively links to
6019 targets with which the library itself was linked. For an executable
6020 with exports (see the ENABLE_EXPORTS target property) no default tran‐
6021 sitive link dependencies are used. This property replaces the default
6022 transitive link dependencies with an explicit list. When the target is
6023 linked into another target using the target_link_libraries() command,
6024 the libraries listed (and recursively their link interface libraries)
6025 will be provided to the other target also. If the list is empty then
6026 no transitive link dependencies will be incorporated when this target
6027 is linked into another target even if the default set is non-empty.
6028 This property is initialized by the value of the
6029 CMAKE_LINK_INTERFACE_LIBRARIES variable if it is set when a target is
6030 created. This property is ignored for STATIC libraries.
6031 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
6033 policy CMP0022 is NEW.
6034 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
6036 Creating Relocatable Packages
6038 Note that it is not advisable to populate the LINK_INTERFACE_LIBRARIES
6039 of a target with absolute paths to dependencies. That would hard-code
6040 into installed packages the library file paths for dependencies as
6041 found on the machine the package was made on.
6042 See the Creating Relocatable Packages section of the cmake-packages(7)
6044 manual for discussion of additional care that must be taken when speci‐
6045 fying usage requirements while creating packages for redistribution.
6046 LINK_INTERFACE_LIBRARIES_<CONFIG>
6048 Per-configuration list of public interface libraries for a target.
6049 This is the configuration-specific version of LINK_INTERFACE_LIBRARIES.
6051 If set, this property completely overrides the generic property for the
6052 named configuration.
6053 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
6055 policy CMP0022 is NEW.
6056 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
6058 Creating Relocatable Packages
6060 Note that it is not advisable to populate the LINK_INTERFACE_LI‐
6061 BRARIES_<CONFIG> of a target with absolute paths to dependencies. That
6062 would hard-code into installed packages the library file paths for de‐
6063 pendencies as found on the machine the package was made on.
6064 See the Creating Relocatable Packages section of the cmake-packages(7)
6066 manual for discussion of additional care that must be taken when speci‐
6067 fying usage requirements while creating packages for redistribution.
6068 LINK_INTERFACE_MULTIPLICITY
6070 Repetition count for STATIC libraries with cyclic dependencies.
6071 When linking to a STATIC library target with cyclic dependencies the
6073 linker may need to scan more than once through the archives in the
6074 strongly connected component of the dependency graph. CMake by default
6075 constructs the link line so that the linker will scan through the com‐
6076 ponent at least twice. This property specifies the minimum number of
6077 scans if it is larger than the default. CMake uses the largest value
6078 specified by any target in a component.
6079 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
6081 Per-configuration repetition count for cycles of STATIC libraries.
6082 This is the configuration-specific version of
6084 LINK_INTERFACE_MULTIPLICITY. If set, this property completely over‐
6085 rides the generic property for the named configuration.
6086 LINK_LIBRARIES
6088 List of direct link dependencies.
6089 This property specifies the list of libraries or targets which will be
6091 used for linking. In addition to accepting values from the
6092 target_link_libraries() command, values may be set directly on any tar‐
6093 get using the set_property() command.
6094 The value of this property is used by the generators to construct the
6096 link rule for the target. The direct link dependencies are linked
6097 first, followed by indirect dependencies from the transitive closure of
6098 the direct dependencies' INTERFACE_LINK_LIBRARIES properties. See pol‐
6099 icy CMP0022.
6100 Contents of LINK_LIBRARIES may use generator expressions with the syn‐
6102 tax $<...>. Policy CMP0131 affects the behavior of the LINK_ONLY gen‐
6103 erator expression for this property.
6104 See the cmake-buildsystem(7) manual for more on defining buildsystem
6106 properties.
6107 NOTE:
6109 A call to target_link_libraries(<target> ...) may update this prop‐
6110 erty on <target>. If <target> was not created in the same directory
6111 as the call then target_link_libraries() will wrap each entry with
6112 the form ::@(directory-id);...;::@, where the ::@ is literal and the
6113 (directory-id) is unspecified. This tells the generators that the
6114 named libraries must be looked up in the scope of the caller rather
6115 than in the scope in which the <target> was created. Valid direc‐
6116 tory ids are stripped on export by the install(EXPORT) and export()
6117 commands.
6118 In advanced use cases, the list of direct link dependencies specified
6120 by this property may be updated by usage requirements from dependen‐
6121 cies. See the INTERFACE_LINK_LIBRARIES_DIRECT and
6122 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties.
6123 LINK_LIBRARIES_ONLY_TARGETS
6125 New in version 3.23.
6126 Enforce that link items that can be target names are actually existing
6129 targets.
6130 Set this property to a true value to enable additional checks on the
6132 contents of the LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES target
6133 properties, typically populated by target_link_libraries(). Checks are
6134 also applied to libraries added to a target through the
6135 INTERFACE_LINK_LIBRARIES_DIRECT properties of its dependencies. CMake
6136 will verify that link items that might be target names actually name
6137 existing targets. An item is considered a possible target name if:
6138 • it does not contain a / or \, and
6140 • it does not start in -, and
6142 • (for historical reasons) it does not start in $ or `.
6144 This property is initialized by the value of the
6146 CMAKE_LINK_LIBRARIES_ONLY_TARGETS variable when a non-imported target
6147 is created. The property may be explicitly enabled on an imported tar‐
6148 get to check its link interface.
6149 In the following example, CMake will halt with an error at configure
6151 time because miLib is not a target:
6152 set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON)
6154 add_library(myLib STATIC myLib.c)
6155 add_executable(myExe myExe.c)
6156 target_link_libraries(myExe PRIVATE miLib) # typo for myLib
6157 In order to link toolchain-provided libraries by name while still en‐
6159 forcing LINK_LIBRARIES_ONLY_TARGETS, use an imported Interface Library
6160 with the IMPORTED_LIBNAME target property:
6161 add_library(toolchain::m INTERFACE IMPORTED)
6163 set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m")
6164 target_link_libraries(myExe PRIVATE toolchain::m)
6165 See also policy CMP0028.
6167 NOTE:
6169 If INTERFACE_LINK_LIBRARIES contains generator expressions, its ac‐
6170 tual list of link items may depend on the type and properties of the
6171 consuming target. In such cases CMake may not always detect names
6172 of missing targets that only appear for specific consumers. A fu‐
6173 ture version of CMake with improved heuristics may start triggering
6174 errors on projects accepted by previous versions of CMake.
6175 LINK_LIBRARY_OVERRIDE
6177 New in version 3.24.
6178 Override the library features associated with libraries from
6181 LINK_LIBRARY generator expressions. This can be used to resolve incom‐
6182 patible library features that result from specifying different features
6183 for the same library in different LINK_LIBRARY generator expressions.
6184 This property supports overriding multiple libraries and features. It
6186 expects a semicolon-separated list, where each list item has the fol‐
6187 lowing form:
6188 feature[,link-item]*
6190 For each comma-separated link-item, any existing library feature asso‐
6192 ciated with it will be ignored for the target this property is set on.
6193 The item will instead be associated with the specified feature. Each
6194 link-item can be anything that would be accepted as part of a li‐
6195 brary-list in a LINK_LIBRARY generator expression.
6196 add_library(lib1 ...)
6198 add_library(lib2 ...)
6199 add_library(lib3 ...)
6200 target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
6202 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
6203 target_link_libraries(lib3 PRIVATE lib1 lib2)
6204 # lib1 is associated with both feature2 and no feature. Without any override,
6206 # this would result in a fatal error at generation time for lib3.
6207 # Define an override to resolve the incompatible feature associations.
6208 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
6209 # lib1 and external will now be associated with feature2 instead when linking lib3
6211 It is also possible to override any feature with the pre-defined DE‐
6213 FAULT library feature. This effectively discards any feature for that
6214 link item, for that target only (lib3 in this example):
6215 # When linking lib3, discard any library feature for lib1, and use feature2 for external
6217 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
6218 "DEFAULT,lib1"
6219 "feature2,external"
6220 )
6221 The above example also demonstrates how to specify different feature
6223 overrides for different link items. See the
6224 LINK_LIBRARY_OVERRIDE_<LIBRARY> target property for an alternative way
6225 of overriding library features for individual libraries, which may be
6226 simpler in some cases. If both properties are defined and specify an
6227 override for the same link item, LINK_LIBRARY_OVERRIDE_<LIBRARY> takes
6228 precedence over LINK_LIBRARY_OVERRIDE.
6229 Contents of LINK_LIBRARY_OVERRIDE may use generator expressions.
6231 For more information about library features, see the
6233 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and
6234 CMAKE_LINK_LIBRARY_USING_<FEATURE> variables.
6235 LINK_LIBRARY_OVERRIDE_<LIBRARY>
6237 New in version 3.24.
6238 Override the library feature associated with <LIBRARY> from
6241 LINK_LIBRARY generator expressions. This can be used to resolve incom‐
6242 patible library features that result from specifying different features
6243 for <LIBRARY> in different LINK_LIBRARY generator expressions.
6244 When set on a target, this property holds a single library feature
6246 name, which will be applied to <LIBRARY> when linking that target.
6247 add_library(lib1 ...)
6249 add_library(lib2 ...)
6250 add_library(lib3 ...)
6251 target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
6253 target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
6254 target_link_libraries(lib3 PRIVATE lib1 lib2)
6255 # lib1 is associated with both feature2 and no feature. Without any override,
6257 # this would result in a fatal error at generation time for lib3.
6258 # Define an override to resolve the incompatible feature associations.
6259 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
6260 # lib1 will now be associated with feature2 instead when linking lib3
6262 It is also possible to override any feature with the pre-defined DE‐
6264 FAULT library feature. This effectively discards any feature for that
6265 link item, for that target only (lib3 in this example):
6266 # When linking lib3, discard any library feature for lib1
6268 set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
6269 See the LINK_LIBRARY_OVERRIDE target property for an alternative way of
6271 overriding library features for multiple libraries at once. If both
6272 properties are defined and specify an override for the same link item,
6273 LINK_LIBRARY_OVERRIDE_<LIBRARY> takes precedence over
6274 LINK_LIBRARY_OVERRIDE.
6275 Contents of LINK_LIBRARY_OVERRIDE_<LIBRARY> may use generator expres‐
6277 sions.
6278 For more information about library features, see the
6280 CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and
6281 CMAKE_LINK_LIBRARY_USING_<FEATURE> variables.
6282 LINK_OPTIONS
6284 New in version 3.13.
6285 List of options to use for the link step of shared library, module and
6288 executable targets as well as the device link step. Targets that are
6289 static libraries need to use the STATIC_LIBRARY_OPTIONS target prop‐
6290 erty.
6291 These options are used for both normal linking and device linking (see
6293 policy CMP0105). To control link options for normal and device link
6294 steps, $<HOST_LINK> and $<DEVICE_LINK> generator expressions can be
6295 used.
6296 This property holds a semicolon-separated list of options specified so
6298 far for its target. Use the target_link_options() command to append
6299 more options.
6300 This property is initialized by the LINK_OPTIONS directory property
6302 when a target is created, and is used by the generators to set the op‐
6303 tions for the compiler.
6304 Contents of LINK_OPTIONS may use "generator expressions" with the syn‐
6306 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6307 able expressions. See the cmake-buildsystem(7) manual for more on
6308 defining buildsystem properties.
6309 NOTE:
6311 This property must be used in preference to LINK_FLAGS property.
6312 Host And Device Specific Link Options
6314 New in version 3.18: When a device link step is involved, which is con‐
6315 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
6316 properties and policy CMP0105, the raw options will be delivered to the
6317 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
6318 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
6319 sion will be used only for the device link step. Options wrapped with
6320 $<HOST_LINK:...> generator expression will be used only for the host
6321 link step.
6322 Option De-duplication
6325 The final set of options used for a target is constructed by accumulat‐
6326 ing options from the current target and the usage requirements of its
6327 dependencies. The set of options is de-duplicated to avoid repetition.
6328 New in version 3.12: While beneficial for individual options, the
6330 de-duplication step can break up option groups. For example, -option A
6331 -option B becomes -option A B. One may specify a group of options us‐
6332 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
6333 is dropped, and the rest of the option string is parsed using the
6334 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
6335 "SHELL:-option B" becomes -option A -option B.
6336 Handling Compiler Driver Differences
6339 To pass options to the linker tool, each compiler driver has its own
6340 syntax. The LINKER: prefix and , separator can be used to specify, in
6341 a portable way, options to pass to the linker tool. LINKER: is replaced
6342 by the appropriate driver option and , by the appropriate driver sepa‐
6343 rator. The driver prefix and driver separator are given by the values
6344 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6345 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6346 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6348 Clang and -Wl,-z,defs for GNU GCC.
6349 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6351 sion.
6352 The LINKER: prefix supports, as an alternative syntax, specification of
6354 arguments using the SHELL: prefix and space as separator. The previous
6355 example then becomes "LINKER:SHELL:-z defs".
6356 NOTE:
6358 Specifying the SHELL: prefix anywhere other than at the beginning of
6359 the LINKER: prefix is not supported.
6360 LINK_SEARCH_END_STATIC
6362 End a link line such that static system libraries are used.
6363 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
6365 mine whether to use static or shared libraries for -lXXX options.
6366 CMake uses these options to set the link type for libraries whose full
6367 paths are not known or (in some cases) are in implicit link directories
6368 for the platform. By default CMake adds an option at the end of the
6369 library list (if necessary) to set the linker search type back to its
6370 starting type. This property switches the final linker search type to
6371 -Bstatic regardless of how it started.
6372 This property is initialized by the value of the variable
6374 CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created.
6375 See also LINK_SEARCH_START_STATIC.
6377 LINK_SEARCH_START_STATIC
6379 Assume the linker looks for static libraries by default.
6380 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
6382 mine whether to use static or shared libraries for -lXXX options.
6383 CMake uses these options to set the link type for libraries whose full
6384 paths are not known or (in some cases) are in implicit link directories
6385 for the platform. By default the linker search type is assumed to be
6386 -Bdynamic at the beginning of the library list. This property switches
6387 the assumption to -Bstatic. It is intended for use when linking an ex‐
6388 ecutable statically (e.g. with the GNU -static option).
6389 This property is initialized by the value of the variable
6391 CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is
6392 created.
6393 See also LINK_SEARCH_END_STATIC.
6395 LINK_WHAT_YOU_USE
6397 New in version 3.7.
6398 This is a boolean option that, when set to TRUE, will automatically run
6401 contents of variable CMAKE_LINK_WHAT_YOU_USE_CHECK on the target after
6402 it is linked. In addition, the linker flag specified by variable
6403 CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG will be passed to the target with
6404 the link command so that all libraries specified on the command line
6405 will be linked into the target. This will result in the link producing
6406 a list of libraries that provide no symbols used by this target but are
6407 being linked to it.
6408 NOTE:
6410 For now, it is only supported for ELF platforms and is only applica‐
6411 ble to executable and shared or module library targets. This prop‐
6412 erty will be ignored for any other targets and configurations.
6413 This property is initialized by the value of the
6415 CMAKE_LINK_WHAT_YOU_USE variable if it is set when a target is created.
6416 LINKER_LANGUAGE
6418 Specifies language whose compiler will invoke the linker.
6419 For executables, shared libraries, and modules, this sets the language
6421 whose compiler is used to link the target (such as "C" or "CXX"). A
6422 typical value for an executable is the language of the source file pro‐
6423 viding the program entry point (main). If not set, the language with
6424 the highest linker preference value is the default. Details of the
6425 linker preferences are considered internal, but some limited discussion
6426 can be found under the internal CMAKE_<LANG>_LINKER_PREFERENCE vari‐
6427 ables.
6428 If this property is not set by the user, it will be calculated at gen‐
6430 erate-time by CMake.
6431 LOCATION
6433 Read-only location of a target on disk.
6434 For an imported target, this read-only property returns the value of
6436 the LOCATION_<CONFIG> property for an unspecified configuration <CON‐
6437 FIG> provided by the target.
6438 For a non-imported target, this property is provided for compatibility
6440 with CMake 2.4 and below. It was meant to get the location of an exe‐
6441 cutable target's output file for use in add_custom_command(). The path
6442 may contain a build-system-specific portion that is replaced at build
6443 time with the configuration getting built (such as $(ConfigurationName)
6444 in VS). In CMake 2.6 and above add_custom_command() automatically rec‐
6445 ognizes a target name in its COMMAND and DEPENDS options and computes
6446 the target location. In CMake 2.8.4 and above add_custom_command()
6447 recognizes generator expressions to refer to target locations anywhere
6448 in the command. Therefore this property is not needed for creating
6449 custom commands.
6450 Do not set properties that affect the location of a target after read‐
6452 ing this property. These include properties whose names match (RUN‐
6453 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IM‐
6454 PLIB_)?(PREFIX|SUFFIX), or "LINKER_LANGUAGE". Failure to follow this
6455 rule is not diagnosed and leaves the location of the target undefined.
6456 LOCATION_<CONFIG>
6458 Read-only property providing a target location on disk.
6459 A read-only property that indicates where a target's main file is lo‐
6461 cated on disk for the configuration <CONFIG>. The property is defined
6462 only for library and executable targets. An imported target may pro‐
6463 vide a set of configurations different from that of the importing
6464 project. By default CMake looks for an exact-match but otherwise uses
6465 an arbitrary available configuration. Use the
6466 MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations
6467 explicitly.
6468 Do not set properties that affect the location of a target after read‐
6470 ing this property. These include properties whose names match (RUN‐
6471 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IM‐
6472 PLIB_)?(PREFIX|SUFFIX), or LINKER_LANGUAGE. Failure to follow this
6473 rule is not diagnosed and leaves the location of the target undefined.
6474 MACHO_COMPATIBILITY_VERSION
6476 New in version 3.17.
6477 What compatibility version number is this target for Mach-O binaries.
6480 For shared libraries on Mach-O systems (e.g. macOS, iOS) the MACHO_COM‐
6482 PATIBILITY_VERSION property corresponds to the compatibility version
6483 and MACHO_CURRENT_VERSION corresponds to the current version. These
6484 are both embedded in the shared library binary and can be checked with
6485 the otool -L <binary> command.
6486 It should be noted that the MACHO_CURRENT_VERSION and MACHO_COMPATIBIL‐
6488 ITY_VERSION properties do not affect the file names or version-related
6489 symlinks that CMake generates for the library. The VERSION and
6490 SOVERSION target properties still control the file and symlink names.
6491 The install_name is also still controlled by SOVERSION.
6492 When MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION are not
6494 given, VERSION and SOVERSION are used for the version details to be em‐
6495 bedded in the binaries respectively. The MACHO_CURRENT_VERSION and MA‐
6496 CHO_COMPATIBILITY_VERSION properties only need to be given if the
6497 project needs to decouple the file and symlink naming from the version
6498 details embedded in the binaries (e.g. to match libtool conventions).
6499 MACHO_CURRENT_VERSION
6501 New in version 3.17.
6502 What current version number is this target for Mach-O binaries.
6505 For shared libraries on Mach-O systems (e.g. macOS, iOS) the
6507 MACHO_COMPATIBILITY_VERSION property corresponds to the compatibility
6508 version and MACHO_CURRENT_VERSION corresponds to the current version.
6509 These are both embedded in the shared library binary and can be checked
6510 with the otool -L <binary> command.
6511 It should be noted that the MACHO_CURRENT_VERSION and
6513 MACHO_COMPATIBILITY_VERSION properties do not affect the file names or
6514 version-related symlinks that CMake generates for the library. The
6515 VERSION and SOVERSION target properties still control the file and sym‐
6516 link names. The install_name is also still controlled by SOVERSION.
6517 When MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION are not
6519 given, VERSION and SOVERSION are used for the version details to be em‐
6520 bedded in the binaries respectively. The MACHO_CURRENT_VERSION and
6521 MACHO_COMPATIBILITY_VERSION properties only need to be given if the
6522 project needs to decouple the file and symlink naming from the version
6523 details embedded in the binaries (e.g. to match libtool conventions).
6524 MACOSX_BUNDLE
6526 Build an executable as an Application Bundle on macOS or iOS.
6527 When this property is set to TRUE the executable when built on macOS or
6529 iOS will be created as an application bundle. This makes it a GUI exe‐
6530 cutable that can be launched from the Finder. See the
6531 MACOSX_BUNDLE_INFO_PLIST target property for information about creation
6532 of the Info.plist file for the application bundle. This property is
6533 initialized by the value of the variable CMAKE_MACOSX_BUNDLE if it is
6534 set when a target is created.
6535 MACOSX_BUNDLE_INFO_PLIST
6537 Specify a custom Info.plist template for a macOS and iOS Application
6538 Bundle.
6539 An executable target with MACOSX_BUNDLE enabled will be built as an ap‐
6541 plication bundle on macOS. By default its Info.plist file is created
6542 by configuring a template called MacOSXBundleInfo.plist.in located in
6543 the CMAKE_MODULE_PATH. This property specifies an alternative template
6544 file name which may be a full path.
6545 The following target properties may be set to specify content to be
6547 configured into the file:
6548 MACOSX_BUNDLE_BUNDLE_NAME
6550 Sets CFBundleName.
6551 MACOSX_BUNDLE_BUNDLE_VERSION
6553 Sets CFBundleVersion.
6554 MACOSX_BUNDLE_COPYRIGHT
6556 Sets NSHumanReadableCopyright.
6557 MACOSX_BUNDLE_GUI_IDENTIFIER
6559 Sets CFBundleIdentifier.
6560 MACOSX_BUNDLE_ICON_FILE
6562 Sets CFBundleIconFile.
6563 MACOSX_BUNDLE_INFO_STRING
6565 Sets CFBundleGetInfoString.
6566 MACOSX_BUNDLE_LONG_VERSION_STRING
6568 Sets CFBundleLongVersionString.
6569 MACOSX_BUNDLE_SHORT_VERSION_STRING
6571 Sets CFBundleShortVersionString.
6572 CMake variables of the same name may be set to affect all targets in a
6574 directory that do not have each specific property set. If a custom
6575 Info.plist is specified by this property it may of course hard-code all
6576 the settings instead of using the target properties.
6577 MACOSX_FRAMEWORK_INFO_PLIST
6579 Specify a custom Info.plist template for a macOS and iOS Framework.
6580 A library target with FRAMEWORK enabled will be built as a framework on
6582 macOS. By default its Info.plist file is created by configuring a tem‐
6583 plate called MacOSXFrameworkInfo.plist.in located in the
6584 CMAKE_MODULE_PATH. This property specifies an alternative template
6585 file name which may be a full path.
6586 The following target properties may be set to specify content to be
6588 configured into the file:
6589 MACOSX_FRAMEWORK_BUNDLE_VERSION
6591 Sets CFBundleVersion.
6592 MACOSX_FRAMEWORK_ICON_FILE
6594 Sets CFBundleIconFile.
6595 MACOSX_FRAMEWORK_IDENTIFIER
6597 Sets CFBundleIdentifier.
6598 MACOSX_FRAMEWORK_SHORT_VERSION_STRING
6600 Sets CFBundleShortVersionString.
6601 CMake variables of the same name may be set to affect all targets in a
6603 directory that do not have each specific property set. If a custom
6604 Info.plist is specified by this property it may of course hard-code all
6605 the settings instead of using the target properties.
6606 MACOSX_RPATH
6608 Whether this target on macOS or iOS is located at runtime using rpaths.
6609 When this property is set to TRUE, the directory portion of the in‐
6611 stall_name field of this shared library will be @rpath unless overrid‐
6612 den by INSTALL_NAME_DIR. This indicates the shared library is to be
6613 found at runtime using runtime paths (rpaths).
6614 This property is initialized by the value of the variable
6616 CMAKE_MACOSX_RPATH if it is set when a target is created.
6617 Runtime paths will also be embedded in binaries using this target and
6619 can be controlled by the INSTALL_RPATH target property on the target
6620 linking to this target.
6621 Policy CMP0042 was introduced to change the default value of MA‐
6623 COSX_RPATH to TRUE. This is because use of @rpath is a more flexible
6624 and powerful alternative to @executable_path and @loader_path.
6625 MANUALLY_ADDED_DEPENDENCIES
6627 New in version 3.8.
6628 Get manually added dependencies to other top-level targets.
6631 This read-only property can be used to query all dependencies that were
6633 added for this target with the add_dependencies() command.
6634 MAP_IMPORTED_CONFIG_<CONFIG>
6636 Map from project configuration to imported target's configuration.
6637 Set this to the list of configurations of an imported target that may
6639 be used for the current project's <CONFIG> configuration. Targets im‐
6640 ported from another project may not provide the same set of configura‐
6641 tion names available in the current project. Setting this property
6642 tells CMake what imported configurations are suitable for use when
6643 building the <CONFIG> configuration. The first configuration in the
6644 list found to be provided by the imported target (i.e. via
6645 IMPORTED_LOCATION_<CONFIG> for the mapped-to <CONFIG>) is selected. As
6646 a special case, an empty list element refers to the configuration-less
6647 imported target location (i.e. IMPORTED_LOCATION).
6648 If this property is set and no matching configurations are available,
6650 then the imported target is considered to be not found. This property
6651 is ignored for non-imported targets.
6652 This property is initialized by the value of the
6654 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable if it is set when a target
6655 is created.
6656 Example
6658 For example creating imported C++ library foo:
6659 add_library(foo STATIC IMPORTED)
6661 Use foo_debug path for Debug build type:
6663 set_property(
6665 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG
6666 )
6667 set_target_properties(foo PROPERTIES
6669 IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
6670 IMPORTED_LOCATION_DEBUG "${foo_debug}"
6671 )
6672 Use foo_release path for Release build type:
6674 set_property(
6676 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE
6677 )
6678 set_target_properties(foo PROPERTIES
6680 IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
6681 IMPORTED_LOCATION_RELEASE "${foo_release}"
6682 )
6683 Use Release version of library for MinSizeRel and RelWithDebInfo build
6685 types:
6686 set_target_properties(foo PROPERTIES
6688 MAP_IMPORTED_CONFIG_MINSIZEREL Release
6689 MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
6690 )
6691 MSVC_DEBUG_INFORMATION_FORMAT
6693 New in version 3.25.
6694 Select debug information format when targeting the MSVC ABI.
6697 The allowed values are:
6699 Embedded
6701 Compile with -Z7 or equivalent flag(s) to produce object files
6702 with full symbolic debugging information.
6703 ProgramDatabase
6705 Compile with -Zi or equivalent flag(s) to produce a program
6706 database that contains all the symbolic debugging information.
6707 EditAndContinue
6709 Compile with -ZI or equivalent flag(s) to produce a program
6710 database that supports the Edit and Continue feature.
6711 The value is ignored on compilers not targeting the MSVC ABI, but an
6713 unsupported value will be rejected as an error when using a compiler
6714 targeting the MSVC ABI.
6715 The value may also be the empty string (""), in which case no debug in‐
6717 formation format flag will be added explicitly by CMake.
6718 Use generator expressions to support per-configuration specification.
6720 For example, the code:
6721 add_executable(foo foo.c)
6723 set_property(TARGET foo PROPERTY
6724 MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
6725 selects for the target foo the program database debug information for‐
6727 mat for the Debug configuration.
6728 This property is initialized from the value of the
6730 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT variable, if it is set. If this
6731 property is not set, CMake selects a debug information format using the
6732 default value $<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>, if
6733 supported by the compiler, and otherwise $<$<CONFIG:Debug,RelWithDe‐
6734 bInfo>:Embedded>.
6735 NOTE:
6737 This property has effect only when policy CMP0141 is set to NEW
6738 prior to the first project() or enable_language() command that en‐
6739 ables a language using a compiler targeting the MSVC ABI.
6740 MSVC_RUNTIME_LIBRARY
6742 New in version 3.15.
6743 Select the MSVC runtime library for use by compilers targeting the MSVC
6746 ABI.
6747 The allowed values are:
6749 MultiThreaded
6751 Compile with -MT or equivalent flag(s) to use a multi-threaded
6752 statically-linked runtime library.
6753 MultiThreadedDLL
6755 Compile with -MD or equivalent flag(s) to use a multi-threaded
6756 dynamically-linked runtime library.
6757 MultiThreadedDebug
6759 Compile with -MTd or equivalent flag(s) to use a multi-threaded
6760 statically-linked runtime library.
6761 MultiThreadedDebugDLL
6763 Compile with -MDd or equivalent flag(s) to use a multi-threaded
6764 dynamically-linked runtime library.
6765 The value is ignored on compilers not targeting the MSVC ABI, but an
6767 unsupported value will be rejected as an error when using a compiler
6768 targeting the MSVC ABI.
6769 The value may also be the empty string ("") in which case no runtime
6771 library selection flag will be added explicitly by CMake. Note that
6772 with Visual Studio Generators the native build system may choose to add
6773 its own default runtime library selection flag.
6774 Use generator expressions to support per-configuration specification.
6776 For example, the code:
6777 add_executable(foo foo.c)
6779 set_property(TARGET foo PROPERTY
6780 MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
6781 selects for the target foo a multi-threaded statically-linked runtime
6783 library with or without debug information depending on the configura‐
6784 tion.
6785 The property is initialized from the value of the
6787 CMAKE_MSVC_RUNTIME_LIBRARY variable, if it is set. If the property is
6788 not set, then CMake uses the default value MultiThreaded$<$<CONFIG:De‐
6789 bug>:Debug>DLL to select a MSVC runtime library.
6790 NOTE:
6792 This property has effect only when policy CMP0091 is set to NEW
6793 prior to the first project() or enable_language() command that en‐
6794 ables a language using a compiler targeting the MSVC ABI.
6795 NAME
6797 Logical name for the target.
6798 Read-only logical name for the target as used by CMake.
6800 NO_SONAME
6802 Whether to set soname when linking a shared library.
6803 Enable this boolean property if a generated SHARED library should not
6805 have soname set. Default is to set soname on all shared libraries as
6806 long as the platform supports it. Generally, use this property only
6807 for leaf private libraries or plugins. If you use it on normal shared
6808 libraries which other targets link against, on some platforms a linker
6809 will insert a full path to the library (as specified at link time) into
6810 the dynamic section of the dependent binary. Therefore, once in‐
6811 stalled, dynamic loader may eventually fail to locate the library for
6812 the binary.
6813 NO_SYSTEM_FROM_IMPORTED
6815 Do not treat include directories from the interfaces of consumed
6816 Imported Targets as system directories.
6817 When the consumed target's SYSTEM property is set to true, the contents
6819 of the INTERFACE_INCLUDE_DIRECTORIES target property are treated as
6820 system includes or, on Apple platforms, when the target is a framework,
6821 it will be treated as system. By default, SYSTEM is true for imported
6822 targets and false for other target types. If the NO_SYSTEM_FROM_IM‐
6823 PORTED property is set to true on a consuming target, compilation of
6824 sources in that consuming target will not treat the contents of the
6825 INTERFACE_INCLUDE_DIRECTORIES of consumed imported targets as system
6826 includes, even if that imported target's SYSTEM property is false.
6827 Directories listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES property
6829 of consumed targets are not affected by NO_SYSTEM_FROM_IMPORTED. Those
6830 directories will always be treated as system include directories by
6831 consumers.
6832 This property is initialized by the value of the
6834 CMAKE_NO_SYSTEM_FROM_IMPORTED variable if it is set when a target is
6835 created.
6836 See the EXPORT_NO_SYSTEM target property to set this behavior on the
6838 target providing the include directories rather than the target consum‐
6839 ing them.
6840 OBJC_EXTENSIONS
6842 New in version 3.16.
6843 Boolean specifying whether compiler specific extensions are requested.
6846 This property specifies whether compiler specific extensions should be
6848 used. For some compilers, this results in adding a flag such as
6849 -std=gnu11 instead of -std=c11 to the compile line. This property is
6850 ON by default. The basic OBJC standard level is controlled by the
6851 OBJC_STANDARD target property.
6852 If the property is not set, and the project has set the C_EXTENSIONS,
6854 the value of C_EXTENSIONS is set for OBJC_EXTENSIONS.
6855 See the cmake-compile-features(7) manual for information on compile
6857 features and a list of supported compilers.
6858 This property is initialized by the value of the CMAKE_OBJC_EXTENSIONS
6860 variable if set when a target is created and otherwise by the value of
6861 CMAKE_OBJC_EXTENSIONS_DEFAULT (see CMP0128).
6862 OBJC_STANDARD
6864 New in version 3.16.
6865 The OBJC standard whose features are requested to build this target.
6868 This property specifies the OBJC standard whose features are requested
6870 to build this target. For some compilers, this results in adding a
6871 flag such as -std=gnu11 to the compile line.
6872 Supported values are:
6874 90 Objective C89/C90
6876 99 Objective C99
6878 11 Objective C11
6880 If the value requested does not result in a compile flag being added
6882 for the compiler in use, a previous standard flag will be added in‐
6883 stead. This means that using:
6884 set_property(TARGET tgt PROPERTY OBJC_STANDARD 11)
6886 with a compiler which does not support -std=gnu11 or an equivalent flag
6888 will not result in an error or warning, but will instead add the
6889 -std=gnu99 or -std=gnu90 flag if supported. This "decay" behavior may
6890 be controlled with the OBJC_STANDARD_REQUIRED target property. Addi‐
6891 tionally, the OBJC_EXTENSIONS target property may be used to control
6892 whether compiler-specific extensions are enabled on a per-target basis.
6893 If the property is not set, and the project has set the C_STANDARD, the
6895 value of C_STANDARD is set for OBJC_STANDARD.
6896 See the cmake-compile-features(7) manual for information on compile
6898 features and a list of supported compilers.
6899 This property is initialized by the value of the CMAKE_OBJC_STANDARD
6901 variable if it is set when a target is created.
6902 OBJC_STANDARD_REQUIRED
6904 New in version 3.16.
6905 Boolean describing whether the value of OBJC_STANDARD is a requirement.
6908 If this property is set to ON, then the value of the OBJC_STANDARD tar‐
6910 get property is treated as a requirement. If this property is OFF or
6911 unset, the OBJC_STANDARD target property is treated as optional and may
6912 "decay" to a previous standard if the requested is not available.
6913 If the property is not set, and the project has set the
6915 C_STANDARD_REQUIRED, the value of C_STANDARD_REQUIRED is set for
6916 OBJC_STANDARD_REQUIRED.
6917 See the cmake-compile-features(7) manual for information on compile
6919 features and a list of supported compilers.
6920 This property is initialized by the value of the
6922 CMAKE_OBJC_STANDARD_REQUIRED variable if it is set when a target is
6923 created.
6924 OBJCXX_EXTENSIONS
6926 New in version 3.16.
6927 Boolean specifying whether compiler specific extensions are requested.
6930 This property specifies whether compiler specific extensions should be
6932 used. For some compilers, this results in adding a flag such as
6933 -std=gnu++11 instead of -std=c++11 to the compile line. This property
6934 is ON by default. The basic ObjC++ standard level is controlled by the
6935 OBJCXX_STANDARD target property.
6936 See the cmake-compile-features(7) manual for information on compile
6938 features and a list of supported compilers.
6939 If the property is not set, and the project has set the CXX_EXTENSIONS,
6941 the value of CXX_EXTENSIONS is set for OBJCXX_EXTENSIONS.
6942 This property is initialized by the value of the
6944 CMAKE_OBJCXX_EXTENSIONS variable if set when a target is created and
6945 otherwise by the value of CMAKE_OBJCXX_EXTENSIONS_DEFAULT (see
6946 CMP0128).
6947 OBJCXX_STANDARD
6949 New in version 3.16.
6950 The ObjC++ standard whose features are requested to build this target.
6953 This property specifies the ObjC++ standard whose features are re‐
6955 quested to build this target. For some compilers, this results in
6956 adding a flag such as -std=gnu++11 to the compile line.
6957 Supported values are:
6959 98 Objective C++98
6961 11 Objective C++11
6963 14 Objective C++14
6965 17 Objective C++17
6967 20 Objective C++20
6969 23 New in version 3.20.
6971 Objective C++23
6974 26 New in version 3.25.
6976 Objective C++26. CMake 3.25 and later recognize 26 as a valid
6979 value, no version has support for any compiler.
6980 If the value requested does not result in a compile flag being added
6982 for the compiler in use, a previous standard flag will be added in‐
6983 stead. This means that using:
6984 set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11)
6986 with a compiler which does not support -std=gnu++11 or an equivalent
6988 flag will not result in an error or warning, but will instead add the
6989 -std=gnu++98 flag if supported. This "decay" behavior may be con‐
6990 trolled with the OBJCXX_STANDARD_REQUIRED target property. Addition‐
6991 ally, the OBJCXX_EXTENSIONS target property may be used to control
6992 whether compiler-specific extensions are enabled on a per-target basis.
6993 If the property is not set, and the project has set the CXX_STANDARD,
6995 the value of CXX_STANDARD is set for OBJCXX_STANDARD.
6996 See the cmake-compile-features(7) manual for information on compile
6998 features and a list of supported compilers.
6999 This property is initialized by the value of the CMAKE_OBJCXX_STANDARD
7001 variable if it is set when a target is created.
7002 OBJCXX_STANDARD_REQUIRED
7004 New in version 3.16.
7005 Boolean describing whether the value of OBJCXX_STANDARD is a require‐
7008 ment.
7009 If this property is set to ON, then the value of the OBJCXX_STANDARD
7011 target property is treated as a requirement. If this property is OFF
7012 or unset, the OBJCXX_STANDARD target property is treated as optional
7013 and may "decay" to a previous standard if the requested is not avail‐
7014 able.
7015 If the property is not set, and the project has set the
7017 CXX_STANDARD_REQUIRED, the value of CXX_STANDARD_REQUIRED is set for
7018 OBJCXX_STANDARD_REQUIRED.
7019 See the cmake-compile-features(7) manual for information on compile
7021 features and a list of supported compilers.
7022 This property is initialized by the value of the
7024 CMAKE_OBJCXX_STANDARD_REQUIRED variable if it is set when a target is
7025 created.
7026 OPTIMIZE_DEPENDENCIES
7028 New in version 3.19.
7029 Activates dependency optimization of static and object libraries.
7032 When this property is set to true, some dependencies for a static or
7034 object library may be removed at generation time if they are not neces‐
7035 sary to build the library, since static and object libraries don't ac‐
7036 tually link against anything.
7037 If a static or object library has dependency optimization enabled, it
7039 first discards all dependencies. Then, it looks through all of the di‐
7040 rect and indirect dependencies that it initially had, and adds them
7041 back if they meet any of the following criteria:
7042 • The dependency was added to the library by add_dependencies().
7044 • The dependency was added to the library through a source file in the
7046 library generated by a custom command that uses the dependency.
7047 • The dependency has any PRE_BUILD, PRE_LINK, or POST_BUILD custom com‐
7049 mands associated with it.
7050 • The dependency contains any source files that were generated by a
7052 custom command.
7053 • The dependency contains any languages which produce side effects that
7055 are relevant to the library. Currently, all languages except C, C++,
7056 Objective-C, Objective-C++, assembly, and CUDA are assumed to produce
7057 side effects. However, side effects from one language are assumed
7058 not to be relevant to another (for example, a Fortran library is as‐
7059 sumed to not have any side effects that are relevant for a Swift li‐
7060 brary.)
7061 As an example, assume you have a static Fortran library which depends
7063 on a static C library, which in turn depends on a static Fortran li‐
7064 brary. The top-level Fortran library has optimization enabled, but the
7065 middle C library does not. If you build the top Fortran library, the
7066 bottom Fortran library will also build, but not the middle C library,
7067 since the C library does not have any side effects that are relevant
7068 for the Fortran library. However, if you build the middle C library,
7069 the bottom Fortran library will also build, even though it does not
7070 have any side effects that are relevant to the C library, since the C
7071 library does not have optimization enabled.
7072 This property is initialized by the value of the
7074 CMAKE_OPTIMIZE_DEPENDENCIES variable when the target is created.
7075 OSX_ARCHITECTURES
7077 Target specific architectures for macOS.
7078 The OSX_ARCHITECTURES property sets the target binary architecture for
7080 targets on macOS (-arch). This property is initialized by the value of
7081 the variable CMAKE_OSX_ARCHITECTURES if it is set when a target is cre‐
7082 ated. Use OSX_ARCHITECTURES_<CONFIG> to set the binary architectures
7083 on a per-configuration basis, where <CONFIG> is an upper-case name
7084 (e.g. OSX_ARCHITECTURES_DEBUG).
7085 OSX_ARCHITECTURES_<CONFIG>
7087 Per-configuration macOS and iOS binary architectures for a target.
7088 This property is the configuration-specific version of
7090 OSX_ARCHITECTURES.
7091 OUTPUT_NAME
7093 Output name for target files.
7094 This sets the base name for output files created for an executable or
7096 library target. If not set, the logical target name is used by default
7097 during generation. The value is not set by default during configura‐
7098 tion.
7099 Contents of OUTPUT_NAME and the variants listed below may use generator
7101 expressions.
7102 See also the variants:
7104 • OUTPUT_NAME_<CONFIG>
7106 • ARCHIVE_OUTPUT_NAME_<CONFIG>
7108 • ARCHIVE_OUTPUT_NAME
7110 • LIBRARY_OUTPUT_NAME_<CONFIG>
7112 • LIBRARY_OUTPUT_NAME
7114 • RUNTIME_OUTPUT_NAME_<CONFIG>
7116 • RUNTIME_OUTPUT_NAME
7118 OUTPUT_NAME_<CONFIG>
7120 Per-configuration target file base name.
7121 This is the configuration-specific version of the OUTPUT_NAME target
7123 property.
7124 PCH_INSTANTIATE_TEMPLATES
7126 New in version 3.19.
7127 When this property is set to true, the precompiled header compiler op‐
7130 tions will contain a flag to instantiate templates during the genera‐
7131 tion of the PCH if supported. This can significantly improve compile
7132 times. Supported in Clang since version 11.
7133 This property is initialized by the value of the
7135 CMAKE_PCH_INSTANTIATE_TEMPLATES variable if it is set when a target is
7136 created. If that variable is not set, the property defaults to ON.
7137 PCH_WARN_INVALID
7139 New in version 3.18.
7140 When this property is set to true, the precompile header compiler op‐
7143 tions will contain a compiler flag which should warn about invalid pre‐
7144 compiled headers e.g. -Winvalid-pch for GNU compiler.
7145 This property is initialized by the value of the CMAKE_PCH_WARN_INVALID
7147 variable if it is set when a target is created. If that variable is
7148 not set, the property defaults to ON.
7149 PDB_NAME
7151 Output name for the MS debug symbol .pdb file generated by the linker
7152 for an executable or shared library target.
7153 This property specifies the base name for the debug symbols file. If
7155 not set, the OUTPUT_NAME target property value or logical target name
7156 is used by default.
7157 NOTE:
7159 This property does not apply to STATIC library targets because no
7160 linker is invoked to produce them so they have no linker-generated
7161 .pdb file containing debug symbols.
7162 The linker-generated program database files are specified by the
7164 /pdb linker flag and are not the same as compiler-generated program
7165 database files specified by the /Fd compiler flag. Use the
7166 COMPILE_PDB_NAME property to specify the latter.
7167 PDB_NAME_<CONFIG>
7169 Per-configuration output name for the MS debug symbol .pdb file gener‐
7170 ated by the linker for an executable or shared library target.
7171 This is the configuration-specific version of PDB_NAME.
7173 NOTE:
7175 This property does not apply to STATIC library targets because no
7176 linker is invoked to produce them so they have no linker-generated
7177 .pdb file containing debug symbols.
7178 The linker-generated program database files are specified by the
7180 /pdb linker flag and are not the same as compiler-generated program
7181 database files specified by the /Fd compiler flag. Use the
7182 COMPILE_PDB_NAME_<CONFIG> property to specify the latter.
7183 PDB_OUTPUT_DIRECTORY
7185 Output directory for the MS debug symbols .pdb file generated by the
7186 linker for an executable or shared library target.
7187 This property specifies the directory into which the MS debug symbols
7189 will be placed by the linker. The property value may use generator ex‐
7190 pressions. Multi-configuration generators append a per-configuration
7191 subdirectory to the specified directory unless a generator expression
7192 is used.
7193 This property is initialized by the value of the
7195 CMAKE_PDB_OUTPUT_DIRECTORY variable if it is set when a target is cre‐
7196 ated.
7197 NOTE:
7199 This property does not apply to STATIC library targets because no
7200 linker is invoked to produce them so they have no linker-generated
7201 .pdb file containing debug symbols.
7202 The linker-generated program database files are specified by the
7204 /pdb linker flag and are not the same as compiler-generated program
7205 database files specified by the /Fd compiler flag. Use the
7206 COMPILE_PDB_OUTPUT_DIRECTORY property to specify the latter.
7207 PDB_OUTPUT_DIRECTORY_<CONFIG>
7209 Per-configuration output directory for the MS debug symbol .pdb file
7210 generated by the linker for an executable or shared library target.
7211 This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
7213 multi-configuration generators (Visual Studio Generators, Xcode) do NOT
7214 append a per-configuration subdirectory to the specified directory.
7215 This property is initialized by the value of the
7216 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a target
7217 is created.
7218 Contents of PDB_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
7220 sions.
7221 NOTE:
7223 This property does not apply to STATIC library targets because no
7224 linker is invoked to produce them so they have no linker-generated
7225 .pdb file containing debug symbols.
7226 The linker-generated program database files are specified by the
7228 /pdb linker flag and are not the same as compiler-generated program
7229 database files specified by the /Fd compiler flag. Use the
7230 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the lat‐
7231 ter.
7232 POSITION_INDEPENDENT_CODE
7234 Whether to create a position-independent target
7235 The POSITION_INDEPENDENT_CODE property determines whether position in‐
7237 dependent executables or shared libraries will be created. This prop‐
7238 erty is True by default for SHARED and MODULE library targets and False
7239 otherwise. This property is initialized by the value of the
7240 CMAKE_POSITION_INDEPENDENT_CODE variable if it is set when a target is
7241 created.
7242 NOTE:
7244 For executable targets, the link step is controlled by the CMP0083
7245 policy and the CheckPIESupported module.
7246 PRECOMPILE_HEADERS
7248 New in version 3.16.
7249 List of header files to precompile.
7252 This property holds a semicolon-separated list of header files to pre‐
7254 compile specified so far for its target. Use the
7255 target_precompile_headers() command to append more header files.
7256 This property supports generator expressions.
7258 PRECOMPILE_HEADERS_REUSE_FROM
7260 New in version 3.16.
7261 Target from which to reuse the precompiled headers build artifact.
7264 See the second signature of target_precompile_headers() command for
7266 more detailed information.
7267 PREFIX
7269 What comes before the library name.
7270 A target property that can be set to override the prefix (such as lib)
7272 on a library name.
7273 PRIVATE_HEADER
7275 Specify private header files in a FRAMEWORK shared library target.
7276 Shared library targets marked with the FRAMEWORK property generate
7278 frameworks on macOS, iOS and normal shared libraries on other plat‐
7279 forms. This property may be set to a list of header files to be placed
7280 in the PrivateHeaders directory inside the framework folder. On
7281 non-Apple platforms these headers may be installed using the PRI‐
7282 VATE_HEADER option to the install(TARGETS) command.
7283 PROJECT_LABEL
7285 Change the name of a target in an IDE.
7286 Can be used to change the name of the target in an IDE like Visual Stu‐
7288 dio.
7289 PUBLIC_HEADER
7291 Specify public header files in a FRAMEWORK shared library target.
7292 Shared library targets marked with the FRAMEWORK property generate
7294 frameworks on macOS, iOS and normal shared libraries on other plat‐
7295 forms. This property may be set to a list of header files to be placed
7296 in the Headers directory inside the framework folder. On non-Apple
7297 platforms these headers may be installed using the PUBLIC_HEADER option
7298 to the install(TARGETS) command.
7299 RESOURCE
7301 Specify resource files in a FRAMEWORK or BUNDLE.
7302 Target marked with the FRAMEWORK or BUNDLE property generate framework
7304 or application bundle (both macOS and iOS is supported) or normal
7305 shared libraries on other platforms. This property may be set to a
7306 list of files to be placed in the corresponding directory (eg. Re‐
7307 sources directory for macOS) inside the bundle. On non-Apple platforms
7308 these files may be installed using the RESOURCE option to the
7309 install(TARGETS) command.
7310 Following example of Application Bundle:
7312 add_executable(ExecutableTarget
7314 addDemo.c
7315 resourcefile.txt
7316 appresourcedir/appres.txt)
7317 target_link_libraries(ExecutableTarget heymath mul)
7319 set(RESOURCE_FILES
7321 resourcefile.txt
7322 appresourcedir/appres.txt)
7323 set_target_properties(ExecutableTarget PROPERTIES
7325 MACOSX_BUNDLE TRUE
7326 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget
7327 RESOURCE "${RESOURCE_FILES}")
7328 will produce flat structure for iOS systems:
7330 ExecutableTarget.app
7332 appres.txt
7333 ExecutableTarget
7334 Info.plist
7335 resourcefile.txt
7336 For macOS systems it will produce following directory structure:
7338 ExecutableTarget.app/
7340 Contents
7341 Info.plist
7342 MacOS
7343 ExecutableTarget
7344 Resources
7345 appres.txt
7346 resourcefile.txt
7347 For Linux, such CMake script produce following files:
7349 ExecutableTarget
7351 Resources
7352 appres.txt
7353 resourcefile.txt
7354 RULE_LAUNCH_COMPILE
7356 Specify a launcher for compile rules.
7357 NOTE:
7359 This property is intended for internal use by ctest(1). Projects
7360 and developers should use the <LANG>_COMPILER_LAUNCHER target prop‐
7361 erties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables
7362 instead.
7363 See the global property of the same name for details. This overrides
7365 the global and directory property for a target.
7366 RULE_LAUNCH_CUSTOM
7368 Specify a launcher for custom rules.
7369 See the global property of the same name for details. This overrides
7371 the global and directory property for a target.
7372 RULE_LAUNCH_LINK
7374 Specify a launcher for link rules.
7375 NOTE:
7377 This property is intended for internal use by ctest(1). Projects
7378 and developers should use the <LANG>_LINKER_LAUNCHER target proper‐
7379 ties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables in‐
7380 stead.
7381 See the global property of the same name for details. This overrides
7383 the global and directory property for a target.
7384 RUNTIME_OUTPUT_DIRECTORY
7386 Output directory in which to build RUNTIME target files.
7387 This property specifies the directory into which runtime target files
7389 should be built. The property value may use generator expressions.
7390 Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Con‐
7391 fig) append a per-configuration subdirectory to the specified directory
7392 unless a generator expression is used.
7393 This property is initialized by the value of the
7395 CMAKE_RUNTIME_OUTPUT_DIRECTORY variable if it is set when a target is
7396 created.
7397 See also the RUNTIME_OUTPUT_DIRECTORY_<CONFIG> target property.
7399 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
7401 Per-configuration output directory for RUNTIME target files.
7402 This is a per-configuration version of the RUNTIME_OUTPUT_DIRECTORY
7404 target property, but multi-configuration generators (Visual Studio Gen‐
7405 erators, Xcode) do NOT append a per-configuration subdirectory to the
7406 specified directory. This property is initialized by the value of the
7407 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
7408 target is created.
7409 Contents of RUNTIME_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
7411 sions.
7412 RUNTIME_OUTPUT_NAME
7414 Output name for RUNTIME target files.
7415 This property specifies the base name for runtime target files. It
7417 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
7418 See also the RUNTIME_OUTPUT_NAME_<CONFIG> target property.
7420 RUNTIME_OUTPUT_NAME_<CONFIG>
7422 Per-configuration output name for RUNTIME target files.
7423 This is the configuration-specific version of the RUNTIME_OUTPUT_NAME
7425 target property.
7426 SKIP_BUILD_RPATH
7428 Should rpaths be used for the build tree.
7429 SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic gen‐
7431 eration of an rpath allowing the target to run from the build tree, see
7432 also the BUILD_RPATH target property. This property is initialized by
7433 the value of the variable CMAKE_SKIP_BUILD_RPATH if it is set when a
7434 target is created.
7435 SOURCE_DIR
7437 New in version 3.4.
7438 This read-only property reports the value of the
7441 CMAKE_CURRENT_SOURCE_DIR variable in the directory in which the target
7442 was defined.
7443 SOURCES
7445 This specifies the list of paths to source files for the target. The
7446 following commands all set or add to the SOURCES target property and
7447 are the usual way to manipulate it:
7448 • add_executable()
7450 • add_library()
7452 • add_custom_target()
7454 • target_sources()
7456 Contents of SOURCES may use generator expressions. If a path starts
7458 with a generator expression, it is expected to evaluate to an absolute
7459 path. Not doing so is considered undefined behavior.
7460 Paths that are for files generated by the build will be treated as rel‐
7462 ative to the build directory of the target, if the path is not already
7463 specified as an absolute path. Note that whether a file is seen as
7464 generated may be affected by policy CMP0118.
7465 If a path does not start with a generator expression, is not an abso‐
7467 lute path and is not a generated file, it will be treated as relative
7468 to the location selected by the first of the following that matches:
7469 • If a file by the specified path exists relative to the target's
7471 source directory, use that file.
7472 • If policy CMP0115 is not set to NEW, try appending each known source
7474 file extension to the path and check if that exists relative to the
7475 target's source directory.
7476 • Repeat the above two steps, this time relative to the target's binary
7478 directory instead.
7479 Note that the above decisions are made at generation time, not build
7481 time.
7482 See the cmake-buildsystem(7) manual for more on defining buildsystem
7484 properties.
7485 SOVERSION
7487 What version number is this target.
7488 For shared libraries VERSION and SOVERSION can be used to specify the
7490 build version and API version respectively. When building or in‐
7491 stalling appropriate symlinks are created if the platform supports sym‐
7492 links and the linker supports so-names. If only one of both is speci‐
7493 fied the missing is assumed to have the same version number. SOVERSION
7494 is ignored if NO_SONAME property is set.
7495 Windows Versions
7497 For shared libraries and executables on Windows the VERSION attribute
7498 is parsed to extract a <major>.<minor> version number. These numbers
7499 are used as the image version of the binary.
7500 Mach-O Versions
7502 For shared libraries and executables on Mach-O systems (e.g. macOS,
7503 iOS), the SOVERSION property corresponds to the compatibility version
7504 and VERSION corresponds to the current version (unless Mach-O specific
7505 overrides are provided, as discussed below). See the FRAMEWORK target
7506 property for an example.
7507 For shared libraries, the MACHO_COMPATIBILITY_VERSION and
7509 MACHO_CURRENT_VERSION properties can be used to override the compati‐
7510 bility version and current version respectively. Note that SOVERSION
7511 will still be used to form the install_name and both SOVERSION and
7512 VERSION may also affect the file and symlink names.
7513 Versions of Mach-O binaries may be checked with the otool -L <binary>
7515 command.
7516 STATIC_LIBRARY_FLAGS
7518 Archiver (or MSVC librarian) flags for a static library target. Tar‐
7519 gets that are shared libraries, modules, or executables need to use the
7520 LINK_OPTIONS or LINK_FLAGS target properties.
7521 The STATIC_LIBRARY_FLAGS property, managed as a string, can be used to
7523 add extra flags to the link step of a static library target.
7524 STATIC_LIBRARY_FLAGS_<CONFIG> will add to the configuration <CONFIG>,
7525 for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO, ...
7526 NOTE:
7528 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
7529 erty.
7530 STATIC_LIBRARY_FLAGS_<CONFIG>
7532 Per-configuration archiver (or MSVC librarian) flags for a static li‐
7533 brary target.
7534 This is the configuration-specific version of STATIC_LIBRARY_FLAGS.
7536 NOTE:
7538 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
7539 erty.
7540 STATIC_LIBRARY_OPTIONS
7542 New in version 3.13.
7543 Archiver (or MSVC librarian) flags for a static library target. Tar‐
7546 gets that are shared libraries, modules, or executables need to use the
7547 LINK_OPTIONS target property.
7548 This property holds a semicolon-separated list of options specified so
7550 far for its target. Use set_target_properties() or set_property() com‐
7551 mands to set its content.
7552 Contents of STATIC_LIBRARY_OPTIONS may use "generator expressions" with
7554 the syntax $<...>. See the cmake-generator-expressions(7) manual for
7555 available expressions. See the cmake-buildsystem(7) manual for more on
7556 defining buildsystem properties.
7557 NOTE:
7559 This property must be used in preference to STATIC_LIBRARY_FLAGS
7560 property.
7561 Option De-duplication
7563 The final set of options used for a target is constructed by accumulat‐
7564 ing options from the current target and the usage requirements of its
7565 dependencies. The set of options is de-duplicated to avoid repetition.
7566 New in version 3.12: While beneficial for individual options, the
7568 de-duplication step can break up option groups. For example, -option A
7569 -option B becomes -option A B. One may specify a group of options us‐
7570 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
7571 is dropped, and the rest of the option string is parsed using the
7572 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
7573 "SHELL:-option B" becomes -option A -option B.
7574 SUFFIX
7577 What comes after the target name.
7578 A target property that can be set to override the suffix (such as .so
7580 or .exe) on the name of a library, module or executable.
7581 Swift_DEPENDENCIES_FILE
7583 New in version 3.15.
7584 This property sets the path for the Swift dependency file (swiftdep)
7587 for the target. If one is not specified, it will default to <TAR‐
7588 GET>.swiftdeps.
7589 Swift_LANGUAGE_VERSION
7591 New in version 3.16.
7592 This property sets the language version for the Swift sources in the
7595 target. If one is not specified, it will default to <CMAKE_Swift_LAN‐
7596 GUAGE_VERSION> if specified, otherwise it is the latest version sup‐
7597 ported by the compiler.
7598 Swift_MODULE_DIRECTORY
7600 New in version 3.15.
7601 Specify output directory for Swift modules provided by the target.
7604 If the target contains Swift source files, this specifies the directory
7606 in which the modules will be placed. When this property is not set,
7607 the modules will be placed in the build directory corresponding to the
7608 target's source directory. If the variable
7609 CMAKE_Swift_MODULE_DIRECTORY is set when a target is created its value
7610 is used to initialize this property.
7611 Swift_MODULE_NAME
7613 New in version 3.15.
7614 This property specifies the name of the Swift module. It is defaulted
7617 to the name of the target.
7618 SYSTEM
7620 New in version 3.25.
7621 Specifies that a target is a system target. This has the following ef‐
7624 fects:
7625 • Entries of INTERFACE_INCLUDE_DIRECTORIES are treated as system in‐
7627 clude directories when compiling consumers. Entries of
7628 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES are not affected, and will al‐
7629 ways be treated as system include directories.
7630 • On Apple platforms, If the FRAMEWORK target property is true, the
7632 frameworks directory is treated as system.
7633 For imported targets, this property defaults to true, which means that
7635 their INTERFACE_INCLUDE_DIRECTORIES and, if the FRAMEWORK target prop‐
7636 erty is true, frameworks directory are treated as system directories by
7637 default. If their SYSTEM property is false, then their
7638 INTERFACE_INCLUDE_DIRECTORIES as well as frameworks will not be treated
7639 as system. Use the EXPORT_NO_SYSTEM property to change how a target's
7640 SYSTEM property is set when it is installed.
7641 For non-imported targets, this target property is initialized from the
7643 SYSTEM directory property when the target is created.
7644 TYPE
7646 The type of the target.
7647 This read-only property can be used to test the type of the given tar‐
7649 get. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, SHARED_LIBRARY,
7650 OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal
7651 target types.
7652 UNITY_BUILD
7654 New in version 3.16.
7655 When this property is set to true, the target source files will be com‐
7658 bined into batches for faster compilation. This is done by creating a
7659 (set of) unity sources which #include the original sources, then com‐
7660 piling these unity sources instead of the originals. This is known as
7661 a Unity or Jumbo build.
7662 CMake provides different algorithms for selecting which sources are
7664 grouped together into a bucket. Algorithm selection is decided by the
7665 UNITY_BUILD_MODE target property, which has the following acceptable
7666 values:
7667 • BATCH When in this mode CMake determines which files are grouped to‐
7669 gether. The UNITY_BUILD_BATCH_SIZE property controls the upper limit
7670 on how many sources can be combined per unity source file.
7671 • GROUP When in this mode each target explicitly specifies how to group
7673 source files. Each source file that has the same UNITY_GROUP value
7674 will be grouped together. Any sources that don't have this property
7675 will be compiled individually. The UNITY_BUILD_BATCH_SIZE property is
7676 ignored when using this mode.
7677 If no explicit UNITY_BUILD_MODE has been specified, CMake will default
7679 to BATCH.
7680 Unity builds are not currently supported for all languages. CMake ver‐
7682 sion 3.27.7 supports combining C and CXX source files. For targets
7683 that mix source files from more than one language, CMake will separate
7684 the languages such that each generated unity source file only contains
7685 sources for a single language.
7686 This property is initialized by the value of the CMAKE_UNITY_BUILD
7688 variable when a target is created.
7689 NOTE:
7691 Projects should not directly set the UNITY_BUILD property or its as‐
7692 sociated CMAKE_UNITY_BUILD variable to true. Depending on the capa‐
7693 bilities of the build machine and compiler used, it might or might
7694 not be appropriate to enable unity builds. Therefore, this feature
7695 should be under developer control, which would normally be through
7696 the developer choosing whether or not to set the CMAKE_UNITY_BUILD
7697 variable on the cmake(1) command line or some other equivalent
7698 method. However, it IS recommended to set the UNITY_BUILD target
7699 property to false if it is known that enabling unity builds for the
7700 target can lead to problems.
7701 ODR (One definition rule) errors
7703 When multiple source files are included into one source file, as is
7704 done for unity builds, it can potentially lead to ODR errors. CMake
7705 provides a number of measures to help address such problems:
7706 • Any source file that has a non-empty COMPILE_OPTIONS,
7708 COMPILE_DEFINITIONS, COMPILE_FLAGS, or INCLUDE_DIRECTORIES source
7709 property will not be combined into a unity source.
7710 • Projects can prevent an individual source file from being combined
7712 into a unity source by setting its SKIP_UNITY_BUILD_INCLUSION source
7713 property to true. This can be a more effective way to prevent prob‐
7714 lems with specific files than disabling unity builds for an entire
7715 target.
7716 • Projects can set UNITY_BUILD_UNIQUE_ID to cause a valid C-identifier
7718 to be generated which is unique per file in a unity build. This can
7719 be used to avoid problems with anonymous namespaces in unity builds.
7720 • The UNITY_BUILD_CODE_BEFORE_INCLUDE and
7722 UNITY_BUILD_CODE_AFTER_INCLUDE target properties can be used to in‐
7723 ject code into the unity source files before and after every #include
7724 statement.
7725 • The order of source files added to the target via commands like
7727 add_library(), add_executable() or target_sources() will be preserved
7728 in the generated unity source files. This can be used to manually
7729 enforce a specific grouping based on the UNITY_BUILD_BATCH_SIZE tar‐
7730 get property.
7731 UNITY_BUILD_BATCH_SIZE
7733 New in version 3.16.
7734 Specifies the maximum number of source files that can be combined into
7737 any one unity source file when unity builds are enabled by the
7738 UNITY_BUILD target property. The original source files will be dis‐
7739 tributed across as many unity source files as necessary to honor this
7740 limit.
7741 The initial value for this property is taken from the
7743 CMAKE_UNITY_BUILD_BATCH_SIZE variable when the target is created. If
7744 that variable has not been set, the initial value will be 8.
7745 The batch size needs to be selected carefully. If set too high, the
7747 size of the combined source files could result in the compiler using
7748 excessive memory or hitting other similar limits. In extreme cases,
7749 this can even result in build failure. On the other hand, if the batch
7750 size is too low, there will be little gain in build performance.
7751 Although strongly discouraged, the batch size may be set to a value of
7753 0 to combine all the sources for the target into a single unity file,
7754 regardless of how many sources are involved. This runs the risk of
7755 creating an excessively large unity source file and negatively impact‐
7756 ing the build performance, so a value of 0 is not generally recom‐
7757 mended.
7758 UNITY_BUILD_CODE_AFTER_INCLUDE
7760 New in version 3.16.
7761 Code snippet which is included verbatim by the UNITY_BUILD feature just
7764 after every #include statement in the generated unity source files.
7765 For example:
7766 set(after [[
7768 #if defined(NOMINMAX)
7769 #undef NOMINMAX
7770 #endif
7771 ]])
7772 set_target_properties(myTarget PROPERTIES
7773 UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
7774 )
7775 See also UNITY_BUILD_CODE_BEFORE_INCLUDE.
7777 UNITY_BUILD_CODE_BEFORE_INCLUDE
7779 New in version 3.16.
7780 Code snippet which is included verbatim by the UNITY_BUILD feature just
7783 before every #include statement in the generated unity source files.
7784 For example:
7785 set(before [[
7787 #if !defined(NOMINMAX)
7788 #define NOMINMAX
7789 #endif
7790 ]])
7791 set_target_properties(myTarget PROPERTIES
7792 UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
7793 )
7794 See also UNITY_BUILD_CODE_AFTER_INCLUDE.
7796 UNITY_BUILD_MODE
7798 New in version 3.18.
7799 CMake provides different algorithms for selecting which sources are
7802 grouped together into a bucket. Selection is decided by this property,
7803 which has the following acceptable values:
7804 BATCH When in this mode CMake determines which files are grouped to‐
7806 gether. The UNITY_BUILD_BATCH_SIZE property controls the upper
7807 limit on how many sources can be combined per unity source file.
7808 Example usage:
7810 add_library(example_library
7812 source1.cxx
7813 source2.cxx
7814 source3.cxx
7815 source4.cxx)
7816 set_target_properties(example_library PROPERTIES
7818 UNITY_BUILD_MODE BATCH
7819 UNITY_BUILD_BATCH_SIZE 2
7820 )
7821 GROUP When in this mode each target explicitly specifies how to group
7823 source files. Each source file that has the same UNITY_GROUP
7824 value will be grouped together. Any sources that don't have this
7825 property will be compiled individually. The
7826 UNITY_BUILD_BATCH_SIZE property is ignored when using this mode.
7827 Example usage:
7829 add_library(example_library
7831 source1.cxx
7832 source2.cxx
7833 source3.cxx
7834 source4.cxx)
7835 set_target_properties(example_library PROPERTIES
7837 UNITY_BUILD_MODE GROUP
7838 )
7839 set_source_files_properties(source1.cxx source2.cxx source3.cxx
7841 PROPERTIES UNITY_GROUP "bucket1"
7842 )
7843 set_source_files_properties(source4.cxx
7844 PROPERTIES UNITY_GROUP "bucket2"
7845 )
7846 If no explicit UNITY_BUILD_MODE has been specified, CMake will default
7848 to BATCH.
7849 UNITY_BUILD_UNIQUE_ID
7851 New in version 3.20.
7852 The name of a valid C-identifier which is set to a unique per-file
7855 value during unity builds.
7856 When this property is populated and when UNITY_BUILD is true, the prop‐
7858 erty value is used to define a compiler definition of the specified
7859 name. The value of the defined symbol is unspecified, but it is unique
7860 per file path.
7861 Given:
7863 set_target_properties(myTarget PROPERTIES
7865 UNITY_BUILD "ON"
7866 UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID"
7867 )
7868 the MY_UNITY_ID symbol is defined to a unique per-file value.
7870 One known use case for this identifier is to disambiguate the variables
7872 in an anonymous namespace in a limited scope. Anonymous namespaces
7873 present a problem for unity builds because they are used to ensure that
7874 certain variables and declarations are scoped to a translation unit
7875 which is approximated by a single source file. When source files are
7876 combined in a unity build file, those variables in different files are
7877 combined in a single translation unit and the names clash. This prop‐
7878 erty can be used to avoid that with code like the following:
7879 // Needed for when unity builds are disabled
7881 #ifndef MY_UNITY_ID
7882 #define MY_UNITY_ID
7883 #endif
7884 namespace { namespace MY_UNITY_ID {
7886 // The name 'i' clashes (or could clash) with other
7887 // variables in other anonymous namespaces
7888 int i = 42;
7889 }}
7890 int use_var()
7892 {
7893 return MY_UNITY_ID::i;
7894 }
7895 The pseudonymous namespace is used within a truly anonymous namespace.
7897 On many platforms, this maintains the invariant that the symbols within
7898 do not get external linkage when performing a unity build.
7899 VERIFY_INTERFACE_HEADER_SETS
7901 New in version 3.24.
7902 Used to verify that all headers in a target's PUBLIC and INTERFACE
7905 header sets can be included on their own.
7906 When this property is set to true, and the target is an object library,
7908 static library, shared library, interface library, or executable with
7909 exports enabled, and the target has one or more PUBLIC or INTERFACE
7910 header sets, an object library target named <target_name>_verify_inter‐
7911 face_header_sets is created. This verification target has one source
7912 file per header in the PUBLIC and INTERFACE header sets. Each source
7913 file only includes its associated header file. The verification target
7914 links against the original target to get all of its usage requirements.
7915 The verification target has its EXCLUDE_FROM_ALL and
7916 DISABLE_PRECOMPILE_HEADERS properties set to true, and its AUTOMOC,
7917 AUTORCC, AUTOUIC, and UNITY_BUILD properties set to false.
7918 If the header's LANGUAGE property is set, the value of that property is
7920 used to determine the language with which to compile the header file.
7921 Otherwise, if the target has any C++ sources, the header is compiled as
7922 C++. Otherwise, if the target has any C sources, the header is com‐
7923 piled as C. Otherwise, if C++ is enabled globally, the header is com‐
7924 piled as C++. Otherwise, if C is enabled globally, the header is com‐
7925 piled as C. Otherwise, the header file is not compiled.
7926 If the header's SKIP_LINTING property is set to true, the file is not
7928 compiled.
7929 If any verification targets are created, a top-level target called
7931 all_verify_interface_header_sets is created which depends on all veri‐
7932 fication targets.
7933 This property is initialized by the value of the
7935 CMAKE_VERIFY_INTERFACE_HEADER_SETS variable if it is set when a target
7936 is created.
7937 If the project wishes to control which header sets are verified by this
7939 property, it can set INTERFACE_HEADER_SETS_TO_VERIFY.
7940 VERSION
7942 What version number is this target.
7943 For shared libraries VERSION and SOVERSION can be used to specify the
7945 build version and API version respectively. When building or in‐
7946 stalling appropriate symlinks are created if the platform supports sym‐
7947 links and the linker supports so-names. If only one of both is speci‐
7948 fied the missing is assumed to have the same version number. For exe‐
7949 cutables VERSION can be used to specify the build version. When build‐
7950 ing or installing appropriate symlinks are created if the platform sup‐
7951 ports symlinks.
7952 Windows Versions
7954 For shared libraries and executables on Windows the VERSION attribute
7955 is parsed to extract a <major>.<minor> version number. These numbers
7956 are used as the image version of the binary.
7957 Mach-O Versions
7959 For shared libraries and executables on Mach-O systems (e.g. macOS,
7960 iOS), the SOVERSION property corresponds to the compatibility version
7961 and VERSION corresponds to the current version (unless Mach-O specific
7962 overrides are provided, as discussed below). See the FRAMEWORK target
7963 property for an example.
7964 For shared libraries, the MACHO_COMPATIBILITY_VERSION and
7966 MACHO_CURRENT_VERSION properties can be used to override the compati‐
7967 bility version and current version respectively. Note that SOVERSION
7968 will still be used to form the install_name and both SOVERSION and VER‐
7969 SION may also affect the file and symlink names.
7970 Versions of Mach-O binaries may be checked with the otool -L <binary>
7972 command.
7973 VISIBILITY_INLINES_HIDDEN
7975 Whether to add a compile flag to hide symbols of inline functions
7976 The VISIBILITY_INLINES_HIDDEN property determines whether a flag for
7978 hiding symbols for inline functions, such as -fvisibility-inlines-hid‐
7979 den, should be used when invoking the compiler. This property affects
7980 compilation in sources of all types of targets (subject to policy
7981 CMP0063).
7982 This property is initialized by the value of the
7984 CMAKE_VISIBILITY_INLINES_HIDDEN variable if it is set when a target is
7985 created.
7986 VS_CONFIGURATION_TYPE
7988 New in version 3.6.
7989 Visual Studio project configuration type.
7992 Sets the ConfigurationType attribute for a generated Visual Studio
7994 project. The property value may use generator expressions. If this
7995 property is set, it overrides the default setting that is based on the
7996 target type (e.g. StaticLibrary, Application, ...).
7997 Supported on Visual Studio Generators for VS 2010 and higher.
7999 VS_DEBUGGER_COMMAND
8001 New in version 3.12.
8002 Sets the local debugger command for Visual Studio C++ targets. The
8005 property value may use generator expressions. This is defined in <Lo‐
8006 calDebuggerCommand> in the Visual Studio project file. This property
8007 is initialized by the value of the variable CMAKE_VS_DEBUGGER_COMMAND
8008 if it is set when a target is created.
8009 This property only works for Visual Studio 11 2012 and above; it is ig‐
8011 nored on other generators.
8012 VS_DEBUGGER_COMMAND_ARGUMENTS
8014 New in version 3.13.
8015 Sets the local debugger command line arguments for Visual Studio C++
8018 targets. The property value may use generator expressions. This is
8019 defined in <LocalDebuggerCommandArguments> in the Visual Studio project
8020 file. This property is initialized by the value of the variable
8021 CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS if it is set when a target is cre‐
8022 ated.
8023 This property only works for Visual Studio 11 2012 and above; it is ig‐
8025 nored on other generators.
8026 VS_DEBUGGER_ENVIRONMENT
8028 New in version 3.13.
8029 Sets the local debugger environment for Visual Studio C++ targets. The
8032 property value may use generator expressions. This is defined in <Lo‐
8033 calDebuggerEnvironment> in the Visual Studio project file. This prop‐
8034 erty is initialized by the value of the variable
8035 CMAKE_VS_DEBUGGER_ENVIRONMENT if it is set when a target is created.
8036 This property only works for Visual Studio 11 2012 and above; it is ig‐
8038 nored on other generators.
8039 VS_DEBUGGER_WORKING_DIRECTORY
8041 New in version 3.8.
8042 Sets the local debugger working directory for Visual Studio C++ tar‐
8045 gets. The property value may use generator expressions. This is de‐
8046 fined in <LocalDebuggerWorkingDirectory> in the Visual Studio project
8047 file. This property is initialized by the value of the variable
8048 CMAKE_VS_DEBUGGER_WORKING_DIRECTORY if it is set when a target is cre‐
8049 ated.
8050 This property only works for Visual Studio 11 2012 and above; it is ig‐
8052 nored on other generators.
8053 VS_DESKTOP_EXTENSIONS_VERSION
8055 New in version 3.4.
8056 Visual Studio Windows 10 Desktop Extensions Version
8059 Specifies the version of the Desktop Extensions that should be included
8061 in the target. For example 10.0.10240.0. If the value is not specified,
8062 the Desktop Extensions will not be included. To use the same version of
8063 the extensions as the Windows 10 SDK that is being used, you can use
8064 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
8065 VS_DOTNET_DOCUMENTATION_FILE
8067 New in version 3.17.
8068 Visual Studio managed project .NET documentation output
8071 Sets the target XML documentation file output.
8073 VS_DOTNET_REFERENCE_<refname>
8075 New in version 3.8.
8076 Visual Studio managed project .NET reference with name <refname> and
8079 hint path.
8080 Adds one .NET reference to generated Visual Studio project. The refer‐
8082 ence will have the name <refname> and will point to the assembly given
8083 as value of the property.
8084 See also VS_DOTNET_REFERENCES and VS_DOTNET_REFERENCES_COPY_LOCAL
8086 VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>
8088 New in version 3.10.
8089 Defines an XML property <tagname> for a .NET reference <refname>.
8092 Reference properties can be set for .NET references which are defined
8094 by the target properties VS_DOTNET_REFERENCES,
8095 VS_DOTNET_REFERENCE_<refname> and also for project references to other
8096 C# targets which are established by target_link_libraries().
8097 This property is only applicable to C# targets and Visual Studio gener‐
8099 ators 2010 and later.
8100 VS_DOTNET_REFERENCES
8102 Visual Studio managed project .NET references
8103 Adds one or more semicolon-delimited .NET references to a generated
8105 Visual Studio project. For example, "System;System.Windows.Forms".
8106 VS_DOTNET_REFERENCES_COPY_LOCAL
8108 New in version 3.8.
8109 Sets the Copy Local property for all .NET hint references in the target
8112 Boolean property to enable/disable copying of .NET hint references to
8114 output directory. The default is ON.
8115 VS_DOTNET_STARTUP_OBJECT
8117 New in version 3.24.
8118 Sets the startup object property in Visual Studio .NET targets. The
8121 property value defines a full qualified class name (including package
8122 name), for example: MyCompany.Package.MyStarterClass.
8123 If the property is unset, Visual Studio uses the first matching static
8125 void Main(string[]) function signature by default. When more than one
8126 Main() method is available in the current project, the property becomes
8127 mandatory for building the project.
8128 This property only works for Visual Studio 11 2012 and above; it is ig‐
8130 nored on other generators.
8131 set_property(TARGET ${TARGET_NAME} PROPERTY
8133 VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")
8134 VS_DOTNET_TARGET_FRAMEWORK_VERSION
8136 Specify the .NET target framework version.
8137 Used to specify the .NET target framework version for C++/CLI. For ex‐
8139 ample, "v4.5".
8140 This property is deprecated and should not be used anymore. Use
8142 DOTNET_TARGET_FRAMEWORK or DOTNET_TARGET_FRAMEWORK_VERSION instead.
8143 VS_DPI_AWARE
8145 New in version 3.16.
8146 Set the Manifest Tool -> Input and Output -> DPI Awareness in the Vis‐
8149 ual Studio target project properties.
8150 Valid values are PerMonitor, ON, or OFF.
8152 For example:
8154 add_executable(myproject myproject.cpp)
8156 set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor")
8157 VS_GLOBAL_KEYWORD
8159 Visual Studio project keyword for VS 10 (2010) and newer.
8160 Sets the "keyword" attribute for a generated Visual Studio project.
8162 Defaults to "Win32Proj". You may wish to override this value with
8163 "ManagedCProj", for example, in a Visual Studio managed C++ unit test
8164 project.
8165 Use the VS_KEYWORD target property to set the keyword for Visual Studio
8167 9 (2008) and older.
8168 VS_GLOBAL_PROJECT_TYPES
8170 Visual Studio project type(s).
8171 Can be set to one or more UUIDs recognized by Visual Studio to indicate
8173 the type of project. This value is copied verbatim into the generated
8174 project file. Example for a managed C++ unit testing project:
8175 {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}
8177 UUIDs are semicolon-delimited.
8179 VS_GLOBAL_ROOTNAMESPACE
8181 Visual Studio project root namespace.
8182 Sets the "RootNamespace" attribute for a generated Visual Studio
8184 project. The attribute will be generated only if this is set.
8185 VS_GLOBAL_<variable>
8187 Visual Studio project-specific global variable.
8188 Tell the Visual Studio generator to set the global variable '<vari‐
8190 able>' to a given value in the generated Visual Studio project. Ig‐
8191 nored on other generators. Qt integration works better if
8192 VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For ex‐
8193 ample, "4.7.3"
8194 VS_IOT_EXTENSIONS_VERSION
8196 New in version 3.4.
8197 Visual Studio Windows 10 IoT Extensions Version
8200 Specifies the version of the IoT Extensions that should be included in
8202 the target. For example 10.0.10240.0. If the value is not specified,
8203 the IoT Extensions will not be included. To use the same version of the
8204 extensions as the Windows 10 SDK that is being used, you can use the
8205 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
8206 VS_IOT_STARTUP_TASK
8208 New in version 3.4.
8209 Visual Studio Windows 10 IoT Continuous Background Task
8212 Specifies that the target should be compiled as a Continuous Background
8214 Task library.
8215 VS_JUST_MY_CODE_DEBUGGING
8217 New in version 3.15.
8218 Enable Just My Code with Visual Studio debugger.
8221 Supported on Visual Studio Generators for VS 2010 and higher, Makefile
8223 Generators and the Ninja generators.
8224 This property is initialized by the CMAKE_VS_JUST_MY_CODE_DEBUGGING
8226 variable if it is set when a target is created.
8227 VS_KEYWORD
8229 Visual Studio project keyword for VS 9 (2008) and older.
8230 Can be set to change the visual studio keyword, for example Qt integra‐
8232 tion works better if this is set to Qt4VSv1.0.
8233 Use the VS_GLOBAL_KEYWORD target property to set the keyword for Visual
8235 Studio 11 (2012) and newer.
8236 VS_MOBILE_EXTENSIONS_VERSION
8238 New in version 3.4.
8239 Visual Studio Windows 10 Mobile Extensions Version
8242 Specifies the version of the Mobile Extensions that should be included
8244 in the target. For example 10.0.10240.0. If the value is not specified,
8245 the Mobile Extensions will not be included. To use the same version of
8246 the extensions as the Windows 10 SDK that is being used, you can use
8247 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
8248 VS_NO_COMPILE_BATCHING
8250 New in version 3.24.
8251 Turn off compile batching for the target. Usually MSBuild calls the
8254 compiler with multiple c/cpp files and compiler starts subprocesses for
8255 each file to make the build parallel. If you want compiler to be in‐
8256 voked with one file at a time set VS_NO_COMPILE_BATCHING to ON. If this
8257 flag is set MSBuild will call compiler with one c/cpp file at a time.
8258 Useful when you want to use tool that replaces the compiler, for exam‐
8259 ple some build caching tool.
8260 This property is initialized by the CMAKE_VS_NO_COMPILE_BATCHING vari‐
8262 able if it is set when a target is created.
8263 Example
8265 This shows setting the property for the target foo.
8266 add_library(foo SHARED foo.cpp)
8268 set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)
8269 VS_NO_SOLUTION_DEPLOY
8271 New in version 3.15.
8272 Specify that the target should not be marked for deployment to a Win‐
8275 dows CE or Windows Phone device in the generated Visual Studio solu‐
8276 tion.
8277 Be default, all EXE and shared library (DLL) targets are marked to de‐
8279 ploy to the target device in the generated Visual Studio solution.
8280 Generator expressions are supported.
8282 There are reasons one might want to exclude a target / generated
8284 project from deployment:
8285 • The library or executable may not be necessary in the primary de‐
8287 ploy/debug scenario, and excluding from deployment saves time in the
8288 develop/download/debug cycle.
8289 • There may be insufficient space on the target device to accommodate
8291 all of the build products.
8292 • Visual Studio 2013 requires a target device IP address be entered for
8294 each target marked for deployment. For large numbers of targets,
8295 this can be tedious. NOTE: Visual Studio will deploy all project de‐
8296 pendencies of a project tagged for deployment to the IP address con‐
8297 figured for that project even if those dependencies are not tagged
8298 for deployment.
8299 Example 1
8301 This shows setting the variable for the target foo.
8302 add_library(foo SHARED foo.cpp)
8304 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON)
8305 Example 2
8307 This shows setting the variable for the Release configuration only.
8308 add_library(foo SHARED foo.cpp)
8310 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>")
8311 VS_PACKAGE_REFERENCES
8313 New in version 3.15.
8314 Visual Studio package references for nuget.
8317 Adds one or more semicolon-delimited package references to a generated
8319 Visual Studio project. The version of the package will be underscore
8320 delimited. For example, boost_1.7.0;nunit_3.12.*.
8321 set_property(TARGET ${TARGET_NAME} PROPERTY
8323 VS_PACKAGE_REFERENCES "boost_1.7.0")
8324 VS_PLATFORM_TOOLSET
8326 New in version 3.18.
8327 Overrides the platform toolset used to build a target.
8330 Only supported when the compiler used by the given toolset is the same
8332 as the compiler used to build the whole source tree.
8333 This is especially useful to create driver projects with the toolsets
8335 "WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0".
8336 VS_PROJECT_IMPORT
8338 New in version 3.15.
8339 Visual Studio managed project imports
8342 Adds to a generated Visual Studio project one or more semicolon-delim‐
8344 ited paths to .props files needed when building projects from some
8345 NuGet packages. For example, my_packages_path/MyPack‐
8346 age.1.0.0/build/MyPackage.props.
8347 VS_SCC_AUXPATH
8349 Visual Studio Source Code Control Aux Path.
8350 Can be set to change the visual studio source code control auxpath
8352 property.
8353 VS_SCC_LOCALPATH
8355 Visual Studio Source Code Control Local Path.
8356 Can be set to change the visual studio source code control local path
8358 property.
8359 VS_SCC_PROJECTNAME
8361 Visual Studio Source Code Control Project.
8362 Can be set to change the visual studio source code control project name
8364 property.
8365 VS_SCC_PROVIDER
8367 Visual Studio Source Code Control Provider.
8368 Can be set to change the visual studio source code control provider
8370 property.
8371 VS_SDK_REFERENCES
8373 New in version 3.7.
8374 Visual Studio project SDK references. Specify a semicolon-separated
8377 list of SDK references to be added to a generated Visual Studio
8378 project, e.g. Microsoft.AdMediatorWindows81, Version=1.0.
8379 VS_SOLUTION_DEPLOY
8381 New in version 3.18.
8382 Specify that the target should be marked for deployment when not tar‐
8385 geting Windows CE, Windows Phone or a Windows Store application.
8386 If the target platform doesn't support deployment, this property won't
8388 have any effect.
8389 Generator expressions are supported.
8391 Examples
8393 Always deploy target foo:
8394 add_executable(foo SHARED foo.cpp)
8396 set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)
8397 Deploy target foo for all configurations except Release:
8399 add_executable(foo SHARED foo.cpp)
8401 set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")
8402 VS_SOURCE_SETTINGS_<tool>
8404 New in version 3.18.
8405 Set any item metadata on all non-built files that use <tool>.
8408 Takes a list of Key=Value pairs. Tells the Visual Studio generator to
8410 set Key to Value as item metadata on all non-built files that use
8411 <tool>.
8412 For example:
8414 set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")
8416 will set Key to Value and Key2 to Value2 for all non-built files that
8418 use FXCompile.
8419 Generator expressions are supported.
8421 VS_USER_PROPS
8423 New in version 3.8.
8424 Sets the user props file to be included in the visual studio C++
8427 project file. The standard path is $(UserRootDir)\\Micro‐
8428 soft.Cpp.$(Platform).user.props, which is in most cases the same as
8429 %LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Micro‐
8430 soft.Cpp.Win32.user.props or %LOCALAPPDATA%\\Microsoft\\MS‐
8431 Build\\v4.0\\Microsoft.Cpp.x64.user.props.
8432 The *.user.props files can be used for Visual Studio wide configuration
8434 which is independent from cmake.
8435 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
8437 New in version 3.4.
8438 Visual Studio Windows Target Platform Minimum Version
8441 For Windows 10. Specifies the minimum version of the OS that is being
8443 targeted. For example 10.0.10240.0. If the value is not specified, the
8444 value of the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable will be
8445 used on WindowsStore projects. Otherwise the target platform minimum
8446 version will not be specified for the project.
8447 New in version 3.27: This property is initialized by the value of the
8449 CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION variable if it is set when
8450 a target is created.
8451 VS_WINRT_COMPONENT
8454 New in version 3.1.
8455 Mark a target as a Windows Runtime component for the Visual Studio gen‐
8458 erator. Compile the target with C++/CX language extensions for Windows
8459 Runtime. For SHARED and MODULE libraries, this also defines the
8460 _WINRT_DLL preprocessor macro.
8461 NOTE:
8463 Currently this is implemented only by Visual Studio generators.
8464 Support may be added to other generators in the future.
8465 VS_WINRT_EXTENSIONS
8467 Deprecated. Use VS_WINRT_COMPONENT instead. This property was an ex‐
8468 perimental partial implementation of that one.
8469 VS_WINRT_REFERENCES
8471 Visual Studio project Windows Runtime Metadata references
8472 Adds one or more semicolon-delimited WinRT references to a generated
8474 Visual Studio project. For example, "Windows;Windows.UI.Core".
8475 WATCOM_RUNTIME_LIBRARY
8477 New in version 3.24.
8478 Select the Watcom runtime library for use by compilers targeting the
8481 Watcom ABI.
8482 The allowed values are:
8484 SingleThreaded
8486 Compile without additional flags to use a single-threaded stati‐
8487 cally-linked runtime library.
8488 SingleThreadedDLL
8490 Compile with -br or equivalent flag(s) to use a single-threaded
8491 dynamically-linked runtime library. This is not available for
8492 Linux targets.
8493 MultiThreaded
8495 Compile with -bm or equivalent flag(s) to use a multi-threaded
8496 statically-linked runtime library.
8497 MultiThreadedDLL
8499 Compile with -bm -br or equivalent flag(s) to use a
8500 multi-threaded dynamically-linked runtime library. This is not
8501 available for Linux targets.
8502 The value is ignored on non-Watcom compilers but an unsupported value
8504 will be rejected as an error when using a compiler targeting the Watcom
8505 ABI.
8506 The value may also be the empty string ("") in which case no runtime
8508 library selection flag will be added explicitly by CMake.
8509 Use generator expressions to support per-configuration specification.
8511 For example, the code:
8513 add_executable(foo foo.c)
8515 set_property(TARGET foo PROPERTY
8516 WATCOM_RUNTIME_LIBRARY "MultiThreaded")
8517 selects for the target foo a multi-threaded statically-linked runtime
8519 library.
8520 If this property is not set then CMake uses the default value Multi‐
8522 ThreadedDLL on Windows and SingleThreaded on other platforms to select
8523 a Watcom runtime library.
8524 NOTE:
8526 This property has effect only when policy CMP0136 is set to NEW
8527 prior to the first project() or enable_language() command that en‐
8528 ables a language using a compiler targeting the Watcom ABI.
8529 WIN32_EXECUTABLE
8531 Build an executable with a WinMain entry point on windows.
8532 When this property is set to true the executable when linked on Windows
8534 will be created with a WinMain() entry point instead of just main().
8535 This makes it a GUI executable instead of a console application. See
8536 the CMAKE_MFC_FLAG variable documentation to configure use of the Mi‐
8537 crosoft Foundation Classes (MFC) for WinMain executables. This prop‐
8538 erty is initialized by the value of the CMAKE_WIN32_EXECUTABLE variable
8539 if it is set when a target is created.
8540 This property supports generator expressions, except if the target is
8542 managed (contains C# code.)
8543 WINDOWS_EXPORT_ALL_SYMBOLS
8545 New in version 3.4.
8546 This property is implemented only for MS-compatible tools on Windows.
8549 Enable this boolean property to automatically create a module defini‐
8551 tion (.def) file with all global symbols found in the input .obj files
8552 for a SHARED library (or executable with ENABLE_EXPORTS) on Windows.
8553 The module definition file will be passed to the linker causing all
8554 symbols to be exported from the .dll. For global data symbols, __de‐
8555 clspec(dllimport) must still be used when compiling against the code in
8556 the .dll. All other function symbols will be automatically exported
8557 and imported by callers. This simplifies porting projects to Windows
8558 by reducing the need for explicit dllexport markup, even in C++
8559 classes.
8560 When this property is enabled, zero or more .def files may also be
8562 specified as source files of the target. The exports named by these
8563 files will be merged with those detected from the object files to gen‐
8564 erate a single module definition file to be passed to the linker. This
8565 can be used to export symbols from a .dll that are not in any of its
8566 object files but are added by the linker from dependencies (e.g.
8567 msvcrt.lib).
8568 This property is initialized by the value of the
8570 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS variable if it is set when a target is
8571 created.
8572 XCODE_ATTRIBUTE_<an-attribute>
8574 Set Xcode target attributes directly.
8575 Tell the Xcode generator to set <an-attribute> to a given value in the
8577 generated Xcode project. Ignored on other generators.
8578 This offers low-level control over the generated Xcode project file.
8580 It is meant as a last resort for specifying settings that CMake does
8581 not otherwise have a way to control. Although this can override a set‐
8582 ting CMake normally produces on its own, doing so bypasses CMake's
8583 model of the project and can break things.
8584 See the CMAKE_XCODE_ATTRIBUTE_<an-attribute> variable to set attributes
8586 on all targets in a directory tree.
8587 Contents of XCODE_ATTRIBUTE_<an-attribute> may use "generator expres‐
8589 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
8590 manual for available expressions. See the cmake-buildsystem(7) manual
8591 for more on defining buildsystem properties.
8592 XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY
8594 New in version 3.20.
8595 Tell the Xcode generator to perform code signing for all the frameworks
8598 and libraries that are embedded using the XCODE_EMBED_FRAMEWORKS prop‐
8599 erty.
8600 New in version 3.21.
8602 This property was generalized to other types of embedded items. See
8605 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY for the more general form.
8606 XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY
8608 New in version 3.20.
8609 Tell the Xcode generator to remove headers from all the frameworks that
8612 are embedded using the XCODE_EMBED_FRAMEWORKS property.
8613 New in version 3.21.
8615 This property was generalized to other types of embedded items. See
8618 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY for the more general form.
8619 XCODE_EMBED_<type>
8621 New in version 3.20.
8622 Tell the Xcode generator to embed the specified list of items into the
8625 target bundle. <type> specifies the embed build phase to use. See the
8626 Xcode documentation for the base location of each <type>.
8627 The supported values for <type> are:
8629 FRAMEWORKS
8631 The specified items will be added to the Embed Frameworks build
8632 phase. The items can be CMake target names or paths to frame‐
8633 works or libraries.
8634 APP_EXTENSIONS
8636 New in version 3.21.
8637 The specified items will be added to the Embed App Extensions
8640 build phase, with Destination set to PlugIns and Foundation Ex‐
8641 tensions They must be CMake target names.
8642 EXTENSIONKIT_EXTENSIONS
8644 New in version 3.26.
8645 The specified items will be added to the Embed App Extensions
8648 build phase, with Destination set to ExtensionKit Extensions
8649 They must be CMake target names, and should likely have the
8650 XCODE_PRODUCT_TYPE target property set to com.apple.prod‐
8651 uct-type.extensionkit-extension as well as the XCODE_EX‐
8652 PLICIT_FILE_TYPE to wrapper.extensionkit-extension
8653 PLUGINS
8655 New in version 3.23.
8656 The specified items will be added to the Embed PlugIns build
8659 phase. They must be CMake target names.
8660 See also XCODE_EMBED_<type>_PATH,
8662 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY and
8663 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY.
8664 XCODE_EMBED_<type>_CODE_SIGN_ON_COPY
8666 New in version 3.20.
8667 Boolean property used only by the Xcode generator. It specifies
8670 whether to perform code signing for the items that are embedded using
8671 the XCODE_EMBED_<type> property.
8672 The supported values for <type> are:
8674 FRAMEWORKS
8676 APP_EXTENSIONS
8678 New in version 3.21.
8679 EXTENSIONKIT_EXTENSIONS
8682 New in version 3.26.
8683 PLUGINS
8686 New in version 3.23.
8687 If a XCODE_EMBED_<type>_CODE_SIGN_ON_COPY property is not defined on
8690 the target, no code signing on copy will be performed for that <type>.
8691 XCODE_EMBED_<type>_PATH
8693 New in version 3.20.
8694 This property is used only by the Xcode generator. When defined, it
8697 specifies the relative path to use when embedding the items specified
8698 by XCODE_EMBED_<type>. The path is relative to the base location of
8699 the Embed XXX build phase associated with <type>. See the Xcode docu‐
8700 mentation for the base location of each <type>.
8701 The supported values for <type> are:
8703 FRAMEWORKS
8705 APP_EXTENSIONS
8707 New in version 3.21.
8708 EXTENSIONKIT_EXTENSIONS
8711 New in version 3.26.
8712 PLUGINS
8715 New in version 3.23.
8716 XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY
8719 New in version 3.20.
8720 Boolean property used only by the Xcode generator. It specifies
8723 whether to remove headers from all the frameworks that are embedded us‐
8724 ing the XCODE_EMBED_<type> property.
8725 The supported values for <type> are:
8727 FRAMEWORKS
8729 If the XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY property is
8730 not defined, headers will not be removed on copy by default.
8731 APP_EXTENSIONS
8733 New in version 3.21.
8734 If the XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY prop‐
8737 erty is not defined, headers WILL be removed on copy by default.
8738 EXTENSIONKIT_EXTENSIONS
8740 New in version 3.26.
8741 If the XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY prop‐
8744 erty is not defined, headers WILL be removed on copy by default.
8745 PLUGINS
8747 New in version 3.23.
8748 XCODE_EXPLICIT_FILE_TYPE
8751 New in version 3.8.
8752 Set the Xcode explicitFileType attribute on its reference to a target.
8755 CMake computes a default based on target type but can be told explic‐
8756 itly with this property.
8757 See also XCODE_PRODUCT_TYPE.
8759 XCODE_GENERATE_SCHEME
8761 New in version 3.15.
8762 If enabled, the Xcode generator will generate schema files. These are
8765 useful to invoke analyze, archive, build-for-testing and test actions
8766 from the command line.
8767 This property is initialized by the value of the variable
8769 CMAKE_XCODE_GENERATE_SCHEME if it is set when a target is created.
8770 The following target properties overwrite the default of the corre‐
8772 sponding settings on the "Diagnostic" tab for each schema file. Each
8773 of those is initialized by the respective CMAKE_ variable at target
8774 creation time.
8775 • XCODE_SCHEME_ADDRESS_SANITIZER
8777 • XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
8779 • XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
8781 • XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
8783 • XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
8785 • XCODE_SCHEME_GUARD_MALLOC
8787 • XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
8789 • XCODE_SCHEME_MALLOC_GUARD_EDGES
8791 • XCODE_SCHEME_MALLOC_SCRIBBLE
8793 • XCODE_SCHEME_MALLOC_STACK
8795 • XCODE_SCHEME_THREAD_SANITIZER
8797 • XCODE_SCHEME_THREAD_SANITIZER_STOP
8799 • XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
8801 • XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
8803 • XCODE_SCHEME_LAUNCH_CONFIGURATION
8805 • XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
8807 • XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
8809 • XCODE_SCHEME_ZOMBIE_OBJECTS
8811 The following target properties will be applied on the "Info", "Argu‐
8813 ments", and "Options" tab:
8814 • XCODE_SCHEME_ARGUMENTS
8816 • XCODE_SCHEME_DEBUG_AS_ROOT
8818 • XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
8820 • XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
8822 • XCODE_SCHEME_ENVIRONMENT
8824 • XCODE_SCHEME_EXECUTABLE
8826 • XCODE_SCHEME_LAUNCH_MODE
8828 • XCODE_SCHEME_WORKING_DIRECTORY
8830 XCODE_LINK_BUILD_PHASE_MODE
8832 New in version 3.19.
8833 When using the Xcode generator, libraries to be linked will be speci‐
8836 fied in the Xcode project file using either the "Link Binary With Li‐
8837 braries" build phase or directly as linker flags. The former allows
8838 Xcode to manage build paths, which may be necessary when creating Xcode
8839 archives because it may use different build paths to a regular build.
8840 This property controls usage of "Link Binary With Libraries" build
8842 phase for a target that is an app bundle, executable, shared library,
8843 shared framework or a module library.
8844 Possible values are:
8846 • NONE The libraries will be linked by specifying the linker flags di‐
8848 rectly.
8849 • BUILT_ONLY The "Link Binary With Libraries" build phase will be used
8851 to link to another target under the following conditions:
8852 • The target to be linked to is a regular non-imported, non-interface
8854 library target.
8855 • The output directory of the target being built has not been changed
8857 from its default (see RUNTIME_OUTPUT_DIRECTORY and
8858 LIBRARY_OUTPUT_DIRECTORY).
8859 • KNOWN_LOCATION The "Link Binary With Libraries" build phase will be
8861 used to link to another target under the same conditions as with
8862 BUILT_ONLY and also:
8863 • Imported library targets except those of type UNKNOWN.
8865 • Any non-target library specified directly with a path.
8867 For all other cases, the libraries will be linked by specifying the
8869 linker flags directly.
8870 WARNING:
8872 Libraries linked using "Link Binary With Libraries" are linked after
8873 the ones linked through regular linker flags. This order should be
8874 taken into account when different static libraries contain symbols
8875 with the same name, as the former ones will take precedence over the
8876 latter.
8877 WARNING:
8879 If two or more directories contain libraries with identical file
8880 names and some libraries are linked from those directories, the li‐
8881 brary search path lookup will end up linking libraries from the
8882 first directory. This is a known limitation of Xcode.
8883 This property is initialized by the value of the
8885 CMAKE_XCODE_LINK_BUILD_PHASE_MODE variable if it is set when a target
8886 is created.
8887 XCODE_PRODUCT_TYPE
8889 New in version 3.8.
8890 Set the Xcode productType attribute on its reference to a target.
8893 CMake computes a default based on target type but can be told explic‐
8894 itly with this property.
8895 See also XCODE_EXPLICIT_FILE_TYPE.
8897 XCODE_SCHEME_ADDRESS_SANITIZER
8899 New in version 3.13.
8900 Whether to enable Address Sanitizer in the Diagnostics section of the
8903 generated Xcode scheme.
8904 This property is initialized by the value of the variable
8906 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER if it is set when a target is cre‐
8907 ated.
8908 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8910 to see all Xcode schema related properties.
8911 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
8913 New in version 3.13.
8914 Whether to enable Detect use of stack after return in the Diagnostics
8917 section of the generated Xcode scheme.
8918 This property is initialized by the value of the variable
8920 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN if it is set when
8921 a target is created.
8922 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8924 to see all Xcode schema related properties.
8925 XCODE_SCHEME_ARGUMENTS
8927 New in version 3.13.
8928 Specify command line arguments that should be added to the Arguments
8931 section of the generated Xcode scheme.
8932 If set to a list of arguments those will be added to the scheme.
8934 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8936 to see all Xcode schema related properties.
8937 XCODE_SCHEME_DEBUG_AS_ROOT
8939 New in version 3.15.
8940 Whether to debug the target as 'root'.
8943 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8945 to see all Xcode schema related properties.
8946 XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
8948 New in version 3.16.
8949 Whether to enable Allow debugging when using document Versions Browser
8952 in the Options section of the generated Xcode scheme.
8953 This property is initialized by the value of the variable
8955 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING if it is set when a target
8956 is created.
8957 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8959 to see all Xcode schema related properties.
8960 XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
8962 New in version 3.13.
8963 Whether to disable the Main Thread Checker in the Diagnostics section
8966 of the generated Xcode scheme.
8967 This property is initialized by the value of the variable
8969 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER if it is set when a tar‐
8970 get is created.
8971 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8973 to see all Xcode schema related properties.
8974 XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
8976 New in version 3.13.
8977 Whether to enable Dynamic Library Loads in the Diagnostics section of
8980 the generated Xcode scheme.
8981 This property is initialized by the value of the variable
8983 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS if it is set when a target is
8984 created.
8985 Please refer to the XCODE_GENERATE_SCHEME target property documentation
8987 to see all Xcode schema related properties.
8988 XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
8990 New in version 3.13.
8991 Whether to enable Dynamic Linker API usage in the Diagnostics section
8994 of the generated Xcode scheme.
8995 This property is initialized by the value of the variable
8997 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE if it is set when a target
8998 is created.
8999 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9001 to see all Xcode schema related properties.
9002 XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
9004 New in version 3.25.
9005 Property value for Metal: API Validation in the Options section of the
9008 generated Xcode scheme.
9009 This property is initialized by the value of the variable
9011 CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION if it is set when a target
9012 is created.
9013 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9015 to see all Xcode schema related properties.
9016 XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
9018 New in version 3.23.
9019 Property value for GPU Frame Capture in the Options section of the gen‐
9022 erated Xcode scheme. Example values are Metal and Disabled.
9023 This property is initialized by the value of the variable
9025 CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE if it is set when a
9026 target is created.
9027 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9029 to see all Xcode schema related properties.
9030 XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
9032 New in version 3.25.
9033 Property value for Metal: Shader Validation in the Options section of
9036 the generated Xcode scheme.
9037 This property is initialized by the value of the variable
9039 CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION if it is set when a
9040 target is created.
9041 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9043 to see all Xcode schema related properties.
9044 XCODE_SCHEME_ENVIRONMENT
9046 New in version 3.13.
9047 Specify environment variables that should be added to the Arguments
9050 section of the generated Xcode scheme.
9051 If set to a list of environment variables and values of the form MY‐
9053 VAR=value those environment variables will be added to the scheme.
9054 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9056 to see all Xcode schema related properties.
9057 XCODE_SCHEME_EXECUTABLE
9059 New in version 3.13.
9060 Specify path to executable in the Info section of the generated Xcode
9063 scheme. If not set the schema generator will select the current target
9064 if it is actually executable.
9065 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9067 to see all Xcode schema related properties.
9068 XCODE_SCHEME_GUARD_MALLOC
9070 New in version 3.13.
9071 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
9074 ated Xcode scheme.
9075 This property is initialized by the value of the variable
9077 CMAKE_XCODE_SCHEME_GUARD_MALLOC if it is set when a target is created.
9078 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9080 to see all Xcode schema related properties.
9081 XCODE_SCHEME_LAUNCH_CONFIGURATION
9083 New in version 3.25.
9084 Set the build configuration to run the target.
9087 This property is initialized by the value of the variable
9089 CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION if it is set when a target is
9090 created.
9091 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9093 to see all Xcode schema related properties.
9094 XCODE_SCHEME_LAUNCH_MODE
9096 New in version 3.25.
9097 Property value for Launch in the Info section of the generated Xcode
9100 scheme.
9101 Possible values are:
9103 AUTO Launch automatically. This is the default.
9105 WAIT Wait for the executable to be launched.
9107 This property is initialized by the value of the variable
9109 CMAKE_XCODE_SCHEME_LAUNCH_MODE if it is set when a target is created.
9110 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9112 to see all Xcode schema related properties.
9113 XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
9115 New in version 3.13.
9116 Whether to enable the Main Thread Checker option Pause on issues in the
9119 Diagnostics section of the generated Xcode scheme.
9120 This property is initialized by the value of the variable
9122 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP if it is set when a target
9123 is created.
9124 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9126 to see all Xcode schema related properties.
9127 XCODE_SCHEME_MALLOC_GUARD_EDGES
9129 New in version 3.13.
9130 Whether to enable Malloc Guard Edges in the Diagnostics section of the
9133 generated Xcode scheme.
9134 This property is initialized by the value of the variable
9136 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES if it is set when a target is
9137 created.
9138 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9140 to see all Xcode schema related properties.
9141 XCODE_SCHEME_MALLOC_SCRIBBLE
9143 New in version 3.13.
9144 Whether to enable Malloc Scribble in the Diagnostics section of the
9147 generated Xcode scheme.
9148 This property is initialized by the value of the variable
9150 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE if it is set when a target is cre‐
9151 ated.
9152 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9154 to see all Xcode schema related properties.
9155 XCODE_SCHEME_MALLOC_STACK
9157 New in version 3.13.
9158 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
9161 ated Xcode scheme.
9162 This property is initialized by the value of the variable
9164 CMAKE_XCODE_SCHEME_MALLOC_STACK if it is set when a target is created.
9165 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9167 to see all Xcode schema related properties.
9168 XCODE_SCHEME_THREAD_SANITIZER
9170 New in version 3.13.
9171 Whether to enable Thread Sanitizer in the Diagnostics section of the
9174 generated Xcode scheme.
9175 This property is initialized by the value of the variable
9177 CMAKE_XCODE_SCHEME_THREAD_SANITIZER if it is set when a target is cre‐
9178 ated.
9179 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9181 to see all Xcode schema related properties.
9182 XCODE_SCHEME_THREAD_SANITIZER_STOP
9184 New in version 3.13.
9185 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
9188 section of the generated Xcode scheme.
9189 This property is initialized by the value of the variable
9191 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP if it is set when a target is
9192 created.
9193 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9195 to see all Xcode schema related properties.
9196 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
9198 New in version 3.13.
9199 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
9202 tion of the generated Xcode scheme.
9203 This property is initialized by the value of the variable
9205 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER if it is set when a
9206 target is created.
9207 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9209 to see all Xcode schema related properties.
9210 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
9212 New in version 3.13.
9213 Whether to enable Undefined Behavior Sanitizer option Pause on issues
9216 in the Diagnostics section of the generated Xcode scheme.
9217 This property is initialized by the value of the variable
9219 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP if it is set when
9220 a target is created.
9221 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9223 to see all Xcode schema related properties.
9224 XCODE_SCHEME_WORKING_DIRECTORY
9226 New in version 3.17.
9227 Specify the Working Directory of the Run and Profile actions in the
9230 generated Xcode scheme. In case the value contains generator expres‐
9231 sions those are evaluated.
9232 This property is initialized by the value of the variable
9234 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY if it is set when a target is cre‐
9235 ated.
9236 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9238 to see all Xcode schema related properties.
9239 XCODE_SCHEME_ZOMBIE_OBJECTS
9241 New in version 3.13.
9242 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
9245 erated Xcode scheme.
9246 This property is initialized by the value of the variable
9248 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS if it is set when a target is cre‐
9249 ated.
9250 Please refer to the XCODE_GENERATE_SCHEME target property documentation
9252 to see all Xcode schema related properties.
9253 XCODE_XCCONFIG
9255 New in version 3.24.
9256 If set, the Xcode generator will register the specified file as a tar‐
9259 get-level XCConfig file. For global XCConfig files see the
9260 CMAKE_XCODE_XCCONFIG variable.
9261 This feature is intended to ease migration from native Xcode projects
9263 to CMake projects.
9264 Contents of XCODE_XCCONFIG may use generator expressions.
9266 XCTEST
9268 New in version 3.3.
9269 This target is a XCTest CFBundle on the Mac.
9272 This property will usually get set via the xctest_add_bundle() macro in
9274 FindXCTest module.
9275 If a module library target has this property set to true it will be
9277 built as a CFBundle when built on the Mac. It will have the directory
9278 structure required for a CFBundle.
9279 This property depends on BUNDLE to be effective.
9281
9283 ATTACHED_FILES
9284 Attach a list of files to a dashboard submission.
9285 Set this property to a list of files that will be encoded and submitted
9287 to the dashboard as an addition to the test result.
9288 ATTACHED_FILES_ON_FAIL
9290 Attach a list of files to a dashboard submission if the test fails.
9291 Same as ATTACHED_FILES, but these files will only be included if the
9293 test does not pass.
9294 COST
9296 This property describes the cost of a test. When parallel testing is
9297 enabled, tests in the test set will be run in descending order of cost.
9298 Projects can explicitly define the cost of a test by setting this prop‐
9299 erty to a floating point value.
9300 When the cost of a test is not defined by the project, ctest will ini‐
9302 tially use a default cost of 0. It computes a weighted average of the
9303 cost each time a test is run and uses that as an improved estimate of
9304 the cost for the next run. The more a test is re-run in the same build
9305 directory, the more representative the cost should become.
9306 DEPENDS
9308 Specifies that this test should only be run after the specified list of
9309 tests.
9310 Set this to a list of tests that must finish before this test is run.
9312 The results of those tests are not considered, the dependency relation‐
9313 ship is purely for order of execution (i.e. it is really just a run af‐
9314 ter relationship). Consider using test fixtures with setup tests if a
9315 dependency with successful completion is required (see
9316 FIXTURES_REQUIRED).
9317 Examples
9319 add_test(NAME baseTest1 ...)
9320 add_test(NAME baseTest2 ...)
9321 add_test(NAME dependsTest12 ...)
9322 set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2")
9324 # dependsTest12 runs after baseTest1 and baseTest2, even if they fail
9325 DISABLED
9327 New in version 3.9.
9328 If set to True, the test will be skipped and its status will be 'Not
9331 Run'. A DISABLED test will not be counted in the total number of tests
9332 and its completion status will be reported to CDash as Disabled.
9333 A DISABLED test does not participate in test fixture dependency resolu‐
9335 tion. If a DISABLED test has fixture requirements defined in its
9336 FIXTURES_REQUIRED property, it will not cause setup or cleanup tests
9337 for those fixtures to be added to the test set.
9338 If a test with the FIXTURES_SETUP property set is DISABLED, the fixture
9340 behavior will be as though that setup test was passing and any test
9341 case requiring that fixture will still run.
9342 ENVIRONMENT
9344 Specify environment variables that should be defined for running a
9345 test.
9346 Set to a semicolon-separated list list of environment variables and
9348 values of the form MYVAR=value. Those environment variables will be
9349 defined while running the test. The environment changes from this
9350 property do not affect other tests.
9351 ENVIRONMENT_MODIFICATION
9353 New in version 3.22.
9354 Specify environment variables that should be modified for running a
9357 test. Note that the operations performed by this property are performed
9358 after the ENVIRONMENT property is already applied.
9359 Set to a semicolon-separated list of environment variables and values
9361 of the form MYVAR=OP:VALUE, where MYVAR is the case-sensitive name of
9362 an environment variable to be modified. Entries are considered in the
9363 order specified in the property's value. The OP may be one of:
9364 • reset: Reset to the unmodified value, ignoring all modifications
9366 to MYVAR prior to this entry. Note that this will reset the vari‐
9367 able to the value set by ENVIRONMENT, if it was set, and otherwise
9368 to its state from the rest of the CTest execution.
9369 • set: Replaces the current value of MYVAR with VALUE.
9371 • unset: Unsets the current value of MYVAR.
9373 • string_append: Appends singular VALUE to the current value of MY‐
9375 VAR.
9376 • string_prepend: Prepends singular VALUE to the current value of
9378 MYVAR.
9379 • path_list_append: Appends singular VALUE to the current value of
9381 MYVAR using the host platform's path list separator (; on Windows
9382 and : elsewhere).
9383 • path_list_prepend: Prepends singular VALUE to the current value of
9385 MYVAR using the host platform's path list separator (; on Windows
9386 and : elsewhere).
9387 • cmake_list_append: Appends singular VALUE to the current value of
9389 MYVAR using ; as the separator.
9390 • cmake_list_prepend: Prepends singular VALUE to the current value
9392 of MYVAR using ; as the separator.
9393 Unrecognized OP values will result in the test failing before it is ex‐
9395 ecuted. This is so that future operations may be added without changing
9396 valid behavior of existing tests.
9397 The environment changes from this property do not affect other tests.
9399 FAIL_REGULAR_EXPRESSION
9401 If the output matches this regular expression the test will fail, re‐
9402 gardless of the process exit code.
9403 If set, if the output matches one of specified regular expressions, the
9405 test will fail. Example:
9406 set_tests_properties(mytest PROPERTIES
9408 FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
9409 )
9410 FAIL_REGULAR_EXPRESSION expects a list of regular expressions.
9412 See also the PASS_REGULAR_EXPRESSION and SKIP_REGULAR_EXPRESSION test
9414 properties.
9415 FIXTURES_CLEANUP
9417 New in version 3.7.
9418 Specifies a list of fixtures for which the test is to be treated as a
9421 cleanup test. These fixture names are distinct from test case names and
9422 are not required to have any similarity to the names of tests associ‐
9423 ated with them.
9424 Fixture cleanup tests are ordinary tests with all of the usual test
9426 functionality. Setting the FIXTURES_CLEANUP property for a test has two
9427 primary effects:
9428 • CTest will ensure the test executes after all other tests which list
9430 any of the fixtures in its FIXTURES_REQUIRED property.
9431 • If CTest is asked to run only a subset of tests (e.g. using regular
9433 expressions or the --rerun-failed option) and the cleanup test is not
9434 in the set of tests to run, it will automatically be added if any
9435 tests in the set require any fixture listed in FIXTURES_CLEANUP.
9436 A cleanup test can have multiple fixtures listed in its FIX‐
9438 TURES_CLEANUP property. It will execute only once for the whole CTest
9439 run, not once for each fixture. A fixture can also have more than one
9440 cleanup test defined. If there are multiple cleanup tests for a fix‐
9441 ture, projects can control their order with the usual DEPENDS test
9442 property if necessary.
9443 A cleanup test is allowed to require other fixtures, but not any fix‐
9445 ture listed in its FIXTURES_CLEANUP property. For example:
9446 # Ok: Dependent fixture is different to cleanup
9448 set_tests_properties(cleanupFoo PROPERTIES
9449 FIXTURES_CLEANUP Foo
9450 FIXTURES_REQUIRED Bar
9451 )
9452 # Error: cannot require same fixture as cleanup
9454 set_tests_properties(cleanupFoo PROPERTIES
9455 FIXTURES_CLEANUP Foo
9456 FIXTURES_REQUIRED Foo
9457 )
9458 Cleanup tests will execute even if setup or regular tests for that fix‐
9460 ture fail or are skipped.
9461 See FIXTURES_REQUIRED for a more complete discussion of how to use test
9463 fixtures.
9464 FIXTURES_REQUIRED
9466 New in version 3.7.
9467 Specifies a list of fixtures the test requires. Fixture names are case
9470 sensitive and they are not required to have any similarity to test
9471 names.
9472 Fixtures are a way to attach setup and cleanup tasks to a set of tests.
9474 If a test requires a given fixture, then all tests marked as setup
9475 tasks for that fixture will be executed first (once for the whole set
9476 of tests, not once per test requiring the fixture). After all tests re‐
9477 quiring a particular fixture have completed, CTest will ensure all
9478 tests marked as cleanup tasks for that fixture are then executed. Tests
9479 are marked as setup tasks with the FIXTURES_SETUP property and as
9480 cleanup tasks with the FIXTURES_CLEANUP property. If any of a fixture's
9481 setup tests fail, all tests listing that fixture in their FIXTURES_RE‐
9482 QUIRED property will not be executed. The cleanup tests for the fixture
9483 will always be executed, even if some setup tests fail.
9484 When CTest is asked to execute only a subset of tests (e.g. by the use
9486 of regular expressions or when run with the --rerun-failed command line
9487 option), it will automatically add any setup or cleanup tests for fix‐
9488 tures required by any of the tests that are in the execution set. This
9489 behavior can be overridden with the -FS, -FC and -FA command line op‐
9490 tions to ctest(1) if desired.
9491 Since setup and cleanup tasks are also tests, they can have an ordering
9493 specified by the DEPENDS test property just like any other tests. This
9494 can be exploited to implement setup or cleanup using multiple tests for
9495 a single fixture to modularise setup or cleanup logic.
9496 The concept of a fixture is different to that of a resource specified
9498 by RESOURCE_LOCK, but they may be used together. A fixture defines a
9499 set of tests which share setup and cleanup requirements, whereas a re‐
9500 source lock has the effect of ensuring a particular set of tests do not
9501 run in parallel. Some situations may need both, such as setting up a
9502 database, serializing test access to that database and deleting the
9503 database again at the end. For such cases, tests would populate both
9504 FIXTURES_REQUIRED and RESOURCE_LOCK to combine the two behaviors. Names
9505 used for RESOURCE_LOCK have no relationship with names of fixtures, so
9506 note that a resource lock does not imply a fixture and vice versa.
9507 Consider the following example which represents a database test sce‐
9509 nario similar to that mentioned above:
9510 add_test(NAME testsDone COMMAND emailResults)
9512 add_test(NAME fooOnly COMMAND testFoo)
9513 add_test(NAME dbOnly COMMAND testDb)
9514 add_test(NAME dbWithFoo COMMAND testDbWithFoo)
9515 add_test(NAME createDB COMMAND initDB)
9516 add_test(NAME setupUsers COMMAND userCreation)
9517 add_test(NAME cleanupDB COMMAND deleteDB)
9518 add_test(NAME cleanupFoo COMMAND removeFoos)
9519 set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)
9521 set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB)
9523 set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB)
9524 set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB)
9525 set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo)
9526 set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo")
9527 set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo)
9529 set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB)
9530 set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo")
9531 set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
9533 PROPERTIES RESOURCE_LOCK DbAccess)
9534 Key points from this example:
9536 • Two fixtures are defined: DB and Foo. Tests can require a single fix‐
9538 ture as fooOnly and dbOnly do, or they can depend on multiple fix‐
9539 tures like dbWithFoo does.
9540 • A DEPENDS relationship is set up to ensure setupUsers happens after
9542 createDB, both of which are setup tests for the DB fixture and will
9543 therefore be executed before the dbOnly and dbWithFoo tests automati‐
9544 cally.
9545 • No explicit DEPENDS relationships were needed to make the setup tests
9547 run before or the cleanup tests run after the regular tests.
9548 • The Foo fixture has no setup tests defined, only a single cleanup
9550 test.
9551 • testsDone is a cleanup test for both the DB and Foo fixtures. There‐
9553 fore, it will only execute once regular tests for both fixtures have
9554 finished (i.e. after fooOnly, dbOnly and dbWithFoo). No DEPENDS rela‐
9555 tionship was specified for testsDone, so it is free to run before,
9556 after or concurrently with other cleanup tests for either fixture.
9557 • The setup and cleanup tests never list the fixtures they are for in
9559 their own FIXTURES_REQUIRED property, as that would result in a de‐
9560 pendency on themselves and be considered an error.
9561 FIXTURES_SETUP
9563 New in version 3.7.
9564 Specifies a list of fixtures for which the test is to be treated as a
9567 setup test. These fixture names are distinct from test case names and
9568 are not required to have any similarity to the names of tests associ‐
9569 ated with them.
9570 Fixture setup tests are ordinary tests with all of the usual test func‐
9572 tionality. Setting the FIXTURES_SETUP property for a test has two pri‐
9573 mary effects:
9574 • CTest will ensure the test executes before any other test which lists
9576 the fixture name(s) in its FIXTURES_REQUIRED property.
9577 • If CTest is asked to run only a subset of tests (e.g. using regular
9579 expressions or the --rerun-failed option) and the setup test is not
9580 in the set of tests to run, it will automatically be added if any
9581 tests in the set require any fixture listed in FIXTURES_SETUP.
9582 A setup test can have multiple fixtures listed in its FIXTURES_SETUP
9584 property. It will execute only once for the whole CTest run, not once
9585 for each fixture. A fixture can also have more than one setup test de‐
9586 fined. If there are multiple setup tests for a fixture, projects can
9587 control their order with the usual DEPENDS test property if necessary.
9588 A setup test is allowed to require other fixtures, but not any fixture
9590 listed in its FIXTURES_SETUP property. For example:
9591 # Ok: dependent fixture is different to setup
9593 set_tests_properties(setupFoo PROPERTIES
9594 FIXTURES_SETUP Foo
9595 FIXTURES_REQUIRED Bar
9596 )
9597 # Error: cannot require same fixture as setup
9599 set_tests_properties(setupFoo PROPERTIES
9600 FIXTURES_SETUP Foo
9601 FIXTURES_REQUIRED Foo
9602 )
9603 If any of a fixture's setup tests fail, none of the tests listing that
9605 fixture in its FIXTURES_REQUIRED property will be run. Cleanup tests
9606 will, however, still be executed.
9607 See FIXTURES_REQUIRED for a more complete discussion of how to use test
9609 fixtures.
9610 LABELS
9612 Specify a list of text labels associated with a test. The labels are
9613 reported in both the ctest output summary and in dashboard submissions.
9614 They can also be used to filter the set of tests to be executed (see
9615 the ctest -L and ctest -LE options).
9616 See Additional Labels for adding labels to a test dynamically during
9618 test execution.
9619 MEASUREMENT
9621 Specify a CDASH measurement and value to be reported for a test.
9622 If set to a name then that name will be reported to CDASH as a named
9624 measurement with a value of 1. You may also specify a value by setting
9625 MEASUREMENT to measurement=value.
9626 PASS_REGULAR_EXPRESSION
9628 The output must match this regular expression for the test to pass.
9629 The process exit code is ignored.
9630 If set, the test output will be checked against the specified regular
9632 expressions and at least one of the regular expressions has to match,
9633 otherwise the test will fail. Example:
9634 set_tests_properties(mytest PROPERTIES
9636 PASS_REGULAR_EXPRESSION "TestPassed;All ok"
9637 )
9638 PASS_REGULAR_EXPRESSION expects a list of regular expressions.
9640 See also the FAIL_REGULAR_EXPRESSION and SKIP_REGULAR_EXPRESSION test
9642 properties.
9643 PROCESSOR_AFFINITY
9645 New in version 3.12.
9646 Set to a true value to ask CTest to launch the test process with CPU
9649 affinity for a fixed set of processors. If enabled and supported for
9650 the current platform, CTest will choose a set of processors to place in
9651 the CPU affinity mask when launching the test process. The number of
9652 processors in the set is determined by the PROCESSORS test property or
9653 the number of processors available to CTest, whichever is smaller. The
9654 set of processors chosen will be disjoint from the processors assigned
9655 to other concurrently running tests that also have the PROCESSOR_AFFIN‐
9656 ITY property enabled.
9657 PROCESSORS
9659 Set to specify how many process slots this test requires. If not set,
9660 the default is 1 processor.
9661 Denotes the number of processors that this test will require. This is
9663 typically used for MPI tests, and should be used in conjunction with
9664 the ctest_test() PARALLEL_LEVEL option.
9665 This will also be used to display a weighted test timing result in la‐
9667 bel and subproject summaries in the command line output of ctest(1).
9668 The wall clock time for the test run will be multiplied by this prop‐
9669 erty to give a better idea of how much cpu resource CTest allocated for
9670 the test.
9671 See also the PROCESSOR_AFFINITY test property.
9673 REQUIRED_FILES
9675 List of files required to run the test. The filenames are relative to
9676 the test WORKING_DIRECTORY unless an absolute path is specified.
9677 If set to a list of files, the test will not be run unless all of the
9679 files exist.
9680 Examples
9682 Suppose that test.txt is created by test baseTest and none.txt does not
9683 exist:
9684 add_test(NAME baseTest ...) # Assumed to create test.txt
9686 add_test(NAME fileTest ...)
9687 # The following ensures that if baseTest is successful, test.txt will
9689 # have been created before fileTest is run
9690 set_tests_properties(fileTest PROPERTIES
9691 DEPENDS baseTest
9692 REQUIRED_FILES test.txt
9693 )
9694 add_test(NAME notRunTest ...)
9696 # The following makes notRunTest depend on two files. Nothing creates
9698 # the none.txt file, so notRunTest will fail with status "Not Run".
9699 set_tests_properties(notRunTest PROPERTIES
9700 REQUIRED_FILES "test.txt;none.txt"
9701 )
9702 The above example demonstrates how REQUIRED_FILES works, but it is not
9704 the most robust way to implement test ordering with failure detection.
9705 For that, test fixtures are a better alternative (see
9706 FIXTURES_REQUIRED).
9707 RESOURCE_GROUPS
9709 New in version 3.16.
9710 Specify resources required by a test, grouped in a way that is meaning‐
9713 ful to the test. See resource allocation for more information on how
9714 this property integrates into the CTest resource allocation feature.
9715 The RESOURCE_GROUPS property is a semicolon-separated list of group de‐
9717 scriptions. Each entry consists of an optional number of groups using
9718 the description followed by a series of resource requirements for those
9719 groups. These requirements (and the number of groups) are separated by
9720 commas. The resource requirements consist of the name of a resource
9721 type, followed by a colon, followed by an unsigned integer specifying
9722 the number of slots required on one resource of the given type.
9723 The RESOURCE_GROUPS property tells CTest what resources a test expects
9725 to use grouped in a way meaningful to the test. The test itself must
9726 read the environment variables to determine which resources have been
9727 allocated to each group. For example, each group may correspond to a
9728 process the test will spawn when executed.
9729 Consider the following example:
9731 add_test(NAME MyTest COMMAND MyExe)
9733 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
9734 "2,gpus:2"
9735 "gpus:4,crypto_chips:2")
9736 In this example, there are two group descriptions (implicitly separated
9738 by a semicolon.) The content of the first description is 2,gpus:2. This
9739 description specifies 2 groups, each of which requires 2 slots from a
9740 single GPU. The content of the second description is
9741 gpus:4,crypto_chips:2. This description does not specify a group count,
9742 so a default of 1 is assumed. This single group requires 4 slots from
9743 a single GPU and 2 slots from a single cryptography chip. In total, 3
9744 resource groups are specified for this test, each with its own unique
9745 requirements.
9746 Note that the number of slots following the resource type specifies
9748 slots from a single instance of the resource. If the resource group can
9749 tolerate receiving slots from different instances of the same resource,
9750 it can indicate this by splitting the specification into multiple re‐
9751 quirements of one slot. For example:
9752 add_test(NAME MyTest COMMAND MyExe)
9754 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
9755 "gpus:1,gpus:1,gpus:1,gpus:1")
9756 In this case, the single resource group indicates that it needs four
9758 GPU slots, all of which may come from separate GPUs (though they don't
9759 have to; CTest may still assign slots from the same GPU.)
9760 When CTest sets the environment variables for a test, it assigns a
9762 group number based on the group description, starting at 0 on the left
9763 and the number of groups minus 1 on the right. For example, in the ex‐
9764 ample above, the two groups in the first description would have IDs of
9765 0 and 1, and the single group in the second description would have an
9766 ID of 2.
9767 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
9769 purposes, but they are distinct and orthogonal. Resources specified by
9770 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
9771 RESOURCE_LOCK is a simpler property that is used for locking one global
9772 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
9773 tiple tests to simultaneously use multiple resources of the same type,
9774 specifying their requirements in a fine-grained manner.
9775 RESOURCE_LOCK
9777 Specify a list of resources that are locked by this test.
9778 If multiple tests specify the same resource lock, they are guaranteed
9780 not to run concurrently.
9781 See also FIXTURES_REQUIRED if the resource requires any setup or
9783 cleanup steps.
9784 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
9786 purposes, but they are distinct and orthogonal. Resources specified by
9787 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
9788 RESOURCE_LOCK is a simpler property that is used for locking one global
9789 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
9790 tiple tests to simultaneously use multiple resources of the same type,
9791 specifying their requirements in a fine-grained manner.
9792 RUN_SERIAL
9794 Do not run this test in parallel with any other test.
9795 Use this option in conjunction with the ctest_test PARALLEL_LEVEL op‐
9797 tion to specify that this test should not be run in parallel with any
9798 other tests.
9799 SKIP_REGULAR_EXPRESSION
9801 New in version 3.16.
9802 If the output matches this regular expression the test will be marked
9805 as skipped.
9806 If set, if the output matches one of specified regular expressions, the
9808 test will be marked as skipped. Example:
9809 set_property(TEST mytest PROPERTY
9811 SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped"
9812 )
9813 SKIP_REGULAR_EXPRESSION expects a list of regular expressions.
9815 See also the SKIP_RETURN_CODE, PASS_REGULAR_EXPRESSION, and
9817 FAIL_REGULAR_EXPRESSION test properties.
9818 SKIP_RETURN_CODE
9820 Return code to mark a test as skipped.
9821 Sometimes only a test itself can determine if all requirements for the
9823 test are met. If such a situation should not be considered a hard fail‐
9824 ure a return code of the process can be specified that will mark the
9825 test as Not Run if it is encountered. Valid values are in the range of
9826 0 to 255, inclusive.
9827 See also the SKIP_REGULAR_EXPRESSION property.
9829 TIMEOUT
9831 How many seconds to allow for this test.
9832 This property if set will limit a test to not take more than the speci‐
9834 fied number of seconds to run. If it exceeds that the test process
9835 will be killed and ctest will move to the next test. This setting
9836 takes precedence over CTEST_TEST_TIMEOUT.
9837 An explicit 0 value means the test has no timeout, except as necessary
9839 to honor ctest --stop-time.
9840 See also TIMEOUT_AFTER_MATCH and TIMEOUT_SIGNAL_NAME.
9842 TIMEOUT_AFTER_MATCH
9844 New in version 3.6.
9845 Change a test's timeout duration after a matching line is encountered
9848 in its output.
9849 Usage
9851 add_test(mytest ...)
9852 set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}")
9853 Description
9855 Allow a test seconds to complete after regex is encountered in its out‐
9856 put.
9857 When the test outputs a line that matches regex its start time is reset
9859 to the current time and its timeout duration is changed to seconds.
9860 Prior to this, the timeout duration is determined by the TIMEOUT prop‐
9861 erty or the CTEST_TEST_TIMEOUT variable if either of these are set.
9862 Because the test's start time is reset, its execution time will not in‐
9863 clude any time that was spent waiting for the matching output.
9864 TIMEOUT_AFTER_MATCH is useful for avoiding spurious timeouts when your
9866 test must wait for some system resource to become available before it
9867 can execute. Set TIMEOUT to a longer duration that accounts for re‐
9868 source acquisition and use TIMEOUT_AFTER_MATCH to control how long the
9869 actual test is allowed to run.
9870 If the required resource can be controlled by CTest you should use
9872 RESOURCE_LOCK instead of TIMEOUT_AFTER_MATCH. This property should be
9873 used when only the test itself can determine when its required re‐
9874 sources are available.
9875 See also TIMEOUT_SIGNAL_NAME.
9877 TIMEOUT_SIGNAL_GRACE_PERIOD
9879 New in version 3.27.
9880 If the TIMEOUT_SIGNAL_NAME test property is set, this property speci‐
9883 fies the number of seconds to wait for a test process to terminate af‐
9884 ter sending the custom signal. Otherwise, this property has no mean‐
9885 ing.
9886 The grace period may be any real value greater than 0.0, but not
9888 greater than 60.0. If this property is not set, the default is 1.0
9889 second.
9890 This is available only on platforms supporting POSIX signals. It is
9892 not available on Windows.
9893 TIMEOUT_SIGNAL_NAME
9895 New in version 3.27.
9896 Specify a custom signal to send to a test process when its timeout is
9899 reached. This is available only on platforms supporting POSIX signals.
9900 It is not available on Windows.
9901 The name must be one of the following:
9903 SIGINT Interrupt.
9905 SIGQUIT
9907 Quit.
9908 SIGTERM
9910 Terminate.
9911 SIGUSR1
9913 User defined signal 1.
9914 SIGUSR2
9916 User defined signal 2.
9917 The custom signal is sent to the test process to give it a chance to
9919 exit gracefully during a grace period:
9920 • If the test process created any children, it is responsible for ter‐
9922 minating them too.
9923 • The grace period length is determined by the
9925 TIMEOUT_SIGNAL_GRACE_PERIOD test property.
9926 • If the test process does not terminate before the grace period ends,
9928 ctest(1) will force termination of its entire process tree via
9929 SIGSTOP and SIGKILL.
9930 See also CTEST_TEST_TIMEOUT, TIMEOUT, and TIMEOUT_AFTER_MATCH.
9932 WILL_FAIL
9934 If set to true, this will invert the pass/fail flag of the test.
9935 This property can be used for tests that are expected to fail and re‐
9937 turn a non-zero return code. Note that system-level test failures such
9938 as segmentation faults or heap errors will still fail the test even if
9939 WILL_FALL is true.
9940 WORKING_DIRECTORY
9942 The directory from which the test executable will be called.
9943 If this is not set, the test will be run with the working directory set
9945 to the binary directory associated with where the test was created
9946 (i.e. the CMAKE_CURRENT_BINARY_DIR for where add_test() was called).
9947
9949 ABSTRACT
9950 Is this source file an abstract class.
9951 A property on a source file that indicates if the source file repre‐
9953 sents a class that is abstract. This only makes sense for languages
9954 that have a notion of an abstract class and it is only used by some
9955 tools that wrap classes into other languages.
9956 AUTORCC_OPTIONS
9958 Additional options for rcc when using AUTORCC
9959 This property holds additional command line options which will be used
9961 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
9962 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
9963 By default it is empty.
9965 The options set on the .qrc source file may override AUTORCC_OPTIONS
9967 set on the target.
9968 EXAMPLE
9970 # ...
9971 set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9")
9972 # ...
9973 AUTOUIC_OPTIONS
9975 Additional options for uic when using AUTOUIC
9976 This property holds additional command line options which will be used
9978 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
9979 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
9980 By default it is empty.
9982 The options set on the .ui source file may override AUTOUIC_OPTIONS set
9984 on the target.
9985 EXAMPLE
9987 # ...
9988 set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection")
9989 # ...
9990 COMPILE_DEFINITIONS
9992 Preprocessor definitions for compiling a source file.
9993 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
9995 list of preprocessor definitions using the syntax VAR or VAR=value.
9996 Function-style definitions are not supported. CMake will automatically
9997 escape the value correctly for the native build system (note that CMake
9998 language syntax may require escapes to specify some values). This
9999 property may be set on a per-configuration basis using the name COM‐
10000 PILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case name (ex.
10001 COMPILE_DEFINITIONS_DEBUG).
10002 CMake will automatically drop some definitions that are not supported
10004 by the native build tool. Xcode does not support per-configuration
10005 definitions on source files.
10006 New in version 3.26: Any leading -D on an item will be removed.
10008 Disclaimer: Most native build tools have poor support for escaping cer‐
10011 tain values. CMake has work-arounds for many cases but some values may
10012 just not be possible to pass correctly. If a value does not seem to be
10013 escaped correctly, do not attempt to work-around the problem by adding
10014 escape sequences to the value. Your work-around may break in a future
10015 version of CMake that has improved escape support. Instead consider
10016 defining the macro in a (configured) header file. Then report the lim‐
10017 itation. Known limitations include:
10018 # - broken almost everywhere
10020 ; - broken in VS IDE 7.0 and Borland Makefiles
10021 , - broken in VS IDE
10022 % - broken in some cases in NMake
10023 & | - broken in some cases on MinGW
10024 ^ < > \" - broken in most Make tools on Windows
10025 CMake does not reject these values outright because they do work in
10027 some cases. Use with caution.
10028 Contents of COMPILE_DEFINITIONS may use cmake-generator-expressions(7)
10030 with the syntax $<...>. See the cmake-generator-expressions(7) manual
10031 for available expressions. However, Xcode does not support per-config
10032 per-source settings, so expressions that depend on the build configura‐
10033 tion are not allowed with that generator.
10034 Generator expressions should be preferred instead of setting the alter‐
10036 native per-configuration property.
10037 COMPILE_FLAGS
10039 Additional flags to be added when compiling this source file.
10040 The COMPILE_FLAGS property, managed as a string, sets additional com‐
10042 piler flags used that will be added to the list of compile flags when
10043 this source file builds. The flags will be added after target-wide
10044 flags (except in some cases not supported by the Visual Studio 9 2008
10045 generator).
10046 Use COMPILE_DEFINITIONS to pass additional preprocessor definitions.
10048 Contents of COMPILE_FLAGS may use "generator expressions" with the syn‐
10050 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
10051 able expressions. However, Xcode does not support per-config
10052 per-source settings, so expressions that depend on the build configura‐
10053 tion are not allowed with that generator.
10054 NOTE:
10056 This property has been superseded by the COMPILE_OPTIONS property.
10057 COMPILE_OPTIONS
10059 New in version 3.11.
10060 List of additional options to pass to the compiler.
10063 This property holds a semicolon-separated list of options and will be
10065 added to the list of compile flags when this source file builds. The
10066 options will be added after target-wide options (except in some cases
10067 not supported by the Visual Studio 9 2008 generator).
10068 Contents of COMPILE_OPTIONS may use "generator expressions" with the
10070 syntax $<...>. See the cmake-generator-expressions(7) manual for
10071 available expressions. However, Xcode does not support per-config
10072 per-source settings, so expressions that depend on the build configura‐
10073 tion are not allowed with that generator.
10074 Usage example:
10076 set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer")
10078 Related properties:
10080 • Prefer this property over COMPILE_FLAGS.
10082 • Use COMPILE_DEFINITIONS to pass additional preprocessor definitions.
10084 • Use INCLUDE_DIRECTORIES to pass additional include directories.
10086 Related commands:
10088 • add_compile_options() for directory-wide settings
10090 • target_compile_options() for target-specific settings
10092 CXX_SCAN_FOR_MODULES
10094 New in version 3.26.
10095 CXX_SCAN_FOR_MODULES is a boolean specifying whether CMake will scan
10098 the source for C++ module dependencies. See also the
10099 CXX_SCAN_FOR_MODULES for target-wide settings.
10100 When this property is set ON, CMake will scan the source at build time
10102 and add module dependency information to the compile line as necessary.
10103 When this property is set OFF, CMake will not scan the source at build
10104 time. When this property is unset, the CXX_SCAN_FOR_MODULES property
10105 is consulted.
10106 Note that scanning is only performed if C++20 or higher is enabled for
10108 the target and the source uses the CXX language. Scanning for modules
10109 in sources belonging to file sets of type CXX_MODULES is always per‐
10110 formed.
10111 NOTE:
10113 This setting is meaningful only when experimental support for C++
10114 modules has been enabled by the CMAKE_EXPERIMENTAL_CXX_MOD‐
10115 ULE_CMAKE_API gate.
10116 EXTERNAL_OBJECT
10118 If set to true then this is an object file.
10119 If this property is set to True then the source file is really an ob‐
10121 ject file and should not be compiled. It will still be linked into the
10122 target though.
10123 Fortran_FORMAT
10125 Set to FIXED or FREE to indicate the Fortran source layout.
10126 This property tells CMake whether a given Fortran source file uses
10128 fixed-format or free-format. CMake will pass the corresponding format
10129 flag to the compiler. Consider using the target-wide Fortran_FORMAT
10130 property if all source files in a target share the same format.
10131 NOTE:
10133 For some compilers, NAG, PGI and Solaris Studio, setting this to OFF
10134 will have no effect.
10135 Fortran_PREPROCESS
10137 New in version 3.18.
10138 Control whether the Fortran source file should be unconditionally pre‐
10141 processed.
10142 If unset or empty, rely on the compiler to determine whether the file
10144 should be preprocessed. If explicitly set to OFF then the file does not
10145 need to be preprocessed. If explicitly set to ON, then the file does
10146 need to be preprocessed as part of the compilation step.
10147 When using the Ninja generator, all source files are first preprocessed
10149 in order to generate module dependency information. Setting this prop‐
10150 erty to OFF will make Ninja skip this step.
10151 Consider using the target-wide Fortran_PREPROCESS property if all
10153 source files in a target need to be preprocessed.
10154 GENERATED
10156 Is this source file generated as part of the build or CMake process.
10157 Changed in version 3.20: The GENERATED source file property is now vis‐
10159 ible in all directories.
10160 Tells the internal CMake engine that a source file is generated by an
10163 outside process such as another build step, or the execution of CMake
10164 itself. This information is then used to exempt the file from any ex‐
10165 istence or validity checks.
10166 Any file that is
10168 • created by the execution of commands such as add_custom_command()
10170 which run during the build
10171 • listed as one of the BYPRODUCTS of an add_custom_command() or
10173 add_custom_target() command, or
10174 • created by a CMake AUTOGEN operation such as AUTOMOC, AUTORCC, or
10176 AUTOUIC
10177 will be marked with the GENERATED property.
10179 When a generated file created as the OUTPUT of an add_custom_command()
10181 command is explicitly listed as a source file for any target in the
10182 same directory scope (which usually means the same CMakeLists.txt
10183 file), CMake will automatically create a dependency to make sure the
10184 file is generated before building that target.
10185 The Makefile Generators will remove GENERATED files during make clean.
10187 Generated sources may be hidden in some IDE tools, while in others they
10189 might be shown. For the special case of sources generated by CMake's
10190 AUTOMOC, AUTORCC or AUTOUIC functionality, the AUTOGEN_SOURCE_GROUP,
10191 AUTOMOC_SOURCE_GROUP, AUTORCC_SOURCE_GROUP and AUTOUIC_SOURCE_GROUP
10192 target properties may influence where the generated sources are grouped
10193 in the project's file lists.
10194 NOTE:
10196 Starting with CMake 3.20 the GENERATED source file property can be
10197 set and retrieved from any directory scope. It is an all-or-nothing
10198 property. It also can no longer be removed or unset if it was set
10199 to TRUE. Policy CMP0118 was introduced to allow supporting the OLD
10200 behavior for some time.
10201 HEADER_FILE_ONLY
10203 Is this source file only a header file.
10204 A property on a source file that indicates if the source file is a
10206 header file with no associated implementation. This is set automati‐
10207 cally based on the file extension and is used by CMake to determine if
10208 certain dependency information should be computed.
10209 By setting this property to ON, you can disable compilation of the
10211 given source file, even if it should be compiled because it is part of
10212 the library's/executable's sources.
10213 This is useful if you have some source files which you somehow
10215 pre-process, and then add these pre-processed sources via add_library()
10216 or add_executable(). Normally, in IDE, there would be no reference of
10217 the original sources, only of these pre-processed sources. So by set‐
10218 ting this property for all the original source files to ON, and then
10219 either calling add_library() or add_executable() while passing both the
10220 pre-processed sources and the original sources, or by using
10221 target_sources() to add original source files will do exactly what
10222 would one expect, i.e. the original source files would be visible in
10223 IDE, and will not be built.
10224 INCLUDE_DIRECTORIES
10226 New in version 3.11.
10227 List of preprocessor include file search directories.
10230 This property holds a semicolon-separated list of paths and will be
10232 added to the list of include directories when this source file builds.
10233 These directories will take precedence over directories defined at tar‐
10234 get level except for Xcode generator due to technical limitations.
10235 Relative paths should not be added to this property directly.
10237 Contents of INCLUDE_DIRECTORIES may use "generator expressions" with
10239 the syntax $<...>. See the cmake-generator-expressions(7) manual for
10240 available expressions. However, Xcode does not support per-config
10241 per-source settings, so expressions that depend on the build configura‐
10242 tion are not allowed with that generator.
10243 KEEP_EXTENSION
10245 Make the output file have the same extension as the source file.
10246 If this property is set then the file extension of the output file will
10248 be the same as that of the source file. Normally the output file ex‐
10249 tension is computed based on the language of the source file, for exam‐
10250 ple .cxx will go to a .o extension.
10251 LABELS
10253 Specify a list of text labels associated with a source file.
10254 This property has meaning only when the source file is listed in a tar‐
10256 get whose LABELS property is also set. No other semantics are cur‐
10257 rently specified.
10258 LANGUAGE
10260 Specify the programming language in which a source file is written.
10261 A property that can be set to indicate what programming language the
10263 source file is. If it is not set the language is determined based on
10264 the file extension. Typical values are CXX (i.e. C++), C, CSharp,
10265 CUDA, Fortran, HIP, ISPC, and ASM. Setting this property for a file
10266 means this file will be compiled, unless HEADER_FILE_ONLY is set.
10267 Changed in version 3.20: Setting this property causes the source file
10269 to be compiled as the specified language, using explicit flags if pos‐
10270 sible. Previously it only caused the specified language's compiler to
10271 be used. See policy CMP0119.
10272 LOCATION
10275 The full path to a source file.
10276 A read only property on a SOURCE FILE that contains the full path to
10278 the source file.
10279 MACOSX_PACKAGE_LOCATION
10281 Place a source file inside a Application Bundle (MACOSX_BUNDLE), Core
10282 Foundation Bundle (BUNDLE), or Framework Bundle (FRAMEWORK). It is ap‐
10283 plicable for macOS and iOS.
10284 Executable targets with the MACOSX_BUNDLE property set are built as
10286 macOS or iOS application bundles on Apple platforms. Shared library
10287 targets with the FRAMEWORK property set are built as macOS or iOS
10288 frameworks on Apple platforms. Module library targets with the BUNDLE
10289 property set are built as macOS CFBundle bundles on Apple platforms.
10290 Source files listed in the target with this property set will be copied
10291 to a directory inside the bundle or framework content folder specified
10292 by the property value. For macOS Application Bundles the content
10293 folder is <name>.app/Contents. For macOS Frameworks the content folder
10294 is <name>.framework/Versions/<version>. For macOS CFBundles the con‐
10295 tent folder is <name>.bundle/Contents (unless the extension is
10296 changed). See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target
10297 properties for specifying files meant for Headers, PrivateHeaders, or
10298 Resources directories.
10299 If the specified location is equal to Resources, the resulting location
10301 will be the same as if the RESOURCE property had been used. If the
10302 specified location is a sub-folder of Resources, it will be placed into
10303 the respective sub-folder. Note: For iOS Apple uses a flat bundle lay‐
10304 out where no Resources folder exist. Therefore CMake strips the Re‐
10305 sources folder name from the specified location.
10306 OBJECT_DEPENDS
10308 Additional files on which a compiled object file depends.
10309 Specifies a semicolon-separated list of full-paths to files on which
10311 any object files compiled from this source file depend. On Makefile
10312 Generators and the Ninja generator an object file will be recompiled if
10313 any of the named files is newer than it. Visual Studio Generators and
10314 the Xcode generator cannot implement such compilation dependencies.
10315 This property need not be used to specify the dependency of a source
10317 file on a generated header file that it includes. Although the prop‐
10318 erty was originally introduced for this purpose, it is no longer neces‐
10319 sary. If the generated header file is created by a custom command in
10320 the same target as the source file, the automatic dependency scanning
10321 process will recognize the dependency. If the generated header file is
10322 created by another target, an inter-target dependency should be created
10323 with the add_dependencies() command (if one does not already exist due
10324 to linking relationships).
10325 OBJECT_OUTPUTS
10327 Additional outputs for a Ninja or Makefile Generators rule.
10328 Additional outputs created by compilation of this source file. If any
10330 of these outputs is missing the object will be recompiled. This is
10331 supported only on the Ninja and Makefile Generators and will be ignored
10332 on other generators.
10333 This property supports generator expressions.
10335 SKIP_AUTOGEN
10337 New in version 3.8.
10338 Exclude the source file from AUTOMOC, AUTOUIC and AUTORCC processing
10341 (for Qt projects).
10342 For finer exclusion control see SKIP_AUTOMOC, SKIP_AUTOUIC and
10344 SKIP_AUTORCC.
10345 EXAMPLE
10347 # ...
10348 set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
10349 # ...
10350 SKIP_AUTOMOC
10352 New in version 3.8.
10353 Exclude the source file from AUTOMOC processing (for Qt projects).
10356 For broader exclusion control see SKIP_AUTOGEN.
10358 EXAMPLE
10360 # ...
10361 set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
10362 # ...
10363 SKIP_AUTORCC
10365 New in version 3.8.
10366 Exclude the source file from AUTORCC processing (for Qt projects).
10369 For broader exclusion control see SKIP_AUTOGEN.
10371 EXAMPLE
10373 # ...
10374 set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
10375 # ...
10376 SKIP_AUTOUIC
10378 New in version 3.8.
10379 Exclude the source file from AUTOUIC processing (for Qt projects).
10382 SKIP_AUTOUIC can be set on C++ header and source files and on .ui
10384 files.
10385 For broader exclusion control see SKIP_AUTOGEN.
10387 EXAMPLE
10389 # ...
10390 set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
10391 set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON)
10392 set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON)
10393 # ...
10394 SKIP_LINTING
10396 New in version 3.27.
10397 This property allows you to exclude a specific source file from the
10400 linting process. The linting process involves running tools such as
10401 <LANG>_CPPLINT, <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and
10402 <LANG>_INCLUDE_WHAT_YOU_USE on the source files, as well as compiling
10403 header files as part of VERIFY_INTERFACE_HEADER_SETS. By setting
10404 SKIP_LINTING on a source file, the mentioned linting tools will not be
10405 executed for that particular file.
10406 Example
10408 Consider a C++ project that includes multiple source files, such as
10409 main.cpp, things.cpp, and generatedBindings.cpp. In this example, you
10410 want to exclude the generatedBindings.cpp file from the linting
10411 process. To achieve this, you can utilize the SKIP_LINTING property
10412 with the set_source_files_properties() command as shown below:
10413 add_executable(MyApp main.cpp things.cpp generatedBindings.cpp)
10415 set_source_files_properties(generatedBindings.cpp PROPERTIES
10417 SKIP_LINTING ON
10418 )
10419 In the provided code snippet, the SKIP_LINTING property is set to true
10421 for the generatedBindings.cpp source file. As a result, when the lint‐
10422 ing tools specified by <LANG>_CPPLINT, <LANG>_CLANG_TIDY,
10423 <LANG>_CPPCHECK, or <LANG>_INCLUDE_WHAT_YOU_USE are executed, they will
10424 skip analyzing the generatedBindings.cpp file.
10425 By using the SKIP_LINTING property, you can selectively exclude spe‐
10427 cific source files from the linting process. This allows you to focus
10428 the linting tools on the relevant parts of your project, enhancing the
10429 efficiency and effectiveness of the linting workflow.
10430 SKIP_PRECOMPILE_HEADERS
10432 New in version 3.16.
10433 Is this source file skipped by PRECOMPILE_HEADERS feature.
10436 This property helps with build problems that one would run into when
10438 using the PRECOMPILE_HEADERS feature.
10439 One example would be the usage of Objective-C (*.m) files, and Objec‐
10441 tive-C++ (*.mm) files, which lead to compilation failure because they
10442 are treated (in case of Ninja / Makefile generator) as C, and CXX re‐
10443 spectively. The precompile headers are not compatible between lan‐
10444 guages.
10445 SKIP_UNITY_BUILD_INCLUSION
10447 New in version 3.16.
10448 Setting this property to true ensures the source file will be skipped
10451 by unity builds when its associated target has its UNITY_BUILD property
10452 set to true. The source file will instead be compiled on its own in
10453 the same way as it would with unity builds disabled.
10454 This property helps with "ODR (One definition rule)" problems where
10456 combining a particular source file with others might lead to build er‐
10457 rors or other unintended side effects.
10458 Swift_DEPENDENCIES_FILE
10460 New in version 3.15.
10461 This property sets the path for the Swift dependency file (swiftdeps)
10464 for the source. If one is not specified, it will default to <OB‐
10465 JECT>.swiftdeps.
10466 Swift_DIAGNOSTICS_FILE
10468 New in version 3.15.
10469 This property controls where the Swift diagnostics are serialized.
10472 SYMBOLIC
10474 Is this just a name for a rule.
10475 If SYMBOLIC (boolean) is set to True the build system will be informed
10477 that the source file is not actually created on disk but instead used
10478 as a symbolic name for a build rule.
10479 UNITY_GROUP
10481 New in version 3.18.
10482 This property controls which bucket the source will be part of when the
10485 UNITY_BUILD_MODE is set to GROUP.
10486 VS_COPY_TO_OUT_DIR
10488 New in version 3.8.
10489 Sets the <CopyToOutputDirectory> tag for a source file in a Visual Stu‐
10492 dio project file. Valid values are Never, Always and PreserveNewest.
10493 VS_CSHARP_<tagname>
10495 New in version 3.8.
10496 Visual Studio and CSharp source-file-specific configuration.
10499 Tell the Visual Studio generators to set the source file tag <tagname>
10501 to a given value in the generated Visual Studio CSharp project. Ignored
10502 on other generators and languages. This property can be used to define
10503 dependencies between source files or set any other Visual Studio spe‐
10504 cific parameters.
10505 Example usage:
10507 set_source_files_properties(<filename>
10509 PROPERTIES
10510 VS_CSHARP_DependentUpon <other file>
10511 VS_CSHARP_SubType "Form")
10512 VS_DEPLOYMENT_CONTENT
10514 New in version 3.1.
10515 Mark a source file as content for deployment with a Windows Phone or
10518 Windows Store application when built with a Visual Studio generators.
10519 The value must evaluate to either 1 or 0 and may use generator expres‐
10520 sions to make the choice based on the build configuration. The .vcx‐
10521 proj file entry for the source file will be marked either Deployment‐
10522 Content or ExcludedFromBuild for values 1 and 0, respectively.
10523 VS_DEPLOYMENT_LOCATION
10525 New in version 3.1.
10526 Specifies the deployment location for a content source file with a Win‐
10529 dows Phone or Windows Store application when built with a Visual Studio
10530 generators. This property is only applicable when using
10531 VS_DEPLOYMENT_CONTENT. The value represent the path relative to the
10532 app package and applies to all configurations.
10533 VS_INCLUDE_IN_VSIX
10535 New in version 3.8.
10536 Boolean property to specify if the file should be included within a
10539 VSIX (Visual Studio Integration Extension) extension package. This is
10540 needed for development of Visual Studio extensions.
10541 VS_RESOURCE_GENERATOR
10543 New in version 3.8.
10544 This property allows to specify the resource generator to be used on
10547 this file. It defaults to PublicResXFileCodeGenerator if not set.
10548 This property only applies to C# projects.
10550 VS_SETTINGS
10552 New in version 3.18.
10553 Set any item metadata on a file.
10556 New in version 3.22: This property is honored for all source file
10558 types. Previously it worked only for non-built files.
10559 Takes a list of Key=Value pairs. Tells the Visual Studio generator to
10562 set Key to Value as item metadata on the file.
10563 For example:
10565 set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2")
10567 will set Key to Value and Key2 to Value2 on the file.hlsl item as meta‐
10569 data.
10570 Generator expressions are supported.
10572 VS_SHADER_DISABLE_OPTIMIZATIONS
10574 New in version 3.11.
10575 Disable compiler optimizations for an .hlsl source file. This adds the
10578 -Od flag to the command line for the FxCompiler tool. Specify the
10579 value true for this property to disable compiler optimizations.
10580 VS_SHADER_ENABLE_DEBUG
10582 New in version 3.11.
10583 Enable debugging information for an .hlsl source file. This adds the
10586 -Zi flag to the command line for the FxCompiler tool. Specify the
10587 value true to generate debugging information for the compiled shader.
10588 VS_SHADER_ENTRYPOINT
10590 New in version 3.1.
10591 Specifies the name of the entry point for the shader of a .hlsl source
10594 file.
10595 VS_SHADER_FLAGS
10597 New in version 3.2.
10598 Set additional Visual Studio shader flags of a .hlsl source file.
10601 VS_SHADER_MODEL
10603 New in version 3.1.
10604 Specifies the shader model of a .hlsl source file. Some shader types
10607 can only be used with recent shader models
10608 VS_SHADER_OBJECT_FILE_NAME
10610 New in version 3.12.
10611 Specifies a file name for the compiled shader object file for an .hlsl
10614 source file. This adds the -Fo flag to the command line for the FxCom‐
10615 piler tool.
10616 VS_SHADER_OUTPUT_HEADER_FILE
10618 New in version 3.10.
10619 Set filename for output header file containing object code of a .hlsl
10622 source file.
10623 VS_SHADER_TYPE
10625 New in version 3.1.
10626 Set the Visual Studio shader type of a .hlsl source file.
10629 VS_SHADER_VARIABLE_NAME
10631 New in version 3.10.
10632 Set name of variable in header file containing object code of a .hlsl
10635 source file.
10636 VS_TOOL_OVERRIDE
10638 New in version 3.7.
10639 Override the default Visual Studio tool that will be applied to the
10642 source file with a new tool not based on the extension of the file.
10643 VS_XAML_TYPE
10645 New in version 3.3.
10646 Mark a Extensible Application Markup Language (XAML) source file as a
10649 different type than the default Page. The most common usage would be
10650 to set the default App.xaml file as ApplicationDefinition.
10651 WRAP_EXCLUDE
10653 Exclude this source file from any code wrapping techniques.
10654 Some packages can wrap source files into alternate languages to provide
10656 additional functionality.
10657 For example, C++ code can be wrapped into Java or Python, using SWIG.
10659 If WRAP_EXCLUDE is set to True, that indicates that this source file
10660 should not be wrapped.
10661 XCODE_EXPLICIT_FILE_TYPE
10663 New in version 3.1.
10664 Set the Xcode explicitFileType attribute on its reference to a source
10667 file. CMake computes a default based on file extension but can be told
10668 explicitly with this property.
10669 See also XCODE_LAST_KNOWN_FILE_TYPE.
10671 XCODE_FILE_ATTRIBUTES
10673 New in version 3.7.
10674 Add values to the Xcode ATTRIBUTES setting on its reference to a source
10677 file. Among other things, this can be used to set the role on a .mig
10678 file:
10679 set_source_files_properties(defs.mig
10681 PROPERTIES
10682 XCODE_FILE_ATTRIBUTES "Client;Server"
10683 )
10684 XCODE_LAST_KNOWN_FILE_TYPE
10686 New in version 3.1.
10687 Set the Xcode lastKnownFileType attribute on its reference to a source
10690 file. CMake computes a default based on file extension but can be told
10691 explicitly with this property.
10692 See also XCODE_EXPLICIT_FILE_TYPE, which is preferred over this prop‐
10694 erty if set.
10695
10697 ADVANCED
10698 True if entry should be hidden by default in GUIs.
10699 This is a boolean value indicating whether the entry is considered in‐
10701 teresting only for advanced configuration. The mark_as_advanced() com‐
10702 mand modifies this property.
10703 HELPSTRING
10705 Help associated with entry in GUIs.
10706 This string summarizes the purpose of an entry to help users set it
10708 through a CMake GUI.
10709 MODIFIED
10711 Internal management property. Do not set or get.
10712 This is an internal cache entry property managed by CMake to track in‐
10714 teractive user modification of entries. Ignore it.
10715 STRINGS
10717 Enumerate possible STRING entry values for GUI selection.
10718 For cache entries with type STRING, this enumerates a set of values.
10720 CMake GUIs may use this to provide a selection widget instead of a
10721 generic string entry field. This is for convenience only. CMake does
10722 not enforce that the value matches one of those listed.
10723 TYPE
10725 Widget type for entry in GUIs.
10726 Cache entry values are always strings, but CMake GUIs present widgets
10728 to help users set values. The GUIs use this property as a hint to de‐
10729 termine the widget type. Valid TYPE values are:
10730 BOOL = Boolean ON/OFF value.
10732 PATH = Path to a directory.
10733 FILEPATH = Path to a file.
10734 STRING = Generic string value.
10735 INTERNAL = Do not present in GUI at all.
10736 STATIC = Value managed by CMake, do not change.
10737 UNINITIALIZED = Type not yet specified.
10738 Generally the TYPE of a cache entry should be set by the command which
10740 creates it ( set(), option(), find_library(), etc.).
10741 VALUE
10743 Value of a cache entry.
10744 This property maps to the actual value of a cache entry. Setting this
10746 property always sets the value without checking, so use with care.
10747
10749 CPACK_DESKTOP_SHORTCUTS
10750 New in version 3.3.
10751 Species a list of shortcut names that should be created on the Desktop
10754 for this file.
10755 The property is currently only supported by the CPack WIX Generator.
10757 CPACK_NEVER_OVERWRITE
10759 New in version 3.1.
10760 Request that this file not be overwritten on install or reinstall.
10763 The property is currently only supported by the CPack WIX Generator.
10765 CPACK_PERMANENT
10767 New in version 3.1.
10768 Request that this file not be removed on uninstall.
10771 The property is currently only supported by the CPack WIX Generator.
10773 CPACK_START_MENU_SHORTCUTS
10775 New in version 3.3.
10776 Species a list of shortcut names that should be created in the Start
10779 Menu for this file.
10780 The property is currently only supported by the CPack WIX Generator.
10782 CPACK_STARTUP_SHORTCUTS
10784 New in version 3.3.
10785 Species a list of shortcut names that should be created in the Startup
10788 folder for this file.
10789 The property is currently only supported by the CPack WIX Generator.
10791 CPACK_WIX_ACL
10793 New in version 3.1.
10794 Specifies access permissions for files or directories installed by a
10797 WiX installer.
10798 The property can contain multiple list entries, each of which has to
10800 match the following format.
10801 <user>[@<domain>]=<permission>[,<permission>]
10803 <user> and <domain> specify the windows user and domain for which the
10805 <Permission> element should be generated.
10806 <permission> is any of the YesNoType attributes listed here:
10808 http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html
10810 The property is currently only supported by the CPack WIX Generator.
10812
10814 ADDITIONAL_MAKE_CLEAN_FILES
10815 Deprecated since version 3.15: Use ADDITIONAL_CLEAN_FILES instead.
10816 Additional files to remove during the clean stage.
10819 A ;-list of files that will be removed as a part of the make clean tar‐
10821 get.
10822 Arguments to ADDITIONAL_MAKE_CLEAN_FILES may use generator expressions.
10824 This property only works for the Makefile generators. It is ignored on
10826 other generators.
10827 COMPILE_DEFINITIONS_<CONFIG>
10829 Ignored. See CMake Policy CMP0043.
10830 Per-configuration preprocessor definitions in a directory.
10832 This is the configuration-specific version of COMPILE_DEFINITIONS where
10834 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
10835 This property will be initialized in each directory by its value in the
10837 directory's parent.
10838 Contents of COMPILE_DEFINITIONS_<CONFIG> may use "generator expres‐
10840 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10841 manual for available expressions. See the cmake-buildsystem(7) manual
10842 for more on defining buildsystem properties.
10843 Generator expressions should be preferred instead of setting this prop‐
10845 erty.
10846 INTERPROCEDURAL_OPTIMIZATION
10848 This directory property does not exist anymore.
10849 See the target property INTERPROCEDURAL_OPTIMIZATION instead.
10851 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
10853 This directory property does not exist anymore.
10854 See the target property INTERPROCEDURAL_OPTIMIZATION_<CONFIG> instead.
10856 TEST_INCLUDE_FILE
10858 Deprecated. Use TEST_INCLUDE_FILES instead.
10859 A cmake file that will be included when ctest is run.
10861 If you specify TEST_INCLUDE_FILE, that file will be included and pro‐
10863 cessed when ctest is run on the directory.
10864
10866 COMPILE_DEFINITIONS_<CONFIG>
10867 Ignored. See CMake Policy CMP0043.
10868 Per-configuration preprocessor definitions on a target.
10870 This is the configuration-specific version of COMPILE_DEFINITIONS where
10872 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
10873 Contents of COMPILE_DEFINITIONS_<CONFIG> may use "generator expres‐
10875 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10876 manual for available expressions. See the cmake-buildsystem(7) manual
10877 for more on defining buildsystem properties.
10878 Generator expressions should be preferred instead of setting this prop‐
10880 erty.
10881 POST_INSTALL_SCRIPT
10883 Deprecated install support.
10884 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
10886 way to specify CMake scripts to run before and after installing a tar‐
10887 get. They are used only when the old INSTALL_TARGETS command is used
10888 to install the target. Use the install() command instead.
10889 PRE_INSTALL_SCRIPT
10891 Deprecated install support.
10892 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
10894 way to specify CMake scripts to run before and after installing a tar‐
10895 get. They are used only when the old INSTALL_TARGETS command is used
10896 to install the target. Use the install() command instead.
10897
10899 COMPILE_DEFINITIONS_<CONFIG>
10900 Ignored. See CMake Policy CMP0043.
10901 Per-configuration preprocessor definitions on a source file.
10903 This is the configuration-specific version of COMPILE_DEFINITIONS.
10905 Note that Xcode does not support per-configuration source file flags so
10906 this property will be ignored by the Xcode generator.
10907
10909 2000-2023 Kitware, Inc. and Contributors
109103.27.7 Oct 07, 2023 CMAKE-PROPERTIES(7)