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 add_custom_tar‐
19 get() names. For projects that care only about Makefile Generators and
20 do not wish to support Xcode or Visual Studio Generators IDE genera‐
21 tors, one may set this property to True to allow duplicate custom tar‐
22 gets. The property allows multiple add_custom_target() command calls
23 in different directories to specify the same target name. However,
24 setting this property will cause non-Makefile generators to produce an
25 error and refuse to generate the project.
26 AUTOGEN_SOURCE_GROUP
28 Name of the source_group() for AUTOMOC and AUTORCC generated files.
29 Files generated by AUTOMOC and AUTORCC are not always known at config‐
31 ure time and therefore can’t be passed to source_group().
32 AUTOGEN_SOURCE_GROUP an be used instead to generate or select a source
33 group for AUTOMOC and AUTORCC generated files.
34 For AUTOMOC and AUTORCC specific overrides see AUTOMOC_SOURCE_GROUP and
36 AUTORCC_SOURCE_GROUP respectively.
37 AUTOGEN_TARGETS_FOLDER
39 Name of FOLDER for *_autogen targets that are added automatically by
40 CMake for targets for which AUTOMOC is enabled.
41 If not set, CMake uses the FOLDER property of the parent target as a
43 default value for this property. See also the documentation for the
44 FOLDER target property and the AUTOMOC target property.
45 AUTOMOC_SOURCE_GROUP
47 Name of the source_group() for AUTOMOC generated files.
48 When set this is used instead of AUTOGEN_SOURCE_GROUP for files gener‐
50 ated by AUTOMOC.
51 AUTOMOC_TARGETS_FOLDER
53 Name of FOLDER for *_autogen targets that are added automatically by
54 CMake for targets for which AUTOMOC is enabled.
55 This property is obsolete. Use AUTOGEN_TARGETS_FOLDER instead.
57 If not set, CMake uses the FOLDER property of the parent target as a
59 default value for this property. See also the documentation for the
60 FOLDER target property and the AUTOMOC target property.
61 AUTORCC_SOURCE_GROUP
63 Name of the source_group() for AUTORCC generated files.
64 When set this is used instead of AUTOGEN_SOURCE_GROUP for files gener‐
66 ated by AUTORCC.
67 CMAKE_C_KNOWN_FEATURES
69 List of C features known to this version of CMake.
70 The features listed in this global property may be known to be avail‐
72 able to the C compiler. If the feature is available with the C com‐
73 piler, it will be listed in the CMAKE_C_COMPILE_FEATURES variable.
74 The features listed here may be used with the target_compile_features()
76 command. See the cmake-compile-features(7) manual for information on
77 compile features and a list of supported compilers.
78 The features known to this version of CMake are:
80 c_std_90
82 Compiler mode is at least C 90.
83 c_std_99
85 Compiler mode is at least C 99.
86 c_std_11
88 Compiler mode is at least C 11.
89 c_function_prototypes
91 Function prototypes, as defined in ISO/IEC 9899:1990.
92 c_restrict
94 restrict keyword, as defined in ISO/IEC 9899:1999.
95 c_static_assert
97 Static assert, as defined in ISO/IEC 9899:2011.
98 c_variadic_macros
100 Variadic macros, as defined in ISO/IEC 9899:1999.
101 CMAKE_CXX_KNOWN_FEATURES
103 List of C++ features known to this version of CMake.
104 The features listed in this global property may be known to be avail‐
106 able to the C++ compiler. If the feature is available with the C++
107 compiler, it will be listed in the CMAKE_CXX_COMPILE_FEATURES variable.
108 The features listed here may be used with the target_compile_features()
110 command. See the cmake-compile-features(7) manual for information on
111 compile features and a list of supported compilers.
112 The features known to this version of CMake are:
114 cxx_std_98
116 Compiler mode is at least C++ 98.
117 cxx_std_11
119 Compiler mode is at least C++ 11.
120 cxx_std_14
122 Compiler mode is at least C++ 14.
123 cxx_std_17
125 Compiler mode is at least C++ 17.
126 cxx_std_20
128 Compiler mode is at least C++ 20.
129 cxx_aggregate_default_initializers
131 Aggregate default initializers, as defined in N3605.
132 cxx_alias_templates
134 Template aliases, as defined in N2258.
135 cxx_alignas
137 Alignment control alignas, as defined in N2341.
138 cxx_alignof
140 Alignment control alignof, as defined in N2341.
141 cxx_attributes
143 Generic attributes, as defined in N2761.
144 cxx_attribute_deprecated
146 [[deprecated]] attribute, as defined in N3760.
147 cxx_auto_type
149 Automatic type deduction, as defined in N1984.
150 cxx_binary_literals
152 Binary literals, as defined in N3472.
153 cxx_constexpr
155 Constant expressions, as defined in N2235.
156 cxx_contextual_conversions
158 Contextual conversions, as defined in N3323.
159 cxx_decltype_incomplete_return_types
161 Decltype on incomplete return types, as defined in N3276.
162 cxx_decltype
164 Decltype, as defined in N2343.
165 cxx_decltype_auto
167 decltype(auto) semantics, as defined in N3638.
168 cxx_default_function_template_args
170 Default template arguments for function templates, as defined in
171 DR226
172 cxx_defaulted_functions
174 Defaulted functions, as defined in N2346.
175 cxx_defaulted_move_initializers
177 Defaulted move initializers, as defined in N3053.
178 cxx_delegating_constructors
180 Delegating constructors, as defined in N1986.
181 cxx_deleted_functions
183 Deleted functions, as defined in N2346.
184 cxx_digit_separators
186 Digit separators, as defined in N3781.
187 cxx_enum_forward_declarations
189 Enum forward declarations, as defined in N2764.
190 cxx_explicit_conversions
192 Explicit conversion operators, as defined in N2437.
193 cxx_extended_friend_declarations
195 Extended friend declarations, as defined in N1791.
196 cxx_extern_templates
198 Extern templates, as defined in N1987.
199 cxx_final
201 Override control final keyword, as defined in N2928, N3206 and
202 N3272.
203 cxx_func_identifier
205 Predefined __func__ identifier, as defined in N2340.
206 cxx_generalized_initializers
208 Initializer lists, as defined in N2672.
209 cxx_generic_lambdas
211 Generic lambdas, as defined in N3649.
212 cxx_inheriting_constructors
214 Inheriting constructors, as defined in N2540.
215 cxx_inline_namespaces
217 Inline namespaces, as defined in N2535.
218 cxx_lambdas
220 Lambda functions, as defined in N2927.
221 cxx_lambda_init_captures
223 Initialized lambda captures, as defined in N3648.
224 cxx_local_type_template_args
226 Local and unnamed types as template arguments, as defined in
227 N2657.
228 cxx_long_long_type
230 long long type, as defined in N1811.
231 cxx_noexcept
233 Exception specifications, as defined in N3050.
234 cxx_nonstatic_member_init
236 Non-static data member initialization, as defined in N2756.
237 cxx_nullptr
239 Null pointer, as defined in N2431.
240 cxx_override
242 Override control override keyword, as defined in N2928, N3206
243 and N3272.
244 cxx_range_for
246 Range-based for, as defined in N2930.
247 cxx_raw_string_literals
249 Raw string literals, as defined in N2442.
250 cxx_reference_qualified_functions
252 Reference qualified functions, as defined in N2439.
253 cxx_relaxed_constexpr
255 Relaxed constexpr, as defined in N3652.
256 cxx_return_type_deduction
258 Return type deduction on normal functions, as defined in N3386.
259 cxx_right_angle_brackets
261 Right angle bracket parsing, as defined in N1757.
262 cxx_rvalue_references
264 R-value references, as defined in N2118.
265 cxx_sizeof_member
267 Size of non-static data members, as defined in N2253.
268 cxx_static_assert
270 Static assert, as defined in N1720.
271 cxx_strong_enums
273 Strongly typed enums, as defined in N2347.
274 cxx_thread_local
276 Thread-local variables, as defined in N2659.
277 cxx_trailing_return_types
279 Automatic function return type, as defined in N2541.
280 cxx_unicode_literals
282 Unicode string literals, as defined in N2442.
283 cxx_uniform_initialization
285 Uniform initialization, as defined in N2640.
286 cxx_unrestricted_unions
288 Unrestricted unions, as defined in N2544.
289 cxx_user_literals
291 User-defined literals, as defined in N2765.
292 cxx_variable_templates
294 Variable templates, as defined in N3651.
295 cxx_variadic_macros
297 Variadic macros, as defined in N1653.
298 cxx_variadic_templates
300 Variadic templates, as defined in N2242.
301 cxx_template_template_parameters
303 Template template parameters, as defined in ISO/IEC 14882:1998.
304 CMAKE_ROLE
306 Tells what mode the current running script is in. Could be one of sev‐
307 eral values:
308 PROJECT
310 Running in project mode (processing a CMakeLists.txt file).
311 SCRIPT Running in -P script mode.
313 FIND_PACKAGE
315 Running in --find-package mode.
316 CTEST Running in CTest script mode.
318 CPACK Running in CPack.
320 DEBUG_CONFIGURATIONS
322 Specify which configurations are for debugging.
323 The value must be a semi-colon separated list of configuration names.
325 Currently this property is used only by the target_link_libraries()
326 command. Additional uses may be defined in the future.
327 This property must be set at the top level of the project and before
329 the first target_link_libraries() command invocation. If any entry in
330 the list does not match a valid configuration for the project the
331 behavior is undefined.
332 DISABLED_FEATURES
334 List of features which are disabled during the CMake run.
335 List of features which are disabled during the CMake run. By default
337 it contains the names of all packages which were not found. This is
338 determined using the <NAME>_FOUND variables. Packages which are
339 searched QUIET are not listed. A project can add its own features to
340 this list. This property is used by the macros in FeatureSum‐
341 mary.cmake.
342 ENABLED_FEATURES
344 List of features which are enabled during the CMake run.
345 List of features which are enabled during the CMake run. By default it
347 contains the names of all packages which were found. This is deter‐
348 mined using the <NAME>_FOUND variables. Packages which are searched
349 QUIET are not listed. A project can add its own features to this list.
350 This property is used by the macros in FeatureSummary.cmake.
351 ENABLED_LANGUAGES
353 Read-only property that contains the list of currently enabled lan‐
354 guages
355 Set to list of currently enabled languages.
357 FIND_LIBRARY_USE_LIB32_PATHS
359 Whether the find_library() command should automatically search lib32
360 directories.
361 FIND_LIBRARY_USE_LIB32_PATHS is a boolean specifying whether the
363 find_library() command should automatically search the lib32 variant of
364 directories called lib in the search path when building 32-bit bina‐
365 ries.
366 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
368 FIND_LIBRARY_USE_LIB64_PATHS
370 Whether find_library() should automatically search lib64 directories.
371 FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
373 find_library() command should automatically search the lib64 variant of
374 directories called lib in the search path when building 64-bit bina‐
375 ries.
376 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
378 FIND_LIBRARY_USE_LIBX32_PATHS
380 Whether the find_library() command should automatically search libx32
381 directories.
382 FIND_LIBRARY_USE_LIBX32_PATHS is a boolean specifying whether the
384 find_library() command should automatically search the libx32 variant
385 of directories called lib in the search path when building x32-abi
386 binaries.
387 See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.
389 FIND_LIBRARY_USE_OPENBSD_VERSIONING
391 Whether find_library() should find OpenBSD-style shared libraries.
392 This property is a boolean specifying whether the find_library() com‐
394 mand should find shared libraries with OpenBSD-style versioned exten‐
395 sion: “.so.<major>.<minor>”. The property is set to true on OpenBSD
396 and false on other platforms.
397 GENERATOR_IS_MULTI_CONFIG
399 Read-only property that is true on multi-configuration generators.
400 True when using a multi-configuration generator (such as Visual Studio
402 Generators or Xcode). Multi-config generators use CMAKE_CONFIGURA‐
403 TION_TYPES as the set of configurations and ignore CMAKE_BUILD_TYPE.
404 GLOBAL_DEPENDS_DEBUG_MODE
406 Enable global target dependency graph debug mode.
407 CMake automatically analyzes the global inter-target dependency graph
409 at the beginning of native build system generation. This property
410 causes it to display details of its analysis to stderr.
411 GLOBAL_DEPENDS_NO_CYCLES
413 Disallow global target dependency graph cycles.
414 CMake automatically analyzes the global inter-target dependency graph
416 at the beginning of native build system generation. It reports an
417 error if the dependency graph contains a cycle that does not consist of
418 all STATIC library targets. This property tells CMake to disallow all
419 cycles completely, even among static libraries.
420 IN_TRY_COMPILE
422 Read-only property that is true during a try-compile configuration.
423 True when building a project inside a try_compile() or try_run() com‐
425 mand.
426 PACKAGES_FOUND
428 List of packages which were found during the CMake run.
429 List of packages which were found during the CMake run. Whether a
431 package has been found is determined using the <NAME>_FOUND variables.
432 PACKAGES_NOT_FOUND
434 List of packages which were not found during the CMake run.
435 List of packages which were not found during the CMake run. Whether a
437 package has been found is determined using the <NAME>_FOUND variables.
438 JOB_POOLS
440 Ninja only: List of available pools.
441 A pool is a named integer property and defines the maximum number of
443 concurrent jobs which can be started by a rule assigned to the pool.
444 The JOB_POOLS property is a semicolon-separated list of pairs using the
445 syntax NAME=integer (without a space after the equality sign).
446 For instance:
448 set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10)
450 Defined pools could be used globally by setting CMAKE_JOB_POOL_COMPILE
452 and CMAKE_JOB_POOL_LINK or per target by setting the target properties
453 JOB_POOL_COMPILE and JOB_POOL_LINK. Custom commands and custom targets
454 can specify pools using the option JOB_POOL. Using a pool that is not
455 defined by JOB_POOLS causes an error by ninja at build time.
456 If not set, this property uses the value of the CMAKE_JOB_POOLS vari‐
458 able.
459 Build targets provided by CMake that are meant for individual interac‐
461 tive use, such as install, are placed in the console pool automati‐
462 cally.
463 PREDEFINED_TARGETS_FOLDER
465 Name of FOLDER for targets that are added automatically by CMake.
466 If not set, CMake uses “CMakePredefinedTargets” as a default value for
468 this property. Targets such as INSTALL, PACKAGE and RUN_TESTS will be
469 organized into this FOLDER. See also the documentation for the FOLDER
470 target property.
471 ECLIPSE_EXTRA_NATURES
473 List of natures to add to the generated Eclipse project file.
474 Eclipse projects specify language plugins by using natures. This prop‐
476 erty should be set to the unique identifier for a nature (which looks
477 like a Java package name).
478 Also see the ECLIPSE_EXTRA_CPROJECT_CONTENTS property.
480 ECLIPSE_EXTRA_CPROJECT_CONTENTS
482 Additional contents to be inserted into the generated Eclipse cproject
483 file.
484 The cproject file defines the CDT specific information. Some third
486 party IDE’s are based on Eclipse with the addition of other information
487 specific to that IDE. Through this property, it is possible to add
488 this additional contents to the generated project. It is expected to
489 contain valid XML.
490 Also see the ECLIPSE_EXTRA_NATURES property.
492 REPORT_UNDEFINED_PROPERTIES
494 If set, report any undefined properties to this file.
495 If this property is set to a filename then when CMake runs it will
497 report any properties or variables that were accessed but not defined
498 into the filename specified in this property.
499 RULE_LAUNCH_COMPILE
501 Specify a launcher for compile rules.
502 Makefile Generators and the Ninja generator prefix compiler commands
504 with the given launcher command line. This is intended to allow
505 launchers to intercept build problems with high granularity. Other
506 generators ignore this property because their underlying build systems
507 provide no hook to wrap individual commands with a launcher.
508 RULE_LAUNCH_CUSTOM
510 Specify a launcher for custom rules.
511 Makefile Generators and the Ninja generator prefix custom commands with
513 the given launcher command line. This is intended to allow launchers
514 to intercept build problems with high granularity. Other generators
515 ignore this property because their underlying build systems provide no
516 hook to wrap individual commands with a launcher.
517 RULE_LAUNCH_LINK
519 Specify a launcher for link rules.
520 Makefile Generators and the Ninja generator prefix link and archive
522 commands with the given launcher command line. This is intended to
523 allow launchers to intercept build problems with high granularity.
524 Other generators ignore this property because their underlying build
525 systems provide no hook to wrap individual commands with a launcher.
526 RULE_MESSAGES
528 Specify whether to report a message for each make rule.
529 This property specifies whether Makefile generators should add a
531 progress message describing what each build rule does. If the property
532 is not set the default is ON. Set the property to OFF to disable gran‐
533 ular messages and report only as each target completes. This is
534 intended to allow scripted builds to avoid the build time cost of
535 detailed reports. If a CMAKE_RULE_MESSAGES cache entry exists its
536 value initializes the value of this property. Non-Makefile generators
537 currently ignore this property.
538 TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
540 Set if shared libraries may be named like archives.
541 On AIX shared libraries may be named “lib<name>.a”. This property is
543 set to true on such platforms.
544 TARGET_MESSAGES
546 Specify whether to report the completion of each target.
547 This property specifies whether Makefile Generators should add a
549 progress message describing that each target has been completed. If
550 the property is not set the default is ON. Set the property to OFF to
551 disable target completion messages.
552 This option is intended to reduce build output when little or no work
554 needs to be done to bring the build tree up to date.
555 If a CMAKE_TARGET_MESSAGES cache entry exists its value initializes the
557 value of this property.
558 Non-Makefile generators currently ignore this property.
560 See the counterpart property RULE_MESSAGES to disable everything except
562 for target completion messages.
563 TARGET_SUPPORTS_SHARED_LIBS
565 Does the target platform support shared libraries.
566 TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target
568 platform supports shared libraries. Basically all current general gen‐
569 eral purpose OS do so, the exception are usually embedded systems with
570 no or special OSs.
571 USE_FOLDERS
573 Use the FOLDER target property to organize targets into folders.
574 If not set, CMake treats this property as OFF by default. CMake gener‐
576 ators that are capable of organizing into a hierarchy of folders use
577 the values of the FOLDER target property to name those folders. See
578 also the documentation for the FOLDER target property.
579 XCODE_EMIT_EFFECTIVE_PLATFORM_NAME
581 Control emission of EFFECTIVE_PLATFORM_NAME by the Xcode generator.
582 It is required for building the same target with multiple SDKs. A com‐
584 mon use case is the parallel use of iphoneos and iphonesimulator SDKs.
585 Three different states possible that control when the Xcode generator
587 emits the EFFECTIVE_PLATFORM_NAME variable:
588 · If set to ON it will always be emitted
590 · If set to OFF it will never be emitted
592 · If unset (the default) it will only be emitted when the project was
594 configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
595 of the simulators.
596 NOTE:
598 When this behavior is enable for generated Xcode projects, the
599 EFFECTIVE_PLATFORM_NAME variable will leak into Generator expres‐
600 sions like TARGET_FILE and will render those mostly unusable.
601
603 ADDITIONAL_CLEAN_FILES
604 A ;-list of files or directories that will be removed as a part of the
605 global clean target. It is useful for specifying generated files or
606 directories that are used by multiple targets or by CMake itself, or
607 that are generated in ways which cannot be captured as outputs or
608 byproducts of custom commands.
609 If an additional clean file is specific to a single target only, then
611 the ADDITIONAL_CLEAN_FILES target property would usually be a better
612 choice than this directory property.
613 Relative paths are allowed and are interpreted relative to the current
615 binary directory.
616 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
618 This property only works for the Ninja and the Makefile generators. It
620 is ignored by other generators.
621 BINARY_DIR
623 This read-only directory property reports absolute path to the binary
624 directory corresponding to the source on which it is read.
625 BUILDSYSTEM_TARGETS
627 This read-only directory property contains a semicolon-separated list
628 of buildsystem targets added in the directory by calls to the
629 add_library(), add_executable(), and add_custom_target() commands. The
630 list does not include any Imported Targets or Alias Targets, but does
631 include Interface Libraries. Each entry in the list is the logical
632 name of a target, suitable to pass to the get_property() command TARGET
633 option.
634 CACHE_VARIABLES
636 List of cache variables available in the current directory.
637 This read-only property specifies the list of CMake cache variables
639 currently defined. It is intended for debugging purposes.
640 CLEAN_NO_CUSTOM
642 Set to true to tell Makefile Generators not to remove the outputs of
643 custom commands for this directory during the make clean operation.
644 This is ignored on other generators because it is not possible to
645 implement.
646 CMAKE_CONFIGURE_DEPENDS
648 Tell CMake about additional input files to the configuration process.
649 If any named file is modified the build system will re-run CMake to
650 re-configure the file and generate the build system again.
651 Specify files as a semicolon-separated list of paths. Relative paths
653 are interpreted as relative to the current source directory.
654 COMPILE_DEFINITIONS
656 Preprocessor definitions for compiling a directory’s sources.
657 This property specifies the list of options given so far to the
659 add_compile_definitions() (or add_definitions()) command.
660 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
662 list of preprocessor definitions using the syntax VAR or VAR=value.
663 Function-style definitions are not supported. CMake will automatically
664 escape the value correctly for the native build system (note that CMake
665 language syntax may require escapes to specify some values).
666 This property will be initialized in each directory by its value in the
668 directory’s parent.
669 CMake will automatically drop some definitions that are not supported
671 by the native build tool.
672 Disclaimer: Most native build tools have poor support for escaping cer‐
674 tain values. CMake has work-arounds for many cases but some values may
675 just not be possible to pass correctly. If a value does not seem to be
676 escaped correctly, do not attempt to work-around the problem by adding
677 escape sequences to the value. Your work-around may break in a future
678 version of CMake that has improved escape support. Instead consider
679 defining the macro in a (configured) header file. Then report the lim‐
680 itation. Known limitations include:
681 # - broken almost everywhere
683 ; - broken in VS IDE 7.0 and Borland Makefiles
684 , - broken in VS IDE
685 % - broken in some cases in NMake
686 & | - broken in some cases on MinGW
687 ^ < > \" - broken in most Make tools on Windows
688 CMake does not reject these values outright because they do work in
690 some cases. Use with caution.
691 Contents of COMPILE_DEFINITIONS may use “generator expressions” with
693 the syntax $<...>. See the cmake-generator-expressions(7) manual for
694 available expressions. See the cmake-buildsystem(7) manual for more on
695 defining buildsystem properties.
696 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
698 specify per-configuration definitions. Generator expressions should be
699 preferred instead of setting the alternative property.
700 COMPILE_OPTIONS
702 List of options to pass to the compiler.
703 This property holds a semicolon-separated list of options given so far
705 to the add_compile_options() command.
706 This property is used to initialize the COMPILE_OPTIONS target property
708 when a target is created, which is used by the generators to set the
709 options for the compiler.
710 Contents of COMPILE_OPTIONS may use “generator expressions” with the
712 syntax $<...>. See the cmake-generator-expressions(7) manual for
713 available expressions. See the cmake-buildsystem(7) manual for more on
714 defining buildsystem properties.
715 DEFINITIONS
717 For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead.
718 This read-only property specifies the list of flags given so far to the
720 add_definitions() command. It is intended for debugging purposes. Use
721 the COMPILE_DEFINITIONS directory property instead.
722 This built-in read-only property does not exist if policy CMP0059 is
724 set to NEW.
725 EXCLUDE_FROM_ALL
727 Set this directory property to a true value on a subdirectory to
728 exclude its targets from the “all” target of its ancestors. If
729 excluded, running e.g. make in the parent directory will not build tar‐
730 gets the subdirectory by default. This does not affect the “all” tar‐
731 get of the subdirectory itself. Running e.g. make inside the subdirec‐
732 tory will still build its targets.
733 If the EXCLUDE_FROM_ALL target property is set on a target then its
735 value determines whether the target is included in the “all” target of
736 this directory and its ancestors.
737 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
739 Specify #include line transforms for dependencies in a directory.
740 This property specifies rules to transform macro-like #include lines
742 during implicit dependency scanning of C and C++ source files. The
743 list of rules must be semicolon-separated with each entry of the form
744 A_MACRO(%)=value-with-% (the % must be literal). During dependency
745 scanning occurrences of A_MACRO(...) on #include lines will be replaced
746 by the value given with the macro argument substituted for %. For
747 example, the entry
748 MYDIR(%)=<mydir/%>
750 will convert lines of the form
752 #include MYDIR(myheader.h)
754 to
756 #include <mydir/myheader.h>
758 allowing the dependency to be followed.
760 This property applies to sources in all targets within a directory.
762 The property value is initialized in each directory by its value in the
763 directory’s parent.
764 INCLUDE_DIRECTORIES
766 List of preprocessor include file search directories.
767 This property specifies the list of directories given so far to the
769 include_directories() command.
770 This property is used to populate the INCLUDE_DIRECTORIES target prop‐
772 erty, which is used by the generators to set the include directories
773 for the compiler.
774 In addition to accepting values from that command, values may be set
776 directly on any directory using the set_property() command, and can be
777 set on the current directory using the set_directory_properties() com‐
778 mand. A directory gets its initial value from its parent directory if
779 it has one. The initial value of the INCLUDE_DIRECTORIES target prop‐
780 erty comes from the value of this property. Both directory and target
781 property values are adjusted by calls to the include_directories() com‐
782 mand. Calls to set_property() or set_directory_properties(), however,
783 will update the directory property value without updating target prop‐
784 erty values. Therefore direct property updates must be made before
785 calls to add_executable() or add_library() for targets they are meant
786 to affect.
787 The target property values are used by the generators to set the
789 include paths for the compiler.
790 Contents of INCLUDE_DIRECTORIES may use “generator expressions” with
792 the syntax $<...>. See the cmake-generator-expressions(7) manual for
793 available expressions. See the cmake-buildsystem(7) manual for more on
794 defining buildsystem properties.
795 INCLUDE_REGULAR_EXPRESSION
797 Include file scanning regular expression.
798 This property specifies the regular expression used during dependency
800 scanning to match include files that should be followed. See the
801 include_regular_expression() command for a high-level interface to set
802 this property.
803 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
805 Per-configuration interprocedural optimization for a directory.
806 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
808 If set, this property overrides the generic property for the named con‐
809 figuration.
810 INTERPROCEDURAL_OPTIMIZATION
812 Enable interprocedural optimization for targets in a directory.
813 If set to true, enables interprocedural optimizations if they are known
815 to be supported by the compiler.
816 LABELS
818 Specify a list of text labels associated with a directory and all of
819 its subdirectories. This is equivalent to setting the LABELS target
820 property and the LABELS test property on all targets and tests in the
821 current directory and subdirectories. Note: Launchers must enabled to
822 propagate labels to targets.
823 The CMAKE_DIRECTORY_LABELS variable can be used to initialize this
825 property.
826 The list is reported in dashboard submissions.
828 LINK_DIRECTORIES
830 List of linker search directories.
831 This property holds a semicolon-separated list of directories and is
833 typically populated using the link_directories() command. It gets its
834 initial value from its parent directory, if it has one.
835 The directory property is used to initialize the LINK_DIRECTORIES tar‐
837 get property when a target is created. That target property is used by
838 the generators to set the library search directories for the linker.
839 Contents of LINK_DIRECTORIES may use “generator expressions” with the
841 syntax $<...>. See the cmake-generator-expressions(7) manual for
842 available expressions. See the cmake-buildsystem(7) manual for more on
843 defining buildsystem properties.
844 LINK_OPTIONS
846 List of options to use for the link step of shared library, module and
847 executable targets.
848 This property holds a semicolon-separated list of options given so far
850 to the add_link_options() command.
851 This property is used to initialize the LINK_OPTIONS target property
853 when a target is created, which is used by the generators to set the
854 options for the compiler.
855 Contents of LINK_OPTIONS may use “generator expressions” with the syn‐
857 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
858 able expressions. See the cmake-buildsystem(7) manual for more on
859 defining buildsystem properties.
860 LISTFILE_STACK
862 The current stack of listfiles being processed.
863 This property is mainly useful when trying to debug errors in your
865 CMake scripts. It returns a list of what list files are currently
866 being processed, in order. So if one listfile does an include() com‐
867 mand then that is effectively pushing the included listfile onto the
868 stack.
869 MACROS
871 List of macro commands available in the current directory.
872 This read-only property specifies the list of CMake macros currently
874 defined. It is intended for debugging purposes. See the macro() com‐
875 mand.
876 PARENT_DIRECTORY
878 Source directory that added current subdirectory.
879 This read-only property specifies the source directory that added the
881 current source directory as a subdirectory of the build. In the
882 top-level directory the value is the empty-string.
883 RULE_LAUNCH_COMPILE
885 Specify a launcher for compile rules.
886 See the global property of the same name for details. This overrides
888 the global property for a directory.
889 RULE_LAUNCH_CUSTOM
891 Specify a launcher for custom rules.
892 See the global property of the same name for details. This overrides
894 the global property for a directory.
895 RULE_LAUNCH_LINK
897 Specify a launcher for link rules.
898 See the global property of the same name for details. This overrides
900 the global property for a directory.
901 SOURCE_DIR
903 This read-only directory property reports absolute path to the source
904 directory on which it is read.
905 SUBDIRECTORIES
907 This read-only directory property contains a semicolon-separated list
908 of subdirectories processed so far by the add_subdirectory() or sub‐
909 dirs() commands. Each entry is the absolute path to the source direc‐
910 tory (containing the CMakeLists.txt file). This is suitable to pass to
911 the get_property() command DIRECTORY option.
912 NOTE:
914 The subdirs() command does not process its arguments until after the
915 calling directory is fully processed. Therefore looking up this
916 property in the current directory will not see them.
917 TESTS
919 List of tests.
920 This read-only property holds a semicolon-separated list of tests
922 defined so far, in the current directory, by the add_test() command.
923 TEST_INCLUDE_FILES
925 A list of cmake files that will be included when ctest is run.
926 If you specify TEST_INCLUDE_FILES, those files will be included and
928 processed when ctest is run on the directory.
929 VARIABLES
931 List of variables defined in the current directory.
932 This read-only property specifies the list of CMake variables currently
934 defined. It is intended for debugging purposes.
935 VS_GLOBAL_SECTION_POST_<section>
937 Specify a postSolution global section in Visual Studio.
938 Setting a property like this generates an entry of the following form
940 in the solution file:
941 GlobalSection(<section>) = postSolution
943 <contents based on property value>
944 EndGlobalSection
945 The property must be set to a semicolon-separated list of key=value
947 pairs. Each such pair will be transformed into an entry in the solu‐
948 tion global section. Whitespace around key and value is ignored. List
949 elements which do not contain an equal sign are skipped.
950 This property only works for Visual Studio 9 and above; it is ignored
952 on other generators. The property only applies when set on a directory
953 whose CMakeLists.txt contains a project() command.
954 Note that CMake generates postSolution sections ExtensibilityGlobals
956 and ExtensibilityAddIns by default. If you set the corresponding prop‐
957 erty, it will override the default section. For example, setting
958 VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default
959 contents of the ExtensibilityGlobals section, while keeping Extensibil‐
960 ityAddIns on its default. However, CMake will always add a Solu‐
961 tionGuid to the ExtensibilityGlobals section if it is not specified
962 explicitly.
963 VS_GLOBAL_SECTION_PRE_<section>
965 Specify a preSolution global section in Visual Studio.
966 Setting a property like this generates an entry of the following form
968 in the solution file:
969 GlobalSection(<section>) = preSolution
971 <contents based on property value>
972 EndGlobalSection
973 The property must be set to a semicolon-separated list of key=value
975 pairs. Each such pair will be transformed into an entry in the solu‐
976 tion global section. Whitespace around key and value is ignored. List
977 elements which do not contain an equal sign are skipped.
978 This property only works for Visual Studio 9 and above; it is ignored
980 on other generators. The property only applies when set on a directory
981 whose CMakeLists.txt contains a project() command.
982 VS_STARTUP_PROJECT
984 Specify the default startup project in a Visual Studio solution.
985 The Visual Studio Generators create a .sln file for each directory
987 whose CMakeLists.txt file calls the project() command. Set this prop‐
988 erty in the same directory as a project() command call (e.g. in the
989 top-level CMakeLists.txt file) to specify the default startup project
990 for the corresponding solution file.
991 The property must be set to the name of an existing target. This will
993 cause that project to be listed first in the generated solution file
994 causing Visual Studio to make it the startup project if the solution
995 has never been opened before.
996 If this property is not specified, then the ALL_BUILD project will be
998 the default.
999
1001 ADDITIONAL_CLEAN_FILES
1002 A ;-list of files or directories that will be removed as a part of the
1003 global clean target. It can be used to specify files and directories
1004 that are generated as part of building the target or that are directly
1005 associated with the target in some way (e.g. created as a result of
1006 running the target).
1007 For custom targets, if such files can be captured as outputs or byprod‐
1009 ucts instead, then that should be preferred over adding them to this
1010 property. If an additional clean file is used by multiple targets or
1011 isn’t target-specific, then the ADDITIONAL_CLEAN_FILES directory prop‐
1012 erty may be the more appropriate property to use.
1013 Relative paths are allowed and are interpreted relative to the current
1015 binary directory.
1016 Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.
1018 This property only works for the Ninja and the Makefile generators. It
1020 is ignored by other generators.
1021 ALIASED_TARGET
1023 Name of target aliased by this target.
1024 If this is an Alias Target, this property contains the name of the tar‐
1026 get aliased.
1027 ANDROID_ANT_ADDITIONAL_OPTIONS
1029 Set the additional options for Android Ant build system. This is a
1030 string value containing all command line options for the Ant build.
1031 This property is initialized by the value of the
1032 CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS variable if it is set when a tar‐
1033 get is created.
1034 ANDROID_API
1036 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1037 Edition, this property sets the Android target API version (e.g. 15).
1038 The version number must be a positive decimal integer. This property
1039 is initialized by the value of the CMAKE_ANDROID_API variable if it is
1040 set when a target is created.
1041 ANDROID_API_MIN
1043 Set the Android MIN API version (e.g. 9). The version number must be a
1044 positive decimal integer. This property is initialized by the value of
1045 the CMAKE_ANDROID_API_MIN variable if it is set when a target is cre‐
1046 ated. Native code builds using this API version.
1047 ANDROID_ARCH
1049 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1050 Edition, this property sets the Android target architecture.
1051 This is a string property that could be set to the one of the following
1053 values:
1054 · armv7-a: “ARMv7-A (armv7-a)”
1056 · armv7-a-hard: “ARMv7-A, hard-float ABI (armv7-a)”
1058 · arm64-v8a: “ARMv8-A, 64bit (arm64-v8a)”
1060 · x86: “x86 (x86)”
1062 · x86_64: “x86_64 (x86_64)”
1064 This property is initialized by the value of the CMAKE_ANDROID_ARCH
1066 variable if it is set when a target is created.
1067 ANDROID_ASSETS_DIRECTORIES
1069 Set the Android assets directories to copy into the main assets folder
1070 before build. This a string property that contains the directory paths
1071 separated by semicolon. This property is initialized by the value of
1072 the CMAKE_ANDROID_ASSETS_DIRECTORIES variable if it is set when a tar‐
1073 get is created.
1074 ANDROID_GUI
1076 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1077 Edition, this property specifies whether to build an executable as an
1078 application package on Android.
1079 When this property is set to true the executable when built for Android
1081 will be created as an application package. This property is initial‐
1082 ized by the value of the CMAKE_ANDROID_GUI variable if it is set when a
1083 target is created.
1084 Add the AndroidManifest.xml source file explicitly to the target
1086 add_executable() command invocation to specify the root directory of
1087 the application package source.
1088 ANDROID_JAR_DEPENDENCIES
1090 Set the Android property that specifies JAR dependencies. This is a
1091 string value property. This property is initialized by the value of the
1092 CMAKE_ANDROID_JAR_DEPENDENCIES variable if it is set when a target is
1093 created.
1094 ANDROID_JAR_DIRECTORIES
1096 Set the Android property that specifies directories to search for the
1097 JAR libraries.
1098 This a string property that contains the directory paths separated by
1100 semicolons. This property is initialized by the value of the
1101 CMAKE_ANDROID_JAR_DIRECTORIES variable if it is set when a target is
1102 created.
1103 Contents of ANDROID_JAR_DIRECTORIES may use “generator expressions”
1105 with the syntax $<...>. See the cmake-generator-expressions(7) manual
1106 for available expressions.
1107 ANDROID_JAVA_SOURCE_DIR
1109 Set the Android property that defines the Java source code root direc‐
1110 tories. This a string property that contains the directory paths sepa‐
1111 rated by semicolon. This property is initialized by the value of the
1112 CMAKE_ANDROID_JAVA_SOURCE_DIR variable if it is set when a target is
1113 created.
1114 ANDROID_NATIVE_LIB_DEPENDENCIES
1116 Set the Android property that specifies the .so dependencies. This is
1117 a string property.
1118 This property is initialized by the value of the
1120 CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES variable if it is set when a tar‐
1121 get is created.
1122 Contents of ANDROID_NATIVE_LIB_DEPENDENCIES may use “generator expres‐
1124 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
1125 manual for available expressions.
1126 ANDROID_NATIVE_LIB_DIRECTORIES
1128 Set the Android property that specifies directories to search for the
1129 .so libraries.
1130 This a string property that contains the directory paths separated by
1132 semicolons.
1133 This property is initialized by the value of the
1135 CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES variable if it is set when a tar‐
1136 get is created.
1137 Contents of ANDROID_NATIVE_LIB_DIRECTORIES may use “generator expres‐
1139 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
1140 manual for available expressions.
1141 ANDROID_PROCESS_MAX
1143 Set the Android property that defines the maximum number of a parallel
1144 Android NDK compiler processes (e.g. 4). This property is initialized
1145 by the value of the CMAKE_ANDROID_PROCESS_MAX variable if it is set
1146 when a target is created.
1147 ANDROID_PROGUARD
1149 When this property is set to true that enables the ProGuard tool to
1150 shrink, optimize, and obfuscate the code by removing unused code and
1151 renaming classes, fields, and methods with semantically obscure names.
1152 This property is initialized by the value of the CMAKE_ANDROID_PROGUARD
1153 variable if it is set when a target is created.
1154 ANDROID_PROGUARD_CONFIG_PATH
1156 Set the Android property that specifies the location of the ProGuard
1157 config file. Leave empty to use the default one. This a string prop‐
1158 erty that contains the path to ProGuard config file. This property is
1159 initialized by the value of the CMAKE_ANDROID_PROGUARD_CONFIG_PATH
1160 variable if it is set when a target is created.
1161 ANDROID_SECURE_PROPS_PATH
1163 Set the Android property that states the location of the secure proper‐
1164 ties file. This is a string property that contains the file path.
1165 This property is initialized by the value of the
1166 CMAKE_ANDROID_SECURE_PROPS_PATH variable if it is set when a target is
1167 created.
1168 ANDROID_SKIP_ANT_STEP
1170 Set the Android property that defines whether or not to skip the Ant
1171 build step. This is a boolean property initialized by the value of the
1172 CMAKE_ANDROID_SKIP_ANT_STEP variable if it is set when a target is cre‐
1173 ated.
1174 ANDROID_STL_TYPE
1176 When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
1177 Edition, this property specifies the type of STL support for the
1178 project. This is a string property that could set to the one of the
1179 following values:
1180 none No C++ Support
1182 system Minimal C++ without STL
1184 gabi++_static
1186 GAbi++ Static
1187 gabi++_shared
1189 GAbi++ Shared
1190 gnustl_static
1192 GNU libstdc++ Static
1193 gnustl_shared
1195 GNU libstdc++ Shared
1196 stlport_static
1198 STLport Static
1199 stlport_shared
1201 STLport Shared
1202 This property is initialized by the value of the CMAKE_ANDROID_STL_TYPE
1204 variable if it is set when a target is created.
1205 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
1207 Per-configuration output directory for ARCHIVE target files.
1208 This is a per-configuration version of the ARCHIVE_OUTPUT_DIRECTORY
1210 target property, but multi-configuration generators (VS, Xcode) do NOT
1211 append a per-configuration subdirectory to the specified directory.
1212 This property is initialized by the value of the CMAKE_ARCHIVE_OUT‐
1213 PUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.
1214 Contents of ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
1216 sions.
1217 ARCHIVE_OUTPUT_DIRECTORY
1219 Output directory in which to build ARCHIVE target files.
1220 This property specifies the directory into which archive target files
1222 should be built. The property value may use generator expressions.
1223 Multi-configuration generators (VS, Xcode) append a per-configuration
1224 subdirectory to the specified directory unless a generator expression
1225 is used.
1226 This property is initialized by the value of the variable CMAKE_AR‐
1228 CHIVE_OUTPUT_DIRECTORY if it is set when a target is created.
1229 See also the ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> target property.
1231 ARCHIVE_OUTPUT_NAME_<CONFIG>
1233 Per-configuration output name for ARCHIVE target files.
1234 This is the configuration-specific version of the ARCHIVE_OUTPUT_NAME
1236 target property.
1237 ARCHIVE_OUTPUT_NAME
1239 Output name for ARCHIVE target files.
1240 This property specifies the base name for archive target files. It
1242 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
1243 See also the ARCHIVE_OUTPUT_NAME_<CONFIG> target property.
1245 AUTOGEN_BUILD_DIR
1247 Directory where AUTOMOC, AUTOUIC and AUTORCC generate files for the
1248 target.
1249 The directory is created on demand and automatically added to the ADDI‐
1251 TIONAL_CLEAN_FILES target property.
1252 When unset or empty the directory <dir>/<target-name>_autogen is used
1254 where <dir> is CMAKE_CURRENT_BINARY_DIR and <target-name> is NAME.
1255 By default AUTOGEN_BUILD_DIR is unset.
1257 See the cmake-qt(7) manual for more information on using CMake with Qt.
1259 AUTOGEN_ORIGIN_DEPENDS
1261 Switch for forwarding origin target dependencies to the corresponding
1262 _autogen target.
1263 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1265 sponding _autogen target which generates moc and uic files. As this
1266 _autogen target is created at generate-time, it is not possible to
1267 define dependencies of it using e.g. add_dependencies(). Instead the
1268 AUTOGEN_ORIGIN_DEPENDS target property decides whether the origin tar‐
1269 get dependencies should be forwarded to the _autogen target or not.
1270 By default AUTOGEN_ORIGIN_DEPENDS is initialized from CMAKE_AUTO‐
1272 GEN_ORIGIN_DEPENDS which is ON by default.
1273 In total the dependencies of the _autogen target are composed from
1275 · forwarded origin target dependencies (enabled by default via
1277 AUTOGEN_ORIGIN_DEPENDS)
1278 · additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1280 See the cmake-qt(7) manual for more information on using CMake with Qt.
1282 Note
1284 Disabling AUTOGEN_ORIGIN_DEPENDS is useful to avoid building of origin
1285 target dependencies when building the _autogen target only. This is
1286 especially interesting when a global autogen target is enabled.
1287 When the _autogen target doesn’t require all the origin target’s depen‐
1289 dencies, and AUTOGEN_ORIGIN_DEPENDS is disabled, it might be necessary
1290 to extend AUTOGEN_TARGET_DEPENDS to add missing dependencies.
1291 AUTOGEN_PARALLEL
1293 Number of parallel moc or uic processes to start when using AUTOMOC and
1294 AUTOUIC.
1295 The custom <origin>_autogen target starts a number of threads of which
1297 each one parses a source file and on demand starts a moc or uic
1298 process. AUTOGEN_PARALLEL controls how many parallel threads (and
1299 therefore moc or uic processes) are started.
1300 · An empty (or unset) value or the string AUTO sets the number of
1302 threads/processes to the number of physical CPUs on the host system.
1303 · A positive non zero integer value sets the exact thread/process
1305 count.
1306 · Otherwise a single thread/process is started.
1308 By default AUTOGEN_PARALLEL is initialized from CMAKE_AUTOGEN_PARALLEL.
1310 See the cmake-qt(7) manual for more information on using CMake with Qt.
1312 AUTOGEN_TARGET_DEPENDS
1314 Additional target dependencies of the corresponding _autogen target.
1315 Targets which have their AUTOMOC or AUTOUIC property ON have a corre‐
1317 sponding _autogen target which generates moc and uic files. As this
1318 _autogen target is created at generate-time, it is not possible to
1319 define dependencies of it using e.g. add_dependencies(). Instead the
1320 AUTOGEN_TARGET_DEPENDS target property can be set to a ;-list of addi‐
1321 tional dependencies for the _autogen target. Dependencies can be tar‐
1322 get names or file names.
1323 In total the dependencies of the _autogen target are composed from
1325 · forwarded origin target dependencies (enabled by default via AUTO‐
1327 GEN_ORIGIN_DEPENDS)
1328 · additional user defined dependencies from AUTOGEN_TARGET_DEPENDS
1330 See the cmake-qt(7) manual for more information on using CMake with Qt.
1332 Use cases
1334 If AUTOMOC or AUTOUIC depends on a file that is either
1335 · a GENERATED non C++ file (e.g. a GENERATED .json or .ui file) or
1337 · a GENERATED C++ file that isn’t recognized by AUTOMOC and AUTOUIC
1339 because it’s skipped by SKIP_AUTOMOC, SKIP_AUTOUIC, SKIP_AUTOGEN or
1340 CMP0071 or
1341 · a file that isn’t in the origin target’s sources
1343 it must added to AUTOGEN_TARGET_DEPENDS.
1345 AUTOMOC_COMPILER_PREDEFINES
1347 Boolean value used by AUTOMOC to determine if the compiler pre defini‐
1348 tions file moc_predefs.h should be generated.
1349 CMake generates a moc_predefs.h file with compiler pre definitions from
1351 the output of the command defined in CMAKE_CXX_COMPILER_PREDEFINES_COM‐
1352 MAND when
1353 · AUTOMOC is enabled,
1355 · AUTOMOC_COMPILER_PREDEFINES is enabled,
1357 · CMAKE_CXX_COMPILER_PREDEFINES_COMMAND isn’t empty and
1359 · the Qt version is greater or equal 5.8.
1361 The moc_predefs.h file, which is generated in AUTOGEN_BUILD_DIR, is
1363 passed to moc as the argument to the --include option.
1364 By default AUTOMOC_COMPILER_PREDEFINES is initialized from CMAKE_AUTO‐
1366 MOC_COMPILER_PREDEFINES, which is ON by default.
1367 See the cmake-qt(7) manual for more information on using CMake with Qt.
1369 AUTOMOC_DEPEND_FILTERS
1371 Filter definitions used by AUTOMOC to extract file names from a source
1372 file that are registered as additional dependencies for the moc file of
1373 the source file.
1374 Filters are defined as KEYWORD;REGULAR_EXPRESSION pairs. First the file
1376 content is searched for KEYWORD. If it is found at least once, then
1377 file names are extracted by successively searching for REGULAR_EXPRES‐
1378 SION and taking the first match group.
1379 The file name found in the first match group is searched for
1381 · first in the vicinity of the source file
1383 · and afterwards in the target’s INCLUDE_DIRECTORIES.
1385 If any of the extracted files changes, then the moc file for the source
1387 file gets rebuilt even when the source file itself doesn’t change.
1388 If any of the extracted files is GENERATED or if it is not in the tar‐
1390 get’s sources, then it might be necessary to add it to the _autogen
1391 target dependencies. See AUTOGEN_TARGET_DEPENDS for reference.
1392 By default AUTOMOC_DEPEND_FILTERS is initialized from CMAKE_AUTO‐
1394 MOC_DEPEND_FILTERS, which is empty by default.
1395 See the cmake-qt(7) manual for more information on using CMake with Qt.
1397 Example 1
1399 A header file my_class.hpp uses a custom macro JSON_FILE_MACRO which is
1400 defined in an other header macros.hpp. We want the moc file of
1401 my_class.hpp to depend on the file name argument of JSON_FILE_MACRO:
1402 // my_class.hpp
1404 class My_Class : public QObject
1405 {
1406 Q_OBJECT
1407 JSON_FILE_MACRO ( "info.json" )
1408 ...
1409 };
1410 In CMakeLists.txt we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS like
1412 this:
1413 list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
1415 "JSON_FILE_MACRO"
1416 "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
1417 )
1418 We assume info.json is a plain (not GENERATED) file that is listed in
1420 the target’s source. Therefore we do not need to add it to AUTO‐
1421 GEN_TARGET_DEPENDS.
1422 Example 2
1424 In the target my_target a header file complex_class.hpp uses a custom
1425 macro JSON_BASED_CLASS which is defined in an other header macros.hpp:
1426 // macros.hpp
1428 ...
1429 #define JSON_BASED_CLASS(name, json) \
1430 class name : public QObject \
1431 { \
1432 Q_OBJECT \
1433 Q_PLUGIN_METADATA(IID "demo" FILE json) \
1434 name() {} \
1435 };
1436 ...
1437 // complex_class.hpp
1439 #pragma once
1440 JSON_BASED_CLASS(Complex_Class, "meta.json")
1441 // end of file
1442 Since complex_class.hpp doesn’t contain a Q_OBJECT macro it would be
1444 ignored by AUTOMOC. We change this by adding JSON_BASED_CLASS to
1445 CMAKE_AUTOMOC_MACRO_NAMES:
1446 list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")
1448 We want the moc file of complex_class.hpp to depend on meta.json. So
1450 we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS:
1451 list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
1453 "JSON_BASED_CLASS"
1454 "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
1455 )
1456 Additionally we assume meta.json is GENERATED which is why we have to
1458 add it to AUTOGEN_TARGET_DEPENDS:
1459 set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")
1461 AUTOMOC_EXECUTABLE
1463 AUTOMOC_EXECUTABLE is file path pointing to the moc executable to use
1464 for AUTOMOC enabled files. Setting this property will make CMake skip
1465 the automatic detection of the moc binary as well as the sanity-tests
1466 normally run to ensure that the binary is available and working as
1467 expected.
1468 Usually this property does not need to be set. Only consider this prop‐
1470 erty if auto-detection of moc can not work – e.g. because you are
1471 building the moc binary as part of your project.
1472 See the cmake-qt(7) manual for more information on using CMake with Qt.
1474 AUTOMOC_MACRO_NAMES
1476 A semicolon-separated list list of macro names used by AUTOMOC to
1477 determine if a C++ file needs to be processed by moc.
1478 This property is only used if the AUTOMOC property is ON for this tar‐
1480 get.
1481 When running AUTOMOC, CMake searches for the strings listed in
1483 AUTOMOC_MACRO_NAMES in C++ source and header files. If any of the
1484 strings is found
1485 · as the first non space string on a new line or
1487 · as the first non space string after a { on a new line,
1489 then the file will be processed by moc.
1491 By default AUTOMOC_MACRO_NAMES is initialized from CMAKE_AUTO‐
1493 MOC_MACRO_NAMES.
1494 See the cmake-qt(7) manual for more information on using CMake with Qt.
1496 Example
1498 In this case the Q_OBJECT macro is hidden inside another macro called
1499 CUSTOM_MACRO. To let CMake know that source files that contain CUS‐
1500 TOM_MACRO need to be moc processed, we call:
1501 set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
1503 AUTOMOC_MOC_OPTIONS
1505 Additional options for moc when using AUTOMOC
1506 This property is only used if the AUTOMOC property is ON for this tar‐
1508 get. In this case, it holds additional command line options which will
1509 be used when moc is executed during the build, i.e. it is equivalent
1510 to the optional OPTIONS argument of the qt4_wrap_cpp() macro.
1511 By default it is empty.
1513 See the cmake-qt(7) manual for more information on using CMake with Qt.
1515 AUTOMOC_PATH_PREFIX
1517 When this property is ON, CMake will generate the -p path prefix option
1518 for moc on AUTOMOC enabled Qt targets.
1519 To generate the path prefix, CMake tests if the header compiled by moc
1521 is in any of the target include directories. If so, CMake will compute
1522 the relative path accordingly. If the header is not in the include
1523 directories, CMake will omit the -p path prefix option. moc usually
1524 generates a relative include path in that case.
1525 AUTOMOC_PATH_PREFIX is initialized from the variable CMAKE_AUTO‐
1527 MOC_PATH_PREFIX, which is ON by default.
1528 See the cmake-qt(7) manual for more information on using CMake with Qt.
1530 Reproducible builds
1532 For reproducible builds is is recommended to keep headers that are moc
1533 compiled in one of the target include directories and set
1534 AUTOMOC_PATH_PREFIX to ON (which is the default). This ensures that
1535 · moc output files are identical on different build setups,
1537 · moc output files will compile correctly when the source and/or build
1539 directory is a symbolic link.
1540 AUTOMOC
1542 Should the target be processed with auto-moc (for Qt projects).
1543 AUTOMOC is a boolean specifying whether CMake will handle the Qt moc
1545 preprocessor automatically, i.e. without having to use the
1546 QT4_WRAP_CPP() or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are sup‐
1547 ported.
1548 This property is initialized by the value of the CMAKE_AUTOMOC variable
1550 if it is set when a target is created.
1551 When this property is set ON, CMake will scan the header and source
1553 files at build time and invoke moc accordingly.
1554 Header file processing
1556 At configuration time, a list of header files that should be scanned by
1557 AUTOMOC is computed from the target’s sources.
1558 · All header files in the target’s sources are added to the scan list.
1560 · For all C++ source files <source_base>.<source_extension> in the tar‐
1562 get’s sources, CMake searches for
1563 · a regular header with the same base name
1565 (<source_base>.<header_extention>) and
1566 · a private header with the same base name and a _p suffix
1568 (<source_base>_p.<header_extention>)
1569 and adds these to the scan list.
1571 At build time, CMake scans each unknown or modified header file from
1573 the list and searches for
1574 · a Qt macro from AUTOMOC_MACRO_NAMES,
1576 · additional file dependencies from the FILE argument of a Q_PLUG‐
1578 IN_METADATA macro and
1579 · additional file dependencies detected by filters defined in AUTO‐
1581 MOC_DEPEND_FILTERS.
1582 If a Qt macro is found, then the header will be compiled by the moc to
1584 the output file moc_<base_name>.cpp. The complete output file path is
1585 described in the section Output file location.
1586 The header will be moc compiled again if a file from the additional
1588 file dependencies changes.
1589 Header moc output files moc_<base_name>.cpp can be included in source
1591 files. In the section Including header moc files in sources there is
1592 more information on that topic.
1593 Source file processing
1595 At build time, CMake scans each unknown or modified C++ source file
1596 from the target’s sources for
1597 · a Qt macro from AUTOMOC_MACRO_NAMES,
1599 · includes of header moc files (see Including header moc files in
1601 sources),
1602 · additional file dependencies from the FILE argument of a Q_PLUG‐
1604 IN_METADATA macro and
1605 · additional file dependencies detected by filters defined in AUTO‐
1607 MOC_DEPEND_FILTERS.
1608 If a Qt macro is found, then the C++ source file <base>.<source_exten‐
1610 sion> is expected to as well contain an include statement
1611 #include <<base>.moc> // or
1613 #include "<base>.moc"
1614 The source file then will be compiled by the moc to the output file
1616 <base>.moc. A description of the complete output file path is in sec‐
1617 tion Output file location.
1618 The source will be moc compiled again if a file from the additional
1620 file dependencies changes.
1621 Including header moc files in sources
1623 A source file can include the moc output file of a header
1624 <header_base>.<header_extension> by using an include statement of the
1625 form
1626 #include <moc_<header_base>.cpp> // or
1628 #include "moc_<header_base>.cpp"
1629 If the moc output file of a header is included by a source, it will be
1631 generated in a different location than if it was not included. This is
1632 described in the section Output file location.
1633 Output file location
1635 Included moc output files
1636 moc output files that are included by a source file will be generated
1637 in
1638 · <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
1640 · <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
1642 tors.
1643 Where <AUTOGEN_BUILD_DIR> is the value of the target property AUTO‐
1645 GEN_BUILD_DIR.
1646 The include directory is automatically added to the target’s
1648 INCLUDE_DIRECTORIES.
1649 Not included moc output files
1651 moc output files that are not included in a source file will be gener‐
1652 ated in
1653 · <AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM> for single configuration
1655 generators or in,
1656 · <AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM> for multi
1658 configuration generators.
1659 Where <SOURCE_DIR_CHECKSUM> is a checksum computed from the relative
1661 parent directory path of the moc input file. This scheme allows to
1662 have moc input files with the same name in different directories.
1663 All not included moc output files will be included automatically by the
1665 CMake generated file
1666 · <AUTOGEN_BUILD_DIR>/mocs_compilation.cpp,
1668 which is added to the target’s sources.
1670 Qt version detection
1672 AUTOMOC enabled targets need to know the Qt major and minor version
1673 they’re working with. The major version usually is provided by the
1674 INTERFACE_QT_MAJOR_VERSION property of the Qt[45]Core library, that the
1675 target links to. To find the minor version, CMake builds a list of
1676 available Qt versions from
1677 · Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR variables (usually
1679 set by find_package(Qt5...))
1680 · Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR directory properties
1682 · QT_VERSION_MAJOR and QT_VERSION_MINOR variables (usually set by
1684 find_package(Qt4...))
1685 · QT_VERSION_MAJOR and QT_VERSION_MINOR directory properties
1687 in the context of the add_executable() or add_library() call.
1689 Assumed INTERFACE_QT_MAJOR_VERSION is a valid number, the first entry
1691 in the list with a matching major version is taken. If no matching
1692 major version was found, an error is generated. If INTER‐
1693 FACE_QT_MAJOR_VERSION is not a valid number, the first entry in the
1694 list is taken.
1695 A find_package(Qt[45]...) call sets the QT/Qt5Core_VERSION_MAJOR/MINOR
1697 variables. If the call is in a different context than the add_exe‐
1698 cutable() or add_library() call, e.g. in a function, then the version
1699 variables might not be available to the AUTOMOC enabled target. In
1700 that case the version variables can be forwarded from the find_pack‐
1701 age(Qt[45]…) calling context to the add_executable() or add_library()
1702 calling context as directory properties. The following Qt5 example
1703 demonstrates the procedure.
1704 function (add_qt5_client)
1706 find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets)
1707 ...
1708 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1709 PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}")
1710 set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
1711 PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}")
1712 ...
1713 endfunction ()
1714 ...
1715 add_qt5_client()
1716 add_executable(myTarget main.cpp)
1717 target_link_libraries(myTarget Qt5::QtWidgets)
1718 set_property(TARGET myTarget PROPERTY AUTOMOC ON)
1719 Modifiers
1721 AUTOMOC_EXECUTABLE: The moc executable will be detected automatically,
1722 but can be forced to a certain binary using this target property.
1723 AUTOMOC_MOC_OPTIONS: Additional command line options for moc can be set
1725 in this target property.
1726 AUTOMOC_MACRO_NAMES: This list of Qt macro names can be extended to
1728 search for additional macros in headers and sources.
1729 AUTOMOC_DEPEND_FILTERS: moc dependency file names can be extracted from
1731 headers or sources by defining file name filters in this target prop‐
1732 erty.
1733 AUTOMOC_COMPILER_PREDEFINES: Compiler pre definitions for moc are writ‐
1735 ten to the moc_predefs.h file. The generation of this file can be
1736 enabled or disabled in this target property.
1737 SKIP_AUTOMOC: Sources and headers can be excluded from AUTOMOC process‐
1739 ing by setting this source file property.
1740 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
1742 AUTORCC processing by setting this source file property.
1743 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
1745 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
1746 AUTOGEN_TARGETS_FOLDER: This global property can be used to group
1748 AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
1749 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
1751 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
1752 project, will be generated when this variable is ON.
1753 AUTOGEN_PARALLEL: This target property controls the number of moc or
1755 uic processes to start in parallel during builds.
1756 See the cmake-qt(7) manual for more information on using CMake with Qt.
1758 AUTOUIC
1760 Should the target be processed with auto-uic (for Qt projects).
1761 AUTOUIC is a boolean specifying whether CMake will handle the Qt uic
1763 code generator automatically, i.e. without having to use the
1764 QT4_WRAP_UI() or QT5_WRAP_UI() macro. Currently Qt4 and Qt5 are sup‐
1765 ported.
1766 This property is initialized by the value of the CMAKE_AUTOUIC variable
1768 if it is set when a target is created.
1769 When this property is ON, CMake will scan the header and source files
1771 at build time and invoke uic accordingly.
1772 Header and source file processing
1774 At build time, CMake scans each header and source file from the tar‐
1775 get’s sources for include statements of the form
1776 #include "ui_<ui_base>.h"
1778 Once such an include statement is found in a file, CMake searches for
1780 the uic input file <ui_base>.ui
1781 · in the vicinity of the file and
1783 · in the AUTOUIC_SEARCH_PATHS of the target.
1785 If the <ui_base>.ui file was found, uic is called on it to generate
1787 ui_<ui_base>.h in the directory
1788 · <AUTOGEN_BUILD_DIR>/include for single configuration generators or in
1790 · <AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration genera‐
1792 tors.
1793 Where <AUTOGEN_BUILD_DIR> is the value of the target property AUTO‐
1795 GEN_BUILD_DIR.
1796 The include directory is automatically added to the target’s
1798 INCLUDE_DIRECTORIES.
1799 Modifiers
1801 AUTOUIC_EXECUTABLE: The uic executable will be detected automatically,
1802 but can be forced to a certain binary using this target property.
1803 AUTOUIC_OPTIONS: Additional command line options for uic can be set via
1805 this source file property on a <base_name>.ui file.
1806 SKIP_AUTOUIC: Source files can be excluded from AUTOUIC processing by
1808 setting this source file property.
1809 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
1811 AUTORCC processing by setting this source file property.
1812 AUTOGEN_TARGETS_FOLDER: This global property can be used to group AUTO‐
1814 MOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
1815 CMAKE_GLOBAL_AUTOGEN_TARGET: A global autogen target, that depends on
1817 all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the
1818 project, will be generated when this variable is ON.
1819 AUTOGEN_PARALLEL: This target property controls the number of moc or
1821 uic processes to start in parallel during builds.
1822 See the cmake-qt(7) manual for more information on using CMake with Qt.
1824 AUTOUIC_EXECUTABLE
1826 AUTOUIC_EXECUTABLE is file path pointing to the uic executable to use
1827 for AUTOUIC enabled files. Setting this property will make CMake skip
1828 the automatic detection of the uic binary as well as the sanity-tests
1829 normally run to ensure that the binary is available and working as
1830 expected.
1831 Usually this property does not need to be set. Only consider this prop‐
1833 erty if auto-detection of uic can not work – e.g. because you are
1834 building the uic binary as part of your project.
1835 See the cmake-qt(7) manual for more information on using CMake with Qt.
1837 AUTOUIC_OPTIONS
1839 Additional options for uic when using AUTOUIC
1840 This property holds additional command line options which will be used
1842 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
1843 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
1844 By default it is empty.
1846 This property is initialized by the value of the CMAKE_AUTOUIC_OPTIONS
1848 variable if it is set when a target is created.
1849 The options set on the target may be overridden by AUTOUIC_OPTIONS set
1851 on the .ui source file.
1852 This property may use “generator expressions” with the syntax $<...>.
1854 See the cmake-generator-expressions(7) manual for available expres‐
1855 sions.
1856 See the cmake-qt(7) manual for more information on using CMake with Qt.
1858 EXAMPLE
1860 # ...
1861 set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection")
1862 # ...
1863 AUTOUIC_SEARCH_PATHS
1865 Search path list used by AUTOUIC to find included .ui files.
1866 This property is initialized by the value of the
1868 CMAKE_AUTOUIC_SEARCH_PATHS variable if it is set when a target is cre‐
1869 ated. Otherwise it is empty.
1870 See the cmake-qt(7) manual for more information on using CMake with Qt.
1872 AUTORCC
1874 Should the target be processed with auto-rcc (for Qt projects).
1875 AUTORCC is a boolean specifying whether CMake will handle the Qt rcc
1877 code generator automatically, i.e. without having to use the
1878 QT4_ADD_RESOURCES() or QT5_ADD_RESOURCES() macro. Currently Qt4 and
1879 Qt5 are supported.
1880 When this property is ON, CMake will handle .qrc files added as target
1882 sources at build time and invoke rcc accordingly. This property is
1883 initialized by the value of the CMAKE_AUTORCC variable if it is set
1884 when a target is created.
1885 By default AUTORCC is processed by a custom command. If the .qrc file
1887 is GENERATED, a custom target is used instead.
1888 When there are multiple .qrc files with the same name, CMake will gen‐
1890 erate unspecified unique output file names for rcc. Therefore, if
1891 Q_INIT_RESOURCE() or Q_CLEANUP_RESOURCE() need to be used, the .qrc
1892 file name must be unique.
1893 Modifiers
1895 AUTORCC_EXECUTABLE: The rcc executable will be detected automatically,
1896 but can be forced to a certain binary by setting this target property.
1897 AUTORCC_OPTIONS: Additional command line options for rcc can be set via
1899 this .qrc source file property.
1900 SKIP_AUTORCC: .qrc files can be excluded from AUTORCC processing by
1902 setting this source file property.
1903 SKIP_AUTOGEN: Source files can be excluded from AUTOMOC, AUTOUIC and
1905 AUTORCC processing by setting this source file property.
1906 AUTOGEN_SOURCE_GROUP: This global property can be used to group files
1908 generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
1909 AUTOGEN_TARGETS_FOLDER: This global property can be used to group AUTO‐
1911 MOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
1912 CMAKE_GLOBAL_AUTORCC_TARGET: A global autorcc target that depends on
1914 all AUTORCC targets in the project will be generated when this variable
1915 is ON.
1916 See the cmake-qt(7) manual for more information on using CMake with Qt.
1918 AUTORCC_EXECUTABLE
1920 AUTORCC_EXECUTABLE is file path pointing to the rcc executable to use
1921 for AUTORCC enabled files. Setting this property will make CMake skip
1922 the automatic detection of the rcc binary as well as the sanity-tests
1923 normally run to ensure that the binary is available and working as
1924 expected.
1925 Usually this property does not need to be set. Only consider this prop‐
1927 erty if auto-detection of rcc can not work – e.g. because you are
1928 building the rcc binary as part of your project.
1929 See the cmake-qt(7) manual for more information on using CMake with Qt.
1931 AUTORCC_OPTIONS
1933 Additional options for rcc when using AUTORCC
1934 This property holds additional command line options which will be used
1936 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
1937 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
1938 By default it is empty.
1940 This property is initialized by the value of the CMAKE_AUTORCC_OPTIONS
1942 variable if it is set when a target is created.
1943 The options set on the target may be overridden by AUTORCC_OPTIONS set
1945 on the .qrc source file.
1946 See the cmake-qt(7) manual for more information on using CMake with Qt.
1948 EXAMPLE
1950 # ...
1951 set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9")
1952 # ...
1953 BINARY_DIR
1955 This read-only property reports the value of the CMAKE_CUR‐
1956 RENT_BINARY_DIR variable in the directory in which the target was
1957 defined.
1958 BUILD_RPATH
1960 A semicolon-separated list specifying runtime path (RPATH) entries to
1961 add to binaries linked in the build tree (for platforms that support
1962 it). The entries will not be used for binaries in the install tree.
1963 See also the INSTALL_RPATH target property.
1964 This property is initialized by the value of the variable
1966 CMAKE_BUILD_RPATH if it is set when a target is created.
1967 This property supports generator expressions.
1969 BUILD_RPATH_USE_ORIGIN
1971 Whether to use relative paths for the build RPATH.
1972 This property is initialized by the value of the variable
1974 CMAKE_BUILD_RPATH_USE_ORIGIN.
1975 On platforms that support runtime paths (RPATH) with the $ORIGIN token,
1977 setting this property to TRUE enables relative paths in the build RPATH
1978 for executables and shared libraries that point to shared libraries in
1979 the same build tree.
1980 Normally the build RPATH of a binary contains absolute paths to the
1982 directory of each shared library it links to. The RPATH entries for
1983 directories contained within the build tree can be made relative to
1984 enable relocatable builds and to help achieve reproducible builds by
1985 omitting the build directory from the build environment.
1986 This property has no effect on platforms that do not support the $ORI‐
1988 GIN token in RPATH, or when the CMAKE_SKIP_RPATH variable is set. The
1989 runtime path set through the BUILD_RPATH target property is also unaf‐
1990 fected by this property.
1991 BUILD_WITH_INSTALL_NAME_DIR
1993 BUILD_WITH_INSTALL_NAME_DIR is a boolean specifying whether the macOS
1994 install_name of a target in the build tree uses the directory given by
1995 INSTALL_NAME_DIR. This setting only applies to targets on macOS.
1996 This property is initialized by the value of the variable
1998 CMAKE_BUILD_WITH_INSTALL_NAME_DIR if it is set when a target is cre‐
1999 ated.
2000 If this property is not set and policy CMP0068 is not NEW, the value of
2002 BUILD_WITH_INSTALL_RPATH is used in its place.
2003 BUILD_WITH_INSTALL_RPATH
2005 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
2006 target in the build tree with the INSTALL_RPATH. This takes precedence
2007 over SKIP_BUILD_RPATH and avoids the need for relinking before instal‐
2008 lation.
2009 This property is initialized by the value of the
2011 CMAKE_BUILD_WITH_INSTALL_RPATH variable if it is set when a target is
2012 created.
2013 If policy CMP0068 is not NEW, this property also controls use of
2015 INSTALL_NAME_DIR in the build tree on macOS. Either way, the
2016 BUILD_WITH_INSTALL_NAME_DIR target property takes precedence.
2017 BUNDLE_EXTENSION
2019 The file extension used to name a BUNDLE, a FRAMEWORK, or a MACOSX_BUN‐
2020 DLE target on the macOS and iOS.
2021 The default value is bundle, framework, or app for the respective tar‐
2023 get types.
2024 BUNDLE
2026 This target is a CFBundle on the macOS.
2027 If a module library target has this property set to true it will be
2029 built as a CFBundle when built on the mac. It will have the directory
2030 structure required for a CFBundle and will be suitable to be used for
2031 creating Browser Plugins or other application resources.
2032 C_EXTENSIONS
2034 Boolean specifying whether compiler specific extensions are requested.
2035 This property specifies whether compiler specific extensions should be
2037 used. For some compilers, this results in adding a flag such as
2038 -std=gnu11 instead of -std=c11 to the compile line. This property is
2039 ON by default. The basic C standard level is controlled by the C_STAN‐
2040 DARD target property.
2041 See the cmake-compile-features(7) manual for information on compile
2043 features and a list of supported compilers.
2044 This property is initialized by the value of the CMAKE_C_EXTENSIONS
2046 variable if it is set when a target is created.
2047 C_STANDARD
2049 The C standard whose features are requested to build this target.
2050 This property specifies the C standard whose features are requested to
2052 build this target. For some compilers, this results in adding a flag
2053 such as -std=gnu11 to the compile line. For compilers that have no
2054 notion of a standard level, such as Microsoft Visual C++ before 2015
2055 Update 3, this has no effect.
2056 Supported values are 90, 99 and 11.
2058 If the value requested does not result in a compile flag being added
2060 for the compiler in use, a previous standard flag will be added
2061 instead. This means that using:
2062 set_property(TARGET tgt PROPERTY C_STANDARD 11)
2064 with a compiler which does not support -std=gnu11 or an equivalent flag
2066 will not result in an error or warning, but will instead add the
2067 -std=gnu99 or -std=gnu90 flag if supported. This “decay” behavior may
2068 be controlled with the C_STANDARD_REQUIRED target property. Addition‐
2069 ally, the C_EXTENSIONS target property may be used to control whether
2070 compiler-specific extensions are enabled on a per-target basis.
2071 See the cmake-compile-features(7) manual for information on compile
2073 features and a list of supported compilers.
2074 This property is initialized by the value of the CMAKE_C_STANDARD vari‐
2076 able if it is set when a target is created.
2077 C_STANDARD_REQUIRED
2079 Boolean describing whether the value of C_STANDARD is a requirement.
2080 If this property is set to ON, then the value of the C_STANDARD target
2082 property is treated as a requirement. If this property is OFF or
2083 unset, the C_STANDARD target property is treated as optional and may
2084 “decay” to a previous standard if the requested is not available. For
2085 compilers that have no notion of a standard level, such as MSVC, this
2086 has no effect.
2087 See the cmake-compile-features(7) manual for information on compile
2089 features and a list of supported compilers.
2090 This property is initialized by the value of the CMAKE_C_STAN‐
2092 DARD_REQUIRED variable if it is set when a target is created.
2093 COMMON_LANGUAGE_RUNTIME
2095 By setting this target property, the target is configured to build with
2096 C++/CLI support.
2097 The Visual Studio generator defines the clr parameter depending on the
2099 value of COMMON_LANGUAGE_RUNTIME:
2100 · property not set: native C++ (i.e. default)
2102 · property set but empty: mixed unmanaged/managed C++
2104 · property set to any non empty value: managed C++
2106 Supported values: "", "pure", "safe"
2108 This property is only evaluated Visual Studio Generators for VS 2010
2110 and above.
2111 To be able to build managed C++ targets with VS 2017 and above the com‐
2113 ponent C++/CLI support must be installed, which may not be done by
2114 default.
2115 See also IMPORTED_COMMON_LANGUAGE_RUNTIME
2117 COMPATIBLE_INTERFACE_BOOL
2119 Properties which must be compatible with their link interface
2120 The COMPATIBLE_INTERFACE_BOOL property may contain a list of properties
2122 for this target which must be consistent when evaluated as a boolean
2123 with the INTERFACE variant of the property in all linked dependees.
2124 For example, if a property FOO appears in the list, then for each
2125 dependee, the INTERFACE_FOO property content in all of its dependencies
2126 must be consistent with each other, and with the FOO property in the
2127 depender.
2128 Consistency in this sense has the meaning that if the property is set,
2130 then it must have the same boolean value as all others, and if the
2131 property is not set, then it is ignored.
2132 Note that for each dependee, the set of properties specified in this
2134 property must not intersect with the set specified in any of the other
2135 Compatible Interface Properties.
2136 COMPATIBLE_INTERFACE_NUMBER_MAX
2138 Properties whose maximum value from the link interface will be used.
2139 The COMPATIBLE_INTERFACE_NUMBER_MAX property may contain a list of
2141 properties for this target whose maximum value may be read at generate
2142 time when evaluated in the INTERFACE variant of the property in all
2143 linked dependees. For example, if a property FOO appears in the list,
2144 then for each dependee, the INTERFACE_FOO property content in all of
2145 its dependencies will be compared with each other and with the FOO
2146 property in the depender. When reading the FOO property at generate
2147 time, the maximum value will be returned. If the property is not set,
2148 then it is ignored.
2149 Note that for each dependee, the set of properties specified in this
2151 property must not intersect with the set specified in any of the other
2152 Compatible Interface Properties.
2153 COMPATIBLE_INTERFACE_NUMBER_MIN
2155 Properties whose maximum value from the link interface will be used.
2156 The COMPATIBLE_INTERFACE_NUMBER_MIN property may contain a list of
2158 properties for this target whose minimum value may be read at generate
2159 time when evaluated in the INTERFACE variant of the property of all
2160 linked dependees. For example, if a property FOO appears in the list,
2161 then for each dependee, the INTERFACE_FOO property content in all of
2162 its dependencies will be compared with each other and with the FOO
2163 property in the depender. When reading the FOO property at generate
2164 time, the minimum value will be returned. If the property is not set,
2165 then it is ignored.
2166 Note that for each dependee, the set of properties specified in this
2168 property must not intersect with the set specified in any of the other
2169 Compatible Interface Properties.
2170 COMPATIBLE_INTERFACE_STRING
2172 Properties which must be string-compatible with their link interface
2173 The COMPATIBLE_INTERFACE_STRING property may contain a list of proper‐
2175 ties for this target which must be the same when evaluated as a string
2176 in the INTERFACE variant of the property all linked dependees. For
2177 example, if a property FOO appears in the list, then for each dependee,
2178 the INTERFACE_FOO property content in all of its dependencies must be
2179 equal with each other, and with the FOO property in the depender. If
2180 the property is not set, then it is ignored.
2181 Note that for each dependee, the set of properties specified in this
2183 property must not intersect with the set specified in any of the other
2184 Compatible Interface Properties.
2185 COMPILE_DEFINITIONS
2187 Preprocessor definitions for compiling a target’s sources.
2188 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
2190 list of preprocessor definitions using the syntax VAR or VAR=value.
2191 Function-style definitions are not supported. CMake will automatically
2192 escape the value correctly for the native build system (note that CMake
2193 language syntax may require escapes to specify some values).
2194 CMake will automatically drop some definitions that are not supported
2196 by the native build tool.
2197 Disclaimer: Most native build tools have poor support for escaping cer‐
2199 tain values. CMake has work-arounds for many cases but some values may
2200 just not be possible to pass correctly. If a value does not seem to be
2201 escaped correctly, do not attempt to work-around the problem by adding
2202 escape sequences to the value. Your work-around may break in a future
2203 version of CMake that has improved escape support. Instead consider
2204 defining the macro in a (configured) header file. Then report the lim‐
2205 itation. Known limitations include:
2206 # - broken almost everywhere
2208 ; - broken in VS IDE 7.0 and Borland Makefiles
2209 , - broken in VS IDE
2210 % - broken in some cases in NMake
2211 & | - broken in some cases on MinGW
2212 ^ < > \" - broken in most Make tools on Windows
2213 CMake does not reject these values outright because they do work in
2215 some cases. Use with caution.
2216 Contents of COMPILE_DEFINITIONS may use “generator expressions” with
2218 the syntax $<...>. See the cmake-generator-expressions(7) manual for
2219 available expressions. See the cmake-buildsystem(7) manual for more on
2220 defining buildsystem properties.
2221 The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to
2223 specify per-configuration definitions. Generator expressions should be
2224 preferred instead of setting the alternative property.
2225 COMPILE_FEATURES
2227 Compiler features enabled for this target.
2228 The list of features in this property are a subset of the features
2230 listed in the CMAKE_CXX_COMPILE_FEATURES variable.
2231 Contents of COMPILE_FEATURES may use “generator expressions” with the
2233 syntax $<...>. See the cmake-generator-expressions(7) manual for
2234 available expressions. See the cmake-compile-features(7) manual for
2235 information on compile features and a list of supported compilers.
2236 COMPILE_FLAGS
2238 Additional flags to use when compiling this target’s sources.
2239 The COMPILE_FLAGS property sets additional compiler flags used to build
2241 sources within the target. Use COMPILE_DEFINITIONS to pass additional
2242 preprocessor definitions.
2243 This property is deprecated. Use the COMPILE_OPTIONS property or the
2245 target_compile_options() command instead.
2246 COMPILE_OPTIONS
2248 List of options to pass to the compiler.
2249 This property holds a semicolon-separated list of options specified so
2251 far for its target. Use the target_compile_options() command to append
2252 more options.
2253 This property is initialized by the COMPILE_OPTIONS directory property
2255 when a target is created, and is used by the generators to set the
2256 options for the compiler.
2257 Contents of COMPILE_OPTIONS may use “generator expressions” with the
2259 syntax $<...>. See the cmake-generator-expressions(7) manual for
2260 available expressions. See the cmake-buildsystem(7) manual for more on
2261 defining buildsystem properties.
2262 COMPILE_PDB_NAME
2264 Output name for the MS debug symbol .pdb file generated by the compiler
2265 while building source files.
2266 This property specifies the base name for the debug symbols file. If
2268 not set, the default is unspecified.
2269 NOTE:
2271 The compiler-generated program database files are specified by the
2272 /Fd compiler flag and are not the same as linker-generated program
2273 database files specified by the /pdb linker flag. Use the PDB_NAME
2274 property to specify the latter.
2275 COMPILE_PDB_NAME_<CONFIG>
2277 Per-configuration output name for the MS debug symbol .pdb file gener‐
2278 ated by the compiler while building source files.
2279 This is the configuration-specific version of COMPILE_PDB_NAME.
2281 NOTE:
2283 The compiler-generated program database files are specified by the
2284 /Fd compiler flag and are not the same as linker-generated program
2285 database files specified by the /pdb linker flag. Use the
2286 PDB_NAME_<CONFIG> property to specify the latter.
2287 COMPILE_PDB_OUTPUT_DIRECTORY
2289 Output directory for the MS debug symbol .pdb file generated by the
2290 compiler while building source files.
2291 This property specifies the directory into which the MS debug symbols
2293 will be placed by the compiler. This property is initialized by the
2294 value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY variable if it is set
2295 when a target is created.
2296 NOTE:
2298 The compiler-generated program database files are specified by the
2299 /Fd compiler flag and are not the same as linker-generated program
2300 database files specified by the /pdb linker flag. Use the PDB_OUT‐
2301 PUT_DIRECTORY property to specify the latter.
2302 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>
2304 Per-configuration output directory for the MS debug symbol .pdb file
2305 generated by the compiler while building source files.
2306 This is a per-configuration version of COMPILE_PDB_OUTPUT_DIRECTORY,
2308 but multi-configuration generators (Visual Studio, Xcode) do NOT append
2309 a per-configuration subdirectory to the specified directory. This
2310 property is initialized by the value of the CMAKE_COMPILE_PDB_OUT‐
2311 PUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.
2312 NOTE:
2314 The compiler-generated program database files are specified by the
2315 /Fd compiler flag and are not the same as linker-generated program
2316 database files specified by the /pdb linker flag. Use the PDB_OUT‐
2317 PUT_DIRECTORY_<CONFIG> property to specify the latter.
2318 <CONFIG>_OUTPUT_NAME
2320 Old per-configuration target file base name. Use OUTPUT_NAME_<CONFIG>
2321 instead.
2322 This is a configuration-specific version of the OUTPUT_NAME target
2324 property.
2325 <CONFIG>_POSTFIX
2327 Postfix to append to the target file name for configuration <CONFIG>.
2328 When building with configuration <CONFIG> the value of this property is
2330 appended to the target file name built on disk. For non-executable
2331 targets, this property is initialized by the value of the variable
2332 CMAKE_<CONFIG>_POSTFIX if it is set when a target is created. This
2333 property is ignored on the Mac for Frameworks and App Bundles.
2334 CROSSCOMPILING_EMULATOR
2336 Use the given emulator to run executables created when crosscompiling.
2337 This command will be added as a prefix to add_test(), add_custom_com‐
2338 mand(), and add_custom_target() commands for built target system exe‐
2339 cutables.
2340 If this property contains a semicolon-separated list, then the first
2342 value is the command and remaining values are its arguments.
2343 This property is initialized by the value of the CMAKE_CROSSCOMPIL‐
2345 ING_EMULATOR variable if it is set when a target is created.
2346 CUDA_PTX_COMPILATION
2348 Compile CUDA sources to .ptx files instead of .obj files within Object
2349 Libraries.
2350 For example:
2352 add_library(myptx OBJECT a.cu b.cu)
2354 set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)
2355 CUDA_SEPARABLE_COMPILATION
2357 CUDA only: Enables separate compilation of device code
2358 If set this will enable separable compilation for all CUDA files for
2360 the given target.
2361 For instance:
2363 set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)
2365 This property is initialized by the value of the CMAKE_CUDA_SEPARA‐
2367 BLE_COMPILATION variable if it is set when a target is created.
2368 CUDA_RESOLVE_DEVICE_SYMBOLS
2370 CUDA only: Enables device linking for the specific library target where
2371 required.
2372 If set, this will tell the required compilers to enable device linking
2374 on the library target. Device linking is an additional link step
2375 required by some CUDA compilers when CUDA_SEPARABLE_COMPILATION is
2376 enabled. Normally device linking is deferred until a shared library or
2377 executable is generated, allowing for multiple static libraries to
2378 resolve device symbols at the same time when they are used by a shared
2379 library or executable.
2380 By default static library targets have this property is disabled, while
2382 shared, module, and executable targets have this property enabled.
2383 Note that device linking is not supported for Object Libraries.
2385 For instance:
2387 set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
2389 CUDA_EXTENSIONS
2391 Boolean specifying whether compiler specific extensions are requested.
2392 This property specifies whether compiler specific extensions should be
2394 used. For some compilers, this results in adding a flag such as
2395 -std=gnu++11 instead of -std=c++11 to the compile line. This property
2396 is ON by default. The basic CUDA/C++ standard level is controlled by
2397 the CUDA_STANDARD target property.
2398 See the cmake-compile-features(7) manual for information on compile
2400 features and a list of supported compilers.
2401 This property is initialized by the value of the CMAKE_CUDA_EXTENSIONS
2403 variable if it is set when a target is created.
2404 CUDA_STANDARD
2406 The CUDA/C++ standard whose features are requested to build this tar‐
2407 get.
2408 This property specifies the CUDA/C++ standard whose features are
2410 requested to build this target. For some compilers, this results in
2411 adding a flag such as -std=gnu++11 to the compile line.
2412 Supported values are 98, 11, 14.
2414 If the value requested does not result in a compile flag being added
2416 for the compiler in use, a previous standard flag will be added
2417 instead. This means that using:
2418 set_property(TARGET tgt PROPERTY CUDA_STANDARD 11)
2420 with a compiler which does not support -std=gnu++11 or an equivalent
2422 flag will not result in an error or warning, but will instead add the
2423 -std=gnu++98 flag if supported. This “decay” behavior may be con‐
2424 trolled with the CUDA_STANDARD_REQUIRED target property. Additionally,
2425 the CUDA_EXTENSIONS target property may be used to control whether com‐
2426 piler-specific extensions are enabled on a per-target basis.
2427 See the cmake-compile-features(7) manual for information on compile
2429 features and a list of supported compilers.
2430 This property is initialized by the value of the CMAKE_CUDA_STANDARD
2432 variable if it is set when a target is created.
2433 CUDA_STANDARD_REQUIRED
2435 Boolean describing whether the value of CUDA_STANDARD is a requirement.
2436 If this property is set to ON, then the value of the CUDA_STANDARD tar‐
2438 get property is treated as a requirement. If this property is OFF or
2439 unset, the CUDA_STANDARD target property is treated as optional and may
2440 “decay” to a previous standard if the requested is not available. For
2441 compilers that have no notion of a standard level, such as MSVC, this
2442 has no effect.
2443 See the cmake-compile-features(7) manual for information on compile
2445 features and a list of supported compilers.
2446 This property is initialized by the value of the CMAKE_CUDA_STAN‐
2448 DARD_REQUIRED variable if it is set when a target is created.
2449 CXX_EXTENSIONS
2451 Boolean specifying whether compiler specific extensions are requested.
2452 This property specifies whether compiler specific extensions should be
2454 used. For some compilers, this results in adding a flag such as
2455 -std=gnu++11 instead of -std=c++11 to the compile line. This property
2456 is ON by default. The basic C++ standard level is controlled by the
2457 CXX_STANDARD target property.
2458 See the cmake-compile-features(7) manual for information on compile
2460 features and a list of supported compilers.
2461 This property is initialized by the value of the CMAKE_CXX_EXTENSIONS
2463 variable if it is set when a target is created.
2464 CXX_STANDARD
2466 The C++ standard whose features are requested to build this target.
2467 This property specifies the C++ standard whose features are requested
2469 to build this target. For some compilers, this results in adding a
2470 flag such as -std=gnu++11 to the compile line. For compilers that have
2471 no notion of a standard level, such as Microsoft Visual C++ before 2015
2472 Update 3, this has no effect.
2473 Supported values are 98, 11, 14, 17, and 20.
2475 If the value requested does not result in a compile flag being added
2477 for the compiler in use, a previous standard flag will be added
2478 instead. This means that using:
2479 set_property(TARGET tgt PROPERTY CXX_STANDARD 11)
2481 with a compiler which does not support -std=gnu++11 or an equivalent
2483 flag will not result in an error or warning, but will instead add the
2484 -std=gnu++98 flag if supported. This “decay” behavior may be con‐
2485 trolled with the CXX_STANDARD_REQUIRED target property. Additionally,
2486 the CXX_EXTENSIONS target property may be used to control whether com‐
2487 piler-specific extensions are enabled on a per-target basis.
2488 See the cmake-compile-features(7) manual for information on compile
2490 features and a list of supported compilers.
2491 This property is initialized by the value of the CMAKE_CXX_STANDARD
2493 variable if it is set when a target is created.
2494 CXX_STANDARD_REQUIRED
2496 Boolean describing whether the value of CXX_STANDARD is a requirement.
2497 If this property is set to ON, then the value of the CXX_STANDARD tar‐
2499 get property is treated as a requirement. If this property is OFF or
2500 unset, the CXX_STANDARD target property is treated as optional and may
2501 “decay” to a previous standard if the requested is not available. For
2502 compilers that have no notion of a standard level, such as MSVC, this
2503 has no effect.
2504 See the cmake-compile-features(7) manual for information on compile
2506 features and a list of supported compilers.
2507 This property is initialized by the value of the CMAKE_CXX_STAN‐
2509 DARD_REQUIRED variable if it is set when a target is created.
2510 DEBUG_POSTFIX
2512 See target property <CONFIG>_POSTFIX.
2513 This property is a special case of the more-general <CONFIG>_POSTFIX
2515 property for the DEBUG configuration.
2516 DEFINE_SYMBOL
2518 Define a symbol when compiling this target’s sources.
2519 DEFINE_SYMBOL sets the name of the preprocessor symbol defined when
2521 compiling sources in a shared library. If not set here then it is set
2522 to target_EXPORTS by default (with some substitutions if the target is
2523 not a valid C identifier). This is useful for headers to know whether
2524 they are being included from inside their library or outside to prop‐
2525 erly setup dllexport/dllimport decorations.
2526 DEPLOYMENT_REMOTE_DIRECTORY
2528 Set the WinCE project RemoteDirectory in DeploymentTool and RemoteExe‐
2529 cutable in DebuggerTool in .vcproj files generated by the Visual Studio
2530 9 2008 generator. This is useful when you want to debug on remote
2531 WinCE device. For example:
2532 set_property(TARGET ${TARGET} PROPERTY
2534 DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage")
2535 produces:
2537 <DeploymentTool RemoteDirectory="\FlashStorage" ... />
2539 <DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... />
2540 DEPLOYMENT_ADDITIONAL_FILES
2542 Set the WinCE project AdditionalFiles in DeploymentTool in .vcproj
2543 files generated by the Visual Studio 9 2008 generator. This is useful
2544 when you want to debug on remote WinCE device. Specify additional
2545 files that will be copied to the device. For example:
2546 set_property(TARGET ${TARGET} PROPERTY
2548 DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0"
2549 "german.lng|local_folder|remote_folder|0")
2550 produces:
2552 <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... />
2554 DISABLE_PRECOMPILE_HEADERS
2556 Disables the precompilation of header files specified by PRECOM‐
2557 PILE_HEADERS property.
2558 If the property is not set, CMake will use the value provided by
2560 CMAKE_DISABLE_PRECOMPILE_HEADERS.
2561 DOTNET_TARGET_FRAMEWORK_VERSION
2563 Specify the .NET target framework version.
2564 Used to specify the .NET target framework version for C++/CLI. For
2566 example: v4.5.
2567 This property is only evaluated for Visual Studio Generators VS 2010
2569 and above.
2570 Can be initialized for all targets using the variable CMAKE_DOTNET_TAR‐
2572 GET_FRAMEWORK_VERSION.
2573 EchoString
2575 A message to be displayed when the target is built.
2576 A message to display on some generators (such as Makefile Generators)
2578 when the target is built.
2579 ENABLE_EXPORTS
2581 Specify whether an executable exports symbols for loadable modules.
2582 Normally an executable does not export any symbols because it is the
2584 final program. It is possible for an executable to export symbols to
2585 be used by loadable modules. When this property is set to true CMake
2586 will allow other targets to “link” to the executable with the tar‐
2587 get_link_libraries() command. On all platforms a target-level depen‐
2588 dency on the executable is created for targets that link to it. Han‐
2589 dling of the executable on the link lines of the loadable modules
2590 varies by platform:
2591 · On Windows-based systems (including Cygwin) an “import library” is
2593 created along with the executable to list the exported symbols.
2594 Loadable modules link to the import library to get the symbols.
2595 · On macOS, loadable modules link to the executable itself using the
2597 -bundle_loader flag.
2598 · On AIX, a linker “import file” is created along with the executable
2600 to list the exported symbols for import when linking other targets.
2601 Loadable modules link to the import file to get the symbols.
2602 · On other platforms, loadable modules are simply linked without refer‐
2604 encing the executable since the dynamic loader will automatically
2605 bind symbols when the module is loaded.
2606 This property is initialized by the value of the variable
2608 CMAKE_ENABLE_EXPORTS if it is set when a target is created.
2609 EXCLUDE_FROM_ALL
2611 Set this target property to a true (or false) value to exclude (or
2612 include) the target from the “all” target of the containing directory
2613 and its ancestors. If excluded, running e.g. make in the containing
2614 directory or its ancestors will not build the target by default.
2615 If this target property is not set then the target will be included in
2617 the “all” target of the containing directory. Furthermore, it will be
2618 included in the “all” target of its ancestor directories unless the
2619 EXCLUDE_FROM_ALL directory property is set.
2620 With EXCLUDE_FROM_ALL set to false or not set at all, the target will
2622 be brought up to date as part of doing a make install or its equivalent
2623 for the CMake generator being used. If a target has EXCLUDE_FROM_ALL
2624 set to true, then any attempt to install that target has undefined
2625 behavior. Note that such a target can still safely be listed in an
2626 install(TARGETS) command as long as the install components the target
2627 belongs to are not part of the set of components that anything tries to
2628 install.
2629 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
2631 Per-configuration version of target exclusion from Build Solution.
2632 This is the configuration-specific version of
2634 EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD
2635 is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes
2636 precedence in configurations for which it has a value.
2637 EXCLUDE_FROM_DEFAULT_BUILD
2639 Exclude target from Build Solution.
2640 This property is only used by Visual Studio generators. When set to
2642 TRUE, the target will not be built when you press Build Solution.
2643 EXPORT_NAME
2645 Exported name for target files.
2646 This sets the name for the IMPORTED target generated by the
2648 install(EXPORT) and export() commands. If not set, the logical target
2649 name is used by default.
2650 EXPORT_PROPERTIES
2652 List additional properties to export for a target.
2653 This property contains a list of property names that should be exported
2655 by the install(EXPORT) and export() commands. By default only a lim‐
2656 ited number of properties are exported. This property can be used to
2657 additionally export other properties as well.
2658 Properties starting with INTERFACE_ or IMPORTED_ are not allowed as
2660 they are reserved for internal CMake use.
2661 Properties containing generator expressions are also not allowed.
2663 FOLDER
2665 Set the folder name. Use to organize targets in an IDE.
2666 Targets with no FOLDER property will appear as top level entities in
2668 IDEs like Visual Studio. Targets with the same FOLDER property value
2669 will appear next to each other in a folder of that name. To nest fold‐
2670 ers, use FOLDER values such as ‘GUI/Dialogs’ with ‘/’ characters sepa‐
2671 rating folder levels.
2672 This property is initialized by the value of the variable CMAKE_FOLDER
2674 if it is set when a target is created.
2675 Fortran_FORMAT
2677 Set to FIXED or FREE to indicate the Fortran source layout.
2678 This property tells CMake whether the Fortran source files in a target
2680 use fixed-format or free-format. CMake will pass the corresponding
2681 format flag to the compiler. Use the source-specific Fortran_FORMAT
2682 property to change the format of a specific source file. If the vari‐
2683 able CMAKE_Fortran_FORMAT is set when a target is created its value is
2684 used to initialize this property.
2685 Fortran_MODULE_DIRECTORY
2687 Specify output directory for Fortran modules provided by the target.
2688 If the target contains Fortran source files that provide modules and
2690 the compiler supports a module output directory this specifies the
2691 directory in which the modules will be placed. When this property is
2692 not set the modules will be placed in the build directory corresponding
2693 to the target’s source directory. If the variable CMAKE_Fortran_MOD‐
2694 ULE_DIRECTORY is set when a target is created its value is used to ini‐
2695 tialize this property.
2696 Note that some compilers will automatically search the module output
2698 directory for modules USEd during compilation but others will not. If
2699 your sources USE modules their location must be specified by
2700 INCLUDE_DIRECTORIES regardless of this property.
2701 FRAMEWORK
2703 Build SHARED or STATIC library as Framework Bundle on the macOS and
2704 iOS.
2705 If such a library target has this property set to TRUE it will be built
2707 as a framework when built on the macOS and iOS. It will have the
2708 directory structure required for a framework and will be suitable to be
2709 used with the -framework option. This property is initialized by the
2710 value of the CMAKE_FRAMEWORK variable if it is set when a target is
2711 created.
2712 To customize Info.plist file in the framework, use MACOSX_FRAME‐
2714 WORK_INFO_PLIST target property.
2715 For macOS see also the FRAMEWORK_VERSION target property.
2717 Example of creation dynamicFramework:
2719 add_library(dynamicFramework SHARED
2721 dynamicFramework.c
2722 dynamicFramework.h
2723 )
2724 set_target_properties(dynamicFramework PROPERTIES
2725 FRAMEWORK TRUE
2726 FRAMEWORK_VERSION C
2727 MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework
2728 MACOSX_FRAMEWORK_INFO_PLIST Info.plist
2729 # "current version" in semantic format in Mach-O binary file
2730 VERSION 16.4.0
2731 # "compatibility version" in semantic format in Mach-O binary file
2732 SOVERSION 1.0.0
2733 PUBLIC_HEADER dynamicFramework.h
2734 XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer"
2735 )
2736 FRAMEWORK_VERSION
2738 Version of a framework created using the FRAMEWORK target property
2739 (e.g. A).
2740 This property only affects macOS, as iOS doesn’t have versioned direc‐
2742 tory structure.
2743 GENERATOR_FILE_NAME
2745 Generator’s file for this target.
2746 An internal property used by some generators to record the name of the
2748 project or dsp file associated with this target. Note that at config‐
2749 ure time, this property is only set for targets created by
2750 include_external_msproject().
2751 GHS_INTEGRITY_APP
2753 ON / OFF boolean to determine if an executable target should be treated
2754 as an Integrity Application.
2755 If no value is set and if a .int file is added as a source file to the
2757 executable target it will be treated as an Integrity Application.
2758 Supported on Green Hills MULTI.
2760 GHS_NO_SOURCE_GROUP_FILE
2762 ON / OFF boolean to control if the project file for a target should be
2763 one single file or multiple files.
2764 The default behavior or when the property is OFF is to generate a
2766 project file for the target and then a sub-project file for each source
2767 group.
2768 When this property is ON or if CMAKE_GHS_NO_SOURCE_GROUP_FILE is ON
2770 then only a single project file is generated for the target.
2771 Supported on Green Hills MULTI.
2773 GNUtoMS
2775 Convert GNU import library (.dll.a) to MS format (.lib).
2776 When linking a shared library or executable that exports symbols using
2778 GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert
2779 the import library (.dll.a) from GNU to MS format (.lib). Both import
2780 libraries will be installed by install(TARGETS) and exported by
2781 install(EXPORT) and export() to be linked by applications with either
2782 GNU- or MS-compatible tools.
2783 If the variable CMAKE_GNUtoMS is set when a target is created its value
2785 is used to initialize this property. The variable must be set prior to
2786 the first command that enables a language such as project() or
2787 enable_language(). CMake provides the variable as an option to the
2788 user automatically when configuring on Windows with GNU tools.
2789 HAS_CXX
2791 Link the target using the C++ linker tool (obsolete).
2792 This is equivalent to setting the LINKER_LANGUAGE property to CXX.
2794 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
2796 Specify #include line transforms for dependencies in a target.
2797 This property specifies rules to transform macro-like #include lines
2799 during implicit dependency scanning of C and C++ source files. The
2800 list of rules must be semicolon-separated with each entry of the form
2801 “A_MACRO(%)=value-with-%” (the % must be literal). During dependency
2802 scanning occurrences of A_MACRO(…) on #include lines will be replaced
2803 by the value given with the macro argument substituted for ‘%’. For
2804 example, the entry
2805 MYDIR(%)=<mydir/%>
2807 will convert lines of the form
2809 #include MYDIR(myheader.h)
2811 to
2813 #include <mydir/myheader.h>
2815 allowing the dependency to be followed.
2817 This property applies to sources in the target on which it is set.
2819 IMPORTED_COMMON_LANGUAGE_RUNTIME
2821 Property to define if the target uses C++/CLI.
2822 Ignored for non-imported targets.
2824 See also the COMMON_LANGUAGE_RUNTIME target property.
2826 IMPORTED_CONFIGURATIONS
2828 Configurations provided for an IMPORTED target.
2829 Set this to the list of configuration names available for an IMPORTED
2831 target. The names correspond to configurations defined in the project
2832 from which the target is imported. If the importing project uses a
2833 different set of configurations the names may be mapped using the
2834 MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non-imported tar‐
2835 gets.
2836 IMPORTED_GLOBAL
2838 Indication of whether an IMPORTED target is globally visible.
2839 The boolean value of this property is True for targets created with the
2841 IMPORTED GLOBAL options to add_executable() or add_library(). It is
2842 always False for targets built within the project.
2843 For targets created with the IMPORTED option to add_executable() or
2845 add_library() but without the additional option GLOBAL this is False,
2846 too. However, setting this property for such a locally IMPORTED target
2847 to True promotes that target to global scope. This promotion can only
2848 be done in the same directory where that IMPORTED target was created in
2849 the first place.
2850 Once an imported target has been made global, it cannot be changed back
2852 to non-global. Therefore, if a project sets this property, it may only
2853 provide a value of True. CMake will issue an error if the project tries
2854 to set the property to a non-True value, even if the value was already
2855 False.
2856 IMPORTED_IMPLIB_<CONFIG>
2858 <CONFIG>-specific version of IMPORTED_IMPLIB property.
2859 Configuration names correspond to those provided by the project from
2861 which the target is imported.
2862 IMPORTED_IMPLIB
2864 Full path to the import library for an IMPORTED target.
2865 Set this to the location of the .lib part of a Windows DLL, or on AIX
2867 set it to an import file created for executables that export symbols
2868 (see the ENABLE_EXPORTS target property). Ignored for non-imported
2869 targets.
2870 IMPORTED_LIBNAME_<CONFIG>
2872 <CONFIG>-specific version of IMPORTED_LIBNAME property.
2873 Configuration names correspond to those provided by the project from
2875 which the target is imported.
2876 IMPORTED_LIBNAME
2878 Specify the link library name for an imported Interface Library.
2879 An interface library builds no library file itself but does specify
2881 usage requirements for its consumers. The IMPORTED_LIBNAME property
2882 may be set to specify a single library name to be placed on the link
2883 line in place of the interface library target name as a requirement for
2884 using the interface.
2885 This property is intended for use in naming libraries provided by a
2887 platform SDK for which the full path to a library file may not be
2888 known. The value may be a plain library name such as foo but may not
2889 be a path (e.g. /usr/lib/libfoo.so) or a flag (e.g. -Wl,...). The name
2890 is never treated as a library target name even if it happens to name
2891 one.
2892 The IMPORTED_LIBNAME property is allowed only on imported Interface
2894 Libraries and is rejected on targets of other types (for which the
2895 IMPORTED_LOCATION target property may be used).
2896 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
2898 <CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
2899 Configuration names correspond to those provided by the project from
2901 which the target is imported. If set, this property completely over‐
2902 rides the generic property for the named configuration.
2903 IMPORTED_LINK_DEPENDENT_LIBRARIES
2905 Dependent shared libraries of an imported shared library.
2906 Shared libraries may be linked to other shared libraries as part of
2908 their implementation. On some platforms the linker searches for the
2909 dependent libraries of shared libraries they are including in the link.
2910 Set this property to the list of dependent shared libraries of an
2911 imported library. The list should be disjoint from the list of inter‐
2912 face libraries in the INTERFACE_LINK_LIBRARIES property. On platforms
2913 requiring dependent shared libraries to be found at link time CMake
2914 uses this list to add appropriate files or paths to the link command
2915 line. Ignored for non-imported targets.
2916 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
2918 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.
2919 Configuration names correspond to those provided by the project from
2921 which the target is imported. If set, this property completely over‐
2922 rides the generic property for the named configuration.
2923 IMPORTED_LINK_INTERFACE_LANGUAGES
2925 Languages compiled into an IMPORTED static library.
2926 Set this to the list of languages of source files compiled to produce a
2928 STATIC IMPORTED library (such as C or CXX). CMake accounts for these
2929 languages when computing how to link a target to the imported library.
2930 For example, when a C executable links to an imported C++ static
2931 library CMake chooses the C++ linker to satisfy language runtime depen‐
2932 dencies of the static library.
2933 This property is ignored for targets that are not STATIC libraries.
2935 This property is ignored for non-imported targets.
2936 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
2938 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.
2939 Configuration names correspond to those provided by the project from
2941 which the target is imported. If set, this property completely over‐
2942 rides the generic property for the named configuration.
2943 This property is ignored if the target also has a non-empty INTER‐
2945 FACE_LINK_LIBRARIES property.
2946 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
2948 IMPORTED_LINK_INTERFACE_LIBRARIES
2950 Transitive link interface of an IMPORTED target.
2951 Set this to the list of libraries whose interface is included when an
2953 IMPORTED library target is linked to another target. The libraries
2954 will be included on the link line for the target. Unlike the
2955 LINK_INTERFACE_LIBRARIES property, this property applies to all
2956 imported target types, including STATIC libraries. This property is
2957 ignored for non-imported targets.
2958 This property is ignored if the target also has a non-empty INTER‐
2960 FACE_LINK_LIBRARIES property.
2961 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
2963 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
2965 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY.
2966 If set, this property completely overrides the generic property for the
2968 named configuration.
2969 IMPORTED_LINK_INTERFACE_MULTIPLICITY
2971 Repetition count for cycles of IMPORTED static libraries.
2972 This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
2974 IMPORTED_LOCATION_<CONFIG>
2976 <CONFIG>-specific version of IMPORTED_LOCATION property.
2977 Configuration names correspond to those provided by the project from
2979 which the target is imported.
2980 IMPORTED_LOCATION
2982 Full path to the main file on disk for an IMPORTED target.
2983 Set this to the location of an IMPORTED target file on disk. For exe‐
2985 cutables this is the location of the executable file. For bundles on
2986 macOS this is the location of the executable file inside Contents/MacOS
2987 under the application bundle folder. For STATIC libraries and modules
2988 this is the location of the library or module. For SHARED libraries on
2989 non-DLL platforms this is the location of the shared library. For
2990 frameworks on macOS this is the location of the library file symlink
2991 just inside the framework folder. For DLLs this is the location of the
2992 .dll part of the library. For UNKNOWN libraries this is the location
2993 of the file to be linked. Ignored for non-imported targets.
2994 The IMPORTED_LOCATION target property may be overridden for a given
2996 configuration <CONFIG> by the configuration-specific IMPORTED_LOCA‐
2997 TION_<CONFIG> target property. Furthermore, the MAP_IMPORTED_CON‐
2998 FIG_<CONFIG> target property may be used to map between a project’s
2999 configurations and those of an imported target. If none of these is
3000 set then the name of any other configuration listed in the
3001 IMPORTED_CONFIGURATIONS target property may be selected and its
3002 IMPORTED_LOCATION_<CONFIG> value used.
3003 To get the location of an imported target read one of the LOCATION or
3005 LOCATION_<CONFIG> properties.
3006 For platforms with import libraries (e.g. Windows) see also
3008 IMPORTED_IMPLIB.
3009 IMPORTED_NO_SONAME_<CONFIG>
3011 <CONFIG>-specific version of IMPORTED_NO_SONAME property.
3012 Configuration names correspond to those provided by the project from
3014 which the target is imported.
3015 IMPORTED_NO_SONAME
3017 Specifies that an IMPORTED shared library target has no soname.
3018 Set this property to true for an imported shared library file that has
3020 no soname field. CMake may adjust generated link commands for some
3021 platforms to prevent the linker from using the path to the library in
3022 place of its missing soname. Ignored for non-imported targets.
3023 IMPORTED_OBJECTS_<CONFIG>
3025 <CONFIG>-specific version of IMPORTED_OBJECTS property.
3026 Configuration names correspond to those provided by the project from
3028 which the target is imported.
3029 IMPORTED_OBJECTS
3031 A semicolon-separated list of absolute paths to the object files on
3032 disk for an imported object library.
3033 Ignored for non-imported targets.
3035 Projects may skip IMPORTED_OBJECTS if the configuration-specific prop‐
3037 erty IMPORTED_OBJECTS_<CONFIG> is set instead.
3038 IMPORTED
3040 Read-only indication of whether a target is IMPORTED.
3041 The boolean value of this property is True for targets created with the
3043 IMPORTED option to add_executable() or add_library(). It is False for
3044 targets built within the project.
3045 IMPORTED_SONAME_<CONFIG>
3047 <CONFIG>-specific version of IMPORTED_SONAME property.
3048 Configuration names correspond to those provided by the project from
3050 which the target is imported.
3051 IMPORTED_SONAME
3053 The soname of an IMPORTED target of shared library type.
3054 Set this to the soname embedded in an imported shared library. This is
3056 meaningful only on platforms supporting the feature. Ignored for
3057 non-imported targets.
3058 IMPORT_PREFIX
3060 What comes before the import library name.
3061 Similar to the target property PREFIX, but used for import libraries
3063 (typically corresponding to a DLL) instead of regular libraries. A
3064 target property that can be set to override the prefix (such as lib) on
3065 an import library name.
3066 IMPORT_SUFFIX
3068 What comes after the import library name.
3069 Similar to the target property SUFFIX, but used for import libraries
3071 (typically corresponding to a DLL) instead of regular libraries. A
3072 target property that can be set to override the suffix (such as .lib)
3073 on an import library name.
3074 INCLUDE_DIRECTORIES
3076 List of preprocessor include file search directories.
3077 This property specifies the list of directories given so far to the
3079 target_include_directories() command. In addition to accepting values
3080 from that command, values may be set directly on any target using the
3081 set_property() command. A target gets its initial value for this prop‐
3082 erty from the value of the INCLUDE_DIRECTORIES directory property.
3083 Both directory and target property values are adjusted by calls to the
3084 include_directories() command.
3085 The value of this property is used by the generators to set the include
3087 paths for the compiler.
3088 Relative paths should not be added to this property directly. Use one
3090 of the commands above instead to handle relative paths.
3091 Contents of INCLUDE_DIRECTORIES may use cmake-generator-expressions(7)
3093 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3094 for available expressions. See the cmake-buildsystem(7) manual for
3095 more on defining buildsystem properties.
3096 INSTALL_NAME_DIR
3098 macOS directory name for installed targets.
3099 INSTALL_NAME_DIR is a string specifying the directory portion of the
3101 “install_name” field of shared libraries on macOS to use in the
3102 installed targets.
3103 This property is initialized by the value of the variable
3105 CMAKE_INSTALL_NAME_DIR if it is set when a target is created.
3106 INSTALL_REMOVE_ENVIRONMENT_RPATH
3108 Controls whether toolchain-defined rpaths should be removed during
3109 installation.
3110 When a target is being installed, CMake may need to rewrite its rpath
3112 information. This occurs when the install rpath (as specified by the
3113 INSTALL_RPATH target property) has different contents to the rpath that
3114 the target was built with. Some toolchains insert their own rpath con‐
3115 tents into the binary as part of the build. By default, CMake will
3116 preserve those extra inserted contents in the install rpath. For those
3117 scenarios where such toolchain-inserted entries need to be discarded
3118 during install, set the INSTALL_REMOVE_ENVIRONMENT_RPATH target prop‐
3119 erty to true.
3120 This property is initialized by the value of CMAKE_INSTALL_REMOVE_ENVI‐
3122 RONMENT_RPATH when the target is created.
3123 INSTALL_RPATH
3125 The rpath to use for installed targets.
3126 A semicolon-separated list specifying the rpath to use in installed
3128 targets (for platforms that support it). This property is initialized
3129 by the value of the variable CMAKE_INSTALL_RPATH if it is set when a
3130 target is created.
3131 This property supports generator expressions.
3133 INSTALL_RPATH_USE_LINK_PATH
3135 Add paths to linker search and installed rpath.
3136 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to True will
3138 append directories in the linker search path and outside the project to
3139 the INSTALL_RPATH. This property is initialized by the value of the
3140 variable CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a target
3141 is created.
3142 INTERFACE_AUTOUIC_OPTIONS
3144 List of interface options to pass to uic.
3145 Targets may populate this property to publish the options required to
3147 use when invoking uic. Consuming targets can add entries to their own
3148 AUTOUIC_OPTIONS property such as $<TARGET_PROPERTY:foo,INTER‐
3149 FACE_AUTOUIC_OPTIONS> to use the uic options specified in the interface
3150 of foo. This is done automatically by the target_link_libraries() com‐
3151 mand.
3152 This property supports generator expressions. See the cmake-genera‐
3154 tor-expressions(7) manual for available expressions.
3155 INTERFACE_COMPILE_DEFINITIONS
3157 List of public compile definitions requirements for a library.
3158 Targets may populate this property to publish the compile definitions
3160 required to compile against the headers for the target. The tar‐
3161 get_compile_definitions() command populates this property with values
3162 given to the PUBLIC and INTERFACE keywords. Projects may also get and
3163 set the property directly.
3164 When target dependencies are specified using target_link_libraries(),
3166 CMake will read this property from all target dependencies to determine
3167 the build properties of the consumer.
3168 Contents of INTERFACE_COMPILE_DEFINITIONS may use “generator expres‐
3170 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
3171 manual for available expressions. See the cmake-buildsystem(7) -manual
3172 for more on defining buildsystem properties.
3173 INTERFACE_COMPILE_FEATURES
3175 List of public compile features requirements for a library.
3176 Targets may populate this property to publish the compile features
3178 required to compile against the headers for the target. The tar‐
3179 get_compile_features() command populates this property with values
3180 given to the PUBLIC and INTERFACE keywords. Projects may also get and
3181 set the property directly.
3182 When target dependencies are specified using target_link_libraries(),
3184 CMake will read this property from all target dependencies to determine
3185 the build properties of the consumer.
3186 Contents of INTERFACE_COMPILE_FEATURES may use “generator expressions”
3188 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3189 for available expressions. See the cmake-buildsystem(7) -manual for
3190 more on defining buildsystem properties.
3191 See the cmake-compile-features(7) manual for information on compile
3193 features and a list of supported compilers.
3194 INTERFACE_COMPILE_OPTIONS
3196 List of public compile options requirements for a library.
3197 Targets may populate this property to publish the compile options
3199 required to compile against the headers for the target. The tar‐
3200 get_compile_options() command populates this property with values given
3201 to the PUBLIC and INTERFACE keywords. Projects may also get and set
3202 the property directly.
3203 When target dependencies are specified using target_link_libraries(),
3205 CMake will read this property from all target dependencies to determine
3206 the build properties of the consumer.
3207 Contents of INTERFACE_COMPILE_OPTIONS may use “generator expressions”
3209 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3210 for available expressions. See the cmake-buildsystem(7) -manual for
3211 more on defining buildsystem properties.
3212 INTERFACE_INCLUDE_DIRECTORIES
3214 List of public include directories requirements for a library.
3215 Targets may populate this property to publish the include directories
3217 required to compile against the headers for the target. The tar‐
3218 get_include_directories() command populates this property with values
3219 given to the PUBLIC and INTERFACE keywords. Projects may also get and
3220 set the property directly.
3221 When target dependencies are specified using target_link_libraries(),
3223 CMake will read this property from all target dependencies to determine
3224 the build properties of the consumer.
3225 Contents of INTERFACE_INCLUDE_DIRECTORIES may use “generator expres‐
3227 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
3228 manual for available expressions. See the cmake-buildsystem(7) -manual
3229 for more on defining buildsystem properties.
3230 Include directories usage requirements commonly differ between the
3232 build-tree and the install-tree. The BUILD_INTERFACE and
3233 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
3234 rate usage requirements based on the usage location. Relative paths
3235 are allowed within the INSTALL_INTERFACE expression and are interpreted
3236 relative to the installation prefix. For example:
3237 target_include_directories(mylib INTERFACE
3239 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
3240 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
3241 )
3242 Creating Relocatable Packages
3244 Note that it is not advisable to populate the INSTALL_INTERFACE of the
3245 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
3246 include directories of dependencies. That would hard-code into
3247 installed packages the include directory paths for dependencies as
3248 found on the machine the package was made on.
3249 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
3251 suitable for specifying the required include directories for headers
3252 provided with the target itself, not those provided by the transitive
3253 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
3254 Those dependencies should themselves be targets that specify their own
3255 header locations in INTERFACE_INCLUDE_DIRECTORIES.
3256 See the Creating Relocatable Packages section of the cmake-packages(7)
3258 manual for discussion of additional care that must be taken when speci‐
3259 fying usage requirements while creating packages for redistribution.
3260 INTERFACE_LINK_DEPENDS
3262 Additional public interface files on which a target binary depends for
3263 linking.
3264 This property is supported only by Ninja and Makefile Generators. It
3266 is intended to specify dependencies on “linker scripts” for custom
3267 Makefile link rules.
3268 When target dependencies are specified using target_link_libraries(),
3270 CMake will read this property from all target dependencies to determine
3271 the build properties of the consumer.
3272 Contents of INTERFACE_LINK_DEPENDS may use “generator expressions” with
3274 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3275 available expressions. See the cmake-buildsystem(7) -manual for more
3276 on defining buildsystem properties.
3277 Link dependency files usage requirements commonly differ between the
3279 build-tree and the install-tree. The BUILD_INTERFACE and
3280 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
3281 rate usage requirements based on the usage location. Relative paths
3282 are allowed within the INSTALL_INTERFACE expression and are interpreted
3283 relative to the installation prefix. For example:
3284 set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS
3286 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript>
3287 $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript
3288 )
3289 INTERFACE_LINK_DIRECTORIES
3291 List of public link directories requirements for a library.
3292 Targets may populate this property to publish the link directories
3294 required to compile against the headers for the target. The tar‐
3295 get_link_directories() command populates this property with values
3296 given to the PUBLIC and INTERFACE keywords. Projects may also get and
3297 set the property directly.
3298 When target dependencies are specified using target_link_libraries(),
3300 CMake will read this property from all target dependencies to determine
3301 the build properties of the consumer.
3302 Contents of INTERFACE_LINK_DIRECTORIES may use “generator expressions”
3304 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3305 for available expressions. See the cmake-buildsystem(7) -manual for
3306 more on defining buildsystem properties.
3307 INTERFACE_LINK_LIBRARIES
3309 List public interface libraries for a library.
3310 This property contains the list of transitive link dependencies. When
3312 the target is linked into another target using the tar‐
3313 get_link_libraries() command, the libraries listed (and recursively
3314 their link interface libraries) will be provided to the other target
3315 also. This property is overridden by the LINK_INTERFACE_LIBRARIES or
3316 LINK_INTERFACE_LIBRARIES_<CONFIG> property if policy CMP0022 is OLD or
3317 unset.
3318 Contents of INTERFACE_LINK_LIBRARIES may use “generator expressions”
3320 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3321 for available expressions. See the cmake-buildsystem(7) manual for
3322 more on defining buildsystem properties.
3323 NOTE:
3325 A call to target_link_libraries(<target> ...) may update this prop‐
3326 erty on <target>. If <target> was not created in the same directory
3327 as the call then target_link_libraries() will add a suffix of the
3328 form ::@<directory-id> to each entry, where the ::@ is a separator
3329 and the <directory-id> is unspecified. This tells the generators
3330 that the named libraries must be looked up in the scope of the call‐
3331 er rather than in the scope in which the <target> was created.
3332 Valid directory ids are stripped on export by the install(EXPORT)
3333 and export() commands.
3334 Creating Relocatable Packages
3336 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
3337 of a target with absolute paths to dependencies. That would hard-code
3338 into installed packages the library file paths for dependencies as
3339 found on the machine the package was made on.
3340 See the Creating Relocatable Packages section of the cmake-packages(7)
3342 manual for discussion of additional care that must be taken when speci‐
3343 fying usage requirements while creating packages for redistribution.
3344 INTERFACE_LINK_OPTIONS
3346 List of public link options requirements for a library.
3347 Targets may populate this property to publish the link options required
3349 to compile against the headers for the target. The tar‐
3350 get_link_options() command populates this property with values given to
3351 the PUBLIC and INTERFACE keywords. Projects may also get and set the
3352 property directly.
3353 When target dependencies are specified using target_link_libraries(),
3355 CMake will read this property from all target dependencies to determine
3356 the build properties of the consumer.
3357 Contents of INTERFACE_LINK_OPTIONS may use “generator expressions” with
3359 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3360 available expressions. See the cmake-buildsystem(7) -manual for more
3361 on defining buildsystem properties.
3362 INTERFACE_PRECOMPILE_HEADERS
3364 List of interface header files to precompile into consuming targets.
3365 Targets may populate this property to publish the header files for con‐
3367 suming targets to precompile. The target_precompile_headers() command
3368 populates this property with values given to the PUBLIC and INTERFACE
3369 keywords. Projects may also get and set the property directly. See
3370 the discussion in target_precompile_headers() for guidance on appropri‐
3371 ate use of this property for installed or exported targets.
3372 Contents of INTERFACE_PRECOMPILE_HEADERS may use “generator expres‐
3374 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
3375 manual for available expressions. See the cmake-buildsystem(7) manual
3376 for more on defining buildsystem properties.
3377 INTERFACE_POSITION_INDEPENDENT_CODE
3379 Whether consumers need to create a position-independent target
3380 The INTERFACE_POSITION_INDEPENDENT_CODE property informs consumers of
3382 this target whether they must set their POSITION_INDEPENDENT_CODE prop‐
3383 erty to ON. If this property is set to ON, then the POSITION_INDEPEN‐
3384 DENT_CODE property on all consumers will be set to ON. Similarly, if
3385 this property is set to OFF, then the POSITION_INDEPENDENT_CODE prop‐
3386 erty on all consumers will be set to OFF. If this property is unde‐
3387 fined, then consumers will determine their POSITION_INDEPENDENT_CODE
3388 property by other means. Consumers must ensure that the targets that
3389 they link to have a consistent requirement for their INTERFACE_POSI‐
3390 TION_INDEPENDENT_CODE property.
3391 Contents of INTERFACE_POSITION_INDEPENDENT_CODE may use “generator
3393 expressions” with the syntax $<...>. See the cmake-generator-expres‐
3394 sions(7) manual for available expressions. See the cmake-buildsys‐
3395 tem(7) manual for more on defining buildsystem properties.
3396 INTERFACE_SOURCES
3398 List of interface sources to compile into consuming targets.
3399 Targets may populate this property to publish the sources for consuming
3401 targets to compile. The target_sources() command populates this prop‐
3402 erty with values given to the PUBLIC and INTERFACE keywords. Projects
3403 may also get and set the property directly.
3404 When target dependencies are specified using target_link_libraries(),
3406 CMake will read this property from all target dependencies to determine
3407 the sources of the consumer.
3408 Contents of INTERFACE_SOURCES may use “generator expressions” with the
3410 syntax $<...>. See the cmake-generator-expressions(7) manual for
3411 available expressions. See the cmake-buildsystem(7) manual for more on
3412 defining buildsystem properties.
3413 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
3415 List of public system include directories for a library.
3416 Targets may populate this property to publish the include directories
3418 which contain system headers, and therefore should not result in com‐
3419 piler warnings. The target_include_directories(SYSTEM) command signa‐
3420 ture populates this property with values given to the PUBLIC and INTER‐
3421 FACE keywords.
3422 Projects may also get and set the property directly, but must be aware
3424 that adding directories to this property does not make those directo‐
3425 ries used during compilation. Adding directories to this property
3426 marks directories as SYSTEM which otherwise would be used in a non-SYS‐
3427 TEM manner. This can appear similar to ‘duplication’, so prefer the
3428 high-level target_include_directories(SYSTEM) command and avoid setting
3429 the property by low-level means.
3430 When target dependencies are specified using target_link_libraries(),
3432 CMake will read this property from all target dependencies to mark the
3433 same include directories as containing system headers.
3434 Contents of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES may use “generator
3436 expressions” with the syntax $<...>. See the cmake-generator-expres‐
3437 sions(7) manual for available expressions. See the cmake-buildsys‐
3438 tem(7) manual for more on defining buildsystem properties.
3439 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
3441 Per-configuration interprocedural optimization for a target.
3442 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
3444 If set, this property overrides the generic property for the named con‐
3445 figuration.
3446 This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZA‐
3448 TION_<CONFIG> variable if it is set when a target is created.
3449 INTERPROCEDURAL_OPTIMIZATION
3451 Enable interprocedural optimization for a target.
3452 If set to true, enables interprocedural optimizations if they are known
3454 to be supported by the compiler. Depending on value of policy CMP0069,
3455 the error will be reported or ignored, if interprocedural optimization
3456 is enabled but not supported.
3457 This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZATION
3459 variable if it is set when a target is created.
3460 IOS_INSTALL_COMBINED
3462 Build a combined (device and simulator) target when installing.
3463 When this property is set to set to false (which is the default) then
3465 it will either be built with the device SDK or the simulator SDK
3466 depending on the SDK set. But if this property is set to true then the
3467 target will at install time also be built for the corresponding SDK and
3468 combined into one library.
3469 This feature requires at least Xcode version 6.
3471 JOB_POOL_COMPILE
3473 Ninja only: Pool used for compiling.
3474 The number of parallel compile processes could be limited by defining
3476 pools with the global JOB_POOLS property and then specifying here the
3477 pool name.
3478 For instance:
3480 set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs)
3482 This property is initialized by the value of CMAKE_JOB_POOL_COMPILE.
3484 JOB_POOL_LINK
3486 Ninja only: Pool used for linking.
3487 The number of parallel link processes could be limited by defining
3489 pools with the global JOB_POOLS property and then specifying here the
3490 pool name.
3491 For instance:
3493 set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs)
3495 This property is initialized by the value of CMAKE_JOB_POOL_LINK.
3497 LABELS
3499 Specify a list of text labels associated with a target.
3500 Target label semantics are currently unspecified.
3502 <LANG>_CLANG_TIDY
3504 This property is implemented only when <LANG> is C or CXX.
3505 Specify a semicolon-separated list containing a command line for the
3507 clang-tidy tool. The Makefile Generators and the Ninja generator will
3508 run this tool along with the compiler and report a warning if the tool
3509 reports any problems.
3510 This property is initialized by the value of the
3512 CMAKE_<LANG>_CLANG_TIDY variable if it is set when a target is created.
3513 <LANG>_COMPILER_LAUNCHER
3515 This property is implemented only when <LANG> is C, CXX, Fortran, or
3516 CUDA.
3517 Specify a semicolon-separated list containing a command line for a com‐
3519 piler launching tool. The Makefile Generators and the Ninja generator
3520 will run this tool and pass the compiler and its arguments to the tool.
3521 Some example tools are distcc and ccache.
3522 This property is initialized by the value of the CMAKE_<LANG>_COM‐
3524 PILER_LAUNCHER variable if it is set when a target is created.
3525 <LANG>_CPPCHECK
3527 This property is supported only when <LANG> is C or CXX.
3528 Specify a semicolon-separated list containing a command line for the
3530 cppcheck static analysis tool. The Makefile Generators and the Ninja
3531 generator will run cppcheck along with the compiler and report any
3532 problems. If the command-line specifies the exit code options to
3533 cppcheck then the build will fail if the tool returns non-zero.
3534 This property is initialized by the value of the CMAKE_<LANG>_CPPCHECK
3536 variable if it is set when a target is created.
3537 <LANG>_CPPLINT
3539 This property is supported only when <LANG> is C or CXX.
3540 Specify a semicolon-separated list containing a command line for the
3542 cpplint style checker. The Makefile Generators and the Ninja generator
3543 will run cpplint along with the compiler and report any problems.
3544 This property is initialized by the value of the CMAKE_<LANG>_CPPLINT
3546 variable if it is set when a target is created.
3547 <LANG>_INCLUDE_WHAT_YOU_USE
3549 This property is implemented only when <LANG> is C or CXX.
3550 Specify a semicolon-separated list containing a command line for the
3552 include-what-you-use tool. The Makefile Generators and the Ninja gen‐
3553 erator will run this tool along with the compiler and report a warning
3554 if the tool reports any problems.
3555 This property is initialized by the value of the
3557 CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE variable if it is set when a target
3558 is created.
3559 <LANG>_VISIBILITY_PRESET
3561 Value for symbol visibility compile flags
3562 The <LANG>_VISIBILITY_PRESET property determines the value passed in a
3564 visibility related compile option, such as -fvisibility= for <LANG>.
3565 This property affects compilation in sources of all types of targets
3566 (subject to policy CMP0063).
3567 This property is initialized by the value of the CMAKE_<LANG>_VISIBIL‐
3569 ITY_PRESET variable if it is set when a target is created.
3570 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
3572 Per-configuration output directory for LIBRARY target files.
3573 This is a per-configuration version of the LIBRARY_OUTPUT_DIRECTORY
3575 target property, but multi-configuration generators (Visual Studio Gen‐
3576 erators, Xcode) do NOT append a per-configuration subdirectory to the
3577 specified directory. This property is initialized by the value of the
3578 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
3579 target is created.
3580 Contents of LIBRARY_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
3582 sions.
3583 LIBRARY_OUTPUT_DIRECTORY
3585 Output directory in which to build LIBRARY target files.
3586 This property specifies the directory into which library target files
3588 should be built. The property value may use generator expressions.
3589 Multi-configuration generators (VS, Xcode) append a per-configuration
3590 subdirectory to the specified directory unless a generator expression
3591 is used.
3592 This property is initialized by the value of the variable
3594 CMAKE_LIBRARY_OUTPUT_DIRECTORY if it is set when a target is created.
3595 See also the LIBRARY_OUTPUT_DIRECTORY_<CONFIG> target property.
3597 LIBRARY_OUTPUT_NAME_<CONFIG>
3599 Per-configuration output name for LIBRARY target files.
3600 This is the configuration-specific version of the LIBRARY_OUTPUT_NAME
3602 target property.
3603 LIBRARY_OUTPUT_NAME
3605 Output name for LIBRARY target files.
3606 This property specifies the base name for library target files. It
3608 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
3609 See also the LIBRARY_OUTPUT_NAME_<CONFIG> target property.
3611 LINK_DEPENDS_NO_SHARED
3613 Do not depend on linked shared library files.
3614 Set this property to true to tell CMake generators not to add
3616 file-level dependencies on the shared library files linked by this tar‐
3617 get. Modification to the shared libraries will not be sufficient to
3618 re-link this target. Logical target-level dependencies will not be
3619 affected so the linked shared libraries will still be brought up to
3620 date before this target is built.
3621 This property is initialized by the value of the variable
3623 CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created.
3624 LINK_DEPENDS
3626 Additional files on which a target binary depends for linking.
3627 Specifies a semicolon-separated list of full-paths to files on which
3629 the link rule for this target depends. The target binary will be
3630 linked if any of the named files is newer than it.
3631 This property is supported only by Ninja and Makefile Generators. It
3633 is intended to specify dependencies on “linker scripts” for custom
3634 Makefile link rules.
3635 Contents of LINK_DEPENDS may use “generator expressions” with the syn‐
3637 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
3638 able expressions. See the cmake-buildsystem(7) manual for more on
3639 defining buildsystem properties.
3640 LINKER_LANGUAGE
3642 Specifies language whose compiler will invoke the linker.
3643 For executables, shared libraries, and modules, this sets the language
3645 whose compiler is used to link the target (such as “C” or “CXX”). A
3646 typical value for an executable is the language of the source file pro‐
3647 viding the program entry point (main). If not set, the language with
3648 the highest linker preference value is the default. See documentation
3649 of CMAKE_<LANG>_LINKER_PREFERENCE variables.
3650 If this property is not set by the user, it will be calculated at gen‐
3652 erate-time by CMake.
3653 LINK_DIRECTORIES
3655 List of directories to use for the link step of shared library, module
3656 and executable targets.
3657 This property holds a semicolon-separated list of directories specified
3659 so far for its target. Use the target_link_directories() command to
3660 append more search directories.
3661 This property is initialized by the LINK_DIRECTORIES directory property
3663 when a target is created, and is used by the generators to set the
3664 search directories for the linker.
3665 Contents of LINK_DIRECTORIES may use “generator expressions” with the
3667 syntax $<...>. See the cmake-generator-expressions(7) manual for
3668 available expressions. See the cmake-buildsystem(7) manual for more on
3669 defining buildsystem properties.
3670 LINK_FLAGS_<CONFIG>
3672 Per-configuration linker flags for a SHARED library, MODULE or EXE‐
3673 CUTABLE target.
3674 This is the configuration-specific version of LINK_FLAGS.
3676 NOTE:
3678 This property has been superseded by LINK_OPTIONS property.
3679 LINK_FLAGS
3681 Additional flags to use when linking this target if it is a shared
3682 library, module library, or an executable. Static libraries need to use
3683 STATIC_LIBRARY_OPTIONS or STATIC_LIBRARY_FLAGS properties.
3684 The LINK_FLAGS property, managed as a string, can be used to add extra
3686 flags to the link step of a target. LINK_FLAGS_<CONFIG> will add to
3687 the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
3688 RELWITHDEBINFO, …
3689 NOTE:
3691 This property has been superseded by LINK_OPTIONS property.
3692 LINK_INTERFACE_LIBRARIES_<CONFIG>
3694 Per-configuration list of public interface libraries for a target.
3695 This is the configuration-specific version of LINK_INTERFACE_LIBRARIES.
3697 If set, this property completely overrides the generic property for the
3698 named configuration.
3699 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
3701 policy CMP0022 is NEW.
3702 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
3704 Creating Relocatable Packages
3706 Note that it is not advisable to populate the LINK_INTER‐
3707 FACE_LIBRARIES_<CONFIG> of a target with absolute paths to dependen‐
3708 cies. That would hard-code into installed packages the library file
3709 paths for dependencies as found on the machine the package was made on.
3710 See the Creating Relocatable Packages section of the cmake-packages(7)
3712 manual for discussion of additional care that must be taken when speci‐
3713 fying usage requirements while creating packages for redistribution.
3714 LINK_INTERFACE_LIBRARIES
3716 List public interface libraries for a shared library or executable.
3717 By default linking to a shared library target transitively links to
3719 targets with which the library itself was linked. For an executable
3720 with exports (see the ENABLE_EXPORTS target property) no default tran‐
3721 sitive link dependencies are used. This property replaces the default
3722 transitive link dependencies with an explicit list. When the target is
3723 linked into another target using the target_link_libraries() command,
3724 the libraries listed (and recursively their link interface libraries)
3725 will be provided to the other target also. If the list is empty then
3726 no transitive link dependencies will be incorporated when this target
3727 is linked into another target even if the default set is non-empty.
3728 This property is initialized by the value of the CMAKE_LINK_INTER‐
3729 FACE_LIBRARIES variable if it is set when a target is created. This
3730 property is ignored for STATIC libraries.
3731 This property is overridden by the INTERFACE_LINK_LIBRARIES property if
3733 policy CMP0022 is NEW.
3734 This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
3736 Creating Relocatable Packages
3738 Note that it is not advisable to populate the LINK_INTERFACE_LIBRARIES
3739 of a target with absolute paths to dependencies. That would hard-code
3740 into installed packages the library file paths for dependencies as
3741 found on the machine the package was made on.
3742 See the Creating Relocatable Packages section of the cmake-packages(7)
3744 manual for discussion of additional care that must be taken when speci‐
3745 fying usage requirements while creating packages for redistribution.
3746 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
3748 Per-configuration repetition count for cycles of STATIC libraries.
3749 This is the configuration-specific version of LINK_INTERFACE_MULTIPLIC‐
3751 ITY. If set, this property completely overrides the generic property
3752 for the named configuration.
3753 LINK_INTERFACE_MULTIPLICITY
3755 Repetition count for STATIC libraries with cyclic dependencies.
3756 When linking to a STATIC library target with cyclic dependencies the
3758 linker may need to scan more than once through the archives in the
3759 strongly connected component of the dependency graph. CMake by default
3760 constructs the link line so that the linker will scan through the com‐
3761 ponent at least twice. This property specifies the minimum number of
3762 scans if it is larger than the default. CMake uses the largest value
3763 specified by any target in a component.
3764 LINK_LIBRARIES
3766 List of direct link dependencies.
3767 This property specifies the list of libraries or targets which will be
3769 used for linking. In addition to accepting values from the tar‐
3770 get_link_libraries() command, values may be set directly on any target
3771 using the set_property() command.
3772 The value of this property is used by the generators to set the link
3774 libraries for the compiler.
3775 Contents of LINK_LIBRARIES may use “generator expressions” with the
3777 syntax $<...>. See the cmake-generator-expressions(7) manual for
3778 available expressions. See the cmake-buildsystem(7) manual for more on
3779 defining buildsystem properties.
3780 NOTE:
3782 A call to target_link_libraries(<target> ...) may update this prop‐
3783 erty on <target>. If <target> was not created in the same directory
3784 as the call then target_link_libraries() will add a suffix of the
3785 form ::@<directory-id> to each entry, where the ::@ is a separator
3786 and the <directory-id> is unspecified. This tells the generators
3787 that the named libraries must be looked up in the scope of the call‐
3788 er rather than in the scope in which the <target> was created.
3789 Valid directory ids are stripped on export by the install(EXPORT)
3790 and export() commands.
3791 LINK_OPTIONS
3793 List of options to use for the link step of shared library, module and
3794 executable targets. Targets that are static libraries need to use the
3795 STATIC_LIBRARY_OPTIONS target property.
3796 This property holds a semicolon-separated list of options specified so
3798 far for its target. Use the target_link_options() command to append
3799 more options.
3800 This property is initialized by the LINK_OPTIONS directory property
3802 when a target is created, and is used by the generators to set the
3803 options for the compiler.
3804 Contents of LINK_OPTIONS may use “generator expressions” with the syn‐
3806 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
3807 able expressions. See the cmake-buildsystem(7) manual for more on
3808 defining buildsystem properties.
3809 NOTE:
3811 This property must be used in preference to LINK_FLAGS property.
3812 LINK_SEARCH_END_STATIC
3814 End a link line such that static system libraries are used.
3815 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
3817 mine whether to use static or shared libraries for -lXXX options.
3818 CMake uses these options to set the link type for libraries whose full
3819 paths are not known or (in some cases) are in implicit link directories
3820 for the platform. By default CMake adds an option at the end of the
3821 library list (if necessary) to set the linker search type back to its
3822 starting type. This property switches the final linker search type to
3823 -Bstatic regardless of how it started.
3824 This property is initialized by the value of the variable
3826 CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created.
3827 See also LINK_SEARCH_START_STATIC.
3829 LINK_SEARCH_START_STATIC
3831 Assume the linker looks for static libraries by default.
3832 Some linkers support switches such as -Bstatic and -Bdynamic to deter‐
3834 mine whether to use static or shared libraries for -lXXX options.
3835 CMake uses these options to set the link type for libraries whose full
3836 paths are not known or (in some cases) are in implicit link directories
3837 for the platform. By default the linker search type is assumed to be
3838 -Bdynamic at the beginning of the library list. This property switches
3839 the assumption to -Bstatic. It is intended for use when linking an
3840 executable statically (e.g. with the GNU -static option).
3841 This property is initialized by the value of the variable
3843 CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is
3844 created.
3845 See also LINK_SEARCH_END_STATIC.
3847 LINK_WHAT_YOU_USE
3849 This is a boolean option that when set to TRUE will automatically run
3850 ldd -r -u on the target after it is linked. In addition, the linker
3851 flag -Wl,--no-as-needed will be passed to the target with the link com‐
3852 mand so that all libraries specified on the command line will be linked
3853 into the target. This will result in the link producing a list of
3854 libraries that provide no symbols used by this target but are being
3855 linked to it. This is only applicable to executable and shared library
3856 targets and will only work when ld and ldd accept the flags used.
3857 This property is initialized by the value of the
3859 CMAKE_LINK_WHAT_YOU_USE variable if it is set when a target is created.
3860 LOCATION_<CONFIG>
3862 Read-only property providing a target location on disk.
3863 A read-only property that indicates where a target’s main file is
3865 located on disk for the configuration <CONFIG>. The property is
3866 defined only for library and executable targets. An imported target
3867 may provide a set of configurations different from that of the import‐
3868 ing project. By default CMake looks for an exact-match but otherwise
3869 uses an arbitrary available configuration. Use the MAP_IMPORTED_CON‐
3870 FIG_<CONFIG> property to map imported configurations explicitly.
3871 Do not set properties that affect the location of a target after read‐
3873 ing this property. These include properties whose names match (RUN‐
3874 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?,
3875 (IMPLIB_)?(PREFIX|SUFFIX), or LINKER_LANGUAGE. Failure to follow this
3876 rule is not diagnosed and leaves the location of the target undefined.
3877 LOCATION
3879 Read-only location of a target on disk.
3880 For an imported target, this read-only property returns the value of
3882 the LOCATION_<CONFIG> property for an unspecified configuration <CON‐
3883 FIG> provided by the target.
3884 For a non-imported target, this property is provided for compatibility
3886 with CMake 2.4 and below. It was meant to get the location of an exe‐
3887 cutable target’s output file for use in add_custom_command(). The path
3888 may contain a build-system-specific portion that is replaced at build
3889 time with the configuration getting built (such as $(ConfigurationName)
3890 in VS). In CMake 2.6 and above add_custom_command() automatically rec‐
3891 ognizes a target name in its COMMAND and DEPENDS options and computes
3892 the target location. In CMake 2.8.4 and above add_custom_command()
3893 recognizes generator expressions to refer to target locations anywhere
3894 in the command. Therefore this property is not needed for creating
3895 custom commands.
3896 Do not set properties that affect the location of a target after read‐
3898 ing this property. These include properties whose names match (RUN‐
3899 TIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?,
3900 (IMPLIB_)?(PREFIX|SUFFIX), or “LINKER_LANGUAGE”. Failure to follow
3901 this rule is not diagnosed and leaves the location of the target unde‐
3902 fined.
3903 MACOSX_BUNDLE_INFO_PLIST
3905 Specify a custom Info.plist template for a macOS and iOS Application
3906 Bundle.
3907 An executable target with MACOSX_BUNDLE enabled will be built as an
3909 application bundle on macOS. By default its Info.plist file is created
3910 by configuring a template called MacOSXBundleInfo.plist.in located in
3911 the CMAKE_MODULE_PATH. This property specifies an alternative template
3912 file name which may be a full path.
3913 The following target properties may be set to specify content to be
3915 configured into the file:
3916 MACOSX_BUNDLE_BUNDLE_NAME
3918 Sets CFBundleName.
3919 MACOSX_BUNDLE_BUNDLE_VERSION
3921 Sets CFBundleVersion.
3922 MACOSX_BUNDLE_COPYRIGHT
3924 Sets NSHumanReadableCopyright.
3925 MACOSX_BUNDLE_GUI_IDENTIFIER
3927 Sets CFBundleIdentifier.
3928 MACOSX_BUNDLE_ICON_FILE
3930 Sets CFBundleIconFile.
3931 MACOSX_BUNDLE_INFO_STRING
3933 Sets CFBundleGetInfoString.
3934 MACOSX_BUNDLE_LONG_VERSION_STRING
3936 Sets CFBundleLongVersionString.
3937 MACOSX_BUNDLE_SHORT_VERSION_STRING
3939 Sets CFBundleShortVersionString.
3940 CMake variables of the same name may be set to affect all targets in a
3942 directory that do not have each specific property set. If a custom
3943 Info.plist is specified by this property it may of course hard-code all
3944 the settings instead of using the target properties.
3945 MACOSX_BUNDLE
3947 Build an executable as an Application Bundle on macOS or iOS.
3948 When this property is set to TRUE the executable when built on macOS or
3950 iOS will be created as an application bundle. This makes it a GUI exe‐
3951 cutable that can be launched from the Finder. See the MACOSX_BUN‐
3952 DLE_INFO_PLIST target property for information about creation of the
3953 Info.plist file for the application bundle. This property is initial‐
3954 ized by the value of the variable CMAKE_MACOSX_BUNDLE if it is set when
3955 a target is created.
3956 MACOSX_FRAMEWORK_INFO_PLIST
3958 Specify a custom Info.plist template for a macOS and iOS Framework.
3959 A library target with FRAMEWORK enabled will be built as a framework on
3961 macOS. By default its Info.plist file is created by configuring a tem‐
3962 plate called MacOSXFrameworkInfo.plist.in located in the CMAKE_MOD‐
3963 ULE_PATH. This property specifies an alternative template file name
3964 which may be a full path.
3965 The following target properties may be set to specify content to be
3967 configured into the file:
3968 MACOSX_FRAMEWORK_BUNDLE_VERSION
3970 Sets CFBundleVersion.
3971 MACOSX_FRAMEWORK_ICON_FILE
3973 Sets CFBundleIconFile.
3974 MACOSX_FRAMEWORK_IDENTIFIER
3976 Sets CFBundleIdentifier.
3977 MACOSX_FRAMEWORK_SHORT_VERSION_STRING
3979 Sets CFBundleShortVersionString.
3980 CMake variables of the same name may be set to affect all targets in a
3982 directory that do not have each specific property set. If a custom
3983 Info.plist is specified by this property it may of course hard-code all
3984 the settings instead of using the target properties.
3985 MACOSX_RPATH
3987 Whether this target on macOS or iOS is located at runtime using rpaths.
3988 When this property is set to TRUE, the directory portion of the
3990 install_name field of this shared library will be @rpath unless over‐
3991 ridden by INSTALL_NAME_DIR. This indicates the shared library is to be
3992 found at runtime using runtime paths (rpaths).
3993 This property is initialized by the value of the variable
3995 CMAKE_MACOSX_RPATH if it is set when a target is created.
3996 Runtime paths will also be embedded in binaries using this target and
3998 can be controlled by the INSTALL_RPATH target property on the target
3999 linking to this target.
4000 Policy CMP0042 was introduced to change the default value of
4002 MACOSX_RPATH to TRUE. This is because use of @rpath is a more flexible
4003 and powerful alternative to @executable_path and @loader_path.
4004 MANUALLY_ADDED_DEPENDENCIES
4006 Get manually added dependencies to other top-level targets.
4007 This read-only property can be used to query all dependencies that were
4009 added for this target with the add_dependencies() command.
4010 MAP_IMPORTED_CONFIG_<CONFIG>
4012 Map from project configuration to imported target’s configuration.
4013 Set this to the list of configurations of an imported target that may
4015 be used for the current project’s <CONFIG> configuration. Targets
4016 imported from another project may not provide the same set of configu‐
4017 ration names available in the current project. Setting this property
4018 tells CMake what imported configurations are suitable for use when
4019 building the <CONFIG> configuration. The first configuration in the
4020 list found to be provided by the imported target (i.e. via
4021 IMPORTED_LOCATION_<CONFIG> for the mapped-to <CONFIG>) is selected. As
4022 a special case, an empty list element refers to the configuration-less
4023 imported target location (i.e. IMPORTED_LOCATION).
4024 If this property is set and no matching configurations are available,
4026 then the imported target is considered to be not found. This property
4027 is ignored for non-imported targets.
4028 This property is initialized by the value of the
4030 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable if it is set when a target
4031 is created.
4032 Example
4034 For example creating imported C++ library foo:
4035 add_library(foo STATIC IMPORTED)
4037 Use foo_debug path for Debug build type:
4039 set_property(
4041 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG
4042 )
4043 set_target_properties(foo PROPERTIES
4045 IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
4046 IMPORTED_LOCATION_DEBUG "${foo_debug}"
4047 )
4048 Use foo_release path for Release build type:
4050 set_property(
4052 TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE
4053 )
4054 set_target_properties(foo PROPERTIES
4056 IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
4057 IMPORTED_LOCATION_RELEASE "${foo_release}"
4058 )
4059 Use Release version of library for MinSizeRel and RelWithDebInfo build
4061 types:
4062 set_target_properties(foo PROPERTIES
4064 MAP_IMPORTED_CONFIG_MINSIZEREL Release
4065 MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
4066 )
4067 MSVC_RUNTIME_LIBRARY
4069 Select the MSVC runtime library for use by compilers targeting the MSVC
4070 ABI.
4071 The allowed values are:
4073 MultiThreaded
4075 Compile with -MT or equivalent flag(s) to use a multi-threaded
4076 statically-linked runtime library.
4077 MultiThreadedDLL
4079 Compile with -MD or equivalent flag(s) to use a multi-threaded
4080 dynamically-linked runtime library.
4081 MultiThreadedDebug
4083 Compile with -MTd or equivalent flag(s) to use a multi-threaded
4084 statically-linked runtime library.
4085 MultiThreadedDebugDLL
4087 Compile with -MDd or equivalent flag(s) to use a multi-threaded
4088 dynamically-linked runtime library.
4089 The value is ignored on non-MSVC compilers but an unsupported value
4091 will be rejected as an error when using a compiler targeting the MSVC
4092 ABI.
4093 The value may also be the empty string ("") in which case no runtime
4095 library selection flag will be added explicitly by CMake. Note that
4096 with Visual Studio Generators the native build system may choose to add
4097 its own default runtime library selection flag.
4098 Use generator expressions to support per-configuration specification.
4100 For example, the code:
4101 add_executable(foo foo.c)
4103 set_property(TARGET foo PROPERTY
4104 MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
4105 selects for the target foo a multi-threaded statically-linked runtime
4107 library with or without debug information depending on the configura‐
4108 tion.
4109 If this property is not set then CMake uses the default value Multi‐
4111 Threaded$<$<CONFIG:Debug>:Debug>DLL to select a MSVC runtime library.
4112 NOTE:
4114 This property has effect only when policy CMP0091 is set to NEW
4115 prior to the first project() or enable_language() command that
4116 enables a language using a compiler targeting the MSVC ABI.
4117 NAME
4119 Logical name for the target.
4120 Read-only logical name for the target as used by CMake.
4122 NO_SONAME
4124 Whether to set soname when linking a shared library.
4125 Enable this boolean property if a generated SHARED library should not
4127 have soname set. Default is to set soname on all shared libraries as
4128 long as the platform supports it. Generally, use this property only
4129 for leaf private libraries or plugins. If you use it on normal shared
4130 libraries which other targets link against, on some platforms a linker
4131 will insert a full path to the library (as specified at link time) into
4132 the dynamic section of the dependent binary. Therefore, once
4133 installed, dynamic loader may eventually fail to locate the library for
4134 the binary.
4135 NO_SYSTEM_FROM_IMPORTED
4137 Do not treat include directories from the interfaces of consumed
4138 imported targets as SYSTEM.
4139 The contents of the INTERFACE_INCLUDE_DIRECTORIES target property of
4141 imported targets are treated as SYSTEM includes by default. If this
4142 property is enabled on a target, compilation of sources in that target
4143 will not treat the contents of the INTERFACE_INCLUDE_DIRECTORIES of
4144 consumed imported targets as system includes.
4145 This property is initialized by the value of the CMAKE_NO_SYS‐
4147 TEM_FROM_IMPORTED variable if it is set when a target is created.
4148 OBJC_EXTENSIONS
4150 Boolean specifying whether compiler specific extensions are requested.
4151 This property specifies whether compiler specific extensions should be
4153 used. For some compilers, this results in adding a flag such as
4154 -std=gnu11 instead of -std=c11 to the compile line. This property is
4155 ON by default. The basic OBJC standard level is controlled by the
4156 OBJC_STANDARD target property.
4157 If the property is not set, and the project has set the C_EXTENSIONS,
4159 the value of C_EXTENSIONS is set for OBJC_EXTENSIONS.
4160 See the cmake-compile-features(7) manual for information on compile
4162 features and a list of supported compilers.
4163 This property is initialized by the value of the CMAKE_OBJC_EXTENSIONS
4165 variable if it is set when a target is created.
4166 OBJC_STANDARD
4168 The OBJC standard whose features are requested to build this target.
4169 This property specifies the OBJC standard whose features are requested
4171 to build this target. For some compilers, this results in adding a
4172 flag such as -std=gnu11 to the compile line.
4173 Supported values are 90, 99 and 11.
4175 If the value requested does not result in a compile flag being added
4177 for the compiler in use, a previous standard flag will be added
4178 instead. This means that using:
4179 set_property(TARGET tgt PROPERTY OBJC_STANDARD 11)
4181 with a compiler which does not support -std=gnu11 or an equivalent flag
4183 will not result in an error or warning, but will instead add the
4184 -std=gnu99 or -std=gnu90 flag if supported. This “decay” behavior may
4185 be controlled with the OBJC_STANDARD_REQUIRED target property. Addi‐
4186 tionally, the OBJC_EXTENSIONS target property may be used to control
4187 whether compiler-specific extensions are enabled on a per-target basis.
4188 If the property is not set, and the project has set the C_STANDARD, the
4190 value of C_STANDARD is set for OBJC_STANDARD.
4191 See the cmake-compile-features(7) manual for information on compile
4193 features and a list of supported compilers.
4194 This property is initialized by the value of the CMAKE_OBJC_STANDARD
4196 variable if it is set when a target is created.
4197 OBJC_STANDARD_REQUIRED
4199 Boolean describing whether the value of OBJC_STANDARD is a requirement.
4200 If this property is set to ON, then the value of the OBJC_STANDARD tar‐
4202 get property is treated as a requirement. If this property is OFF or
4203 unset, the OBJC_STANDARD target property is treated as optional and may
4204 “decay” to a previous standard if the requested is not available.
4205 If the property is not set, and the project has set the C_STAN‐
4207 DARD_REQUIRED, the value of C_STANDARD_REQUIRED is set for
4208 OBJC_STANDARD_REQUIRED.
4209 See the cmake-compile-features(7) manual for information on compile
4211 features and a list of supported compilers.
4212 This property is initialized by the value of the CMAKE_OBJC_STAN‐
4214 DARD_REQUIRED variable if it is set when a target is created.
4215 OBJCXX_EXTENSIONS
4217 Boolean specifying whether compiler specific extensions are requested.
4218 This property specifies whether compiler specific extensions should be
4220 used. For some compilers, this results in adding a flag such as
4221 -std=gnu++11 instead of -std=c++11 to the compile line. This property
4222 is ON by default. The basic ObjC++ standard level is controlled by the
4223 OBJCXX_STANDARD target property.
4224 See the cmake-compile-features(7) manual for information on compile
4226 features and a list of supported compilers.
4227 If the property is not set, and the project has set the CXX_EXTENSIONS,
4229 the value of CXX_EXTENSIONS is set for OBJCXX_EXTENSIONS.
4230 This property is initialized by the value of the CMAKE_OBJCXX_EXTEN‐
4232 SIONS variable if it is set when a target is created.
4233 OBJCXX_STANDARD
4235 The ObjC++ standard whose features are requested to build this target.
4236 This property specifies the ObjC++ standard whose features are
4238 requested to build this target. For some compilers, this results in
4239 adding a flag such as -std=gnu++11 to the compile line.
4240 Supported values are 98, 11, 14, 17, and 20.
4242 If the value requested does not result in a compile flag being added
4244 for the compiler in use, a previous standard flag will be added
4245 instead. This means that using:
4246 set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11)
4248 with a compiler which does not support -std=gnu++11 or an equivalent
4250 flag will not result in an error or warning, but will instead add the
4251 -std=gnu++98 flag if supported. This “decay” behavior may be con‐
4252 trolled with the OBJCXX_STANDARD_REQUIRED target property. Addition‐
4253 ally, the OBJCXX_EXTENSIONS target property may be used to control
4254 whether compiler-specific extensions are enabled on a per-target basis.
4255 If the property is not set, and the project has set the CXX_STANDARD,
4257 the value of CXX_STANDARD is set for OBJCXX_STANDARD.
4258 See the cmake-compile-features(7) manual for information on compile
4260 features and a list of supported compilers.
4261 This property is initialized by the value of the CMAKE_OBJCXX_STANDARD
4263 variable if it is set when a target is created.
4264 OBJCXX_STANDARD_REQUIRED
4266 Boolean describing whether the value of OBJCXX_STANDARD is a require‐
4267 ment.
4268 If this property is set to ON, then the value of the OBJCXX_STANDARD
4270 target property is treated as a requirement. If this property is OFF
4271 or unset, the OBJCXX_STANDARD target property is treated as optional
4272 and may “decay” to a previous standard if the requested is not avail‐
4273 able.
4274 If the property is not set, and the project has set the CXX_STAN‐
4276 DARD_REQUIRED, the value of CXX_STANDARD_REQUIRED is set for
4277 OBJCXX_STANDARD_REQUIRED.
4278 See the cmake-compile-features(7) manual for information on compile
4280 features and a list of supported compilers.
4281 This property is initialized by the value of the CMAKE_OBJCXX_STAN‐
4283 DARD_REQUIRED variable if it is set when a target is created.
4284 OSX_ARCHITECTURES_<CONFIG>
4286 Per-configuration macOS and iOS binary architectures for a target.
4287 This property is the configuration-specific version of OSX_ARCHITEC‐
4289 TURES.
4290 OSX_ARCHITECTURES
4292 Target specific architectures for macOS.
4293 The OSX_ARCHITECTURES property sets the target binary architecture for
4295 targets on macOS (-arch). This property is initialized by the value of
4296 the variable CMAKE_OSX_ARCHITECTURES if it is set when a target is cre‐
4297 ated. Use OSX_ARCHITECTURES_<CONFIG> to set the binary architectures
4298 on a per-configuration basis, where <CONFIG> is an upper-case name
4299 (e.g. OSX_ARCHITECTURES_DEBUG).
4300 OUTPUT_NAME_<CONFIG>
4302 Per-configuration target file base name.
4303 This is the configuration-specific version of the OUTPUT_NAME target
4305 property.
4306 OUTPUT_NAME
4308 Output name for target files.
4309 This sets the base name for output files created for an executable or
4311 library target. If not set, the logical target name is used by default
4312 during generation. The value is not set by default during configura‐
4313 tion.
4314 Contents of OUTPUT_NAME and the variants listed below may use generator
4316 expressions.
4317 See also the variants:
4319 · OUTPUT_NAME_<CONFIG>
4321 · ARCHIVE_OUTPUT_NAME_<CONFIG>
4323 · ARCHIVE_OUTPUT_NAME
4325 · LIBRARY_OUTPUT_NAME_<CONFIG>
4327 · LIBRARY_OUTPUT_NAME
4329 · RUNTIME_OUTPUT_NAME_<CONFIG>
4331 · RUNTIME_OUTPUT_NAME
4333 PDB_NAME_<CONFIG>
4335 Per-configuration output name for the MS debug symbol .pdb file gener‐
4336 ated by the linker for an executable or shared library target.
4337 This is the configuration-specific version of PDB_NAME.
4339 NOTE:
4341 This property does not apply to STATIC library targets because no
4342 linker is invoked to produce them so they have no linker-generated
4343 .pdb file containing debug symbols.
4344 The linker-generated program database files are specified by the
4346 /pdb linker flag and are not the same as compiler-generated program
4347 database files specified by the /Fd compiler flag. Use the COM‐
4348 PILE_PDB_NAME_<CONFIG> property to specify the latter.
4349 PDB_NAME
4351 Output name for the MS debug symbol .pdb file generated by the linker
4352 for an executable or shared library target.
4353 This property specifies the base name for the debug symbols file. If
4355 not set, the OUTPUT_NAME target property value or logical target name
4356 is used by default.
4357 NOTE:
4359 This property does not apply to STATIC library targets because no
4360 linker is invoked to produce them so they have no linker-generated
4361 .pdb file containing debug symbols.
4362 The linker-generated program database files are specified by the
4364 /pdb linker flag and are not the same as compiler-generated program
4365 database files specified by the /Fd compiler flag. Use the COM‐
4366 PILE_PDB_NAME property to specify the latter.
4367 PDB_OUTPUT_DIRECTORY_<CONFIG>
4369 Per-configuration output directory for the MS debug symbol .pdb file
4370 generated by the linker for an executable or shared library target.
4371 This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
4373 multi-configuration generators (Visual Studio Generators, Xcode) do NOT
4374 append a per-configuration subdirectory to the specified directory.
4375 This property is initialized by the value of the CMAKE_PDB_OUT‐
4376 PUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.
4377 Contents of PDB_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
4379 sions.
4380 NOTE:
4382 This property does not apply to STATIC library targets because no
4383 linker is invoked to produce them so they have no linker-generated
4384 .pdb file containing debug symbols.
4385 The linker-generated program database files are specified by the
4387 /pdb linker flag and are not the same as compiler-generated program
4388 database files specified by the /Fd compiler flag. Use the COM‐
4389 PILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the latter.
4390 PDB_OUTPUT_DIRECTORY
4392 Output directory for the MS debug symbols .pdb file generated by the
4393 linker for an executable or shared library target.
4394 This property specifies the directory into which the MS debug symbols
4396 will be placed by the linker. The property value may use generator
4397 expressions. Multi-configuration generators append a per-configuration
4398 subdirectory to the specified directory unless a generator expression
4399 is used.
4400 This property is initialized by the value of the CMAKE_PDB_OUT‐
4402 PUT_DIRECTORY variable if it is set when a target is created.
4403 NOTE:
4405 This property does not apply to STATIC library targets because no
4406 linker is invoked to produce them so they have no linker-generated
4407 .pdb file containing debug symbols.
4408 The linker-generated program database files are specified by the
4410 /pdb linker flag and are not the same as compiler-generated program
4411 database files specified by the /Fd compiler flag. Use the COM‐
4412 PILE_PDB_OUTPUT_DIRECTORY property to specify the latter.
4413 POSITION_INDEPENDENT_CODE
4415 Whether to create a position-independent target
4416 The POSITION_INDEPENDENT_CODE property determines whether position
4418 independent executables or shared libraries will be created. This
4419 property is True by default for SHARED and MODULE library targets and
4420 False otherwise. This property is initialized by the value of the
4421 CMAKE_POSITION_INDEPENDENT_CODE variable if it is set when a target is
4422 created.
4423 NOTE:
4425 For executable targets, the link step is controlled by the CMP0083
4426 policy and the CheckPIESupported module.
4427 PRECOMPILE_HEADERS
4429 List of header files to precompile.
4430 This property holds a semicolon-separated list of header files to pre‐
4432 compile specified so far for its target. Use the target_precom‐
4433 pile_headers() command to append more header files.
4434 This property supports generator expressions.
4436 PRECOMPILE_HEADERS_REUSE_FROM
4438 Target from which to reuse the precompiled headers build artifact.
4439 See the second signature of target_precompile_headers() command for
4441 more detailed information.
4442 PREFIX
4444 What comes before the library name.
4445 A target property that can be set to override the prefix (such as lib)
4447 on a library name.
4448 PRIVATE_HEADER
4450 Specify private header files in a FRAMEWORK shared library target.
4451 Shared library targets marked with the FRAMEWORK property generate
4453 frameworks on macOS, iOS and normal shared libraries on other plat‐
4454 forms. This property may be set to a list of header files to be placed
4455 in the PrivateHeaders directory inside the framework folder. On
4456 non-Apple platforms these headers may be installed using the PRI‐
4457 VATE_HEADER option to the install(TARGETS) command.
4458 PROJECT_LABEL
4460 Change the name of a target in an IDE.
4461 Can be used to change the name of the target in an IDE like Visual Stu‐
4463 dio.
4464 PUBLIC_HEADER
4466 Specify public header files in a FRAMEWORK shared library target.
4467 Shared library targets marked with the FRAMEWORK property generate
4469 frameworks on macOS, iOS and normal shared libraries on other plat‐
4470 forms. This property may be set to a list of header files to be placed
4471 in the Headers directory inside the framework folder. On non-Apple
4472 platforms these headers may be installed using the PUBLIC_HEADER option
4473 to the install(TARGETS) command.
4474 RESOURCE
4476 Specify resource files in a FRAMEWORK or BUNDLE.
4477 Target marked with the FRAMEWORK or BUNDLE property generate framework
4479 or application bundle (both macOS and iOS is supported) or normal
4480 shared libraries on other platforms. This property may be set to a
4481 list of files to be placed in the corresponding directory (eg.
4482 Resources directory for macOS) inside the bundle. On non-Apple plat‐
4483 forms these files may be installed using the RESOURCE option to the
4484 install(TARGETS) command.
4485 Following example of Application Bundle:
4487 add_executable(ExecutableTarget
4489 addDemo.c
4490 resourcefile.txt
4491 appresourcedir/appres.txt)
4492 target_link_libraries(ExecutableTarget heymath mul)
4494 set(RESOURCE_FILES
4496 resourcefile.txt
4497 appresourcedir/appres.txt)
4498 set_target_properties(ExecutableTarget PROPERTIES
4500 MACOSX_BUNDLE TRUE
4501 MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget
4502 RESOURCE "${RESOURCE_FILES}")
4503 will produce flat structure for iOS systems:
4505 ExecutableTarget.app
4507 appres.txt
4508 ExecutableTarget
4509 Info.plist
4510 resourcefile.txt
4511 For macOS systems it will produce following directory structure:
4513 ExecutableTarget.app/
4515 Contents
4516 Info.plist
4517 MacOS
4518 ExecutableTarget
4519 Resources
4520 appres.txt
4521 resourcefile.txt
4522 For Linux, such CMake script produce following files:
4524 ExecutableTarget
4526 Resources
4527 appres.txt
4528 resourcefile.txt
4529 RULE_LAUNCH_COMPILE
4531 Specify a launcher for compile rules.
4532 See the global property of the same name for details. This overrides
4534 the global and directory property for a target.
4535 RULE_LAUNCH_CUSTOM
4537 Specify a launcher for custom rules.
4538 See the global property of the same name for details. This overrides
4540 the global and directory property for a target.
4541 RULE_LAUNCH_LINK
4543 Specify a launcher for link rules.
4544 See the global property of the same name for details. This overrides
4546 the global and directory property for a target.
4547 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
4549 Per-configuration output directory for RUNTIME target files.
4550 This is a per-configuration version of the RUNTIME_OUTPUT_DIRECTORY
4552 target property, but multi-configuration generators (Visual Studio Gen‐
4553 erators, Xcode) do NOT append a per-configuration subdirectory to the
4554 specified directory. This property is initialized by the value of the
4555 CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a
4556 target is created.
4557 Contents of RUNTIME_OUTPUT_DIRECTORY_<CONFIG> may use generator expres‐
4559 sions.
4560 RUNTIME_OUTPUT_DIRECTORY
4562 Output directory in which to build RUNTIME target files.
4563 This property specifies the directory into which runtime target files
4565 should be built. The property value may use generator expressions.
4566 Multi-configuration generators (VS, Xcode) append a per-configuration
4567 subdirectory to the specified directory unless a generator expression
4568 is used.
4569 This property is initialized by the value of the variable CMAKE_RUN‐
4571 TIME_OUTPUT_DIRECTORY if it is set when a target is created.
4572 See also the RUNTIME_OUTPUT_DIRECTORY_<CONFIG> target property.
4574 RUNTIME_OUTPUT_NAME_<CONFIG>
4576 Per-configuration output name for RUNTIME target files.
4577 This is the configuration-specific version of the RUNTIME_OUTPUT_NAME
4579 target property.
4580 RUNTIME_OUTPUT_NAME
4582 Output name for RUNTIME target files.
4583 This property specifies the base name for runtime target files. It
4585 overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
4586 See also the RUNTIME_OUTPUT_NAME_<CONFIG> target property.
4588 SKIP_BUILD_RPATH
4590 Should rpaths be used for the build tree.
4591 SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic gen‐
4593 eration of an rpath allowing the target to run from the build tree.
4594 This property is initialized by the value of the variable
4595 CMAKE_SKIP_BUILD_RPATH if it is set when a target is created.
4596 SOURCE_DIR
4598 This read-only property reports the value of the CMAKE_CUR‐
4599 RENT_SOURCE_DIR variable in the directory in which the target was
4600 defined.
4601 SOURCES
4603 Source names specified for a target.
4604 List of sources specified for a target.
4606 SOVERSION
4608 What version number is this target.
4609 For shared libraries VERSION and SOVERSION can be used to specify the
4611 build version and API version respectively. When building or
4612 installing appropriate symlinks are created if the platform supports
4613 symlinks and the linker supports so-names. If only one of both is
4614 specified the missing is assumed to have the same version number.
4615 SOVERSION is ignored if NO_SONAME property is set.
4616 Windows Versions
4618 For shared libraries and executables on Windows the VERSION attribute
4619 is parsed to extract a <major>.<minor> version number. These numbers
4620 are used as the image version of the binary.
4621 Mach-O Versions
4623 For shared libraries and executables on Mach-O systems (e.g. macOS,
4624 iOS), the SOVERSION property corresponds to compatibility version and
4625 VERSION to current version. See the FRAMEWORK target property for an
4626 example. Versions of Mach-O binaries may be checked with the otool -L
4627 <binary> command.
4628 STATIC_LIBRARY_FLAGS_<CONFIG>
4630 Per-configuration archiver (or MSVC librarian) flags for a static
4631 library target.
4632 This is the configuration-specific version of STATIC_LIBRARY_FLAGS.
4634 NOTE:
4636 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
4637 erty.
4638 STATIC_LIBRARY_FLAGS
4640 Archiver (or MSVC librarian) flags for a static library target. Tar‐
4641 gets that are shared libraries, modules, or executables need to use the
4642 LINK_OPTIONS or LINK_FLAGS target properties.
4643 The STATIC_LIBRARY_FLAGS property, managed as a string, can be used to
4645 add extra flags to the link step of a static library target.
4646 STATIC_LIBRARY_FLAGS_<CONFIG> will add to the configuration <CONFIG>,
4647 for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO, …
4648 NOTE:
4650 This property has been superseded by STATIC_LIBRARY_OPTIONS prop‐
4651 erty.
4652 STATIC_LIBRARY_OPTIONS
4654 Archiver (or MSVC librarian) flags for a static library target. Tar‐
4655 gets that are shared libraries, modules, or executables need to use the
4656 LINK_OPTIONS target property.
4657 This property holds a semicolon-separated list of options specified so
4659 far for its target. Use set_target_properties() or set_property() com‐
4660 mands to set its content.
4661 Contents of STATIC_LIBRARY_OPTIONS may use “generator expressions” with
4663 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4664 available expressions. See the cmake-buildsystem(7) manual for more on
4665 defining buildsystem properties.
4666 NOTE:
4668 This property must be used in preference to STATIC_LIBRARY_FLAGS
4669 property.
4670 SUFFIX
4672 What comes after the target name.
4673 A target property that can be set to override the suffix (such as .so
4675 or .exe) on the name of a library, module or executable.
4676 Swift_DEPENDENCIES_FILE
4678 This property sets the path for the Swift dependency file (swiftdep)
4679 for the target. If one is not specified, it will default to <TAR‐
4680 GET>.swiftdeps.
4681 Swift_LANGUAGE_VERSION
4683 This property sets the language version for the Swift sources in the
4684 target. If one is not specified, it will default to <CMAKE_Swift_LAN‐
4685 GUAGE_VERSION> if specified, otherwise it is the latest version sup‐
4686 ported by the compiler.
4687 Swift_MODULE_DIRECTORY
4689 Specify output directory for Swift modules provided by the target.
4690 If the target contains Swift source files, this specifies the directory
4692 in which the modules will be placed. When this property is not set,
4693 the modules will be placed in the build directory corresponding to the
4694 target’s source directory. If the variable CMAKE_Swift_MODULE_DIREC‐
4695 TORY is set when a target is created its value is used to initialise
4696 this property.
4697 Swift_MODULE_NAME
4699 This property specifies the name of the Swift module. It is defaulted
4700 to the name of the target.
4701 TYPE
4703 The type of the target.
4704 This read-only property can be used to test the type of the given tar‐
4706 get. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, SHARED_LIBRARY,
4707 OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal
4708 target types.
4709 UNITY_BUILD
4711 When this property is set to true, the target source files will be com‐
4712 bined into batches for faster compilation. This is done by creating a
4713 (set of) unity sources which #include the original sources, then com‐
4714 piling these unity sources instead of the originals. This is known as
4715 a Unity or Jumbo build. The UNITY_BUILD_BATCH_SIZE property controls
4716 the upper limit on how many sources can be combined per unity source
4717 file.
4718 Unity builds are not currently supported for all languages. CMake ver‐
4720 sion 3.16.1 supports combining C and CXX source files. For targets
4721 that mix source files from more than one language, CMake will separate
4722 the languages such that each generated unity source file only contains
4723 sources for a single language.
4724 This property is initialized by the value of the CMAKE_UNITY_BUILD
4726 variable when a target is created.
4727 NOTE:
4729 Projects should not directly set the UNITY_BUILD property or its
4730 associated CMAKE_UNITY_BUILD variable to true. Depending on the
4731 capabilities of the build machine and compiler used, it might or
4732 might not be appropriate to enable unity builds. Therefore, this
4733 feature should be under developer control, which would normally be
4734 through the developer choosing whether or not to set the
4735 CMAKE_UNITY_BUILD variable on the cmake(1) command line or some
4736 other equivalent method. However, it IS recommended to set the
4737 UNITY_BUILD target property to false if it is known that enabling
4738 unity builds for the target can lead to problems.
4739 ODR (One definition rule) errors
4741 When multiple source files are included into one source file, as is
4742 done for unity builds, it can potentially lead to ODR errors. CMake
4743 provides a number of measures to help address such problems:
4744 · Any source file that has a non-empty COMPILE_OPTIONS, COMPILE_DEFINI‐
4746 TIONS, COMPILE_FLAGS, or INCLUDE_DIRECTORIES source property will not
4747 be combined into a unity source.
4748 · Projects can prevent an individual source file from being combined
4750 into a unity source by setting its SKIP_UNITY_BUILD_INCLUSION source
4751 property to true. This can be a more effective way to prevent prob‐
4752 lems with specific files than disabling unity builds for an entire
4753 target.
4754 · The UNITY_BUILD_CODE_BEFORE_INCLUDE and
4756 UNITY_BUILD_CODE_AFTER_INCLUDE target properties can be used to
4757 inject code into the unity source files before and after every
4758 #include statement.
4759 · The order of source files added to the target via commands like
4761 add_library(), add_executable() or target_sources() will be preserved
4762 in the generated unity source files. This can be used to manually
4763 enforce a specific grouping based on the UNITY_BUILD_BATCH_SIZE tar‐
4764 get property.
4765 UNITY_BUILD_BATCH_SIZE
4767 Specifies the maximum number of source files that can be combined into
4768 any one unity source file when unity builds are enabled by the
4769 UNITY_BUILD target property. The original source files will be dis‐
4770 tributed across as many unity source files as necessary to honor this
4771 limit.
4772 The initial value for this property is taken from the
4774 CMAKE_UNITY_BUILD_BATCH_SIZE variable when the target is created. If
4775 that variable has not been set, the initial value will be 8.
4776 The batch size needs to be selected carefully. If set too high, the
4778 size of the combined source files could result in the compiler using
4779 excessive memory or hitting other similar limits. In extreme cases,
4780 this can even result in build failure. On the other hand, if the batch
4781 size is too low, there will be little gain in build performance.
4782 Although strongly discouraged, the batch size may be set to a value of
4784 0 to combine all the sources for the target into a single unity file,
4785 regardless of how many sources are involved. This runs the risk of
4786 creating an excessively large unity source file and negatively impact‐
4787 ing the build performance, so a value of 0 is not generally recom‐
4788 mended.
4789 UNITY_BUILD_CODE_AFTER_INCLUDE
4791 Code snippet which is included verbatim by the UNITY_BUILD feature just
4792 after every #include statement in the generated unity source files.
4793 For example:
4794 set(after [[
4796 #if defined(NOMINMAX)
4797 #undef NOMINMAX
4798 #endif
4799 ]])
4800 set_target_properties(myTarget PROPERTIES
4801 UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
4802 )
4803 See also UNITY_BUILD_CODE_BEFORE_INCLUDE.
4805 UNITY_BUILD_CODE_BEFORE_INCLUDE
4807 Code snippet which is included verbatim by the UNITY_BUILD feature just
4808 before every #include statement in the generated unity source files.
4809 For example:
4810 set(before [[
4812 #if !defined(NOMINMAX)
4813 #define NOMINMAX
4814 #endif
4815 ]])
4816 set_target_properties(myTarget PROPERTIES
4817 UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
4818 )
4819 See also UNITY_BUILD_CODE_AFTER_INCLUDE.
4821 VERSION
4823 What version number is this target.
4824 For shared libraries VERSION and SOVERSION can be used to specify the
4826 build version and API version respectively. When building or
4827 installing appropriate symlinks are created if the platform supports
4828 symlinks and the linker supports so-names. If only one of both is
4829 specified the missing is assumed to have the same version number. For
4830 executables VERSION can be used to specify the build version. When
4831 building or installing appropriate symlinks are created if the platform
4832 supports symlinks.
4833 Windows Versions
4835 For shared libraries and executables on Windows the VERSION attribute
4836 is parsed to extract a <major>.<minor> version number. These numbers
4837 are used as the image version of the binary.
4838 Mach-O Versions
4840 For shared libraries and executables on Mach-O systems (e.g. macOS,
4841 iOS), the SOVERSION property correspond to compatibility version and
4842 VERSION to current version. See the FRAMEWORK target property for an
4843 example. Versions of Mach-O binaries may be checked with the otool -L
4844 <binary> command.
4845 VISIBILITY_INLINES_HIDDEN
4847 Whether to add a compile flag to hide symbols of inline functions
4848 The VISIBILITY_INLINES_HIDDEN property determines whether a flag for
4850 hiding symbols for inline functions, such as -fvisibility-inlines-hid‐
4851 den, should be used when invoking the compiler. This property affects
4852 compilation in sources of all types of targets (subject to policy
4853 CMP0063).
4854 This property is initialized by the value of the CMAKE_VISIBIL‐
4856 ITY_INLINES_HIDDEN variable if it is set when a target is created.
4857 VS_CONFIGURATION_TYPE
4859 Visual Studio project configuration type.
4860 Sets the ConfigurationType attribute for a generated Visual Studio
4862 project. The property value may use generator expressions. If this
4863 property is set, it overrides the default setting that is based on the
4864 target type (e.g. StaticLibrary, Application, …).
4865 Supported on Visual Studio Generators for VS 2010 and higher.
4867 VS_DEBUGGER_COMMAND
4869 Sets the local debugger command for Visual Studio C++ targets. The
4870 property value may use generator expressions. This is defined in
4871 <LocalDebuggerCommand> in the Visual Studio project file.
4872 This property only works for Visual Studio 2010 and above; it is
4874 ignored on other generators.
4875 VS_DEBUGGER_COMMAND_ARGUMENTS
4877 Sets the local debugger command line arguments for Visual Studio C++
4878 targets. The property value may use generator expressions. This is
4879 defined in <LocalDebuggerCommandArguments> in the Visual Studio project
4880 file.
4881 This property only works for Visual Studio 2010 and above; it is
4883 ignored on other generators.
4884 VS_DEBUGGER_ENVIRONMENT
4886 Sets the local debugger environment for Visual Studio C++ targets. The
4887 property value may use generator expressions. This is defined in
4888 <LocalDebuggerEnvironment> in the Visual Studio project file.
4889 This property only works for Visual Studio 2010 and above; it is
4891 ignored on other generators.
4892 VS_DEBUGGER_WORKING_DIRECTORY
4894 Sets the local debugger working directory for Visual Studio C++ tar‐
4895 gets. The property value may use generator expressions. This is
4896 defined in <LocalDebuggerWorkingDirectory> in the Visual Studio project
4897 file.
4898 This property only works for Visual Studio 2010 and above; it is
4900 ignored on other generators.
4901 VS_DESKTOP_EXTENSIONS_VERSION
4903 Visual Studio Windows 10 Desktop Extensions Version
4904 Specifies the version of the Desktop Extensions that should be included
4906 in the target. For example 10.0.10240.0. If the value is not specified,
4907 the Desktop Extensions will not be included. To use the same version of
4908 the extensions as the Windows 10 SDK that is being used, you can use
4909 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
4910 VS_DOTNET_REFERENCE_<refname>
4912 Visual Studio managed project .NET reference with name <refname> and
4913 hint path.
4914 Adds one .NET reference to generated Visual Studio project. The refer‐
4916 ence will have the name <refname> and will point to the assembly given
4917 as value of the property.
4918 See also VS_DOTNET_REFERENCES and VS_DOTNET_REFERENCES_COPY_LOCAL
4920 VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>
4922 Defines an XML property <tagname> for a .NET reference <refname>.
4923 Reference properties can be set for .NET references which are defined
4925 by the target properties VS_DOTNET_REFERENCES, VS_DOTNET_REFER‐
4926 ENCE_<refname> and also for project references to other C# targets
4927 which are established by target_link_libraries().
4928 This property is only applicable to C# targets and Visual Studio gener‐
4930 ators 2010 and later.
4931 VS_DOTNET_REFERENCES
4933 Visual Studio managed project .NET references
4934 Adds one or more semicolon-delimited .NET references to a generated
4936 Visual Studio project. For example, “System;System.Windows.Forms”.
4937 VS_DOTNET_REFERENCES_COPY_LOCAL
4939 Sets the Copy Local property for all .NET hint references in the target
4940 Boolean property to enable/disable copying of .NET hint references to
4942 output directory. The default is ON.
4943 VS_DOTNET_TARGET_FRAMEWORK_VERSION
4945 Specify the .NET target framework version.
4946 Used to specify the .NET target framework version for C++/CLI. For
4948 example, “v4.5”.
4949 This property is deprecated and should not be used anymore. Use DOT‐
4951 NET_TARGET_FRAMEWORK_VERSION instead.
4952 VS_DPI_AWARE
4954 Set the Manifest Tool -> Input and Output -> DPI Awareness in the Vis‐
4955 ual Studio target project properties.
4956 Valid values are PerMonitor, ON, or OFF.
4958 For example:
4960 add_executable(myproject myproject.cpp)
4962 set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor")
4963 VS_GLOBAL_KEYWORD
4965 Visual Studio project keyword for VS 10 (2010) and newer.
4966 Sets the “keyword” attribute for a generated Visual Studio project.
4968 Defaults to “Win32Proj”. You may wish to override this value with
4969 “ManagedCProj”, for example, in a Visual Studio managed C++ unit test
4970 project.
4971 Use the VS_KEYWORD target property to set the keyword for Visual Studio
4973 9 (2008) and older.
4974 VS_GLOBAL_PROJECT_TYPES
4976 Visual Studio project type(s).
4977 Can be set to one or more UUIDs recognized by Visual Studio to indicate
4979 the type of project. This value is copied verbatim into the generated
4980 project file. Example for a managed C++ unit testing project:
4981 {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}
4983 UUIDs are semicolon-delimited.
4985 VS_GLOBAL_ROOTNAMESPACE
4987 Visual Studio project root namespace.
4988 Sets the “RootNamespace” attribute for a generated Visual Studio
4990 project. The attribute will be generated only if this is set.
4991 VS_GLOBAL_<variable>
4993 Visual Studio project-specific global variable.
4994 Tell the Visual Studio generator to set the global variable ‘<vari‐
4996 able>’ to a given value in the generated Visual Studio project.
4997 Ignored on other generators. Qt integration works better if
4998 VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For
4999 example, “4.7.3”
5000 VS_IOT_EXTENSIONS_VERSION
5002 Visual Studio Windows 10 IoT Extensions Version
5003 Specifies the version of the IoT Extensions that should be included in
5005 the target. For example 10.0.10240.0. If the value is not specified,
5006 the IoT Extensions will not be included. To use the same version of the
5007 extensions as the Windows 10 SDK that is being used, you can use the
5008 CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
5009 VS_IOT_STARTUP_TASK
5011 Visual Studio Windows 10 IoT Continuous Background Task
5012 Specifies that the target should be compiled as a Continuous Background
5014 Task library.
5015 VS_JUST_MY_CODE_DEBUGGING
5017 Enable Just My Code with Visual Studio debugger.
5018 Supported on Visual Studio Generators for VS 2010 and higher, Makefile
5020 Generators and the Ninja generators.
5021 This property is initialized by the CMAKE_VS_JUST_MY_CODE_DEBUGGING
5023 variable if it is set when a target is created.
5024 VS_KEYWORD
5026 Visual Studio project keyword for VS 9 (2008) and older.
5027 Can be set to change the visual studio keyword, for example Qt integra‐
5029 tion works better if this is set to Qt4VSv1.0.
5030 Use the VS_GLOBAL_KEYWORD target property to set the keyword for Visual
5032 Studio 10 (2010) and newer.
5033 VS_MOBILE_EXTENSIONS_VERSION
5035 Visual Studio Windows 10 Mobile Extensions Version
5036 Specifies the version of the Mobile Extensions that should be included
5038 in the target. For example 10.0.10240.0. If the value is not specified,
5039 the Mobile Extensions will not be included. To use the same version of
5040 the extensions as the Windows 10 SDK that is being used, you can use
5041 the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.
5042 VS_NO_SOLUTION_DEPLOY
5044 Specify that the target should not be marked for deployment to a Win‐
5045 dows CE or Windows Phone device in the generated Visual Studio solu‐
5046 tion.
5047 Be default, all EXE and shared library (DLL) targets are marked to
5049 deploy to the target device in the generated Visual Studio solution.
5050 Generator expressions are supported.
5052 There are reasons one might want to exclude a target / generated
5054 project from deployment:
5055 · The library or executable may not be necessary in the primary
5057 deploy/debug scenario, and excluding from deployment saves time in
5058 the develop/download/debug cycle.
5059 · There may be insufficient space on the target device to accommodate
5061 all of the build products.
5062 · Visual Studio 2013 requires a target device IP address be entered for
5064 each target marked for deployment. For large numbers of targets,
5065 this can be tedious. NOTE: Visual Studio will deploy all project
5066 dependencies of a project tagged for deployment to the IP address
5067 configured for that project even if those dependencies are not tagged
5068 for deployment.
5069 Example 1
5071 This shows setting the variable for the target foo.
5072 add_library(foo SHARED foo.cpp)
5074 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON)
5075 Example 2
5077 This shows setting the variable for the Release configuration only.
5078 add_library(foo SHARED foo.cpp)
5080 set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>")
5081 VS_PACKAGE_REFERENCES
5083 Visual Studio package references for nuget.
5084 Adds one or more semicolon-delimited package references to a generated
5086 Visual Studio project. The version of the package will be underscore
5087 delimited. For example, boost_1.7.0;nunit_3.12.*.
5088 set_property(TARGET ${TARGET_NAME} PROPERTY
5090 VS_PACKAGE_REFERENCES "boost_1.7.0")
5091 VS_PROJECT_IMPORT
5093 Visual Studio managed project imports
5094 Adds to a generated Visual Studio project one or more semicolon-delim‐
5096 ited paths to .props files needed when building projects from some
5097 NuGet packages. For example, my_packages_path/MyPack‐
5098 age.1.0.0/build/MyPackage.props.
5099 VS_SCC_AUXPATH
5101 Visual Studio Source Code Control Aux Path.
5102 Can be set to change the visual studio source code control auxpath
5104 property.
5105 VS_SCC_LOCALPATH
5107 Visual Studio Source Code Control Local Path.
5108 Can be set to change the visual studio source code control local path
5110 property.
5111 VS_SCC_PROJECTNAME
5113 Visual Studio Source Code Control Project.
5114 Can be set to change the visual studio source code control project name
5116 property.
5117 VS_SCC_PROVIDER
5119 Visual Studio Source Code Control Provider.
5120 Can be set to change the visual studio source code control provider
5122 property.
5123 VS_SDK_REFERENCES
5125 Visual Studio project SDK references. Specify a semicolon-separated
5126 list of SDK references to be added to a generated Visual Studio
5127 project, e.g. Microsoft.AdMediatorWindows81, Version=1.0.
5128 VS_USER_PROPS
5130 Sets the user props file to be included in the visual studio C++
5131 project file. The standard path is $(UserRootDir)\\Micro‐
5132 soft.Cpp.$(Platform).user.props, which is in most cases the same as
5133 %LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Micro‐
5134 soft.Cpp.Win32.user.props or %LOCALAPPDATA%\\Micro‐
5135 soft\\MSBuild\\v4.0\\Microsoft.Cpp.x64.user.props.
5136 The *.user.props files can be used for Visual Studio wide configuration
5138 which is independent from cmake.
5139 VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
5141 Visual Studio Windows Target Platform Minimum Version
5142 For Windows 10. Specifies the minimum version of the OS that is being
5144 targeted. For example 10.0.10240.0. If the value is not specified, the
5145 value of CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION will be used on Win‐
5146 dowsStore projects otherwise the target platform minimum version will
5147 not be specified for the project.
5148 VS_WINRT_COMPONENT
5150 Mark a target as a Windows Runtime component for the Visual Studio gen‐
5151 erator. Compile the target with C++/CX language extensions for Windows
5152 Runtime. For SHARED and MODULE libraries, this also defines the
5153 _WINRT_DLL preprocessor macro.
5154 NOTE:
5156 Currently this is implemented only by Visual Studio generators.
5157 Support may be added to other generators in the future.
5158 VS_WINRT_EXTENSIONS
5160 Deprecated. Use VS_WINRT_COMPONENT instead. This property was an
5161 experimental partial implementation of that one.
5162 VS_WINRT_REFERENCES
5164 Visual Studio project Windows Runtime Metadata references
5165 Adds one or more semicolon-delimited WinRT references to a generated
5167 Visual Studio project. For example, “Windows;Windows.UI.Core”.
5168 WIN32_EXECUTABLE
5170 Build an executable with a WinMain entry point on windows.
5171 When this property is set to true the executable when linked on Windows
5173 will be created with a WinMain() entry point instead of just main().
5174 This makes it a GUI executable instead of a console application. See
5175 the CMAKE_MFC_FLAG variable documentation to configure use of the Mi‐
5176 crosoft Foundation Classes (MFC) for WinMain executables. This prop‐
5177 erty is initialized by the value of the CMAKE_WIN32_EXECUTABLE variable
5178 if it is set when a target is created.
5179 WINDOWS_EXPORT_ALL_SYMBOLS
5181 This property is implemented only for MS-compatible tools on Windows.
5182 Enable this boolean property to automatically create a module defini‐
5184 tion (.def) file with all global symbols found in the input .obj files
5185 for a SHARED library (or executable with ENABLE_EXPORTS) on Windows.
5186 The module definition file will be passed to the linker causing all
5187 symbols to be exported from the .dll. For global data symbols,
5188 __declspec(dllimport) must still be used when compiling against the
5189 code in the .dll. All other function symbols will be automatically
5190 exported and imported by callers. This simplifies porting projects to
5191 Windows by reducing the need for explicit dllexport markup, even in C++
5192 classes.
5193 When this property is enabled, zero or more .def files may also be
5195 specified as source files of the target. The exports named by these
5196 files will be merged with those detected from the object files to gen‐
5197 erate a single module definition file to be passed to the linker. This
5198 can be used to export symbols from a .dll that are not in any of its
5199 object files but are added by the linker from dependencies (e.g.
5200 msvcrt.lib).
5201 This property is initialized by the value of the CMAKE_WIN‐
5203 DOWS_EXPORT_ALL_SYMBOLS variable if it is set when a target is created.
5204 XCODE_ATTRIBUTE_<an-attribute>
5206 Set Xcode target attributes directly.
5207 Tell the Xcode generator to set ‘<an-attribute>’ to a given value in
5209 the generated Xcode project. Ignored on other generators.
5210 See the CMAKE_XCODE_ATTRIBUTE_<an-attribute> variable to set attributes
5212 on all targets in a directory tree.
5213 Contents of XCODE_ATTRIBUTE_<an-attribute> may use “generator expres‐
5215 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
5216 manual for available expressions. See the cmake-buildsystem(7) manual
5217 for more on defining buildsystem properties.
5218 XCODE_EXPLICIT_FILE_TYPE
5220 Set the Xcode explicitFileType attribute on its reference to a target.
5221 CMake computes a default based on target type but can be told explic‐
5222 itly with this property.
5223 See also XCODE_PRODUCT_TYPE.
5225 XCODE_GENERATE_SCHEME
5227 If enabled, the Xcode generator will generate schema files. These are
5228 useful to invoke analyze, archive, build-for-testing and test actions
5229 from the command line.
5230 This property is initialized by the value of the variable
5232 CMAKE_XCODE_GENERATE_SCHEME if it is set when a target is created.
5233 The following target properties overwrite the default of the corre‐
5235 sponding settings on the “Diagnostic” tab for each schema file. Each
5236 of those is initialized by the respective CMAKE_ variable at target
5237 creation time.
5238 · XCODE_SCHEME_ADDRESS_SANITIZER
5240 · XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
5242 · XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
5244 · XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
5246 · XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
5248 · XCODE_SCHEME_GUARD_MALLOC
5250 · XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
5252 · XCODE_SCHEME_MALLOC_GUARD_EDGES
5254 · XCODE_SCHEME_MALLOC_SCRIBBLE
5256 · XCODE_SCHEME_MALLOC_STACK
5258 · XCODE_SCHEME_THREAD_SANITIZER
5260 · XCODE_SCHEME_THREAD_SANITIZER_STOP
5262 · XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
5264 · XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
5266 · XCODE_SCHEME_ZOMBIE_OBJECTS
5268 The following target properties will be applied on the “Info”, “Argu‐
5270 ments”, and “Options” tab:
5271 · XCODE_SCHEME_ARGUMENTS
5273 · XCODE_SCHEME_DEBUG_AS_ROOT
5275 · XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
5277 · XCODE_SCHEME_ENVIRONMENT
5279 · XCODE_SCHEME_EXECUTABLE
5281 XCODE_PRODUCT_TYPE
5283 Set the Xcode productType attribute on its reference to a target.
5284 CMake computes a default based on target type but can be told explic‐
5285 itly with this property.
5286 See also XCODE_EXPLICIT_FILE_TYPE.
5288 XCODE_SCHEME_ADDRESS_SANITIZER
5290 Whether to enable Address Sanitizer in the Diagnostics section of the
5291 generated Xcode scheme.
5292 This property is initialized by the value of the variable
5294 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER if it is set when a target is cre‐
5295 ated.
5296 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5298 to see all Xcode schema related properties.
5299 XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
5301 Whether to enable Detect use of stack after return in the Diagnostics
5302 section of the generated Xcode scheme.
5303 This property is initialized by the value of the variable
5305 CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN if it is set when
5306 a target is created.
5307 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5309 to see all Xcode schema related properties.
5310 XCODE_SCHEME_ARGUMENTS
5312 Specify command line arguments that should be added to the Arguments
5313 section of the generated Xcode scheme.
5314 If set to a list of arguments those will be added to the scheme.
5316 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5318 to see all Xcode schema related properties.
5319 XCODE_SCHEME_DEBUG_AS_ROOT
5321 Whether to debug the target as ‘root’.
5322 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5324 to see all Xcode schema related properties.
5325 XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
5327 Whether to enable Allow debugging when using document Versions Browser
5328 in the Options section of the generated Xcode scheme.
5329 This property is initialized by the value of the variable
5331 CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING if it is set when a target
5332 is created.
5333 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5335 to see all Xcode schema related properties.
5336 XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
5338 Whether to disable the Main Thread Checker in the Diagnostics section
5339 of the generated Xcode scheme.
5340 This property is initialized by the value of the variable
5342 CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER if it is set when a tar‐
5343 get is created.
5344 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5346 to see all Xcode schema related properties.
5347 XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
5349 Whether to enable Dynamic Library Loads in the Diagnostics section of
5350 the generated Xcode scheme.
5351 This property is initialized by the value of the variable
5353 CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS if it is set when a target is
5354 created.
5355 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5357 to see all Xcode schema related properties.
5358 XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
5360 Whether to enable Dynamic Linker API usage in the Diagnostics section
5361 of the generated Xcode scheme.
5362 This property is initialized by the value of the variable
5364 CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE if it is set when a target
5365 is created.
5366 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5368 to see all Xcode schema related properties.
5369 XCODE_SCHEME_ENVIRONMENT
5371 Specify environment variables that should be added to the Arguments
5372 section of the generated Xcode scheme.
5373 If set to a list of environment variables and values of the form
5375 MYVAR=value those environment variables will be added to the scheme.
5376 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5378 to see all Xcode schema related properties.
5379 XCODE_SCHEME_EXECUTABLE
5381 Specify path to executable in the Info section of the generated Xcode
5382 scheme. If not set the schema generator will select the current target
5383 if it is actually executable.
5384 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5386 to see all Xcode schema related properties.
5387 XCODE_SCHEME_GUARD_MALLOC
5389 Whether to enable Guard Malloc in the Diagnostics section of the gener‐
5390 ated Xcode scheme.
5391 This property is initialized by the value of the variable
5393 CMAKE_XCODE_SCHEME_GUARD_MALLOC if it is set when a target is created.
5394 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5396 to see all Xcode schema related properties.
5397 XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
5399 Whether to enable the Main Thread Checker option Pause on issues in the
5400 Diagnostics section of the generated Xcode scheme.
5401 This property is initialized by the value of the variable
5403 CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP if it is set when a target
5404 is created.
5405 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5407 to see all Xcode schema related properties.
5408 XCODE_SCHEME_MALLOC_GUARD_EDGES
5410 Whether to enable Malloc Guard Edges in the Diagnostics section of the
5411 generated Xcode scheme.
5412 This property is initialized by the value of the variable
5414 CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES if it is set when a target is
5415 created.
5416 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5418 to see all Xcode schema related properties.
5419 XCODE_SCHEME_MALLOC_SCRIBBLE
5421 Whether to enable Malloc Scribble in the Diagnostics section of the
5422 generated Xcode scheme.
5423 This property is initialized by the value of the variable
5425 CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE if it is set when a target is cre‐
5426 ated.
5427 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5429 to see all Xcode schema related properties.
5430 XCODE_SCHEME_MALLOC_STACK
5432 Whether to enable Malloc Stack in the Diagnostics section of the gener‐
5433 ated Xcode scheme.
5434 This property is initialized by the value of the variable
5436 CMAKE_XCODE_SCHEME_MALLOC_STACK if it is set when a target is created.
5437 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5439 to see all Xcode schema related properties.
5440 XCODE_SCHEME_THREAD_SANITIZER
5442 Whether to enable Thread Sanitizer in the Diagnostics section of the
5443 generated Xcode scheme.
5444 This property is initialized by the value of the variable
5446 CMAKE_XCODE_SCHEME_THREAD_SANITIZER if it is set when a target is cre‐
5447 ated.
5448 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5450 to see all Xcode schema related properties.
5451 XCODE_SCHEME_THREAD_SANITIZER_STOP
5453 Whether to enable Thread Sanitizer - Pause on issues in the Diagnostics
5454 section of the generated Xcode scheme.
5455 This property is initialized by the value of the variable
5457 CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP if it is set when a target is
5458 created.
5459 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5461 to see all Xcode schema related properties.
5462 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
5464 Whether to enable Undefined Behavior Sanitizer in the Diagnostics sec‐
5465 tion of the generated Xcode scheme.
5466 This property is initialized by the value of the variable
5468 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER if it is set when a
5469 target is created.
5470 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5472 to see all Xcode schema related properties.
5473 XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
5475 Whether to enable Undefined Behavior Sanitizer option Pause on issues
5476 in the Diagnostics section of the generated Xcode scheme.
5477 This property is initialized by the value of the variable
5479 CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP if it is set when
5480 a target is created.
5481 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5483 to see all Xcode schema related properties.
5484 XCODE_SCHEME_ZOMBIE_OBJECTS
5486 Whether to enable Zombie Objects in the Diagnostics section of the gen‐
5487 erated Xcode scheme.
5488 This property is initialized by the value of the variable
5490 CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS if it is set when a target is cre‐
5491 ated.
5492 Please refer to the XCODE_GENERATE_SCHEME target property documentation
5494 to see all Xcode schema related properties.
5495 XCTEST
5497 This target is a XCTest CFBundle on the Mac.
5498 This property will usually get set via the xctest_add_bundle() macro in
5500 FindXCTest module.
5501 If a module library target has this property set to true it will be
5503 built as a CFBundle when built on the Mac. It will have the directory
5504 structure required for a CFBundle.
5505 This property depends on BUNDLE to be effective.
5507
5509 ATTACHED_FILES_ON_FAIL
5510 Attach a list of files to a dashboard submission if the test fails.
5511 Same as ATTACHED_FILES, but these files will only be included if the
5513 test does not pass.
5514 ATTACHED_FILES
5516 Attach a list of files to a dashboard submission.
5517 Set this property to a list of files that will be encoded and submitted
5519 to the dashboard as an addition to the test result.
5520 COST
5522 This property describes the cost of a test. When parallel testing is
5523 enabled, tests in the test set will be run in descending order of cost.
5524 Projects can explicitly define the cost of a test by setting this prop‐
5525 erty to a floating point value.
5526 When the cost of a test is not defined by the project, ctest will ini‐
5528 tially use a default cost of 0. It computes a weighted average of the
5529 cost each time a test is run and uses that as an improved estimate of
5530 the cost for the next run. The more a test is re-run in the same build
5531 directory, the more representative the cost should become.
5532 DEPENDS
5534 Specifies that this test should only be run after the specified list of
5535 tests.
5536 Set this to a list of tests that must finish before this test is run.
5538 The results of those tests are not considered, the dependency relation‐
5539 ship is purely for order of execution (i.e. it is really just a run
5540 after relationship). Consider using test fixtures with setup tests if a
5541 dependency with successful completion is required (see FIX‐
5542 TURES_REQUIRED).
5543 DISABLED
5545 If set to True, the test will be skipped and its status will be ‘Not
5546 Run’. A DISABLED test will not be counted in the total number of tests
5547 and its completion status will be reported to CDash as Disabled.
5548 A DISABLED test does not participate in test fixture dependency resolu‐
5550 tion. If a DISABLED test has fixture requirements defined in its FIX‐
5551 TURES_REQUIRED property, it will not cause setup or cleanup tests for
5552 those fixtures to be added to the test set.
5553 If a test with the FIXTURES_SETUP property set is DISABLED, the fixture
5555 behavior will be as though that setup test was passing and any test
5556 case requiring that fixture will still run.
5557 ENVIRONMENT
5559 Specify environment variables that should be defined for running a
5560 test.
5561 If set to a list of environment variables and values of the form
5563 MYVAR=value those environment variables will be defined while running
5564 the test. The environment is restored to its previous state after the
5565 test is done.
5566 FAIL_REGULAR_EXPRESSION
5568 If the output matches this regular expression the test will fail.
5569 If set, if the output matches one of specified regular expressions, the
5571 test will fail. Example:
5572 set_tests_properties(mytest PROPERTIES
5574 FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
5575 )
5576 FAIL_REGULAR_EXPRESSION expects a list of regular expressions.
5578 FIXTURES_CLEANUP
5580 Specifies a list of fixtures for which the test is to be treated as a
5581 cleanup test. These fixture names are distinct from test case names and
5582 are not required to have any similarity to the names of tests associ‐
5583 ated with them.
5584 Fixture cleanup tests are ordinary tests with all of the usual test
5586 functionality. Setting the FIXTURES_CLEANUP property for a test has two
5587 primary effects:
5588 · CTest will ensure the test executes after all other tests which list
5590 any of the fixtures in its FIXTURES_REQUIRED property.
5591 · If CTest is asked to run only a subset of tests (e.g. using regular
5593 expressions or the --rerun-failed option) and the cleanup test is not
5594 in the set of tests to run, it will automatically be added if any
5595 tests in the set require any fixture listed in FIXTURES_CLEANUP.
5596 A cleanup test can have multiple fixtures listed in its FIX‐
5598 TURES_CLEANUP property. It will execute only once for the whole CTest
5599 run, not once for each fixture. A fixture can also have more than one
5600 cleanup test defined. If there are multiple cleanup tests for a fix‐
5601 ture, projects can control their order with the usual DEPENDS test
5602 property if necessary.
5603 A cleanup test is allowed to require other fixtures, but not any fix‐
5605 ture listed in its FIXTURES_CLEANUP property. For example:
5606 # Ok: Dependent fixture is different to cleanup
5608 set_tests_properties(cleanupFoo PROPERTIES
5609 FIXTURES_CLEANUP Foo
5610 FIXTURES_REQUIRED Bar
5611 )
5612 # Error: cannot require same fixture as cleanup
5614 set_tests_properties(cleanupFoo PROPERTIES
5615 FIXTURES_CLEANUP Foo
5616 FIXTURES_REQUIRED Foo
5617 )
5618 Cleanup tests will execute even if setup or regular tests for that fix‐
5620 ture fail or are skipped.
5621 See FIXTURES_REQUIRED for a more complete discussion of how to use test
5623 fixtures.
5624 FIXTURES_REQUIRED
5626 Specifies a list of fixtures the test requires. Fixture names are case
5627 sensitive and they are not required to have any similarity to test
5628 names.
5629 Fixtures are a way to attach setup and cleanup tasks to a set of tests.
5631 If a test requires a given fixture, then all tests marked as setup
5632 tasks for that fixture will be executed first (once for the whole set
5633 of tests, not once per test requiring the fixture). After all tests
5634 requiring a particular fixture have completed, CTest will ensure all
5635 tests marked as cleanup tasks for that fixture are then executed. Tests
5636 are marked as setup tasks with the FIXTURES_SETUP property and as
5637 cleanup tasks with the FIXTURES_CLEANUP property. If any of a fixture’s
5638 setup tests fail, all tests listing that fixture in their FIX‐
5639 TURES_REQUIRED property will not be executed. The cleanup tests for the
5640 fixture will always be executed, even if some setup tests fail.
5641 When CTest is asked to execute only a subset of tests (e.g. by the use
5643 of regular expressions or when run with the --rerun-failed command line
5644 option), it will automatically add any setup or cleanup tests for fix‐
5645 tures required by any of the tests that are in the execution set. This
5646 behavior can be overridden with the -FS, -FC and -FA command line
5647 options to ctest(1) if desired.
5648 Since setup and cleanup tasks are also tests, they can have an ordering
5650 specified by the DEPENDS test property just like any other tests. This
5651 can be exploited to implement setup or cleanup using multiple tests for
5652 a single fixture to modularise setup or cleanup logic.
5653 The concept of a fixture is different to that of a resource specified
5655 by RESOURCE_LOCK, but they may be used together. A fixture defines a
5656 set of tests which share setup and cleanup requirements, whereas a
5657 resource lock has the effect of ensuring a particular set of tests do
5658 not run in parallel. Some situations may need both, such as setting up
5659 a database, serialising test access to that database and deleting the
5660 database again at the end. For such cases, tests would populate both
5661 FIXTURES_REQUIRED and RESOURCE_LOCK to combine the two behaviours.
5662 Names used for RESOURCE_LOCK have no relationship with names of fix‐
5663 tures, so note that a resource lock does not imply a fixture and vice
5664 versa.
5665 Consider the following example which represents a database test sce‐
5667 nario similar to that mentioned above:
5668 add_test(NAME testsDone COMMAND emailResults)
5670 add_test(NAME fooOnly COMMAND testFoo)
5671 add_test(NAME dbOnly COMMAND testDb)
5672 add_test(NAME dbWithFoo COMMAND testDbWithFoo)
5673 add_test(NAME createDB COMMAND initDB)
5674 add_test(NAME setupUsers COMMAND userCreation)
5675 add_test(NAME cleanupDB COMMAND deleteDB)
5676 add_test(NAME cleanupFoo COMMAND removeFoos)
5677 set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)
5679 set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB)
5681 set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB)
5682 set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB)
5683 set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo)
5684 set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo")
5685 set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo)
5687 set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB)
5688 set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo")
5689 set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
5691 PROPERTIES RESOURCE_LOCK DbAccess)
5692 Key points from this example:
5694 · Two fixtures are defined: DB and Foo. Tests can require a single fix‐
5696 ture as fooOnly and dbOnly do, or they can depend on multiple fix‐
5697 tures like dbWithFoo does.
5698 · A DEPENDS relationship is set up to ensure setupUsers happens after
5700 createDB, both of which are setup tests for the DB fixture and will
5701 therefore be executed before the dbOnly and dbWithFoo tests automati‐
5702 cally.
5703 · No explicit DEPENDS relationships were needed to make the setup tests
5705 run before or the cleanup tests run after the regular tests.
5706 · The Foo fixture has no setup tests defined, only a single cleanup
5708 test.
5709 · testsDone is a cleanup test for both the DB and Foo fixtures. There‐
5711 fore, it will only execute once regular tests for both fixtures have
5712 finished (i.e. after fooOnly, dbOnly and dbWithFoo). No DEPENDS rela‐
5713 tionship was specified for testsDone, so it is free to run before,
5714 after or concurrently with other cleanup tests for either fixture.
5715 · The setup and cleanup tests never list the fixtures they are for in
5717 their own FIXTURES_REQUIRED property, as that would result in a
5718 dependency on themselves and be considered an error.
5719 FIXTURES_SETUP
5721 Specifies a list of fixtures for which the test is to be treated as a
5722 setup test. These fixture names are distinct from test case names and
5723 are not required to have any similarity to the names of tests associ‐
5724 ated with them.
5725 Fixture setup tests are ordinary tests with all of the usual test func‐
5727 tionality. Setting the FIXTURES_SETUP property for a test has two pri‐
5728 mary effects:
5729 · CTest will ensure the test executes before any other test which lists
5731 the fixture name(s) in its FIXTURES_REQUIRED property.
5732 · If CTest is asked to run only a subset of tests (e.g. using regular
5734 expressions or the --rerun-failed option) and the setup test is not
5735 in the set of tests to run, it will automatically be added if any
5736 tests in the set require any fixture listed in FIXTURES_SETUP.
5737 A setup test can have multiple fixtures listed in its FIXTURES_SETUP
5739 property. It will execute only once for the whole CTest run, not once
5740 for each fixture. A fixture can also have more than one setup test
5741 defined. If there are multiple setup tests for a fixture, projects can
5742 control their order with the usual DEPENDS test property if necessary.
5743 A setup test is allowed to require other fixtures, but not any fixture
5745 listed in its FIXTURES_SETUP property. For example:
5746 # Ok: dependent fixture is different to setup
5748 set_tests_properties(setupFoo PROPERTIES
5749 FIXTURES_SETUP Foo
5750 FIXTURES_REQUIRED Bar
5751 )
5752 # Error: cannot require same fixture as setup
5754 set_tests_properties(setupFoo PROPERTIES
5755 FIXTURES_SETUP Foo
5756 FIXTURES_REQUIRED Foo
5757 )
5758 If any of a fixture’s setup tests fail, none of the tests listing that
5760 fixture in its FIXTURES_REQUIRED property will be run. Cleanup tests
5761 will, however, still be executed.
5762 See FIXTURES_REQUIRED for a more complete discussion of how to use test
5764 fixtures.
5765 LABELS
5767 Specify a list of text labels associated with a test.
5768 The list is reported in dashboard submissions.
5770 MEASUREMENT
5772 Specify a CDASH measurement and value to be reported for a test.
5773 If set to a name then that name will be reported to CDASH as a named
5775 measurement with a value of 1. You may also specify a value by setting
5776 MEASUREMENT to measurement=value.
5777 PASS_REGULAR_EXPRESSION
5779 The output must match this regular expression for the test to pass.
5780 If set, the test output will be checked against the specified regular
5782 expressions and at least one of the regular expressions has to match,
5783 otherwise the test will fail. Example:
5784 set_tests_properties(mytest PROPERTIES
5786 PASS_REGULAR_EXPRESSION "TestPassed;All ok"
5787 )
5788 PASS_REGULAR_EXPRESSION expects a list of regular expressions.
5790 PROCESSOR_AFFINITY
5792 Set to a true value to ask CTest to launch the test process with CPU
5793 affinity for a fixed set of processors. If enabled and supported for
5794 the current platform, CTest will choose a set of processors to place in
5795 the CPU affinity mask when launching the test process. The number of
5796 processors in the set is determined by the PROCESSORS test property or
5797 the number of processors available to CTest, whichever is smaller. The
5798 set of processors chosen will be disjoint from the processors assigned
5799 to other concurrently running tests that also have the PROCESSOR_AFFIN‐
5800 ITY property enabled.
5801 PROCESSORS
5803 Set to specify how many process slots this test requires. If not set,
5804 the default is 1 processor.
5805 Denotes the number of processors that this test will require. This is
5807 typically used for MPI tests, and should be used in conjunction with
5808 the ctest_test() PARALLEL_LEVEL option.
5809 This will also be used to display a weighted test timing result in
5811 label and subproject summaries in the command line output of ctest(1).
5812 The wall clock time for the test run will be multiplied by this prop‐
5813 erty to give a better idea of how much cpu resource CTest allocated for
5814 the test.
5815 See also the PROCESSOR_AFFINITY test property.
5817 REQUIRED_FILES
5819 List of files required to run the test.
5820 If set to a list of files, the test will not be run unless all of the
5822 files exist.
5823 RESOURCE_GROUPS
5825 Specify resources required by a test, grouped in a way that is meaning‐
5826 ful to the test. See resource allocation for more information on how
5827 this property integrates into the CTest resource allocation feature.
5828 The RESOURCE_GROUPS property is a semicolon-separated list of group
5830 descriptions. Each entry consists of an optional number of groups using
5831 the description followed by a series of resource requirements for those
5832 groups. These requirements (and the number of groups) are separated by
5833 commas. The resource requirements consist of the name of a resource
5834 type, followed by a colon, followed by an unsigned integer specifying
5835 the number of slots required on one resource of the given type.
5836 The RESOURCE_GROUPS property tells CTest what resources a test expects
5838 to use grouped in a way meaningful to the test. The test itself must
5839 read the environment variables to determine which resources have been
5840 allocated to each group. For example, each group may correspond to a
5841 process the test will spawn when executed.
5842 Consider the following example:
5844 add_test(NAME MyTest COMMAND MyExe)
5846 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
5847 "2,gpus:2"
5848 "gpus:4,crypto_chips:2")
5849 In this example, there are two group descriptions (implicitly separated
5851 by a semicolon.) The content of the first description is 2,gpus:2. This
5852 description specifies 2 groups, each of which requires 2 slots from a
5853 single GPU. The content of the second description is
5854 gpus:4,crypto_chips:2. This description does not specify a group count,
5855 so a default of 1 is assumed. This single group requires 4 slots from
5856 a single GPU and 2 slots from a single cryptography chip. In total, 3
5857 resource groups are specified for this test, each with its own unique
5858 requirements.
5859 Note that the number of slots following the resource type specifies
5861 slots from a single instance of the resource. If the resource group can
5862 tolerate receiving slots from different instances of the same resource,
5863 it can indicate this by splitting the specification into multiple
5864 requirements of one slot. For example:
5865 add_test(NAME MyTest COMMAND MyExe)
5867 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
5868 "gpus:1,gpus:1,gpus:1,gpus:1")
5869 In this case, the single resource group indicates that it needs four
5871 GPU slots, all of which may come from separate GPUs (though they don’t
5872 have to; CTest may still assign slots from the same GPU.)
5873 When CTest sets the environment variables for a test, it assigns a
5875 group number based on the group description, starting at 0 on the left
5876 and the number of groups minus 1 on the right. For example, in the
5877 example above, the two groups in the first description would have IDs
5878 of 0 and 1, and the single group in the second description would have
5879 an ID of 2.
5880 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
5882 purposes, but they are distinct and orthogonal. Resources specified by
5883 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
5884 RESOURCE_LOCK is a simpler property that is used for locking one global
5885 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
5886 tiple tests to simultaneously use multiple resources of the same type,
5887 specifying their requirements in a fine-grained manner.
5888 RESOURCE_LOCK
5890 Specify a list of resources that are locked by this test.
5891 If multiple tests specify the same resource lock, they are guaranteed
5893 not to run concurrently.
5894 See also FIXTURES_REQUIRED if the resource requires any setup or
5896 cleanup steps.
5897 Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar
5899 purposes, but they are distinct and orthogonal. Resources specified by
5900 RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas
5901 RESOURCE_LOCK is a simpler property that is used for locking one global
5902 resource, RESOURCE_GROUPS is a more advanced property that allows mul‐
5903 tiple tests to simultaneously use multiple resources of the same type,
5904 specifying their requirements in a fine-grained manner.
5905 RUN_SERIAL
5907 Do not run this test in parallel with any other test.
5908 Use this option in conjunction with the ctest_test PARALLEL_LEVEL
5910 option to specify that this test should not be run in parallel with any
5911 other tests.
5912 SKIP_REGULAR_EXPRESSION
5914 If the output matches this regular expression the test will be marked
5915 as skipped.
5916 If set, if the output matches one of specified regular expressions, the
5918 test will be marked as skipped. Example:
5919 set_property(TEST mytest PROPERTY
5921 SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped"
5922 )
5923 SKIP_REGULAR_EXPRESSION expects a list of regular expressions.
5925 See also the SKIP_RETURN_CODE property.
5927 SKIP_RETURN_CODE
5929 Return code to mark a test as skipped.
5930 Sometimes only a test itself can determine if all requirements for the
5932 test are met. If such a situation should not be considered a hard fail‐
5933 ure a return code of the process can be specified that will mark the
5934 test as Not Run if it is encountered. Valid values are in the range of
5935 0 to 255, inclusive.
5936 See also the SKIP_REGULAR_EXPRESSION property.
5938 TIMEOUT
5940 How many seconds to allow for this test.
5941 This property if set will limit a test to not take more than the speci‐
5943 fied number of seconds to run. If it exceeds that the test process
5944 will be killed and ctest will move to the next test. This setting
5945 takes precedence over CTEST_TEST_TIMEOUT.
5946 TIMEOUT_AFTER_MATCH
5948 Change a test’s timeout duration after a matching line is encountered
5949 in its output.
5950 Usage
5952 add_test(mytest ...)
5953 set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}")
5954 Description
5956 Allow a test seconds to complete after regex is encountered in its out‐
5957 put.
5958 When the test outputs a line that matches regex its start time is reset
5960 to the current time and its timeout duration is changed to seconds.
5961 Prior to this, the timeout duration is determined by the TIMEOUT prop‐
5962 erty or the CTEST_TEST_TIMEOUT variable if either of these are set.
5963 Because the test’s start time is reset, its execution time will not
5964 include any time that was spent waiting for the matching output.
5965 TIMEOUT_AFTER_MATCH is useful for avoiding spurious timeouts when your
5967 test must wait for some system resource to become available before it
5968 can execute. Set TIMEOUT to a longer duration that accounts for
5969 resource acquisition and use TIMEOUT_AFTER_MATCH to control how long
5970 the actual test is allowed to run.
5971 If the required resource can be controlled by CTest you should use
5973 RESOURCE_LOCK instead of TIMEOUT_AFTER_MATCH. This property should be
5974 used when only the test itself can determine when its required
5975 resources are available.
5976 WILL_FAIL
5978 If set to true, this will invert the pass/fail flag of the test.
5979 This property can be used for tests that are expected to fail and
5981 return a non zero return code.
5982 WORKING_DIRECTORY
5984 The directory from which the test executable will be called.
5985 If this is not set, the test will be run with the working directory set
5987 to the binary directory associated with where the test was created
5988 (i.e. the CMAKE_CURRENT_BINARY_DIR for where add_test() was called).
5989
5991 ABSTRACT
5992 Is this source file an abstract class.
5993 A property on a source file that indicates if the source file repre‐
5995 sents a class that is abstract. This only makes sense for languages
5996 that have a notion of an abstract class and it is only used by some
5997 tools that wrap classes into other languages.
5998 AUTOUIC_OPTIONS
6000 Additional options for uic when using AUTOUIC
6001 This property holds additional command line options which will be used
6003 when uic is executed during the build via AUTOUIC, i.e. it is equiva‐
6004 lent to the optional OPTIONS argument of the qt4_wrap_ui() macro.
6005 By default it is empty.
6007 The options set on the .ui source file may override AUTOUIC_OPTIONS set
6009 on the target.
6010 EXAMPLE
6012 # ...
6013 set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection")
6014 # ...
6015 AUTORCC_OPTIONS
6017 Additional options for rcc when using AUTORCC
6018 This property holds additional command line options which will be used
6020 when rcc is executed during the build via AUTORCC, i.e. it is equiva‐
6021 lent to the optional OPTIONS argument of the qt4_add_resources() macro.
6022 By default it is empty.
6024 The options set on the .qrc source file may override AUTORCC_OPTIONS
6026 set on the target.
6027 EXAMPLE
6029 # ...
6030 set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9")
6031 # ...
6032 COMPILE_DEFINITIONS
6034 Preprocessor definitions for compiling a source file.
6035 The COMPILE_DEFINITIONS property may be set to a semicolon-separated
6037 list of preprocessor definitions using the syntax VAR or VAR=value.
6038 Function-style definitions are not supported. CMake will automatically
6039 escape the value correctly for the native build system (note that CMake
6040 language syntax may require escapes to specify some values). This
6041 property may be set on a per-configuration basis using the name COM‐
6042 PILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case name (ex.
6043 COMPILE_DEFINITIONS_DEBUG).
6044 CMake will automatically drop some definitions that are not supported
6046 by the native build tool. Xcode does not support per-configuration
6047 definitions on source files.
6048 Disclaimer: Most native build tools have poor support for escaping cer‐
6050 tain values. CMake has work-arounds for many cases but some values may
6051 just not be possible to pass correctly. If a value does not seem to be
6052 escaped correctly, do not attempt to work-around the problem by adding
6053 escape sequences to the value. Your work-around may break in a future
6054 version of CMake that has improved escape support. Instead consider
6055 defining the macro in a (configured) header file. Then report the lim‐
6056 itation. Known limitations include:
6057 # - broken almost everywhere
6059 ; - broken in VS IDE 7.0 and Borland Makefiles
6060 , - broken in VS IDE
6061 % - broken in some cases in NMake
6062 & | - broken in some cases on MinGW
6063 ^ < > \" - broken in most Make tools on Windows
6064 CMake does not reject these values outright because they do work in
6066 some cases. Use with caution.
6067 Contents of COMPILE_DEFINITIONS may use cmake-generator-expressions(7)
6069 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6070 for available expressions. However, Xcode does not support per-config
6071 per-source settings, so expressions that depend on the build configura‐
6072 tion are not allowed with that generator.
6073 Generator expressions should be preferred instead of setting the alter‐
6075 native per-configuration property.
6076 COMPILE_FLAGS
6078 Additional flags to be added when compiling this source file.
6079 The COMPILE_FLAGS property, managed as a string, sets additional com‐
6081 piler flags used to build source files. Use COMPILE_DEFINITIONS to
6082 pass additional preprocessor definitions.
6083 Contents of COMPILE_FLAGS may use “generator expressions” with the syn‐
6085 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6086 able expressions. However, Xcode does not support per-config
6087 per-source settings, so expressions that depend on the build configura‐
6088 tion are not allowed with that generator.
6089 NOTE:
6091 This property has been superseded by the COMPILE_OPTIONS property.
6092 COMPILE_OPTIONS
6094 List of additional options to pass to the compiler.
6095 This property holds a semicolon-separated list of options and will be
6097 added to the list of compile flags when this source file builds. Use
6098 COMPILE_DEFINITIONS to pass additional preprocessor definitions and
6099 INCLUDE_DIRECTORIES to pass additional include directories.
6100 Contents of COMPILE_OPTIONS may use “generator expressions” with the
6102 syntax $<...>. See the cmake-generator-expressions(7) manual for
6103 available expressions. However, Xcode does not support per-config
6104 per-source settings, so expressions that depend on the build configura‐
6105 tion are not allowed with that generator.
6106 NOTE:
6108 This property should be preferred over the COMPILE_FLAGS property.
6109 EXTERNAL_OBJECT
6111 If set to true then this is an object file.
6112 If this property is set to True then the source file is really an
6114 object file and should not be compiled. It will still be linked into
6115 the target though.
6116 Fortran_FORMAT
6118 Set to FIXED or FREE to indicate the Fortran source layout.
6119 This property tells CMake whether a given Fortran source file uses
6121 fixed-format or free-format. CMake will pass the corresponding format
6122 flag to the compiler. Consider using the target-wide Fortran_FORMAT
6123 property if all source files in a target share the same format.
6124 GENERATED
6126 Is this source file generated as part of the build or CMake process.
6127 Tells the internal CMake engine that a source file is generated by an
6129 outside process such as another build step, or the execution of CMake
6130 itself. This information is then used to exempt the file from any exis‐
6131 tence or validity checks. Generated files are created by the execution
6132 of commands such as add_custom_command() and file(GENERATE).
6133 When a generated file created by an add_custom_command() command is
6135 explicitly listed as a source file for any target in the same directory
6136 scope (which usually means the same CMakeLists.txt file), CMake will
6137 automatically create a dependency to make sure the file is generated
6138 before building that target.
6139 Generated sources may be hidden in some IDE tools, while in others they
6141 might be shown. For the special case of sources generated by CMake’s
6142 AUTOMOC or AUTORCC functionality, the AUTOGEN_SOURCE_GROUP, AUTO‐
6143 MOC_SOURCE_GROUP and AUTORCC_SOURCE_GROUP target properties may influ‐
6144 ence where the generated sources are grouped in the project’s file
6145 lists.
6146 HEADER_FILE_ONLY
6148 Is this source file only a header file.
6149 A property on a source file that indicates if the source file is a
6151 header file with no associated implementation. This is set automati‐
6152 cally based on the file extension and is used by CMake to determine if
6153 certain dependency information should be computed.
6154 By setting this property to ON, you can disable compilation of the
6156 given source file, even if it should be compiled because it is part of
6157 the library’s/executable’s sources.
6158 This is useful if you have some source files which you somehow
6160 pre-process, and then add these pre-processed sources via add_library()
6161 or add_executable(). Normally, in IDE, there would be no reference of
6162 the original sources, only of these pre-processed sources. So by set‐
6163 ting this property for all the original source files to ON, and then
6164 either calling add_library() or add_executable() while passing both the
6165 pre-processed sources and the original sources, or by using tar‐
6166 get_sources() to add original source files will do exactly what would
6167 one expect, i.e. the original source files would be visible in IDE,
6168 and will not be built.
6169 INCLUDE_DIRECTORIES
6171 List of preprocessor include file search directories.
6172 This property holds a semicolon-separated list of paths and will be
6174 added to the list of include directories when this source file builds.
6175 These directories will take precedence over directories defined at tar‐
6176 get level except for Xcode generator due to technical limitations.
6177 Relative paths should not be added to this property directly.
6179 Contents of INCLUDE_DIRECTORIES may use “generator expressions” with
6181 the syntax $<...>. See the cmake-generator-expressions(7) manual for
6182 available expressions. However, Xcode does not support per-config
6183 per-source settings, so expressions that depend on the build configura‐
6184 tion are not allowed with that generator.
6185 KEEP_EXTENSION
6187 Make the output file have the same extension as the source file.
6188 If this property is set then the file extension of the output file will
6190 be the same as that of the source file. Normally the output file
6191 extension is computed based on the language of the source file, for
6192 example .cxx will go to a .o extension.
6193 LABELS
6195 Specify a list of text labels associated with a source file.
6196 This property has meaning only when the source file is listed in a tar‐
6198 get whose LABELS property is also set. No other semantics are cur‐
6199 rently specified.
6200 LANGUAGE
6202 What programming language is the file.
6203 A property that can be set to indicate what programming language the
6205 source file is. If it is not set the language is determined based on
6206 the file extension. Typical values are CXX (i.e. C++), C, CSharp,
6207 CUDA, Fortran, and ASM. Setting this property for a file means this
6208 file will be compiled. Do not set this for headers or files that
6209 should not be compiled.
6210 LOCATION
6212 The full path to a source file.
6213 A read only property on a SOURCE FILE that contains the full path to
6215 the source file.
6216 MACOSX_PACKAGE_LOCATION
6218 Place a source file inside a Application Bundle (MACOSX_BUNDLE), Core
6219 Foundation Bundle (BUNDLE), or Framework Bundle (FRAMEWORK). It is
6220 applicable for macOS and iOS.
6221 Executable targets with the MACOSX_BUNDLE property set are built as
6223 macOS or iOS application bundles on Apple platforms. Shared library
6224 targets with the FRAMEWORK property set are built as macOS or iOS
6225 frameworks on Apple platforms. Module library targets with the BUNDLE
6226 property set are built as macOS CFBundle bundles on Apple platforms.
6227 Source files listed in the target with this property set will be copied
6228 to a directory inside the bundle or framework content folder specified
6229 by the property value. For macOS Application Bundles the content
6230 folder is <name>.app/Contents. For macOS Frameworks the content folder
6231 is <name>.framework/Versions/<version>. For macOS CFBundles the con‐
6232 tent folder is <name>.bundle/Contents (unless the extension is
6233 changed). See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target
6234 properties for specifying files meant for Headers, PrivateHeaders, or
6235 Resources directories.
6236 If the specified location is equal to Resources, the resulting location
6238 will be the same as if the RESOURCE property had been used. If the
6239 specified location is a sub-folder of Resources, it will be placed into
6240 the respective sub-folder. Note: For iOS Apple uses a flat bundle lay‐
6241 out where no Resources folder exist. Therefore CMake strips the
6242 Resources folder name from the specified location.
6243 OBJECT_DEPENDS
6245 Additional files on which a compiled object file depends.
6246 Specifies a semicolon-separated list of full-paths to files on which
6248 any object files compiled from this source file depend. On Makefile
6249 Generators and the Ninja generator an object file will be recompiled if
6250 any of the named files is newer than it. Visual Studio Generators and
6251 the Xcode generator cannot implement such compilation dependencies.
6252 This property need not be used to specify the dependency of a source
6254 file on a generated header file that it includes. Although the prop‐
6255 erty was originally introduced for this purpose, it is no longer neces‐
6256 sary. If the generated header file is created by a custom command in
6257 the same target as the source file, the automatic dependency scanning
6258 process will recognize the dependency. If the generated header file is
6259 created by another target, an inter-target dependency should be created
6260 with the add_dependencies() command (if one does not already exist due
6261 to linking relationships).
6262 OBJECT_OUTPUTS
6264 Additional outputs for a Ninja or Makefile Generators rule.
6265 Additional outputs created by compilation of this source file. If any
6267 of these outputs is missing the object will be recompiled. This is
6268 supported only on the Ninja and Makefile Generators and will be ignored
6269 on other generators.
6270 SKIP_AUTOGEN
6272 Exclude the source file from AUTOMOC, AUTOUIC and AUTORCC processing
6273 (for Qt projects).
6274 For finer exclusion control see SKIP_AUTOMOC, SKIP_AUTOUIC and
6276 SKIP_AUTORCC.
6277 EXAMPLE
6279 # ...
6280 set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
6281 # ...
6282 SKIP_AUTOMOC
6284 Exclude the source file from AUTOMOC processing (for Qt projects).
6285 For broader exclusion control see SKIP_AUTOGEN.
6287 EXAMPLE
6289 # ...
6290 set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
6291 # ...
6292 SKIP_AUTORCC
6294 Exclude the source file from AUTORCC processing (for Qt projects).
6295 For broader exclusion control see SKIP_AUTOGEN.
6297 EXAMPLE
6299 # ...
6300 set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
6301 # ...
6302 SKIP_AUTOUIC
6304 Exclude the source file from AUTOUIC processing (for Qt projects).
6305 SKIP_AUTOUIC can be set on C++ header and source files and on .ui
6307 files.
6308 For broader exclusion control see SKIP_AUTOGEN.
6310 EXAMPLE
6312 # ...
6313 set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
6314 set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON)
6315 set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON)
6316 # ...
6317 SKIP_PRECOMPILE_HEADERS
6319 Is this source file skipped by PRECOMPILE_HEADERS feature.
6320 This property helps with build problems that one would run into when
6322 using the PRECOMPILE_HEADERS feature.
6323 One example would be the usage of Objective-C (.m) files, and Objec‐
6325 tive-C++ (.mm) files, which lead to compilation failure because they
6326 are treated (in case of Ninja / Makefile generator) as C, and CXX
6327 respectively. The precompile headers are not compatible between lan‐
6328 guages.
6329 SKIP_UNITY_BUILD_INCLUSION
6331 Setting this property to true ensures the source file will be skipped
6332 by unity builds when its associated target has its UNITY_BUILD property
6333 set to true. The source file will instead be compiled on its own in
6334 the same way as it would with unity builds disabled.
6335 This property helps with “ODR (One definition rule)” problems where
6337 combining a particular source file with others might lead to build
6338 errors or other unintended side effects.
6339 Swift_DEPENDENCIES_FILE
6341 This property sets the path for the Swift dependency file (swiftdeps)
6342 for the source. If one is not specified, it will default to
6343 <OBJECT>.swiftdeps.
6344 Swift_DIAGNOSTICS_FILE
6346 This property controls where the Swift diagnostics are serialized.
6347 SYMBOLIC
6349 Is this just a name for a rule.
6350 If SYMBOLIC (boolean) is set to True the build system will be informed
6352 that the source file is not actually created on disk but instead used
6353 as a symbolic name for a build rule.
6354 VS_COPY_TO_OUT_DIR
6356 Sets the <CopyToOutputDirectory> tag for a source file in a Visual Stu‐
6357 dio project file. Valid values are Never, Always and PreserveNewest.
6358 VS_CSHARP_<tagname>
6360 Visual Studio and CSharp source-file-specific configuration.
6361 Tell the Visual Studio generators to set the source file tag <tagname>
6363 to a given value in the generated Visual Studio CSharp project. Ignored
6364 on other generators and languages. This property can be used to define
6365 dependencies between source files or set any other Visual Studio spe‐
6366 cific parameters.
6367 Example usage:
6369 set_source_files_property(<filename>
6371 PROPERTIES
6372 VS_CSHARP_DependentUpon <other file>
6373 VS_CSHARP_SubType "Form")
6374 VS_DEPLOYMENT_CONTENT
6376 Mark a source file as content for deployment with a Windows Phone or
6377 Windows Store application when built with a Visual Studio generators.
6378 The value must evaluate to either 1 or 0 and may use generator expres‐
6379 sions to make the choice based on the build configuration. The .vcx‐
6380 proj file entry for the source file will be marked either Deployment‐
6381 Content or ExcludedFromBuild for values 1 and 0, respectively.
6382 VS_DEPLOYMENT_LOCATION
6384 Specifies the deployment location for a content source file with a Win‐
6385 dows Phone or Windows Store application when built with a Visual Studio
6386 generators. This property is only applicable when using VS_DEPLOY‐
6387 MENT_CONTENT. The value represent the path relative to the app package
6388 and applies to all configurations.
6389 VS_INCLUDE_IN_VSIX
6391 Boolean property to specify if the file should be included within a
6392 VSIX (Visual Studio Integration Extension) extension package. This is
6393 needed for development of Visual Studio extensions.
6394 VS_RESOURCE_GENERATOR
6396 This property allows to specify the resource generator to be used on
6397 this file. It defaults to PublicResXFileCodeGenerator if not set.
6398 This property only applies to C# projects.
6400 VS_SHADER_DISABLE_OPTIMIZATIONS
6402 Disable compiler optimizations for an .hlsl source file. This adds the
6403 -Od flag to the command line for the FxCompiler tool. Specify the
6404 value true for this property to disable compiler optimizations.
6405 VS_SHADER_ENABLE_DEBUG
6407 Enable debugging information for an .hlsl source file. This adds the
6408 -Zi flag to the command line for the FxCompiler tool. Specify the
6409 value true to generate debugging information for the compiled shader.
6410 VS_SHADER_ENTRYPOINT
6412 Specifies the name of the entry point for the shader of a .hlsl source
6413 file.
6414 VS_SHADER_FLAGS
6416 Set additional Visual Studio shader flags of a .hlsl source file.
6417 VS_SHADER_MODEL
6419 Specifies the shader model of a .hlsl source file. Some shader types
6420 can only be used with recent shader models
6421 VS_SHADER_OBJECT_FILE_NAME
6423 Specifies a file name for the compiled shader object file for an .hlsl
6424 source file. This adds the -Fo flag to the command line for the FxCom‐
6425 piler tool.
6426 VS_SHADER_OUTPUT_HEADER_FILE
6428 Set filename for output header file containing object code of a .hlsl
6429 source file.
6430 VS_SHADER_TYPE
6432 Set the Visual Studio shader type of a .hlsl source file.
6433 VS_SHADER_VARIABLE_NAME
6435 Set name of variable in header file containing object code of a .hlsl
6436 source file.
6437 VS_TOOL_OVERRIDE
6439 Override the default Visual Studio tool that will be applied to the
6440 source file with a new tool not based on the extension of the file.
6441 VS_XAML_TYPE
6443 Mark a Extensible Application Markup Language (XAML) source file as a
6444 different type than the default Page. The most common usage would be
6445 to set the default App.xaml file as ApplicationDefinition.
6446 WRAP_EXCLUDE
6448 Exclude this source file from any code wrapping techniques.
6449 Some packages can wrap source files into alternate languages to provide
6451 additional functionality.
6452 For example, C++ code can be wrapped into Java or Python, using SWIG.
6454 If WRAP_EXCLUDE is set to True, that indicates that this source file
6455 should not be wrapped.
6456 XCODE_EXPLICIT_FILE_TYPE
6458 Set the Xcode explicitFileType attribute on its reference to a source
6459 file. CMake computes a default based on file extension but can be told
6460 explicitly with this property.
6461 See also XCODE_LAST_KNOWN_FILE_TYPE.
6463 XCODE_FILE_ATTRIBUTES
6465 Add values to the Xcode ATTRIBUTES setting on its reference to a source
6466 file. Among other things, this can be used to set the role on a .mig
6467 file:
6468 set_source_files_properties(defs.mig
6470 PROPERTIES
6471 XCODE_FILE_ATTRIBUTES "Client;Server"
6472 )
6473 XCODE_LAST_KNOWN_FILE_TYPE
6475 Set the Xcode lastKnownFileType attribute on its reference to a source
6476 file. CMake computes a default based on file extension but can be told
6477 explicitly with this property.
6478 See also XCODE_EXPLICIT_FILE_TYPE, which is preferred over this prop‐
6480 erty if set.
6481
6483 ADVANCED
6484 True if entry should be hidden by default in GUIs.
6485 This is a boolean value indicating whether the entry is considered
6487 interesting only for advanced configuration. The mark_as_advanced()
6488 command modifies this property.
6489 HELPSTRING
6491 Help associated with entry in GUIs.
6492 This string summarizes the purpose of an entry to help users set it
6494 through a CMake GUI.
6495 MODIFIED
6497 Internal management property. Do not set or get.
6498 This is an internal cache entry property managed by CMake to track
6500 interactive user modification of entries. Ignore it.
6501 STRINGS
6503 Enumerate possible STRING entry values for GUI selection.
6504 For cache entries with type STRING, this enumerates a set of values.
6506 CMake GUIs may use this to provide a selection widget instead of a
6507 generic string entry field. This is for convenience only. CMake does
6508 not enforce that the value matches one of those listed.
6509 TYPE
6511 Widget type for entry in GUIs.
6512 Cache entry values are always strings, but CMake GUIs present widgets
6514 to help users set values. The GUIs use this property as a hint to
6515 determine the widget type. Valid TYPE values are:
6516 BOOL = Boolean ON/OFF value.
6518 PATH = Path to a directory.
6519 FILEPATH = Path to a file.
6520 STRING = Generic string value.
6521 INTERNAL = Do not present in GUI at all.
6522 STATIC = Value managed by CMake, do not change.
6523 UNINITIALIZED = Type not yet specified.
6524 Generally the TYPE of a cache entry should be set by the command which
6526 creates it ( set(), option(), find_library(), etc.).
6527 VALUE
6529 Value of a cache entry.
6530 This property maps to the actual value of a cache entry. Setting this
6532 property always sets the value without checking, so use with care.
6533
6535 CPACK_DESKTOP_SHORTCUTS
6536 Species a list of shortcut names that should be created on the Desktop
6537 for this file.
6538 The property is currently only supported by the CPack WIX Generator.
6540 CPACK_NEVER_OVERWRITE
6542 Request that this file not be overwritten on install or reinstall.
6543 The property is currently only supported by the CPack WIX Generator.
6545 CPACK_PERMANENT
6547 Request that this file not be removed on uninstall.
6548 The property is currently only supported by the CPack WIX Generator.
6550 CPACK_START_MENU_SHORTCUTS
6552 Species a list of shortcut names that should be created in the Start
6553 Menu for this file.
6554 The property is currently only supported by the CPack WIX Generator.
6556 CPACK_STARTUP_SHORTCUTS
6558 Species a list of shortcut names that should be created in the Startup
6559 folder for this file.
6560 The property is currently only supported by the CPack WIX Generator.
6562 CPACK_WIX_ACL
6564 Specifies access permissions for files or directories installed by a
6565 WiX installer.
6566 The property can contain multiple list entries, each of which has to
6568 match the following format.
6569 <user>[@<domain>]=<permission>[,<permission>]
6571 <user> and <domain> specify the windows user and domain for which the
6573 <Permission> element should be generated.
6574 <permission> is any of the YesNoType attributes listed here:
6576 http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html
6578 The property is currently only supported by the CPack WIX Generator.
6580
6582 ADDITIONAL_MAKE_CLEAN_FILES
6583 Deprecated since version 3.15: Use ADDITIONAL_CLEAN_FILES instead.
6584 Additional files to remove during the clean stage.
6587 A ;-list of files that will be removed as a part of the make clean tar‐
6589 get.
6590 Arguments to ADDITIONAL_MAKE_CLEAN_FILES may use generator expressions.
6592 This property only works for the Makefile generators. It is ignored on
6594 other generators.
6595 COMPILE_DEFINITIONS_<CONFIG>
6597 Ignored. See CMake Policy CMP0043.
6598 Per-configuration preprocessor definitions in a directory.
6600 This is the configuration-specific version of COMPILE_DEFINITIONS where
6602 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
6603 This property will be initialized in each directory by its value in the
6605 directory’s parent.
6606 Contents of COMPILE_DEFINITIONS_<CONFIG> may use “generator expres‐
6608 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
6609 manual for available expressions. See the cmake-buildsystem(7) manual
6610 for more on defining buildsystem properties.
6611 Generator expressions should be preferred instead of setting this prop‐
6613 erty.
6614 TEST_INCLUDE_FILE
6616 Deprecated. Use TEST_INCLUDE_FILES instead.
6617 A cmake file that will be included when ctest is run.
6619 If you specify TEST_INCLUDE_FILE, that file will be included and pro‐
6621 cessed when ctest is run on the directory.
6622
6624 COMPILE_DEFINITIONS_<CONFIG>
6625 Ignored. See CMake Policy CMP0043.
6626 Per-configuration preprocessor definitions on a target.
6628 This is the configuration-specific version of COMPILE_DEFINITIONS where
6630 <CONFIG> is an upper-case name (ex. COMPILE_DEFINITIONS_DEBUG).
6631 Contents of COMPILE_DEFINITIONS_<CONFIG> may use “generator expres‐
6633 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
6634 manual for available expressions. See the cmake-buildsystem(7) manual
6635 for more on defining buildsystem properties.
6636 Generator expressions should be preferred instead of setting this prop‐
6638 erty.
6639 POST_INSTALL_SCRIPT
6641 Deprecated install support.
6642 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
6644 way to specify CMake scripts to run before and after installing a tar‐
6645 get. They are used only when the old INSTALL_TARGETS command is used
6646 to install the target. Use the install() command instead.
6647 PRE_INSTALL_SCRIPT
6649 Deprecated install support.
6650 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
6652 way to specify CMake scripts to run before and after installing a tar‐
6653 get. They are used only when the old INSTALL_TARGETS command is used
6654 to install the target. Use the install() command instead.
6655
6657 COMPILE_DEFINITIONS_<CONFIG>
6658 Ignored. See CMake Policy CMP0043.
6659 Per-configuration preprocessor definitions on a source file.
6661 This is the configuration-specific version of COMPILE_DEFINITIONS.
6663 Note that Xcode does not support per-configuration source file flags so
6664 this property will be ignored by the Xcode generator.
6665
6667 2000-2019 Kitware, Inc. and Contributors
66683.16.1 Dec 14, 2019 CMAKE-PROPERTIES(7)